@syncular/client 0.0.2-2 → 0.0.3-14

package/dist/subscription-state.js

@@ -0,0 +1,185 @@
+/**
+ * @syncular/client - Subscription state helpers
+ *
+ * Stable accessors for sync subscription metadata.
+ */
+import { isRecord } from '@syncular/core';
+import { sql } from 'kysely';
+export const DEFAULT_SYNC_STATE_ID = 'default';
+function isScopeValues(value) {
+    if (!isRecord(value))
+        return false;
+    for (const entry of Object.values(value)) {
+        if (typeof entry === 'string')
+            continue;
+        if (Array.isArray(entry) && entry.every((v) => typeof v === 'string')) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+export function parseBootstrapState(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+        if (!isRecord(parsed))
+            return null;
+        if (typeof parsed.asOfCommitSeq !== 'number')
+            return null;
+        if (!Array.isArray(parsed.tables))
+            return null;
+        if (!parsed.tables.every((table) => typeof table === 'string'))
+            return null;
+        if (typeof parsed.tableIndex !== 'number')
+            return null;
+        if (parsed.rowCursor !== null && typeof parsed.rowCursor !== 'string') {
+            return null;
+        }
+        return {
+            asOfCommitSeq: parsed.asOfCommitSeq,
+            tables: parsed.tables,
+            tableIndex: parsed.tableIndex,
+            rowCursor: parsed.rowCursor,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parseScopes(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return isScopeValues(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseParams(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function mapSubscriptionState(row) {
+    return {
+        stateId: row.state_id,
+        subscriptionId: row.subscription_id,
+        table: row.table,
+        scopes: parseScopes(row.scopes_json),
+        params: parseParams(row.params_json),
+        cursor: row.cursor,
+        bootstrapState: parseBootstrapState(row.bootstrap_state_json),
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export async function listSubscriptionStates(db, options = {}) {
+    const filters = [];
+    if (options.stateId) {
+        filters.push(sql `${sql.ref('state_id')} = ${sql.val(options.stateId)}`);
+    }
+    if (options.table) {
+        filters.push(sql `${sql.ref('table')} = ${sql.val(options.table)}`);
+    }
+    if (options.status) {
+        filters.push(sql `${sql.ref('status')} = ${sql.val(options.status)}`);
+    }
+    const whereClause = filters.length > 0 ? sql `where ${sql.join(filters, sql ` and `)}` : sql ``;
+    const rows = await sql `
+    select
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    from ${sql.table('sync_subscription_state')}
+    ${whereClause}
+    order by ${sql.ref('state_id')} asc, ${sql.ref('subscription_id')} asc
+  `.execute(db);
+    return rows.rows.map((row) => mapSubscriptionState(row));
+}
+export async function getSubscriptionState(db, options) {
+    const stateId = options.stateId ?? DEFAULT_SYNC_STATE_ID;
+    const rows = await sql `
+    select
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    from ${sql.table('sync_subscription_state')}
+    where
+      ${sql.ref('state_id')} = ${sql.val(stateId)}
+      and ${sql.ref('subscription_id')} = ${sql.val(options.subscriptionId)}
+    limit 1
+  `.execute(db);
+    const row = rows.rows[0];
+    return row ? mapSubscriptionState(row) : null;
+}
+export async function upsertSubscriptionState(db, input) {
+    const now = input.nowMs ?? Date.now();
+    const stateId = input.stateId ?? DEFAULT_SYNC_STATE_ID;
+    const bootstrapStateJson = input.bootstrapState === null || input.bootstrapState === undefined
+        ? null
+        : JSON.stringify(input.bootstrapState);
+    await sql `
+    insert into ${sql.table('sync_subscription_state')} (
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    ) values (
+      ${sql.val(stateId)},
+      ${sql.val(input.subscriptionId)},
+      ${sql.val(input.table)},
+      ${sql.val(JSON.stringify(input.scopes ?? {}))},
+      ${sql.val(JSON.stringify(input.params ?? {}))},
+      ${sql.val(input.cursor)},
+      ${sql.val(bootstrapStateJson)},
+      ${sql.val(input.status ?? 'active')},
+      ${sql.val(now)},
+      ${sql.val(now)}
+    )
+    on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
+    do update set
+      ${sql.ref('table')} = ${sql.val(input.table)},
+      ${sql.ref('scopes_json')} = ${sql.val(JSON.stringify(input.scopes ?? {}))},
+      ${sql.ref('params_json')} = ${sql.val(JSON.stringify(input.params ?? {}))},
+      ${sql.ref('cursor')} = ${sql.val(input.cursor)},
+      ${sql.ref('bootstrap_state_json')} = ${sql.val(bootstrapStateJson)},
+      ${sql.ref('status')} = ${sql.val(input.status ?? 'active')},
+      ${sql.ref('updated_at')} = ${sql.val(now)}
+  `.execute(db);
+    const next = await getSubscriptionState(db, {
+        stateId,
+        subscriptionId: input.subscriptionId,
+    });
+    if (!next) {
+        throw new Error(`[subscription-state] Failed to load upserted state for "${input.subscriptionId}"`);
+    }
+    return next;
+}
+//# sourceMappingURL=subscription-state.js.map

package/dist/subscription-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-state.js","sourceRoot":"","sources":["../src/subscription-state.ts"],"names":[],"mappings":"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"}

package/dist/utils/id.d.ts

@@ -5,4 +5,13 @@
  * Generate a random UUID v4
  */
 export declare function randomUUID(): string;
+/**
+ * Build a stable state id from meaningful segments.
+ * Empty/undefined segments are ignored.
+ */
+export declare function buildStateId(...segments: Array<string | null | undefined>): string;
+/**
+ * Create a deterministic fingerprint string for scope values.
+ */
+export declare function createScopeFingerprint(scopes: Record<string, string | string[]>): string;
 //# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAYnC"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAYnC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5C,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,MAAM,CAaR"}

package/dist/utils/id.js

@@ -16,4 +16,31 @@ export function randomUUID() {
         return v.toString(16);
     });
 }
+/**
+ * Build a stable state id from meaningful segments.
+ * Empty/undefined segments are ignored.
+ */
+export function buildStateId(...segments) {
+    const normalized = segments
+        .map((segment) => segment?.trim())
+        .filter((segment) => !!segment && segment.length > 0);
+    if (normalized.length === 0)
+        return 'default';
+    return normalized.join(':');
+}
+/**
+ * Create a deterministic fingerprint string for scope values.
+ */
+export function createScopeFingerprint(scopes) {
+    const entries = Object.entries(scopes)
+        .map(([key, value]) => {
+        const encodedValues = (Array.isArray(value) ? [...value] : [value])
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0)
+            .sort();
+        return `${key}:${encodedValues.join('|')}`;
+    })
+        .sort();
+    return entries.join(';');
+}
 //# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,UAAU,GAAW;IACnC,kEAAkE;IAClE,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IAED,0BAA0B;IAC1B,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;QACpE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAAA,CACvB,CAAC,CAAC;AAAA,CACJ"}
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,UAAU,GAAW;IACnC,kEAAkE;IAClE,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IAED,0BAA0B;IAC1B,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;QACpE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAAA,CACvB,CAAC,CAAC;AAAA,CACJ;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAG,QAA0C,EACrC;IACR,MAAM,UAAU,GAAG,QAAQ;SACxB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;SACjC,MAAM,CAAC,CAAC,OAAO,EAAqB,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE3E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA,CAC7B;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAyC,EACjC;IACR,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QACrB,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;aAChE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;aACjC,IAAI,EAAE,CAAC;QAEV,OAAO,GAAG,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAAA,CAC5C,CAAC;SACD,IAAI,EAAE,CAAC;IAEV,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA,CAC1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.0.2-2",
+  "version": "0.0.3-14",
   "description": "Client-side sync engine with offline-first support, outbox, and conflict resolution",
   "license": "MIT",
   "author": "Benjamin Kniffler",
@@ -46,8 +46,8 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/core": "0.0.2-2",
-    "@syncular/transport-http": "0.0.2-2"
+    "@syncular/core": "0.0.3-14",
+    "@syncular/transport-http": "0.0.3-14"
   },
   "peerDependencies": {
     "kysely": "*"

package/src/client.test.ts

@@ -367,3 +367,42 @@ describe('Client blob upload queue recovery', () => {
     expect(row.error).toContain('Upload timed out while in uploading state');
   });
 });
+
+describe('Client inspector snapshot', () => {
+  let db: Kysely<TestDb>;
+  let client: Client<TestDb>;
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<TestDb>({ path: ':memory:' });
+    await ensureClientSyncSchema(db);
+
+    const handlers = new ClientTableRegistry<TestDb>();
+    client = new Client<TestDb>({
+      db,
+      transport: noopTransport,
+      tableHandlers: handlers,
+      clientId: 'client-inspector',
+      actorId: 'u1',
+      subscriptions: [],
+    });
+  });
+
+  afterEach(async () => {
+    client.destroy();
+    await db.destroy();
+  });
+
+  it('returns a serializable inspector snapshot', async () => {
+    await client.start();
+    await client.sync();
+
+    const snapshot = await client.getInspectorSnapshot({ eventLimit: 20 });
+
+    expect(snapshot).not.toBeNull();
+    expect(snapshot?.version).toBe(1);
+    expect(snapshot?.generatedAt).toBeGreaterThan(0);
+    expect(Array.isArray(snapshot?.recentEvents)).toBe(true);
+    expect(snapshot?.recentEvents.length).toBeGreaterThan(0);
+    expect(snapshot?.diagnostics).toBeDefined();
+  });
+});

package/src/client.ts

@@ -23,8 +23,19 @@ import type {
   ConflictInfo,
   OutboxStats,
   PresenceEntry,
+  SubscriptionProgress,
+  SyncAwaitBootstrapOptions,
+  SyncAwaitPhaseOptions,
+  SyncDiagnostics,
   SyncEngineState,
+  SyncInspectorOptions,
+  SyncInspectorSnapshot,
+  SyncProgress,
+  SyncRepairOptions,
+  SyncResetOptions,
+  SyncResetResult,
   SyncResult,
+  TransportHealth,
 } from './engine/types';
 import type { ClientTableRegistry } from './handlers/registry';
 import { ensureClientSyncSchema } from './migrate';
@@ -35,6 +46,7 @@ import {
 } from './mutations';
 import type { SyncClientPlugin } from './plugins/types';
 import type { SyncClientDb } from './schema';
+import type { SubscriptionState } from './subscription-state';
 
 // ============================================================================
 // Types
@@ -216,7 +228,11 @@ export interface MigrationInfo {
 type ClientEventType =
   | 'sync:start'
   | 'sync:complete'
+  | 'sync:live'
   | 'sync:error'
+  | 'bootstrap:start'
+  | 'bootstrap:progress'
+  | 'bootstrap:complete'
   | 'connection:change'
   | 'data:change'
   | 'outbox:change'
@@ -229,7 +245,25 @@ type ClientEventType =
 type ClientEventPayloads = {
   'sync:start': { timestamp: number };
   'sync:complete': SyncResult;
+  'sync:live': { timestamp: number };
   'sync:error': { code: string; message: string };
+  'bootstrap:start': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+  };
+  'bootstrap:progress': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+    progress: SubscriptionProgress;
+  };
+  'bootstrap:complete': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+    durationMs: number;
+  };
   'connection:change': { previous: string; current: string };
   'data:change': { scopes: string[]; timestamp: number };
   'outbox:change': OutboxStats;
@@ -464,6 +498,29 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
     }));
   }
 
