feat: connectivityProbe + Playwright e2e across Chromium/Firefox/WebKit

Round 3 audit caught two false claims in the README plus a public API
leak. Rather than rewrite the README to be more modest, make the
claims real.

connectivityProbe — captive-portal detection:
  - New FormDraftOptions.connectivityProbe?: () => Promise<boolean>
  - syncQueue calls it before each sync attempt. Falsy/throwing →
    defer without incrementing attempt count. Retry triggers on next
    online/visibilitychange event or user save().
  - Read via ref so the user's probe identity can change without
    recreating the queue.
  - README "actual fetch determines success" rewritten as concrete
    docs + a working pattern using fetch('/api/ping', { method:'HEAD' }).

Playwright e2e suite across 3 browser engines:
  - playwright.config.ts with chromium / firefox / webkit projects.
  - tests/e2e/headline.spec.ts: 7 headline scenarios × 3 browsers =
    21 e2e tests, all green locally. Covers persist/restore, password
    excludeFields, discard race, offline queue + online flush, rapid
    set+discard+set, submit clears storage, multi-tab submit broadcast.
  - The "iOS Safari multi-tab and offline tested" README claim is now
    actually true — WebKit is the iOS Safari engine.
  - CI gains a parallel e2e job with --with-deps browser install and
    failure-only artifact upload.

_resetIndexedDBForTests no longer leaks into public API:
  - Refactored indexedDBAdapter to hold dbPromise inside the closure
    instead of at module scope. Each call yields an independent
    adapter; tests get a clean slate by just calling indexedDBAdapter()
    again. No more publicly-exported test escape hatch.

README factual sweep:
  - "74 unit tests" → "94 unit tests + 21 Playwright e2e"
  - "~3.4 KB brotli" → "~3.85 KB brotli"
  - "v0.1.0-rc.0" → "v0.1.0-rc.1" (status bullet)
  - "iOS Safari: multi-tab and offline tested" → concrete WebKit e2e
    list
  - Documented useFormDraftStatus (previously exported but absent
    from docs).
  - Added Captive portal section with the recommended probe pattern.

Tests: 92 → 94 unit, +21 e2e. Bundle 3.94 KB brotli (8 KB gate).

Author: mayrang

.github/workflows/ci.yml

@@ -17,3 +17,22 @@ jobs:
       - run: npm test -- --reporter=verbose
       - run: npm run build
       - run: npx size-limit
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20', cache: 'npm' }
+      - run: npm ci
+      - run: cd example && npm ci
+      - run: npm run build
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium firefox webkit
+      - run: npm run test:e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.gitignore

@@ -8,3 +8,6 @@ coverage/
 example/node_modules/
 example/dist/
 .size-limit-cache/
+playwright-report/
+test-results/
+playwright/.cache/

README.md

