@fairfox/polly 0.58.0 → 0.59.0

package/dist/src/shared/lib/mesh-client.d.ts

@@ -23,6 +23,7 @@ import { Repo, type StorageAdapterInterface } from "@automerge/automerge-repo/sl
 import type { KeyringStorage } from "./keyring-storage";
 import { type MeshKeyring, MeshNetworkAdapter } from "./mesh-network-adapter";
 import { MeshSignalingClient, type MeshSignalingClientOptions } from "./mesh-signaling-client";
+import { type MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
 import { MeshWebRTCAdapter, type MeshWebRTCAdapterOptions } from "./mesh-webrtc-adapter";
 /** Options for {@link createMeshClient}. */
 export interface CreateMeshClientOptions {
@@ -232,6 +233,28 @@ export interface MeshStateModuleDiagnostics {
      * true` (they're using a module instance no mesh client ever
      * configured). */
     wasResolved: boolean;
+    /** Polly#107 post-H5 instrumentation. Count of `$meshState`-family
+     * lazy factory invocations since module load. Once the consumer's
+     * pre-warm pass completes, this equals the number of distinct
+     * `$mesh*` wrappers whose handles the loader actually tried to
+     * resolve. Compared to {@link lazyReachedRepo}: gap = throws
+     * before any Repo work. */
+    lazyInvocations: number;
+    /** Polly#107 post-H5 instrumentation. Count of factory invocations
+     * that reached the Repo subsystem (`repo.handles[...]`, `repo.find`
+     * or `repo.import`) before returning or throwing. If
+     * {@link lazyInvocations} is N and this is N, every wrapper
+     * touched the Repo — any missing handles are downstream of Repo
+     * registration. If this is < N, the gap is the call site to
+     * instrument next. */
+    lazyReachedRepo: number;
+    /** Polly#107 post-H5 instrumentation. Breadcrumb for the most
+     * recent rejection from a `$meshState`-family `loaded` promise
+     * (or its factory). Captured even when the consumer's wrapper
+     * never awaits `loaded` and the rejection would otherwise vanish
+     * silently. `undefined` means no rejection has escaped any
+     * wrapper on THIS module instance since module load. */
+    lastLoadedRejection: MeshStateLoadedRejectionBreadcrumb | undefined;
 }
 /** The mesh client's enriched per-peer state snapshot. Mirrors the
  * underlying {@link MeshWebRTCAdapter.getPeerStateSnapshot} shape but

package/dist/src/shared/lib/mesh-state.d.ts

@@ -113,6 +113,33 @@ export declare function isMeshStateConfigured(): boolean;
  * called against this module instance. See
  * {@link meshStateEverResolved}. */
 export declare function wasMeshStateResolved(): boolean;
+/** Returns the count of factory invocations since module load. See
+ * {@link lazyInvocations}. */
+export declare function getLazyInvocations(): number;
+/** Returns the count of factory invocations that reached
+ * `repo.find` / `repo.import` since module load. See
+ * {@link lazyReachedRepo}. */
+export declare function getLazyReachedRepo(): number;
+/** Polly#107 post-H5 instrumentation. Records the most recent
+ * rejection (or synchronous throw) escaping the factory body — the
+ * `loaded` promise's rejection path. Today an unawaited rejection
+ * inside a consumer wrapper vanishes without trace; capturing the
+ * message + stack here on the module and exposing it via the
+ * snapshot leaves a breadcrumb the operator can read in one paste.
+ *
+ * The format is the JSON-safe `{ name, message, stack, at }` shape
+ * so the snapshot read does not have to traffic in `Error`
+ * instances. `at` is `Date.now()` at the time the rejection was
+ * captured. */
+export interface MeshStateLoadedRejectionBreadcrumb {
+    name: string;
+    message: string;
+    stack: string | undefined;
+    at: number;
+}
+/** Returns the most recent rejection escaping a `$meshState` factory
+ * invocation since module load. See {@link lastLoadedRejection}. */
+export declare function getLastLoadedRejection(): MeshStateLoadedRejectionBreadcrumb | undefined;
 /**
  * Create a peer-replicated state primitive backed by Automerge with a mesh
  * transport. Every device holds a full replica; no central server holds a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",