@syncular/react 0.15.16 → 0.15.17

package/README.md

@@ -229,6 +229,10 @@ not need a custom retention effect.
 
 ## Other hooks
 
+- `useDiagnostics({ expectedSubscriptions })` observes the versioned,
+  privacy-safe support snapshot. Native/Worker events trigger a fresh request,
+  preserving expected-but-unregistered intent on every host. Subscription ids
+  must be stable and PHI-free; scopes are not accepted.
 - `useSyncStatus()` observes the status domain without a follow-up read after
   every row change. It includes `availability` and `currentSchemaVersion`;
   `outbox` is local push work, while `syncNeeded` specifically means an inbound
@@ -243,3 +247,52 @@ not need a custom retention effect.
   surfaces for integrations.
 
 The hooks are SSR-safe: no local query runs during server rendering.
+
+### Privacy-safe support view
+
+Use application-owned, stable, PHI-free subscription ids to make missing
+registration distinguishable from a completed zero-row bootstrap. The hook
+refreshes after diagnostics events on direct, Worker, Tauri, and React Native
+hosts while preserving that expected intent:
+
+```tsx
+import { useDiagnostics } from '@syncular/react';
+
+const expectedSubscriptions = [
+  { id: 'membership-security', table: 'facility_memberships' },
+  { id: 'scheduler-window', table: 'surgeries' },
+] as const;
+
+function SyncSupportPanel() {
+  const { snapshot, isLoading, error, refresh } = useDiagnostics({
+    expectedSubscriptions,
+  });
+
+  if (isLoading) return <p>Collecting local sync evidence…</p>;
+  if (error) return <p>Diagnostics unavailable: {error.message}</p>;
+
+  return (
+    <section>
+      <button type="button" onClick={() => void refresh()}>
+        Refresh
+      </button>
+      <button
+        type="button"
+        disabled={!snapshot}
+        onClick={() =>
+          snapshot &&
+          void navigator.clipboard.writeText(JSON.stringify(snapshot, null, 2))
+        }
+      >
+        Copy support snapshot
+      </button>
+      <pre>{JSON.stringify(snapshot, null, 2)}</pre>
+    </section>
+  );
+}
+```
+
+The snapshot deliberately excludes scopes, rows, clinical counts, SQL, paths,
+identities, credentials, mutation bodies, stack traces, and arbitrary prose.
+Do not enrich the copied bundle with database files, query results, or console
+dumps. See SPEC §7.6 for the complete contract.

package/dist/client.d.ts

@@ -11,7 +11,7 @@
  * value → read it) and wraps every result in `Promise.resolve`, so a hook
  * never has to care which core it holds.
  */
