@sweidos/eidos 2.2.0 → 2.3.1

package/README.md

@@ -139,15 +139,15 @@ if ('queued' in result) {
 | -------------------------- | ----------------------------- | -------------------------------------------------------------- |
 | **React**                  | `@sweidos/eidos`              | Hooks + `EidosProvider`                                        |
 | **Next.js App Router**     | `@sweidos/eidos/nextjs`       | Pre-marked `'use client'` — no wrapper needed                  |
-| **Next.js Server Actions** | `@eidos/next`                 | `serverAction()` neverLose wrapper + idempotency context       |
+| **Next.js Server Actions** | `@sweidos/next`               | `serverAction()` neverLose wrapper + idempotency context       |
 | **SvelteKit**              | `@sweidos/eidos/sveltekit`    | `initEidosSvelteKit()` in `onMount`, framework-agnostic stores |
 | **Vue**                    | `@sweidos/eidos`              | Framework-agnostic stores via `eidosStatus.subscribe()`        |
 | **React Native**           | `@sweidos/eidos/react-native` | AsyncStorage-backed queue, same `action()` API                 |
 | **Vanilla JS**             | `@sweidos/eidos`              | `eidosStatus`, `eidosQueue`, `eidosQueueStats` stores          |
 | **Vite**                   | `@sweidos/eidos/vite`         | Plugin auto-copies `eidos-sw.js` on every build                |
-| **CRDT merge (Yjs)**       | `@eidos/crdt-yjs`             | `createYjsMergeResolver()` for `conflict.strategy: 'merge'`    |
+| **CRDT merge (Yjs)**       | `@sweidos/crdt-yjs`           | `createYjsMergeResolver()` for `conflict.strategy: 'merge'`    |
 | **TanStack Query**         | `@sweidos/eidos/query`        | `useEidosQuery`, `useEidosMutation`, `withEidosQueryClient`    |
-| **Tauri / Electron**       | `@eidos/sqlite-storage`       | SQLite-backed `QueueStorage`, same `action()` API              |
+| **Tauri / Electron**       | `@sweidos/sqlite-storage`     | SQLite-backed `QueueStorage`, same `action()` API              |
 
 ---
 
@@ -162,10 +162,15 @@ const products = resource('/api/products', {
   offline: true,      // enable SW interception + caching
   strategy?: 'cache-first' | 'stale-while-revalidate' | 'network-first',
   cacheName?: string, // custom cache bucket
-  maxAge?: number,    // TTL in ms — re-fetch after expiry
+  maxAge?: number,    // TTL in ms — enforced by the SW on all requests (not just handle.fetch())
+  maxEntries?: number, // max cache entries; oldest evicted (FIFO) when exceeded
+  networkTimeoutMs?: number, // ms before falling back to cache (network-first & SWR). Default: 3000
   version?: string | number, // bump when the response shape changes —
                               // appended to cacheName (e.g. 'eidos-resources-v1-v2')
-                              // so old-shaped cache entries aren't served
+                              // so old-shaped cache entries aren't served.
+                              // NOTE: this is separate from the SW-internal CACHE_VERSION
+                              // (bumped only on Eidos releases to purge old cache buckets).
+                              // Bump `version` for your data shape; Eidos bumps CACHE_VERSION.
 })
 
 await products.fetch()          // Promise<Response>
@@ -197,6 +202,19 @@ await productPattern.invalidate(); // clear all cached entries matching the patt
 productPattern.unregister();
 ```
 
+| Token    | Matches                                                      |
+| -------- | ------------------------------------------------------------ |
+| `*`      | One path segment — `/api/products/*` ↔ `/api/products/4`     |
+| `**`     | Any number of segments — `https://cdn.example.com/assets/**` |
+| `:param` | A named segment — `/api/users/:id/orders`                    |
+
+Pass the full URL (including origin) for cross-origin resources, e.g.
+`resourcePattern('https://cdn.example.com/assets/**', { offline: true })`.
+
+See it live in the [playground docs → Examples → URL patterns, one
+registration per
+family](https://sweidos.vercel.app/docs/examples#url-patterns-one-registration-per-family).
+
 ### `action(fn, config)`
 
 ```ts
@@ -226,6 +244,62 @@ await cancelByIdempotencyKey(idempotencyKey) // true if cancelled/removed
 await requeueItem(queueItemId)               // true if it was 'failed'
 ```
 
+### Conflict resolution
+
+A `neverLose` action can sit in the queue for a while — by the time it
+replays, the world may have moved on (the requested stock sold out, the
+record was deleted, etc.). `conflict` decides what happens when a replay gets
+a 4xx response, instead of retrying forever or silently dropping the write:
+
+```ts
+class StockConflictError extends Error {
+  status = 409;
+  constructor(public available: number) {
+    super('insufficient stock');
+  }
+}
+
+export const reserveStock = action(
+  async (payload: { productId: number; quantity: number }) => {
+    const res = await fetch('/api/inventory', {
+      method: 'POST',
+      body: JSON.stringify(payload),
+    });
+    if (res.status === 409) {
+      const { available } = await res.json();
+      throw new StockConflictError(available);
+    }
+    if (!res.ok) throw new Error('Reservation failed');
+    return res.json();
+  },
+  {
+    reliability: 'neverLose',
+    name: 'reserveStock',
+    conflict: {
+      strategy: 'custom',
+      resolve: ({ error, args, attempt }) => {
+        if (error instanceof StockConflictError && error.available > 0) {
+          const [payload] = args;
+          // Rewrite the queued args and retry with what's actually available
+          return { resolved: [{ ...payload, quantity: error.available }] };
+        }
+        return 'skip'; // nothing left to reserve — drop the write
+      },
+    },
+  },
+);
+```
+
+| Strategy     | Behavior on 4xx replay                                                |
+| ------------ | --------------------------------------------------------------------- |
+| `serverWins` | Drop the queued item — the server's current state is authoritative.   |
+| `clientWins` | Keep retrying — the write should eventually succeed.                  |
+| `merge`      | Call `resolve(ctx)`; typically used to combine client + server state. |
+| `custom`     | Call `resolve(ctx)`; return `'retry'`, `'skip'`, or `{ resolved }`.   |
+
+See it live in the [playground docs → Examples → Conflict resolution on
+replay](https://sweidos.vercel.app/docs/examples#conflict-resolution-on-replay).
+
 ### React hooks
 
 ```ts
@@ -266,6 +340,86 @@ initEidos({
 The same counters are visible live in `<EidosDevtools />` under the
 "Reliability" tab.
 
+### Handling SW updates
+
+By default, when a new service worker is available it activates immediately
+(`skipWaiting: true`). This matches standard PWA behaviour but can interrupt
+in-flight requests on pages that are mid-navigation.
+
+Opt into the **toast-then-reload** pattern with `skipWaiting: false`:
+
+```ts
+import { initEidos, triggerSwUpdate } from '@sweidos/eidos';
+
+initEidos({
+  skipWaiting: false,
+  onUpdateAvailable: (_registration) => {
+    // Show a toast, banner, or dialog — then call triggerSwUpdate() when the
+    // user confirms they're ready to reload.
+    showToast({
+      message: 'App update ready',
+      action: { label: 'Reload', onClick: triggerSwUpdate },
+    });
+  },
+});
+```
+
+`triggerSwUpdate()` tells the waiting service worker to activate, then the
+browser reloads the page. With `skipWaiting: true` (default) `onUpdateAvailable`
+is never called and `triggerSwUpdate()` is not needed.
+
+> **Tip**: avoid calling `triggerSwUpdate()` while `neverLose` actions are
+> mid-replay. The replay coordination (BroadcastChannel + Web Locks) survives
+> SW activation, but triggering an update during an active replay pass adds
+> unnecessary churn. Wait until the queue drains or use `waitForQueueDrain()`
+> from `@sweidos/eidos/testing` in tests.
+
+### Queue management
+
+Inspect and manage the offline action queue directly — handy for "pending
+changes" panels, manual retry buttons, or a "discard my offline edits" action:
+
+```ts
+import {
+  useEidosQueue,
+  cancelByIdempotencyKey,
+  requeueItem,
+  clearQueue,
+  replayQueue,
+} from '@sweidos/eidos';
+
+function QueuePanel() {
+  const queue = useEidosQueue(); // live list of pending/replaying/failed items
+
+  return queue.map((item) => (
+    <li key={item.id}>
+      {item.actionName} — {item.status}
+
+      {/* Drop a write before it ever reaches the server */}
+      {item.status === 'pending' && (
+        <button onClick={() => cancelByIdempotencyKey(item.idempotencyKey)}>
+          Cancel
+        </button>
+      )}
+
+      {/* Reset a failed item to 'pending' and replay it */}
+      {item.status === 'failed' && (
+        <button onClick={() => requeueItem(item.id)}>Retry</button>
+      )}
+    </li>
+  ));
+}
+
+// Drop every queued write — e.g. on "discard offline changes"
+await clearQueue();
+
+// Force a replay pass — normally triggered automatically on reconnect
+await replayQueue();
+```
+
+See it live in the [playground docs → Examples → Queue management &
+reliability stats](https://sweidos.vercel.app/docs/examples#queue-management-reliability-stats).
+
 ---
 
 ## TanStack Query
@@ -365,6 +519,10 @@ for client-side routing; otherwise the SW opens `data.url` directly.
 
 ## Testing
 
+`@sweidos/eidos/testing` runs entirely at the JS layer — no real Service
+Worker needed — and gives Vitest/Jest/Playwright direct control over online
+state, the action queue, and the resource cache.
+
 ```ts
 import {
   mockOffline,
@@ -380,29 +538,82 @@ import {
 beforeEach(() => resetEidos());
 
 it('queues action while offline', async () => {
-  mockOffline();
-  await createOrder({ productId: 1, qty: 2 });
+  mockOffline({ stubFetch: true });
+  await createOrder({ productId: 1, quantity: 2 });
   expect(getEidosState().queue).toHaveLength(1);
+  expect(getEidosState().queue[0].actionName).toBe('createOrder');
 });
 
 it('replays on reconnect', async () => {
   mockOffline();
-  await createOrder({ productId: 1, qty: 2 });
+  await createOrder({ productId: 1, quantity: 2 });
+
+  // Forces isOnline = true and replays immediately
   const result = await drainQueue();
   expect(result.succeeded).toBe(1);
+
+  // ...or for code that replays itself on the 'online' event:
+  await waitForQueueDrain({ timeout: 2000 });
+  expect(getEidosState().queue).toHaveLength(0);
 });
+
+it('caches GET responses for offline use', async () => {
+  await products.json();
+  const cached = await getCachedEntry('/api/products');
+  expect(cached).toBeDefined();
+});
+
+afterEach(() => clearEidosCache());
 ```
 
 ---
 
 ## OpenAPI codegen
 
+`eidos-gen` reads an OpenAPI 3.x spec (JSON or YAML) and writes typed
+`resource()` + `action()` declarations — request/response interfaces from
+`$ref` schemas, `{id}` → `:id` path-param conversion, and DELETE body
+omission.
+
 ```bash
-npx eidos-gen openapi.json
-# → writes eidos.generated.ts with typed resource() + action() declarations
+npx eidos-gen openapi.json --out src/lib/eidos.generated.ts
+
+eidos-gen: reading openapi.json
+eidos-gen: wrote src/lib/eidos.generated.ts
+           2 resource(s), 2 action(s)
+           2 type(s)
 ```
 
-Handles path params, `$ref` resolution, request/response types, DELETE body omission.
+```ts
+// eidos.generated.ts
+import { resource, action } from '@sweidos/eidos';
+
+export interface Product {
+  id: number;
+  name: string;
+  tags?: string[];
+}
+
+export const listProducts = resource('/products', { offline: true });
+
+export const createProduct = action(
+  async (payload: Product): Promise<Product> => {
+    const res = await fetch('/products', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    return res.json();
+  },
+  { reliability: 'neverLose', name: 'createProduct' },
+);
+```
+
+| Flag           | Effect                                                       |
+| -------------- | ------------------------------------------------------------ |
+| `--out, -o`    | Output file path (default: `eidos.generated.ts`)             |
+| `--no-offline` | Set `offline: false` on every generated `resource()`         |
+| `--eidos`      | Import path for `@sweidos/eidos` (default: `@sweidos/eidos`) |
 
 ---
 
@@ -419,21 +630,56 @@ import { EidosDevtools } from '@sweidos/eidos/devtools';
 
 Panel shows: live queue state · cache entries · SW status · offline simulation toggle.
 
+### `eidosDebug()`
+
+Returns a plain-object snapshot of the full Eidos runtime state — safe to `JSON.stringify`, useful for bug reports or attaching to error-tracking breadcrumbs:
+
+```ts
+import { eidosDebug } from '@sweidos/eidos';
+
+// Print for a bug report
+console.log(JSON.stringify(eidosDebug(), null, 2));
+
+// Attach to a Sentry breadcrumb
+Sentry.addBreadcrumb({ data: eidosDebug() });
+```
+
+Snapshot includes: `version`, `swStatus`, `isOnline`, `resourceCount`, `resources` (per-URL status/hits/cachedAt), `queue` (item list with idempotencyKey/retryCount), `reliability` counters, and `swRegistration` state.
+
+---
+
+## Troubleshooting
+
+Eidos emits plain-English `console.warn` messages in development (`import.meta.env.DEV`) for common setup problems:
+
+| Warning                                             | Cause                                        | Fix                                                                                                                             |
+| --------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `Service workers require a secure context`          | `initEidos()` called on HTTP (non-localhost) | Use `localhost` for dev or deploy to HTTPS                                                                                      |
+| `Service worker file not found at "/eidos-sw.js"`   | SW file missing from `public/`               | Add `eidos()` to `vite.config.ts` plugins, or copy `node_modules/@sweidos/eidos/dist/eidos-sw.js → public/eidos-sw.js` manually |
+| `Service worker registration failed: …`             | Unexpected registration error                | Check `eidosDebug().swError` for the full browser error message                                                                 |
+| `Service workers are not supported in this context` | Old browser, or SW API absent                | No fix needed — Eidos degrades gracefully; only SW-side caching is disabled                                                     |
+
+**[→ Getting started guide](docs/guides/getting-started.md)** — zero-jargon walkthrough: install → Vite plugin → wrap app → first resource + action → offline status UI.
+
+**[→ Full troubleshooting guide](docs/guides/troubleshooting.md)** — per-warning copy-pasteable fixes, runtime issues (stuck SW, maxAge, networkTimeoutMs), and `eidosDebug()` field reference.
+
+**[→ Glossary](docs/guides/glossary.md)** — plain-language definitions of service worker, cache strategy, idempotency key, replay queue, and more.
+
 ---
 
 ## SSR adapters
 
 **Next.js** — import from `@sweidos/eidos/nextjs`. Pre-marked `'use client'`, works in App Router layouts without a wrapper.
 
-**Next.js Server Actions** — `@eidos/next`'s `serverAction()` wraps a `'use server'` function with `action()` (`reliability: 'neverLose'` by default), keyed by `config.name` + `config.namespace`. `getActionContext()` / `idempotencyHeaders()` recover the `idempotencyKey`/`attempt` inside the action body.
+**Next.js Server Actions** — `@sweidos/next`'s `serverAction()` wraps a `'use server'` function with `action()` (`reliability: 'neverLose'` by default), keyed by `config.name` + `config.namespace`. `getActionContext()` / `idempotencyHeaders()` recover the `idempotencyKey`/`attempt` inside the action body.
 
 **SvelteKit** — `initEidosSvelteKit()` inside `onMount`. Framework-agnostic stores (`$eidosQueue`, `$eidosStatus`) work with Svelte's `$` auto-subscribe.
 
 **React Native** — `@sweidos/eidos/react-native` with AsyncStorage-backed queue. Same `action()` API surface, no Service Worker dependency.
 
-**Tauri / Electron** — `@eidos/sqlite-storage` with a SQLite-backed `QueueStorage`. Pass a `@tauri-apps/plugin-sql` `Database` directly, or wrap `better-sqlite3` with the `SqliteLike` interface. Same `action()` API surface, no Service Worker dependency.
+**Tauri / Electron** — `@sweidos/sqlite-storage` with a SQLite-backed `QueueStorage`. Pass a `@tauri-apps/plugin-sql` `Database` directly, or wrap `better-sqlite3` with the `SqliteLike` interface. Same `action()` API surface, no Service Worker dependency.
 
-**CRDT merge (Yjs)** — `@eidos/crdt-yjs`'s `createYjsMergeResolver()` builds a `conflict.resolve` for the `'merge'`/`'custom'` strategy that applies the server's Yjs state and the queued local update to a `Y.Doc`, then rewrites the queued args with the merged update — automatic, loss-free reconciliation of concurrent edits instead of a hand-written `resolve()`.
+**CRDT merge (Yjs)** — `@sweidos/crdt-yjs`'s `createYjsMergeResolver()` builds a `conflict.resolve` for the `'merge'`/`'custom'` strategy that applies the server's Yjs state and the queued local update to a `Y.Doc`, then rewrites the queued args with the merged update — automatic, loss-free reconciliation of concurrent edits instead of a hand-written `resolve()`.
 
 ---
 
@@ -457,7 +703,7 @@ Panel shows: live queue state · cache entries · SW status · offline simulatio
 | Offline writes        | IndexedDB queue, auto-replay + backoff via `action()` | Background Sync, you wire it | No built-in mutation queue |
 | Framework support     | React, Svelte, Vue, Next.js, React Native, vanilla JS | Framework-agnostic (SW only) | Per-library                |
 | TanStack Query bridge | `@sweidos/eidos/query` adapter                        | —                            | Native                     |
-| Bundle size (core)    | ~6.5 kB brotli                                        | ~3-6 kB (modular)            | ~13 kB                     |
+| Bundle size (core)    | ~6.7 kB brotli                                        | ~3-6 kB (modular)            | ~13 kB                     |
 
 Not a TanStack Query replacement — `@sweidos/eidos/query` is a thin adapter so
 you keep TQ's cache/devtools while Eidos owns the offline layer. Workbox is a

package/dist/action.d.ts

@@ -0,0 +1,22 @@
+import { ActionConfig, ActionHandle, ActionFn, ReplayResult } from './types';
+export declare function action<TArgs extends any[], TReturn>(fn: ActionFn<TArgs, TReturn>, config: ActionConfig<TArgs>): ActionHandle<TArgs, TReturn>;
+/**
+ * Cancel an invocation by its `idempotencyKey` (from `ActionContext` /
+ * `onOptimistic`). Aborts the in-flight call if `cancellable: true` and
+ * still running, otherwise removes a not-yet-replayed queued item.
+ * Returns `true` if something was cancelled/removed.
+ *
+ * Shared by every `ActionHandle.cancel()` and by devtools, which can't
+ * address a specific handle from a queue item alone.
+ */
+export declare function cancelByIdempotencyKey(idempotencyKey: string): Promise<boolean>;
+/**
+ * Reset a `'failed'` queue item back to `'pending'` so the next
+ * `replayQueue()` retries it — clears `error`/`nextRetryAt` and resets
+ * `retryCount` to 0. Returns `true` if the item existed and was failed.
+ * Used by devtools' per-item "Retry" action.
+ */
+export declare function requeueItem(id: string): Promise<boolean>;
+export declare function replayQueue(): Promise<ReplayResult>;
+/** Remove all items from the action queue (storage + in-memory store). */
+export declare function clearQueue(): Promise<void>;

package/dist/async-storage-adapter.d.ts

@@ -0,0 +1,25 @@
+import { ActionQueueItem } from './types';
+import { QueueStorage } from './queue-storage';
+/** Minimal subset of @react-native-async-storage/async-storage (or any compatible key-value store). */
+export interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * QueueStorage implementation backed by any AsyncStorage-compatible API.
+ * Pass the AsyncStorage singleton from @react-native-async-storage/async-storage
+ * (or MMKV, SQLite, or any store that satisfies AsyncStorageLike).
+ */
+export declare class AsyncStorageQueueStorage implements QueueStorage {
+    private readonly storage;
+    constructor(storage: AsyncStorageLike);
+    private readAll;
+    private writeAll;
+    add(item: ActionQueueItem): Promise<void>;
+    getAll(): Promise<ActionQueueItem[]>;
+    getPending(): Promise<ActionQueueItem[]>;
+    update(id: string, patch: Partial<ActionQueueItem>): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/debug.d.ts

@@ -0,0 +1,46 @@
+import { ReliabilityStats } from './types';
+export interface EidosDebugSnapshot {
+    version: string;
+    swStatus: string;
+    swError?: string;
+    isOnline: boolean;
+    resourceCount: number;
+    resources: Record<string, {
+        url: string;
+        strategy: string;
+        status: string;
+        cacheHits: number;
+        cacheMisses: number;
+        cachedAt?: number;
+    }>;
+    queue: {
+        id: string;
+        actionId: string;
+        actionName: string;
+        status: string;
+        retryCount: number;
+        maxRetries: number;
+        idempotencyKey: string;
+        schemaVersion: number;
+        queuedAt: number;
+    }[];
+    reliability: ReliabilityStats;
+    swRegistration: {
+        scope: string;
+        scriptURL: string;
+        state: 'installing' | 'waiting' | 'active' | null;
+    } | null;
+}
+/**
+ * Returns a plain-object snapshot of the current Eidos runtime state.
+ * Safe to serialize with `JSON.stringify`. Useful for bug reports,
+ * attaching to error tracking breadcrumbs, and the devtools SW tab.
+ *
+ * @example
+ * // Print for a bug report:
+ * console.log(JSON.stringify(eidosDebug(), null, 2));
+ *
+ * // Attach to a Sentry breadcrumb:
+ * Sentry.addBreadcrumb({ data: eidosDebug() });
+ */
+export declare function eidosDebug(): EidosDebugSnapshot;

package/dist/debug.js

@@ -0,0 +1,43 @@
+import { useEidosStore as a } from "./store.js";
+import { getSwRegistration as r } from "./sw-bridge.js";
+import { VERSION as c } from "./version.js";
+function l() {
+  const t = a.getState(), s = r();
+  return {
+    version: c,
+    swStatus: t.swStatus,
+    ...t.swError !== void 0 && { swError: t.swError },
+    isOnline: t.isOnline,
+    resourceCount: Object.keys(t.resources).length,
+    resources: Object.fromEntries(Object.entries(t.resources).map(([e, i]) => [e, {
+      url: i.url,
+      strategy: i.strategy.swStrategy,
+      status: i.status,
+      cacheHits: i.cacheHits,
+      cacheMisses: i.cacheMisses,
+      ...i.cachedAt !== void 0 && { cachedAt: i.cachedAt }
+    }])),
+    queue: t.queue.map((e) => ({
+      id: e.id,
+      actionId: e.actionId,
+      actionName: e.actionName,
+      status: e.status,
+      retryCount: e.retryCount,
+      maxRetries: e.maxRetries,
+      idempotencyKey: e.idempotencyKey,
+      schemaVersion: e.schemaVersion,
+      queuedAt: e.queuedAt
+    })),
+    reliability: { ...t.reliability },
+    swRegistration: s ? {
+      scope: s.scope,
+      scriptURL: (s.active ?? s.waiting ?? s.installing)?.scriptURL ?? "",
+      state: s.installing ? "installing" : s.waiting ? "waiting" : s.active ? "active" : null
+    } : null
+  };
+}
+export {
+  l as eidosDebug
+};
+
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","names":[],"sources":["../src/debug.ts"],"sourcesContent":["import { useEidosStore } from './store';\nimport { getSwRegistration } from './sw-bridge';\nimport { VERSION } from './version';\nimport type { ReliabilityStats } from './types';\n\nexport interface EidosDebugSnapshot {\n  version: string;\n  swStatus: string;\n  swError?: string;\n  isOnline: boolean;\n  resourceCount: number;\n  resources: Record<\n    string,\n    {\n      url: string;\n      strategy: string;\n      status: string;\n      cacheHits: number;\n      cacheMisses: number;\n      cachedAt?: number;\n    }\n  >;\n  queue: {\n    id: string;\n    actionId: string;\n    actionName: string;\n    status: string;\n    retryCount: number;\n    maxRetries: number;\n    idempotencyKey: string;\n    schemaVersion: number;\n    queuedAt: number;\n  }[];\n  reliability: ReliabilityStats;\n  swRegistration: {\n    scope: string;\n    scriptURL: string;\n    state: 'installing' | 'waiting' | 'active' | null;\n  } | null;\n}\n\n/**\n * Returns a plain-object snapshot of the current Eidos runtime state.\n * Safe to serialize with `JSON.stringify`. Useful for bug reports,\n * attaching to error tracking breadcrumbs, and the devtools SW tab.\n *\n * @example\n * // Print for a bug report:\n * console.log(JSON.stringify(eidosDebug(), null, 2));\n *\n * // Attach to a Sentry breadcrumb:\n * Sentry.addBreadcrumb({ data: eidosDebug() });\n */\nexport function eidosDebug(): EidosDebugSnapshot {\n  const state = useEidosStore.getState();\n  const swReg = getSwRegistration();\n\n  return {\n    version: VERSION,\n    swStatus: state.swStatus,\n    ...(state.swError !== undefined && { swError: state.swError }),\n    isOnline: state.isOnline,\n    resourceCount: Object.keys(state.resources).length,\n    resources: Object.fromEntries(\n      Object.entries(state.resources).map(([url, entry]) => [\n        url,\n        {\n          url: entry.url,\n          strategy: entry.strategy.swStrategy,\n          status: entry.status,\n          cacheHits: entry.cacheHits,\n          cacheMisses: entry.cacheMisses,\n          ...(entry.cachedAt !== undefined && { cachedAt: entry.cachedAt }),\n        },\n      ]),\n    ),\n    queue: state.queue.map((item) => ({\n      id: item.id,\n      actionId: item.actionId,\n      actionName: item.actionName,\n      status: item.status,\n      retryCount: item.retryCount,\n      maxRetries: item.maxRetries,\n      idempotencyKey: item.idempotencyKey,\n      schemaVersion: item.schemaVersion,\n      queuedAt: item.queuedAt,\n    })),\n    reliability: { ...state.reliability },\n    swRegistration: swReg\n      ? {\n          scope: swReg.scope,\n          scriptURL: (swReg.active ?? swReg.waiting ?? swReg.installing)?.scriptURL ?? '',\n          state: swReg.installing\n            ? 'installing'\n            : swReg.waiting\n              ? 'waiting'\n              : swReg.active\n                ? 'active'\n                : null,\n        }\n      : null,\n  };\n}\n"],"mappings":";;;AAqDA,SAAgB,IAAiC;AAC/C,QAAM,IAAQ,EAAc,SAAS,GAC/B,IAAQ,EAAkB;AAEhC,SAAO;AAAA,IACL,SAAS;AAAA,IACT,UAAU,EAAM;AAAA,IAChB,GAAI,EAAM,YAAY,UAAa,EAAE,SAAS,EAAM,QAAQ;AAAA,IAC5D,UAAU,EAAM;AAAA,IAChB,eAAe,OAAO,KAAK,EAAM,SAAS,EAAE;AAAA,IAC5C,WAAW,OAAO,YAChB,OAAO,QAAQ,EAAM,SAAS,EAAE,IAAA,CAAK,CAAC,GAAK,CAAA,MAAW,CACpD,GACA;AAAA,MACE,KAAK,EAAM;AAAA,MACX,UAAU,EAAM,SAAS;AAAA,MACzB,QAAQ,EAAM;AAAA,MACd,WAAW,EAAM;AAAA,MACjB,aAAa,EAAM;AAAA,MACnB,GAAI,EAAM,aAAa,UAAa,EAAE,UAAU,EAAM,SAAS;AAAA,IACjE,CACF,CAAC,CACH;AAAA,IACA,OAAO,EAAM,MAAM,IAAA,CAAK,OAAU;AAAA,MAChC,IAAI,EAAK;AAAA,MACT,UAAU,EAAK;AAAA,MACf,YAAY,EAAK;AAAA,MACjB,QAAQ,EAAK;AAAA,MACb,YAAY,EAAK;AAAA,MACjB,YAAY,EAAK;AAAA,MACjB,gBAAgB,EAAK;AAAA,MACrB,eAAe,EAAK;AAAA,MACpB,UAAU,EAAK;AAAA,IACjB,EAAE;AAAA,IACF,aAAa,EAAE,GAAG,EAAM,YAAY;AAAA,IACpC,gBAAgB,IACZ;AAAA,MACE,OAAO,EAAM;AAAA,MACb,YAAY,EAAM,UAAU,EAAM,WAAW,EAAM,aAAa,aAAa;AAAA,MAC7E,OAAO,EAAM,aACT,eACA,EAAM,UACJ,YACA,EAAM,SACJ,WACA;AAAA,IACV,IACA;AAAA,EACN;AACF"}