+  /**
+   * List persisted subscription metadata rows.
+   */
+  async listSubscriptionStates(args?: {
+    stateId?: string;
+    table?: string;
+    status?: 'active' | 'revoked';
+  }): Promise<SubscriptionState[]> {
+    if (!this.engine) return [];
+    return this.engine.listSubscriptionStates(args);
+  }
+
+  /**
+   * Read one persisted subscription metadata row.
+   */
+  async getSubscriptionState(
+    subscriptionId: string,
+    options?: { stateId?: string }
+  ): Promise<SubscriptionState | null> {
+    if (!this.engine) return null;
+    return this.engine.getSubscriptionState(subscriptionId, options);
+  }
+
   // ===========================================================================
   // State
   // ===========================================================================
@@ -488,6 +545,91 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
     };
   }
 
+  /**
+   * Get current transport health details.
+   */
+  getTransportHealth(): TransportHealth | null {
+    if (!this.engine) return null;
+    return this.engine.getTransportHealth();
+  }
+
+  /**
+   * Get computed sync progress across subscriptions.
+   */
+  async getProgress(): Promise<SyncProgress | null> {
+    if (!this.engine) return null;
+    return this.engine.getProgress();
+  }
+
+  /**
+   * Get a diagnostics snapshot for support/debug flows.
+   */
+  async getDiagnostics(): Promise<SyncDiagnostics | null> {
+    if (!this.engine) return null;
+    return this.engine.getDiagnostics();
+  }
+
+  /**
+   * Get a serializable inspector snapshot for in-app debug tooling.
+   */
+  async getInspectorSnapshot(
+    options?: SyncInspectorOptions
+  ): Promise<SyncInspectorSnapshot | null> {
+    if (!this.engine) return null;
+    return this.engine.getInspectorSnapshot(options);
+  }
+
+  /**
+   * Reset local sync metadata (and optionally synced app rows/outbox/conflicts).
+   */
+  async reset(options: SyncResetOptions): Promise<SyncResetResult> {
+    if (!this.engine) {
+      return {
+        deletedSubscriptionStates: 0,
+        deletedOutboxCommits: 0,
+        deletedConflicts: 0,
+        clearedTables: [],
+      };
+    }
+    return this.engine.reset(options);
+  }
+
+  /**
+   * Run a built-in repair flow for common corruption scenarios.
+   */
+  async repair(options: SyncRepairOptions): Promise<SyncResetResult> {
+    if (!this.engine) {
+      return {
+        deletedSubscriptionStates: 0,
+        deletedOutboxCommits: 0,
+        deletedConflicts: 0,
+        clearedTables: [],
+      };
+    }
+    return this.engine.repair(options);
+  }
+
+  /**
+   * Wait until the channel reaches a target phase.
+   */
+  async awaitPhase(
+    phase: SyncProgress['channelPhase'],
+    options: SyncAwaitPhaseOptions = {}
+  ): Promise<SyncProgress | null> {
+    if (!this.engine) return null;
+    return this.engine.awaitPhase(phase, options);
+  }
+
+  /**
+   * Wait until bootstrap completes for the default state or a specific subscription.
+   */
+  async awaitBootstrapComplete(
+    options: SyncAwaitBootstrapOptions = {}
+  ): Promise<SyncProgress | null> {
+    if (!this.engine) return null;
+    return this.engine.awaitBootstrapComplete(options);
+  }
+
   /**
    * Subscribe to state changes (for useSyncExternalStore).
    */
