@componentor/fs 3.0.51 → 3.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@componentor/fs",
-  "version": "3.0.51",
+  "version": "3.0.53",
   "description": "High-performance OPFS-based Node.js fs polyfill with true sync API, VFS binary format, and bidirectional OPFS mirroring",
   "license": "MIT",
   "author": "Componentor",

package/readme.md

@@ -400,6 +400,31 @@ await fs.setMode('hybrid' | 'vfs' | 'opfs'): Promise<void>
 
 // Non-blocking async init (waits for VFS to be ready)
 await fs.init(): Promise<void>
+
+// Moment-in-time readiness: true only when ready AND no leader transition is
+// in flight (equivalent to isReady && !transitioning)
+fs.ready: boolean
+
+// Await readiness reliably, INCLUDING through an in-flight leader promotion.
+// Resolves immediately if already ready; otherwise resolves on the next time
+// the sync-relay signals 'ready'. Use this to coordinate with another
+// navigator.locks-based leader election running independently of the FS:
+await fs.whenReady(): Promise<void>
+```
+
+The `fs.ready` / `fs.whenReady()` pair exists because the FS elects its own
+multi-tab leader via `navigator.locks`. When the leader tab dies and this tab is
+promoted, there's a window where the new sync-relay worker isn't looping yet —
+issuing a sync op then stalls until the worker's heartbeat watchdog fires. If
+your app also does its own leader election, await `fs.whenReady()` *after*
+acquiring your own lock to be sure the FS has finished any promotion first:
+
+```typescript
+navigator.locks.request('my-app-leader', async () => {
+  await fs.whenReady();      // FS promotion (if any) has completed
+  fs.writeFileSync('/state.json', data); // safe — won't stall the relay worker
+  await new Promise(() => {}); // hold the lock
+});
 ```
 
 ### Watch API
@@ -604,6 +629,19 @@ Make sure `opfsSync` is enabled (it's `true` by default). Files are mirrored to
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
 
+### v3.0.53 (2026)
+
+**Features:**
+- Leader-transition readiness tracking. New `fs.whenReady()` resolves once the filesystem is fully ready *including* any in-flight promotion-to-leader, and a new `fs.ready` getter reports the moment-in-time state. Lets an embedding app that runs its own `navigator.locks` leader election coordinate with the FS's independent election — without it, the app can win its lock and issue sync calls while the FS is still mid-promotion, stalling against the 20 s heartbeat watchdog
+- During `promoteToLeader` the existing `readyPromise` is stale (resolved by the prior lifecycle), so awaiting it would return immediately even though the new sync-relay hasn't signalled `ready`. A `transitioning` flag now guards this: while set, `whenReady()` waits for the *next* `ready` rather than the stale promise. All three `ready` handlers (bootstrap, `promoteToLeader`, `setMode`) clear the flag and flush waiting callers consistently
+
+### v3.0.52 (2026)
+
+**Fixes:**
+- Sync FS calls on the browser main thread (which can't use `Atomics.wait` and so spin on `Atomics.load`) no longer abort a legitimately slow operation. The old fixed timeout (10 s, briefly 60 s) killed in-flight `rename`/`copy` over large trees — e.g. `create-strapi-app`'s git init over a fresh `node_modules` — while a genuinely dead worker still blocked for the whole timeout. The relay worker now pulses a heartbeat counter in the control SAB every 1 s (it keeps ticking even while parked on an `await` inside a long op), and the spin-wait aborts only if that heartbeat stalls for 20 s — no upper bound on a progressing op
+- Fix corruption/hang on large sync writes. A `writeFileSync`/`writeSync`/`appendFileSync` of more than ~2 MB (the default SAB data window) is chunked over the SAB; the response-wait afterward waited on the wrong control-word sentinel (`REQUEST` instead of the last chunk's `CHUNK`), so it fell through immediately and read stale request bytes as the response, then wedged. Now waits on the frame it actually wrote last, matching the async path
+- Add a Playwright regression test round-tripping ≈2 MB / ≈5 MB payloads through the sync and promises write APIs with byte-for-byte verification; `playwright-report/` and `test-results/` are now gitignored
+
 ### v3.0.51 (2026)
 
 **Fixes:**