-import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SecurityLifecycle, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
+import type { ClientChangeListener, ClientDiagnosticsListener, ClientDiagnosticsRequest, ClientDiagnosticsSnapshot, CommitOutcome, CommitOutcomeQuery, ConflictRecord, InvalidationListener, LeadershipState, LeaseState, LocalDataPurgeInput, LocalDataPurgeResult, MutationInput, PresencePeer, QueryReadSpec, QuerySnapshot, RejectionRecord, ResolveCommitOutcomeInput, SchemaFloor, SecurityLifecycle, SqlRow, SqlValue, SyncStatusSnapshot, WindowBase, WindowState } from '@syncular/client';
 /**
  * The structural union of `SyncClient` and `SyncClientHandle`. Members that
  * diverge are typed as "value or method, sync or promise"; {@link normalizeClient}
@@ -21,6 +21,7 @@ import type { ClientChangeListener, CommitOutcome, CommitOutcomeQuery, ConflictR
 export interface SyncClientLike {
     readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
@@ -37,6 +38,7 @@ export interface SyncClientLike {
     purgeLocalData(input: LocalDataPurgeInput): LocalDataPurgeResult | Promise<LocalDataPurgeResult>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
     statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
     conflicts: readonly ConflictRecord[] | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
     rejections: readonly RejectionRecord[] | (() => readonly RejectionRecord[] | Promise<readonly RejectionRecord[]>);
     commitOutcome(clientCommitId: string): CommitOutcome | undefined | Promise<CommitOutcome | undefined>;
@@ -58,6 +60,7 @@ export interface SyncClientLike {
 export interface NormalizedClient {
     readonly currentSchemaVersion?: number;
     onChange(listener: ClientChangeListener): () => void;
+    onDiagnostics(listener: ClientDiagnosticsListener): () => void;
     onInvalidate(listener: InvalidationListener): () => void;
     onPresence(listener: (scopeKey: string) => void): () => void;
     onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
@@ -74,6 +77,7 @@ export interface NormalizedClient {
     purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
     querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
     statusSnapshot(): Promise<SyncStatusSnapshot>;
+    diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
     conflicts(): Promise<readonly ConflictRecord[]>;
     rejections(): Promise<readonly RejectionRecord[]>;
     commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;

package/dist/client.js

@@ -16,6 +16,7 @@ export function normalizeClient(client) {
             ? { currentSchemaVersion: client.currentSchemaVersion }
             : {}),
         onChange: (listener) => client.onChange(listener),
+        onDiagnostics: (listener) => client.onDiagnostics(listener),
         onInvalidate: (listener) => client.onInvalidate(listener),
         onPresence: (listener) => client.onPresence(listener),
         onLeadershipChange: (listener) => client.onLeadershipChange?.(listener) ?? (() => { }),
@@ -29,6 +30,7 @@ export function normalizeClient(client) {
         purgeLocalData: (input) => Promise.resolve(client.purgeLocalData(input)),
         querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
         statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
+        diagnosticsSnapshot: (request) => Promise.resolve(client.diagnosticsSnapshot(request)),
         conflicts: () => resolveMember(client, 'conflicts'),
         rejections: () => resolveMember(client, 'rejections'),
         commitOutcome: (clientCommitId) => Promise.resolve(client.commitOutcome(clientCommitId)),

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { createSyncClientResource, isSyncClientResource, type SyncClientResource
 export { useReactiveStore, useSyncClient } from './use-client.js';
 export { type UseCommitOutcomesResult, useCommitOutcomes, } from './use-commit-outcomes.js';
 export { type UseConflictsResult, useConflicts } from './use-conflicts.js';
+export { type UseDiagnosticsOptions, type UseDiagnosticsResult, useDiagnostics, } from './use-diagnostics.js';
 export { type SyncTableDescriptor, type UseMutationOptions, type UseMutationResult, type UseTableMutationResult, useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';
 export { type NamedQueryDescriptor, useQuery, } from './use-query.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { createSyncClientResource, isSyncClientResource, } from './resource.js';
 export { useReactiveStore, useSyncClient } from './use-client.js';
 export { useCommitOutcomes, } from './use-commit-outcomes.js';
 export { useConflicts } from './use-conflicts.js';
+export { useDiagnostics, } from './use-diagnostics.js';
 export { useMutation, } from './use-mutation.js';
 export { usePresence } from './use-presence.js';
 export { useQuery, } from './use-query.js';

package/dist/use-diagnostics.d.ts

@@ -0,0 +1,20 @@
+import type { ClientDiagnosticsSnapshot, ExpectedDiagnosticSubscription } from '@syncular/client';
+export interface UseDiagnosticsOptions {
+    /**
+     * Application-owned subscription intent. IDs must be stable and PHI-free;
+     * no scope values are accepted by the diagnostics contract.
+     */
+    readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
+}
+export interface UseDiagnosticsResult {
+    readonly snapshot: ClientDiagnosticsSnapshot | undefined;
+    readonly isLoading: boolean;
+    readonly error: Error | undefined;
+    readonly refresh: () => void;
+}
+/**
+ * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
+ * events are treated as invalidation signals and followed by a fresh request,
+ * so expected-but-unregistered subscriptions remain visible on every host.
+ */
+export declare function useDiagnostics(options?: UseDiagnosticsOptions): UseDiagnosticsResult;

