@skyhook-io/radar-app 0.2.2 → 0.3.1

package/src/RadarApp.tsx

@@ -16,22 +16,42 @@
 // Both are applied before any children render so downstream code that
 // reads config synchronously (e.g. URL construction inside fetchJSON)
 // sees the host's values.
-import React from 'react';
-import { BrowserRouter, MemoryRouter } from 'react-router-dom';
-import { QueryClient, QueryClientProvider, MutationCache, QueryCache } from '@tanstack/react-query';
+import React from "react";
+import { BrowserRouter, MemoryRouter } from "react-router-dom";
+import {
+  QueryClient,
+  QueryClientProvider,
+  MutationCache,
+  QueryCache,
+} from "@tanstack/react-query";
 
-import App from './App';
-import { ThemeProvider } from './context/ThemeContext';
-import { ToastProvider, showApiError, showApiSuccess } from './components/ui/Toast';
-import { setApiBase, setBasename } from './api/config';
-import { NavCustomizationProvider } from './context/NavCustomization';
-import type { NavCustomization } from './context/NavCustomization';
+import App from "./App";
+import { ThemeProvider } from "./context/ThemeContext";
+import {
+  ToastProvider,
+  showApiError,
+  showApiSuccess,
+} from "./components/ui/Toast";
+import { setApiBase, setBasename } from "./api/config";
+import { NavCustomizationProvider } from "./context/NavCustomization";
+import { FilterLocationBridge } from "./filter/FilterLocationBridge";
+import type { NavCustomization } from "./context/NavCustomization";
+import type { ClusterLoadState } from "./types/clusterLoadState";
+import { TimelineSourceProvider } from "./context/TimelineSource";
+import type { TimelineSourceConfig } from "./api/timelineSource";
+import { DiagnoseCustomizationProvider } from "./context/DiagnoseCustomization";
+import type {
+  RenderDiagnoseAction,
+  DiagnoseConsentCopy,
+} from "./context/DiagnoseCustomization";
+import { defaultDiagnoseAction } from "./components/diagnose/LocalDiagnoseAction";
+import { DiagnoseProvider } from "./components/diagnose/DiagnoseContext";
 
 // Declare the shape of mutation meta here — inlined rather than in a
 // separate side-effect-only module so consumers that tree-shake aggressively
 // (package.json sets sideEffects: ["*.css"]) can't drop the augmentation.
 // Any consumer that imports RadarApp will pull in this declaration.