@@ -7,7 +7,7 @@
 [![license](https://img.shields.io/npm/l/formdraft)](LICENSE)
 [![zero deps](https://img.shields.io/badge/runtime%20deps-0-success)](#zero-runtime-dependencies)
 
-> ⚠️ **v0.1.0-rc.1 (release candidate).** Code-complete with 74 unit tests. Looking for production feedback before v0.1.0 stable. Try it, report bugs at https://github.com/mayrang/formdraft/issues.
+> ⚠️ **v0.1.0-rc.2 (release candidate).** Code-complete with 94 unit tests + 21 Playwright e2e tests (Chromium / Firefox / WebKit). Looking for production feedback before v0.1.0 stable. Try it, report bugs at https://github.com/mayrang/formdraft/issues.
 
 ![demo](docs/assets/demo.gif)
 
@@ -76,7 +76,7 @@ return <form>{/* form.register, etc. */}<span>{status}</span></form>;
 | Refresh loses 20 minutes of typing | localStorage persist + mount restore |
 | Server save fails silently | retry queue with exponential backoff |
 | Offline write then reconnect | `online` + `visibilitychange` flush |
-| Captive portal (`onLine=true` but no internet) | actual fetch determines success |
+| Captive portal (`onLine=true` but no internet) | pluggable `connectivityProbe` HEAD-checks a known URL before each sync |
 | Two tabs editing same draft | BroadcastChannel + `multiTab='warn'` |
 | Tab A submits, Tab B keeps stale draft | submit broadcast → all tabs discard |
 | Component unmounts mid-sync | guarded; no setState-on-unmounted warnings |
@@ -113,7 +113,23 @@ import { localStorageAdapter, sessionStorageAdapter, indexedDBAdapter } from 'fo
 useFormDraft({ ..., storage: indexedDBAdapter() });  // for big forms
 ```
 
-Or write your own:
+## Captive portal handling
+
+`navigator.onLine === true` lies on captive portals (hotel WiFi, etc.). Pass a probe to HEAD-check a known reachable URL before each sync:
+
+```tsx
+useFormDraft({
+  // ...
+  connectivityProbe: () =>
+    fetch('/api/ping', { method: 'HEAD' })
+      .then((r) => r.ok)
+      .catch(() => false),
+});
+```
+
+When the probe returns `false`, the sync is deferred (not counted as a retry). It re-attempts on the next `online`/`visibilitychange` event, or when `save()` is called.
+
+## Custom storage adapter
 
 ```tsx
 const customAdapter: StorageAdapter = {
@@ -124,6 +140,21 @@ const customAdapter: StorageAdapter = {
 };
 ```
 
+## Reading status from anywhere in the tree
+
+You don't always want to drill the `draft` object down to a deep child just to render a "Saving…" pill in a corner. Subscribe to any active `useFormDraft` instance by its `key`:
+
+```tsx
+import { useFormDraftStatus } from 'formdraft';
+
+function SavingIndicator() {
+  const { status, lastSavedAt } = useFormDraftStatus('profile-form');
+  return <span>{status === 'saved' ? `Saved ${lastSavedAt?.toLocaleTimeString()}` : status}</span>;
+}
+```
+
+Backed by `useSyncExternalStore`; SSR-safe (renders `idle` on the server).
+
 ## Multi-tab strategies
 
 | Strategy | What happens on remote change |
@@ -189,11 +220,11 @@ A: No. formdraft uses BroadcastChannel, navigator.onLine, IndexedDB — all brow
 
 ## Status
 
-- **v0.1.0-rc.0** on [npm](https://www.npmjs.com/package/formdraft) (RC — looking for production feedback)
-- 74 unit tests across 14 modules
-- **~3.4 KB brotli** (8 KB CI gate)
+- **v0.1.0-rc.1** on [npm](https://www.npmjs.com/package/formdraft) (RC — looking for production feedback)
+- 94 unit tests + 21 Playwright e2e (7 headline scenarios × Chromium / Firefox / WebKit)
+- **~3.85 KB brotli** (8 KB CI gate)
 - React 18+; Browser support Chrome/Edge 88+, Firefox 78+, Safari 15.4+
-- iOS Safari: multi-tab and offline tested
+- WebKit (iOS Safari engine): persist, restore, discard race, offline queue, submit broadcast all verified e2e
 - 0 runtime dependencies
 
 ## License

package-lock.json

@@ -39,6 +39,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts,.tsx",
     "size": "size-limit",
+    "test:e2e": "playwright test",
     "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run size"
   },
   "peerDependencies": {
@@ -55,6 +56,7 @@
     }
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@size-limit/preset-small-lib": "^11.0.0",
     "@testing-library/react": "^16.0.0",
     "@types/node": "^20.19.41",

package.json

@@ -0,0 +1,25 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: false,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  reporter: process.env.CI ? [['github'], ['list']] : 'list',
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+    headless: true,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+  ],
+  webServer: {
+    command: 'cd example && npx vite --port 5173',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 60_000,
+  },
+});

playwright.config.ts

@@ -164,6 +164,41 @@ describe('createSyncQueue', () => {
     expect(onAbandoned).toHaveBeenCalledWith(expect.any(Error), { x: 1 });
   });
 
+  it('connectivityProbe returning false defers sync without counting as a failure', async () => {
+    // Captive portal: navigator.onLine is true but real reachability is dead.
+    // Probe returns false → attempt is skipped, attempt counter not incremented,
+    // pendingValues stays so a later online/visibility event can retry.
+    const sync = vi.fn().mockResolvedValue(undefined);
+    let reachable = false;
+    const q = createSyncQueue({
+      sync,
+      retry: { maxAttempts: 2, initialBackoffMs: 100, multiplier: 2, maxBackoffMs: 1000 },
+      connectivityProbe: () => Promise.resolve(reachable),
+    });
+    q.enqueue({ x: 1 });
+    await vi.runAllTimersAsync();
+    expect(sync).not.toHaveBeenCalled();
+    expect(q.pending()).toBe(true); // value still queued
+    // Reachability returns — next online event triggers schedule(0)
+    reachable = true;
+    window.dispatchEvent(new Event('online'));
+    await vi.runAllTimersAsync();
+    expect(sync).toHaveBeenCalledWith({ x: 1 });
+  });
+
+  it('connectivityProbe throwing is treated as not-reachable', async () => {
+    const sync = vi.fn().mockResolvedValue(undefined);
+    const q = createSyncQueue({
+      sync,
+      retry: { maxAttempts: 2, initialBackoffMs: 100, multiplier: 2, maxBackoffMs: 1000 },
+      connectivityProbe: () => Promise.reject(new Error('probe blew up')),
+    });
+    q.enqueue({ x: 1 });
+    await vi.runAllTimersAsync();
+    expect(sync).not.toHaveBeenCalled();
+    expect(q.pending()).toBe(true);
+  });
+
   it('exposes pending() to inspect whether something is queued', async () => {
     setOnline(false);
     const sync = vi.fn().mockResolvedValue(undefined);

src/internal/__tests__/syncQueue.test.ts

@@ -9,6 +9,12 @@ export type SyncQueueOptions<T> = {
   // pending value is being dropped. Caller's last chance to surface the
   // failure (status pill, toast, manual retry button, etc.).
   onAbandoned?: (lastError: Error, values: T) => void;
+  // Optional probe to detect captive portals and other lying-network states
+  // where navigator.onLine === true but actual reachability fails. Called
+  // before each sync attempt. Return false to defer; the queue retries on
+  // the next online event or via the user's own save() call. Throwing is
+  // treated the same as returning false.
+  connectivityProbe?: () => Promise<boolean>;
 };
 
 export type SyncQueue<T> = {
@@ -53,6 +59,20 @@ export function createSyncQueue<T>(opts: SyncQueueOptions<T>): SyncQueue<T> {
     if (pendingValues === null) return;
     if (typeof navigator !== 'undefined' && !navigator.onLine) return;
 
+    // Captive portal / lying-network probe. Caller's responsibility to make
+    // it cheap (HEAD a small endpoint, ~50ms). Skip attempt but DON'T count
+    // as a failure — it's a reachability question, not a sync failure.
+    if (opts.connectivityProbe) {
+      let reachable = false;
+      try {
+        reachable = await opts.connectivityProbe();
+      } catch {
+        reachable = false;
+      }
+      if (cancelled) return;
+      if (!reachable) return;
+    }
+
     const values = pendingValues;
     inFlight = true;
     attempt += 1;

src/internal/syncQueue.ts

@@ -1,9 +1,8 @@
 import { beforeEach, describe, expect, it } from 'vitest';
-import { indexedDBAdapter, _resetIndexedDBForTests } from '../indexedDB';
+import { indexedDBAdapter } from '../indexedDB';
 
 describe('indexedDBAdapter', () => {
   beforeEach(async () => {
-    _resetIndexedDBForTests();
     const a = indexedDBAdapter();
     if (a.clear) await a.clear();
   });

src/storage/__tests__/indexedDB.test.ts

@@ -4,43 +4,52 @@ const DB_NAME = 'formdraft';
 const STORE_NAME = 'drafts';
 const DB_VERSION = 1;
 
-let dbPromise: Promise<IDBDatabase> | null = null;
+/**
+ * Returns a fresh IndexedDB adapter. The DB connection promise is held inside
+ * the closure, not at module scope — so each call yields an independent
+ * adapter and tests get a clean slate without needing a public reset helper.
+ * In typical use, callers create one adapter per form and pass it via
+ * `storage: indexedDBAdapter()`.
+ */
+export function indexedDBAdapter(): StorageAdapter {
+  let dbPromise: Promise<IDBDatabase> | null = null;
 
-function getDb(): Promise<IDBDatabase> {
-  if (dbPromise) return dbPromise;
-  const p = new Promise<IDBDatabase>((resolve, reject) => {
-    const req = indexedDB.open(DB_NAME, DB_VERSION);
-    req.onupgradeneeded = () => {
-      const db = req.result;
-      if (!db.objectStoreNames.contains(STORE_NAME)) db.createObjectStore(STORE_NAME);
-    };
-    req.onsuccess = () => resolve(req.result);
-    req.onerror = () => reject(req.error);
-  });
-  // If open fails (Firefox private mode, version mismatch), don't cache the
-  // rejection forever — next call should re-attempt.
-  p.catch(() => {
-    if (dbPromise === p) dbPromise = null;
-  });
-  dbPromise = p;
-  return p;
-}
+  const getDb = (): Promise<IDBDatabase> => {
+    if (dbPromise) return dbPromise;
+    const p = new Promise<IDBDatabase>((resolve, reject) => {
+      const req = indexedDB.open(DB_NAME, DB_VERSION);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) db.createObjectStore(STORE_NAME);
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+    // If open fails (Firefox private mode, version mismatch), don't cache the
+    // rejection forever — next call should re-attempt.
+    p.catch(() => {
+      if (dbPromise === p) dbPromise = null;
+    });
+    dbPromise = p;
+    return p;
+  };
 
-function tx<T>(mode: IDBTransactionMode, fn: (store: IDBObjectStore) => IDBRequest<T> | void): Promise<T | void> {
-  return getDb().then(
-    (db) =>
-      new Promise<T | void>((resolve, reject) => {
-        const transaction = db.transaction(STORE_NAME, mode);
-        const store = transaction.objectStore(STORE_NAME);
-        const req = fn(store);
-        transaction.oncomplete = () => resolve(req?.result as T | undefined);
-        transaction.onerror = () => reject(transaction.error);
-        transaction.onabort = () => reject(transaction.error);
-      }),
-  );
-}
+  const tx = <T>(
+    mode: IDBTransactionMode,
+    fn: (store: IDBObjectStore) => IDBRequest<T> | void,
+  ): Promise<T | void> =>
+    getDb().then(
+      (db) =>
+        new Promise<T | void>((resolve, reject) => {
+          const transaction = db.transaction(STORE_NAME, mode);
+          const store = transaction.objectStore(STORE_NAME);
+          const req = fn(store);
+          transaction.oncomplete = () => resolve(req?.result as T | undefined);
+          transaction.onerror = () => reject(transaction.error);
+          transaction.onabort = () => reject(transaction.error);
+        }),
+    );
 
-export function indexedDBAdapter(): StorageAdapter {
   return {
     name: 'indexedDB',
     async read(key) {
@@ -58,7 +67,3 @@ export function indexedDBAdapter(): StorageAdapter {
     },
   };
 }
-
-export function _resetIndexedDBForTests(): void {
-  dbPromise = null;
-}