package/dist/use-diagnostics.js

@@ -0,0 +1,44 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSyncClient } from './use-client.js';
+/**
+ * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
+ * events are treated as invalidation signals and followed by a fresh request,
+ * so expected-but-unregistered subscriptions remain visible on every host.
+ */
+export function useDiagnostics(options = {}) {
+    const client = useSyncClient();
+    const requestKey = JSON.stringify(options.expectedSubscriptions ?? []);
+    const request = useMemo(() => {
+        const expectedSubscriptions = JSON.parse(requestKey);
+        return expectedSubscriptions.length === 0 ? {} : { expectedSubscriptions };
+    }, [requestKey]);
+    const generation = useRef(0);
+    const [snapshot, setSnapshot] = useState();
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState();
+    const refresh = useCallback(() => {
+        const current = ++generation.current;
+        setIsLoading(true);
+        void client.diagnosticsSnapshot(request).then((next) => {
+            if (generation.current !== current)
+                return;
+            setSnapshot(next);
+            setError(undefined);
+            setIsLoading(false);
+        }, (reason) => {
+            if (generation.current !== current)
+                return;
+            setError(reason instanceof Error ? reason : new Error(String(reason)));
+            setIsLoading(false);
+        });
+    }, [client, request]);
+    useEffect(() => {
+        const unsubscribe = client.onDiagnostics(refresh);
+        refresh();
+        return () => {
+            generation.current += 1;
+            unsubscribe();
+        };
+    }, [client, refresh]);
+    return { snapshot, isLoading, error, refresh };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.15.16",
+  "version": "0.15.17",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.15.16"
+    "@syncular/client": "0.15.17"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",
-    "@syncular/core": "0.15.16",
-    "@syncular/server": "0.15.16",
+    "@syncular/core": "0.15.17",
+    "@syncular/server": "0.15.17",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/client.ts

@@ -13,6 +13,9 @@
  */
 import type {
   ClientChangeListener,
+  ClientDiagnosticsListener,
+  ClientDiagnosticsRequest,
+  ClientDiagnosticsSnapshot,
   CommitOutcome,
   CommitOutcomeQuery,
   ConflictRecord,
@@ -45,6 +48,7 @@ import type {
 export interface SyncClientLike {
   readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
+  onDiagnostics(listener: ClientDiagnosticsListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
   onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
@@ -73,6 +77,9 @@ export interface SyncClientLike {
     spec: QueryReadSpec,
   ): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
   statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+  diagnosticsSnapshot(
+    request?: ClientDiagnosticsRequest,
+  ): ClientDiagnosticsSnapshot | Promise<ClientDiagnosticsSnapshot>;
   conflicts:
     | readonly ConflictRecord[]
     | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
@@ -133,6 +140,7 @@ function resolveMember<T>(
 export interface NormalizedClient {
   readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
+  onDiagnostics(listener: ClientDiagnosticsListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
   onLeadershipChange(listener: (state: LeadershipState) => void): () => void;
@@ -152,6 +160,9 @@ export interface NormalizedClient {
   purgeLocalData(input: LocalDataPurgeInput): Promise<LocalDataPurgeResult>;
   querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
   statusSnapshot(): Promise<SyncStatusSnapshot>;
+  diagnosticsSnapshot(
+    request?: ClientDiagnosticsRequest,
+  ): Promise<ClientDiagnosticsSnapshot>;
   conflicts(): Promise<readonly ConflictRecord[]>;
   rejections(): Promise<readonly RejectionRecord[]>;
   commitOutcome(clientCommitId: string): Promise<CommitOutcome | undefined>;
@@ -179,6 +190,7 @@ export function normalizeClient(client: SyncClientLike): NormalizedClient {
       ? { currentSchemaVersion: client.currentSchemaVersion }
       : {}),
     onChange: (listener) => client.onChange(listener),
+    onDiagnostics: (listener) => client.onDiagnostics(listener),
     onInvalidate: (listener) => client.onInvalidate(listener),
     onPresence: (listener) => client.onPresence(listener),
     onLeadershipChange: (listener) =>
@@ -195,6 +207,8 @@ export function normalizeClient(client: SyncClientLike): NormalizedClient {
     purgeLocalData: (input) => Promise.resolve(client.purgeLocalData(input)),
     querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
     statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
+    diagnosticsSnapshot: (request) =>
+      Promise.resolve(client.diagnosticsSnapshot(request)),
     conflicts: () => resolveMember(client, 'conflicts'),
     rejections: () => resolveMember(client, 'rejections'),
     commitOutcome: (clientCommitId) =>

package/src/index.ts

@@ -36,6 +36,11 @@ export {
   useCommitOutcomes,
 } from './use-commit-outcomes';
 export { type UseConflictsResult, useConflicts } from './use-conflicts';
+export {
+  type UseDiagnosticsOptions,
+  type UseDiagnosticsResult,
+  useDiagnostics,
+} from './use-diagnostics';
 export {
   type SyncTableDescriptor,
   type UseMutationOptions,

package/src/use-diagnostics.ts

@@ -0,0 +1,75 @@
+import type {
+  ClientDiagnosticsRequest,
+  ClientDiagnosticsSnapshot,
+  ExpectedDiagnosticSubscription,
+} from '@syncular/client';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export interface UseDiagnosticsOptions {
+  /**
+   * Application-owned subscription intent. IDs must be stable and PHI-free;
+   * no scope values are accepted by the diagnostics contract.
+   */
+  readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
+}
+
+export interface UseDiagnosticsResult {
+  readonly snapshot: ClientDiagnosticsSnapshot | undefined;
+  readonly isLoading: boolean;
+  readonly error: Error | undefined;
+  readonly refresh: () => void;
+}
+
+/**
+ * Observe the versioned, privacy-safe diagnostics snapshot. Native/Worker
+ * events are treated as invalidation signals and followed by a fresh request,
+ * so expected-but-unregistered subscriptions remain visible on every host.
+ */
+export function useDiagnostics(
+  options: UseDiagnosticsOptions = {},
+): UseDiagnosticsResult {
+  const client = useSyncClient();
+  const requestKey = JSON.stringify(options.expectedSubscriptions ?? []);
+  const request = useMemo<ClientDiagnosticsRequest>(() => {
+    const expectedSubscriptions = JSON.parse(
+      requestKey,
+    ) as ExpectedDiagnosticSubscription[];
+    return expectedSubscriptions.length === 0 ? {} : { expectedSubscriptions };
+  }, [requestKey]);
+  const generation = useRef(0);
+  const [snapshot, setSnapshot] = useState<
+    ClientDiagnosticsSnapshot | undefined
+  >();
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>();
+
+  const refresh = useCallback(() => {
+    const current = ++generation.current;
+    setIsLoading(true);
+    void client.diagnosticsSnapshot(request).then(
+      (next) => {
+        if (generation.current !== current) return;
+        setSnapshot(next);
+        setError(undefined);
+        setIsLoading(false);
+      },
+      (reason: unknown) => {
+        if (generation.current !== current) return;
+        setError(reason instanceof Error ? reason : new Error(String(reason)));
+        setIsLoading(false);
+      },
+    );
+  }, [client, request]);
+
+  useEffect(() => {
+    const unsubscribe = client.onDiagnostics(refresh);
+    refresh();
+    return () => {
+      generation.current += 1;
+      unsubscribe();
+    };
+  }, [client, refresh]);
+
+  return { snapshot, isLoading, error, refresh };
+}