-declare module '@tanstack/react-query' {
+declare module "@tanstack/react-query" {
   interface Register {
     mutationMeta: {
       errorMessage?: string;
@@ -56,7 +76,7 @@ export interface RadarAppProps {
    *     Escape hatch for tests and for host apps that can't restructure
    *     around a single top-level BrowserRouter.
    */
-  router?: 'browser' | 'memory';
+  router?: "browser" | "memory";
   /**
    * Optional QueryClient override. When consuming Radar inside another app
    * that already has a QueryClientProvider higher in the tree, you may
@@ -70,6 +90,65 @@ export interface RadarAppProps {
    * See ./context/NavCustomization for the slot shape.
    */
   navSlots?: NavCustomization;
+  /**
+   * Whether Radar may set the browser tab title (`document.title`) per view.
+   * Defaults to OFF: embedders keep title ownership without opting out. The
+   * standalone binary opts in (`web/src/main.tsx` renders
+   * `<RadarApp manageDocumentTitle />`), and any full-page embed that wants
+   * Radar's per-view titles can do the same.
+   */
+  manageDocumentTitle?: boolean;
+  /**
+   * Trailing string appended after the per-view label (only when
+   * `manageDocumentTitle` is on). It's the *full* suffix including any
+   * separator, so a host can rebrand (`' — My Cloud'`) or drop it (`''`).
+   * Defaults to `' · Radar'`.
+   */
+  documentTitleSuffix?: string;
+  /**
+   * Injects a resource-level "Diagnose" action (e.g. a "Diagnose with AI"
+   * button) into every resource detail action bar's right-aligned universal
+   * actions. The host returns the node to render given the resource context.
+   * Standalone Radar omits this and renders no Diagnose button — OSS stays
+   * agent-free. See ./context/DiagnoseCustomization for the render-prop shape.
+   */
+  renderDiagnoseAction?: RenderDiagnoseAction;
+  /**
+   * Replaces the first-run consent card's trust copy. REQUIRED of any host whose
+   * backend runs the agent somewhere other than the user's own machine — the
+   * default copy states the agent runs locally, under the user's own model
+   * account, with transcripts kept on their disk, and none of that is true of a
+   * hosted runner. Radar keeps the card's chrome and the Approve/Cancel flow; a
+   * host only supplies the claims. See ./context/DiagnoseCustomization.
+   */
+  diagnoseConsent?: DiagnoseConsentCopy;
+  /**
+   * Initial route for `router: 'memory'` (ignored for 'browser'). Lets a host
+   * deep-link a specific view (e.g. '/topology') without owning the URL bar —
+   * used with `navSlots.chrome: 'none'` to render a single per-cluster view
+   * chromeless under the host's own chrome (Radar Hub's per-cluster destinations).
+   */
+  initialPath?: string;
+  /**
+   * Reports cluster-data warmup after the main connection is usable. Embedders
+   * with their own chrome (Radar Hub) can render this in their topbar while
+   * Radar runs with `navSlots.chrome: 'none'`.
+   */
+  onClusterLoadStateChange?: (state: ClusterLoadState) => void;
+  /**
+   * Selects the store backing the event timeline. Omit for the local event
+   * store the Radar binary keeps (default, standalone behavior). Set
+   * `{ mode: 'retained' }` when embedding behind a proxy that serves a
+   * longer-horizon history at `{apiBase}/timeline/events` +
+   * `{apiBase}/timeline/overview`; `maxRangeDays` caps how far back the
+   * 'all' range reaches. Generic extension point — the backend that answers
+   * the retained endpoints is the host's concern.
+   *
+   * Changing `mode` between renders remounts the timeline view (the local and
+   * retained sources expose different `useEvents` hooks; remounting avoids a
+   * React hook-order violation). Set it once at mount when possible.
+   */
+  timelineSource?: TimelineSourceConfig;
 }
 
 // Default QueryClient with the same shape Radar's standalone binary uses.
@@ -90,13 +169,18 @@ function makeDefaultQueryClient(): QueryClient {
       },
       onSuccess: (_data, _variables, _context, mutation) => {
         const message = mutation.options.meta?.successMessage;
-        if (message) showApiSuccess(message, mutation.options.meta?.successDetail);
+        if (message)
+          showApiSuccess(message, mutation.options.meta?.successDetail);
       },
     }),
     queryCache: new QueryCache({
       onError: (error, query) => {
         if (query.state.data !== undefined) {
-          console.warn('[Background sync failed]', query.queryKey, (error as Error).message);
+          console.warn(
+            "[Background sync failed]",
+            query.queryKey,
+            (error as Error).message,
+          );
         }
       },
     }),
@@ -106,9 +190,16 @@ function makeDefaultQueryClient(): QueryClient {
 export function RadarApp({
   apiBase,
   basename,
-  router = 'browser',
+  router = "browser",
   queryClient,
   navSlots,
+  manageDocumentTitle = false,
+  documentTitleSuffix,
+  renderDiagnoseAction,
+  diagnoseConsent,
+  initialPath,
+  onClusterLoadStateChange,
+  timelineSource,
 }: RadarAppProps): React.ReactElement {
   // Apply runtime config during render so module-level singletons are set
   // before children construct URLs. getApiBase() / getAuthHeaders() /
@@ -121,25 +212,47 @@ export function RadarApp({
 
   // Memo so we don't recreate the QueryClient on every render when the
   // consumer didn't pass one.
-  const client = React.useMemo(() => queryClient ?? makeDefaultQueryClient(), [queryClient]);
+  const client = React.useMemo(
+    () => queryClient ?? makeDefaultQueryClient(),
+    [queryClient],
+  );
 
   const inner = (
     <ThemeProvider>
       <QueryClientProvider client={client}>
         <ToastProvider>
           <NavCustomizationProvider value={navSlots}>
-            <App />
+            <FilterLocationBridge>
+              <TimelineSourceProvider config={timelineSource}>
+                <DiagnoseCustomizationProvider
+                  value={renderDiagnoseAction ?? defaultDiagnoseAction}
+                  consentCopy={diagnoseConsent}
+                >
+                  <DiagnoseProvider>
+                    <App
+                      manageDocumentTitle={manageDocumentTitle}
+                      documentTitleSuffix={documentTitleSuffix}
+                      onClusterLoadStateChange={onClusterLoadStateChange}
+                    />
+                  </DiagnoseProvider>
+                </DiagnoseCustomizationProvider>
+              </TimelineSourceProvider>
+            </FilterLocationBridge>
           </NavCustomizationProvider>
         </ToastProvider>
       </QueryClientProvider>
     </ThemeProvider>
   );
 
-  if (router === 'memory') {
-    return <MemoryRouter initialEntries={['/']}>{inner}</MemoryRouter>;
+  if (router === "memory") {
+    return (
+      <MemoryRouter initialEntries={[initialPath || "/"]}>{inner}</MemoryRouter>
+    );
   }
 
-  return <BrowserRouter basename={basename || undefined}>{inner}</BrowserRouter>;
+  return (
+    <BrowserRouter basename={basename || undefined}>{inner}</BrowserRouter>
+  );
 }
 
 export default RadarApp;

package/src/api/apiResources.ts

@@ -3,7 +3,7 @@ import type { APIResource } from '../types'
 import { apiUrl, getAuthHeaders, getCredentialsMode } from './config'
 
 // Re-export pure functions from package
-export { categorizeResources, CORE_RESOURCES, formatGroupName, shortenGroupName, getKindLabel, getKindPlural } from '@skyhook-io/k8s-ui'
+export { categorizeResources, CORE_RESOURCES, findAPIResourceForRoute, formatGroupName, shortenGroupName, getKindLabel, getKindPlural } from '@skyhook-io/k8s-ui'
 export type { ResourceCategory } from '@skyhook-io/k8s-ui'
 
 async function fetchJSON<T>(path: string): Promise<T> {

package/src/api/client.argoResourceSync.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import { buildArgoResourceSyncVars } from './client'
+
+const options = {
+  revision: 'should-not-survive',
+  prune: true,
+  dryRun: false,
+  force: true,
+  applyOnly: true,
+  syncOptions: ['ServerSideApply=true'],
+}
+
+describe('buildArgoResourceSyncVars', () => {
+  it('preserves the complete Argo status ref and forces resource-safe options', () => {
+    expect(
+      buildArgoResourceSyncVars(
+        'argocd',
+        'guestbook',
+        {
+          group: 'apps',
+          kind: 'Deployment',
+          namespace: 'guestbook',
+          name: 'guestbook-ui',
+        },
+        options,
+      ),
+    ).toEqual({
+      namespace: 'argocd',
+      name: 'guestbook',
+      resources: [
+        {
+          group: 'apps',
+          kind: 'Deployment',
+          namespace: 'guestbook',
+          name: 'guestbook-ui',
+        },
+      ],
+      revision: undefined,
+      prune: false,
+      dryRun: false,
+      force: true,
+      applyOnly: false,
+      syncOptions: ['ServerSideApply=true'],
+    })
+  })
+
+  it('preserves an empty core API group', () => {
+    const variables = buildArgoResourceSyncVars(
+      'argocd',
+      'guestbook',
+      {
+        group: '',
+        kind: 'Service',
+        namespace: 'guestbook',
+        name: 'guestbook-ui',
+      },
+      options,
+    )
+
+    expect(variables.resources).toEqual([
+      {
+        group: '',
+        kind: 'Service',
+        namespace: 'guestbook',
+        name: 'guestbook-ui',
+      },
+    ])
+  })
+})

package/src/api/client.delta.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { deltaFetchCursor, maxEventSeq, mergeDeltaEvents, type ChangesDeltaMeta } from './client'
+import type { TimelineEvent } from '@skyhook-io/k8s-ui'
+
+const mk = (id: string, seq: number, tsOffsetMs: number): TimelineEvent => ({
+  id,
+  seq,
+  timestamp: new Date(1_700_000_000_000 + tsOffsetMs).toISOString(),
+  source: 'informer',
+  kind: 'Pod',
+  namespace: 'default',
+  name: id,
+  eventType: 'update',
+})
+
+describe('maxEventSeq (delta cursor)', () => {
+  it('returns the highest arrival number', () => {
+    expect(maxEventSeq([mk('a', 3, 0), mk('b', 7, 1000), mk('c', 5, 2000)])).toBe(7)
+  })
+
+  it('returns 0 for an empty page or seq-less events', () => {
+    expect(maxEventSeq([])).toBe(0)
+    expect(maxEventSeq([{ ...mk('a', 0, 0), seq: undefined }])).toBe(0)
+  })
+})
+
+describe('mergeDeltaEvents (delta page into cached page)', () => {
+  it('returns the cached reference untouched for an empty delta', () => {
+    const prev = [mk('a', 1, 0)]
+    expect(mergeDeltaEvents(prev, [], 100)).toBe(prev)
+  })
+
+  it('adds new arrivals in newest-first order', () => {
+    const prev = [mk('b', 2, 1000), mk('a', 1, 0)]
+    const merged = mergeDeltaEvents(prev, [mk('c', 3, 2000)], 100)
+    expect(merged.map((e) => e.id)).toEqual(['c', 'b', 'a'])
+  })
+
+  it('replaces a cached row when the same id re-arrives (K8s Event count bump)', () => {
+    const prev = [{ ...mk('bump', 1, 0), count: 1 }, mk('a', 2, 500)]
+    const merged = mergeDeltaEvents(prev, [{ ...mk('bump', 3, 1000), count: 5 }], 100)
+    expect(merged).toHaveLength(2)
+    expect(merged[0].id).toBe('bump')
+    expect(merged[0].count).toBe(5)
+  })
+
+  it('orders a late arrival by its timestamp, not its arrival number', () => {
+    const prev = [mk('b', 2, 2000), mk('a', 1, 1000)]
+    const merged = mergeDeltaEvents(prev, [mk('late', 3, 0)], 100)
+    expect(merged.map((e) => e.id)).toEqual(['b', 'a', 'late'])
+  })
+
+  it('caps the merged page by dropping the oldest', () => {
+    const prev = [mk('b', 2, 2000), mk('a', 1, 1000)]
+    const merged = mergeDeltaEvents(prev, [mk('c', 3, 3000)], 2)
+    expect(merged.map((e) => e.id)).toEqual(['c', 'b'])
+  })
+})
+
+describe('deltaFetchCursor (cursor selection incl. high-water)', () => {
+  const NOW = 1_700_000_000_000
+  const meta = (over: Partial<ChangesDeltaMeta> = {}): ChangesDeltaMeta => ({
+    epoch: 'e1',
+    lastFullMs: NOW - 10_000,
+    highWaterSeq: 0,
+    ...over,
+  })
+
+  it('requires an epoch-stamped prior load and a cached page', () => {
+    expect(deltaFetchCursor(undefined, [mk('a', 1, 0)], NOW)).toBe(0)
+    expect(deltaFetchCursor(meta({ epoch: '' }), [mk('a', 1, 0)], NOW)).toBe(0)
+    expect(deltaFetchCursor(meta(), undefined, NOW)).toBe(0)
+  })
+
+  it('forces a full resync once the anti-entropy interval elapses', () => {
+    expect(deltaFetchCursor(meta({ lastFullMs: NOW - 6 * 60_000 }), [mk('a', 1, 0)], NOW)).toBe(0)
+  })
+
+  it('uses the cached max seq in the ordinary case', () => {
+    expect(deltaFetchCursor(meta(), [mk('a', 7, 0), mk('b', 3, 1000)], NOW)).toBe(7)
+  })
+
+  it('does not regress when a capped-out delta event held the highest seq', () => {
+    // The seq-9 event was merged then dropped by the cap (oldest timestamp);
+    // cached rows top out at 7. The cursor must hold at the high water or the
+    // same delta gets re-downloaded on every refetch.
+    expect(deltaFetchCursor(meta({ highWaterSeq: 9 }), [mk('a', 7, 0)], NOW)).toBe(9)
+  })
+})

package/src/api/client.deltaSync.test.ts

@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { runDeltaSyncFetch, type ChangesDeltaMeta } from './client'
+import type { TimelineEvent } from '@skyhook-io/k8s-ui'
+
+// Orchestration test for the useChanges delta contract. The pure helpers
+// (deltaFetchCursor / mergeDeltaEvents / maxEventSeq) are covered in
+// client.delta.test.ts; here we drive the full runDeltaSyncFetch loop through
+// the real fetch boundary so the header parsing, cursor priming, epoch-resync,
+// and merge all participate.
+
+const BASE_TS = 1_700_000_000_000
+const mk = (id: string, seq: number, tsOffsetMs: number, extra: Partial<TimelineEvent> = {}): TimelineEvent => ({
+  id,
+  seq,
+  timestamp: new Date(BASE_TS + tsOffsetMs).toISOString(),
+  source: 'informer',
+  kind: 'Pod',
+  namespace: 'default',
+  name: id,
+  eventType: 'update',
+  ...extra,
+})
+
+// A page as the server returns it: an events body plus the two frontier headers
+// that fetchChangesPage reads to derive epoch + maxSeq.
+interface Page {
+  events: TimelineEvent[]
+  epoch: string
+  maxSeq: number
+}
+function pageResponse(page: Page): Response {
+  return new Response(JSON.stringify(page.events), {
+    status: 200,
+    headers: {
+      'X-Radar-Timeline-Epoch': page.epoch,
+      'X-Radar-Timeline-Max-Seq': String(page.maxSeq),
+    },
+  })
+}
+
+// The `since_seq` a fetched URL carries, or null for a full fetch.
+function sinceSeqOf(url: string): number | null {
+  const m = url.match(/[?&]since_seq=(\d+)/)
+  return m ? Number(m[1]) : null
+}
+
+let fetchedUrls: string[]
+let responder: (url: string) => Page
+
+beforeEach(() => {
+  fetchedUrls = []
+  vi.stubGlobal('fetch', (input: RequestInfo | URL) => {
+    const url = String(input)
+    fetchedUrls.push(url)
+    return Promise.resolve(pageResponse(responder(url)))
+  })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+const PATH = '/changes?limit=200&filter=all'
+const QUERY_STRING = 'limit=200&filter=all'
+const LIMIT = 200
+const META_KEY = 'changes-key'
+
+// A single query's delta loop: fresh meta store per test, cached page threaded
+// forward across polls, an explicit `now` so the anti-entropy full-resync timer
+// stays out of the way unless a test wants it.
+function run(metaStore: Map<string, ChangesDeltaMeta>, cached: TimelineEvent[] | undefined, now: number) {
+  return runDeltaSyncFetch({ path: PATH, queryString: QUERY_STRING, limit: LIMIT, metaKey: META_KEY, cached, metaStore, now })
+}
+
+const lastUrl = () => fetchedUrls[fetchedUrls.length - 1]
+
+describe('runDeltaSyncFetch (useChanges delta orchestration)', () => {
+  it('first fetch (no cursor) is a full fetch; the cursor is primed from the max-seq header', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    // Header frontier 8 exceeds the highest visible event seq (5): rows dropped
+    // by the server's RBAC filter still advance the cursor.
+    responder = () => ({ events: [mk('a', 5, 2000), mk('b', 3, 1000)], epoch: 'e1', maxSeq: 8 })
+
+    const result = await run(metaStore, undefined, 1_000)
+
+    expect(fetchedUrls).toHaveLength(1)
+    expect(sinceSeqOf(fetchedUrls[0])).toBeNull()
+    expect(result.map((e) => e.id)).toEqual(['a', 'b'])
+
+    const meta = metaStore.get(META_KEY)!
+    expect(meta.epoch).toBe('e1')
+    expect(meta.highWaterSeq).toBe(8)
+    expect(meta.lastFullMs).toBe(1_000)
+  })
+
+  it('a subsequent poll sends since_seq=<cursor>, merges delta rows by id, and advances the cursor', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 2000), mk('b', 3, 1000)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // A new arrival (c) plus a re-arrival of 'a' under a higher seq (count bump).
+    responder = () => ({ events: [mk('c', 7, 3000), mk('a', 6, 2000, { count: 9 })], epoch: 'e1', maxSeq: 7 })
+    const second = await run(metaStore, first, 2_000)
+
+    expect(sinceSeqOf(lastUrl())).toBe(5)
+    expect(second.map((e) => e.id)).toEqual(['c', 'a', 'b'])
+    expect(second.find((e) => e.id === 'a')!.count).toBe(9)
+    expect(metaStore.get(META_KEY)!.highWaterSeq).toBe(7)
+  })
+
+  it('an empty delta carrying a max-seq header still advances the cursor', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 2000)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // The entire page past seq 5 was RBAC-filtered to nothing, but the server
+    // reports the frontier it scanned to.
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 12 })
+    const second = await run(metaStore, first, 2_000)
+    expect(metaStore.get(META_KEY)!.highWaterSeq).toBe(12)
+
+    // The next poll must ride the advanced cursor, not re-request from 5.
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 12 })
+    await run(metaStore, second, 3_000)
+    expect(sinceSeqOf(lastUrl())).toBe(12)
+  })
+
+  it('an empty delta returns the cached array reference (no needless re-render)', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('a', 5, 0)], epoch: 'e1', maxSeq: 5 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    responder = () => ({ events: [], epoch: 'e1', maxSeq: 5 })
+    const second = await run(metaStore, first, 2_000)
+    expect(second).toBe(first)
+  })
+
+  it('an epoch change between polls forces a full resync: cursor reset, list replaced', async () => {
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    responder = () => ({ events: [mk('old', 9, 0)], epoch: 'e1', maxSeq: 9 })
+    const first = await run(metaStore, undefined, 1_000)
+
+    // The store restarted — seq numbering reset low, so a since_seq=9 delta comes
+    // back EMPTY under a NEW epoch. Trusting that empty delta as "nothing new"
+    // would strand the caller on the previous store's rows; the epoch mismatch
+    // must instead trigger a full resync.
+    const restarted = [mk('fresh', 2, 500)]
+    responder = (url) =>
+      sinceSeqOf(url) != null
+        ? { events: [], epoch: 'e2', maxSeq: 2 }
+        : { events: restarted, epoch: 'e2', maxSeq: 2 }
+    const second = await run(metaStore, first, 2_000)
+
+    expect(second).not.toBe(first)
+    expect(second.map((e) => e.id)).toEqual(['fresh'])
+    // Two fetches: the epoch-mismatched delta probe, then the full resync.
+    expect(sinceSeqOf(fetchedUrls[fetchedUrls.length - 2])).toBe(9)
+    expect(sinceSeqOf(lastUrl())).toBeNull()
+
+    const meta = metaStore.get(META_KEY)!
+    expect(meta.epoch).toBe('e2')
+    expect(meta.highWaterSeq).toBe(2)
+    expect(meta.lastFullMs).toBe(2_000)
+  })
+
+  it('equivalence: full → delta → delta yields the same set as a fresh full fetch of the final state', async () => {
+    // A minimal append/replace server keyed by id with monotonic seq. Each fetch
+    // serializes a snapshot, so pages the loop keeps are decoupled from later
+    // mutations of the log.
+    const epoch = 'e1'
+    const log: TimelineEvent[] = []
+    let nextSeq = 1
+    const upsert = (id: string, tsOffsetMs: number, content: number) => {
+      const seq = nextSeq++
+      const existing = log.find((e) => e.id === id)
+      if (existing) {
+        existing.seq = seq
+        existing.count = content
+      } else {
+        log.push(mk(id, seq, tsOffsetMs, { count: content }))
+      }
+    }
+    const newestFirst = (rows: TimelineEvent[]) =>
+      [...rows].sort((a, b) => {
+        const byTime = new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+        return byTime !== 0 ? byTime : (b.seq ?? 0) - (a.seq ?? 0)
+      })
+    responder = (url) => {
+      const since = sinceSeqOf(url)
+      const rows = since == null ? log : log.filter((e) => (e.seq ?? 0) > since)
+      const maxSeq = log.reduce((m, e) => Math.max(m, e.seq ?? 0), 0)
+      return { events: newestFirst(rows), epoch, maxSeq }
+    }
+
+    const metaStore = new Map<string, ChangesDeltaMeta>()
+    upsert('a', 1000, 1)
+    upsert('b', 2000, 1)
+    upsert('c', 3000, 1)
+    const l1 = await run(metaStore, undefined, 1_000)
+
+    upsert('d', 4000, 1)
+    upsert('a', 1000, 2) // a count bump re-arrives under the same id
+    const l2 = await run(metaStore, l1, 2_000)
+
+    upsert('e', 5000, 1)
+    upsert('b', 2000, 2)
+    const l3 = await run(metaStore, l2, 3_000)
+
+    // What a fresh client would get from a single full fetch of the final state.
+    const fresh = newestFirst(log)
+    const asSet = (rows: TimelineEvent[]) => rows.map((e) => `${e.id}:${e.count}`).sort()
+    expect(asSet(l3)).toEqual(asSet(fresh))
+    // No dropped or duplicated ids after two incremental merges.
+    expect(l3).toHaveLength(fresh.length)
+  })
+})