@@ -783,6 +925,10 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       });
     });
 
+    this.engine.on('sync:live', (payload) => {
+      this.emit('sync:live', payload);
+    });
+
     this.engine.on('sync:error', (error) => {
       this.emit('sync:error', { code: error.code, message: error.message });
 
@@ -790,6 +936,18 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       this.checkForNewConflicts();
     });
 
+    this.engine.on('bootstrap:start', (payload) => {
+      this.emit('bootstrap:start', payload);
+    });
+
+    this.engine.on('bootstrap:progress', (payload) => {
+      this.emit('bootstrap:progress', payload);
+    });
+
+    this.engine.on('bootstrap:complete', (payload) => {
+      this.emit('bootstrap:complete', payload);
+    });
+
     this.engine.on('connection:change', (payload) => {
       this.emit('connection:change', payload);
     });

package/src/engine/SyncEngine.test.ts

@@ -154,4 +154,43 @@ describe('SyncEngine WS inline apply', () => {
       .executeTakeFirstOrThrow();
     expect(state.cursor).toBe(0);
   });
+
+  it('returns a bounded inspector snapshot with serializable events', async () => {
+    const handlers = new ClientTableRegistry<TestDb>().register({
+      table: 'tasks',
+      async applySnapshot() {},
+      async clearAll() {},
+      async applyChange() {},
+    });
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-inspector',
+      subscriptions: [],
+      stateId: 'default',
+    });
+
+    await engine.start();
+    await engine.sync();
+
+    const snapshot = await engine.getInspectorSnapshot({ eventLimit: 5 });
+
+    expect(snapshot.version).toBe(1);
+    expect(snapshot.generatedAt).toBeGreaterThan(0);
+    expect(snapshot.recentEvents.length).toBeLessThanOrEqual(5);
+    expect(snapshot.recentEvents.length).toBeGreaterThan(0);
+
+    const first = snapshot.recentEvents[0];
+    if (!first) {
+      throw new Error('Expected at least one inspector event');
+    }
+    expect(typeof first.id).toBe('number');
+    expect(typeof first.event).toBe('string');
+    expect(typeof first.timestamp).toBe('number');
+    expect(typeof first.payload).toBe('object');
+    expect(snapshot.diagnostics).toBeDefined();
+  });
 });