@componentor/fs 3.0.51 → 3.0.53

package/dist/index.d.mts

@@ -348,6 +348,12 @@ declare class VFSFileSystem {
     private rejectReady;
     private initError;
     private isReady;
+    /** True while a leader transition is in flight (promotion to leader, etc.).
+     *  Cleared the moment the new sync-relay signals `ready`. Consumers can
+     *  combine this with `isReady` to know when sync FS ops are safe again. */
+    private transitioning;
+    /** Listeners awaiting the next `ready` signal (used by `whenReady()`). */
+    private readyListeners;
     private config;
     private tabId;
     private _mode;
@@ -514,6 +520,23 @@ declare class VFSFileSystem {
      *  Rejects with corruption error if VFS was corrupt (but system falls back to OPFS mode).
      *  Callers can catch and continue — the fs API works in OPFS mode after rejection. */
     init(): Promise<void>;
+    /** True only while the filesystem is fully ready for synchronous operations
+     *  AND no leader transition is in progress. Reflects the moment-in-time state;
+     *  use `whenReady()` to await readiness reliably. */
+    get ready(): boolean;
+    /** Resolves once the filesystem is fully ready for synchronous operations,
+     *  including any in-flight leader transition (promotion-to-leader, etc.).
+     *  If already ready and no transition is pending, resolves immediately.
+     *
+     *  Use this when coordinating with other Web-Lock-based systems (e.g. a
+     *  parent app that elects its own leader independently of the FS) — the
+     *  timing of the two elections isn't synchronized, so the FS may still be
+     *  reinitialising when the parent's lock fires. Calling `whenReady()`
+     *  after your own leader-acquisition guarantees the FS is back in a state
+     *  where sync ops won't stall the 20-second relay-worker heartbeat. */
+    whenReady(): Promise<void>;
+    /** Internal — called by lifecycle handlers when sync-relay says 'ready'. */
+    private fireReadyListeners;
     /** Switch the filesystem mode at runtime.
      *
      *  Typical flow for IDE corruption recovery:

package/dist/index.js

@@ -362,7 +362,12 @@ var OP = {
 var SAB_OFFSETS = {
   // Int32 - bytes in this chunk
   TOTAL_LEN: 16,
-  // Int32 - reserved
+  // Int32 - 0-based chunk index
+  HEARTBEAT: 28,
+  // Int32 - liveness counter; the relay worker bumps this ~1×/s
+  //         while its event loop is alive (incl. mid-await of a
+  //         long op) so a spin-waiting main thread can tell
+  //         "slow" from "dead". Never written by the main thread.
   HEADER_SIZE: 32
   // Data payload starts here
 };
@@ -2556,19 +2561,37 @@ var DEFAULT_SAB_SIZE = 2 * 1024 * 1024;
 var instanceRegistry = /* @__PURE__ */ new Map();
 var HEADER_SIZE = SAB_OFFSETS.HEADER_SIZE;
 var _canAtomicsWait = typeof globalThis.WorkerGlobalScope !== "undefined";
-var SPIN_TIMEOUT_MS = 1e4;
-function spinWait(arr, index, value) {
+var SAB_HEARTBEAT_INDEX = SAB_OFFSETS.HEARTBEAT >> 2;
+var SPIN_STALL_TIMEOUT_MS = 2e4;
+var SPIN_NO_HEARTBEAT_TIMEOUT_MS = 3e4;
+function spinWait(arr, index, value, heartbeatArr) {
   if (_canAtomicsWait) {
     Atomics.wait(arr, index, value);
-  } else {
+    return;
+  }
+  if (!heartbeatArr) {
     const start = performance.now();
     while (Atomics.load(arr, index) === value) {
-      if (performance.now() - start > SPIN_TIMEOUT_MS) {
+      if (performance.now() - start > SPIN_NO_HEARTBEAT_TIMEOUT_MS) {
         throw new Error(
-          `VFS sync operation timed out after ${SPIN_TIMEOUT_MS / 1e3}s \u2014 SharedWorker may be unresponsive`
+          `VFS sync operation timed out after ${SPIN_NO_HEARTBEAT_TIMEOUT_MS / 1e3}s \u2014 relay worker did not respond`
         );
       }
     }
+    return;
+  }
+  let lastBeat = Atomics.load(heartbeatArr, SAB_HEARTBEAT_INDEX);
+  let lastProgress = performance.now();
+  while (Atomics.load(arr, index) === value) {
+    const beat = Atomics.load(heartbeatArr, SAB_HEARTBEAT_INDEX);
+    if (beat !== lastBeat) {
+      lastBeat = beat;
+      lastProgress = performance.now();
+    } else if (performance.now() - lastProgress > SPIN_STALL_TIMEOUT_MS) {
+      throw new Error(
+        `VFS sync operation aborted: relay worker heartbeat stalled for ${SPIN_STALL_TIMEOUT_MS / 1e3}s \u2014 worker is unresponsive`
+      );
+    }
   }
 }
 var VFSFileSystem = class {
@@ -2593,6 +2616,12 @@ var VFSFileSystem = class {
   rejectReady;
   initError = null;
   isReady = false;
+  /** True while a leader transition is in flight (promotion to leader, etc.).
+   *  Cleared the moment the new sync-relay signals `ready`. Consumers can
+   *  combine this with `isReady` to know when sync FS ops are safe again. */
+  transitioning = false;
+  /** Listeners awaiting the next `ready` signal (used by `whenReady()`). */
+  readyListeners = /* @__PURE__ */ new Set();
   // Config (definite assignment — always set when constructor doesn't return singleton)
   config;
   tabId;
@@ -2668,8 +2697,10 @@ var VFSFileSystem = class {
       const msg = e.data;
       if (msg.type === "ready") {
         this.isReady = true;
+        this.transitioning = false;
         this.initAsyncRelay();
         this.resolveReady();
+        this.fireReadyListeners();
         if (!this.isFollower) {
           this.initLeaderBroker();
         }
@@ -2940,6 +2971,7 @@ var VFSFileSystem = class {
   promoteToLeader() {
     this.isFollower = false;
     this.isReady = false;
+    this.transitioning = true;
     this.brokerInitialized = false;
     if (this.brokerHeartbeatTimer) {
       clearInterval(this.brokerHeartbeatTimer);
@@ -2976,7 +3008,9 @@ var VFSFileSystem = class {
       const msg = e.data;
       if (msg.type === "ready") {
         this.isReady = true;
+        this.transitioning = false;
         this.resolveReady();
+        this.fireReadyListeners();
         this.initLeaderBroker();
       } else if (msg.type === "init-failed") {
         if (msg.error?.startsWith("Corrupt VFS:")) {
@@ -3041,7 +3075,7 @@ var VFSFileSystem = class {
     if (signal === -1) {
       throw this.initError ?? new Error("VFS initialization failed");
     }
-    spinWait(this.readySignal, 0, 0);
+    spinWait(this.readySignal, 0, 0, this.ctrl);
     const finalSignal = Atomics.load(this.readySignal, 0);
     if (finalSignal === -1) {
       throw this.initError ?? new Error("VFS initialization failed");
@@ -3055,7 +3089,8 @@ var VFSFileSystem = class {
     const maxChunk = this.sab.byteLength - HEADER_SIZE;
     const requestBytes = new Uint8Array(requestBuf);
     const totalLenView = new BigUint64Array(this.sab, SAB_OFFSETS.TOTAL_LEN, 1);
-    if (requestBytes.byteLength <= maxChunk) {
+    const multiChunkRequest = requestBytes.byteLength > maxChunk;
+    if (!multiChunkRequest) {
       new Uint8Array(this.sab, HEADER_SIZE, requestBytes.byteLength).set(requestBytes);
       Atomics.store(this.ctrl, 3, requestBytes.byteLength);
       Atomics.store(totalLenView, 0, BigInt(requestBytes.byteLength));
@@ -3079,11 +3114,11 @@ var VFSFileSystem = class {
         Atomics.notify(this.ctrl, 0);
         sent += chunkSize;
         if (sent < requestBytes.byteLength) {
-          spinWait(this.ctrl, 0, sent === chunkSize ? SIGNAL.REQUEST : SIGNAL.CHUNK);
+          spinWait(this.ctrl, 0, sent === chunkSize ? SIGNAL.REQUEST : SIGNAL.CHUNK, this.ctrl);
         }
       }
     }
-    spinWait(this.ctrl, 0, SIGNAL.REQUEST);
+    spinWait(this.ctrl, 0, multiChunkRequest ? SIGNAL.CHUNK : SIGNAL.REQUEST, this.ctrl);
     const signal = Atomics.load(this.ctrl, 0);
     const respChunkLen = Atomics.load(this.ctrl, 3);
     const respTotalLen = Number(Atomics.load(totalLenView, 0));
@@ -3099,7 +3134,7 @@ var VFSFileSystem = class {
       while (received < respTotalLen) {
         Atomics.store(this.ctrl, 0, SIGNAL.CHUNK_ACK);
         Atomics.notify(this.ctrl, 0);
-        spinWait(this.ctrl, 0, SIGNAL.CHUNK_ACK);
+        spinWait(this.ctrl, 0, SIGNAL.CHUNK_ACK, this.ctrl);
         const nextLen = Atomics.load(this.ctrl, 3);
         responseBytes.set(new Uint8Array(this.sab, HEADER_SIZE, nextLen), received);
         received += nextLen;
@@ -3590,6 +3625,44 @@ var VFSFileSystem = class {
       }
     });
   }
+  /** True only while the filesystem is fully ready for synchronous operations
+   *  AND no leader transition is in progress. Reflects the moment-in-time state;
+   *  use `whenReady()` to await readiness reliably. */
+  get ready() {
+    return this.isReady && !this.transitioning;
+  }
+  /** Resolves once the filesystem is fully ready for synchronous operations,
+   *  including any in-flight leader transition (promotion-to-leader, etc.).
+   *  If already ready and no transition is pending, resolves immediately.
+   *
+   *  Use this when coordinating with other Web-Lock-based systems (e.g. a
+   *  parent app that elects its own leader independently of the FS) — the
+   *  timing of the two elections isn't synchronized, so the FS may still be
+   *  reinitialising when the parent's lock fires. Calling `whenReady()`
+   *  after your own leader-acquisition guarantees the FS is back in a state
+   *  where sync ops won't stall the 20-second relay-worker heartbeat. */
+  whenReady() {
+    if (this.isReady && !this.transitioning) return Promise.resolve();
+    if (this.transitioning) {
+      return new Promise((resolve2) => {
+        this.readyListeners.add(resolve2);
+      });
+    }
+    return this.readyPromise.then(() => {
+    });
+  }
+  /** Internal — called by lifecycle handlers when sync-relay says 'ready'. */
+  fireReadyListeners() {
+    const listeners = Array.from(this.readyListeners);
+    this.readyListeners.clear();
+    for (const l of listeners) {
+      try {
+        l();
+      } catch (e) {
+        console.warn("[VFS] readyListener threw:", e);
+      }
+    }
+  }
   /** Switch the filesystem mode at runtime.
    *
    *  Typical flow for IDE corruption recovery:
@@ -3627,7 +3700,9 @@ var VFSFileSystem = class {
       const msg = e.data;
       if (msg.type === "ready") {
         this.isReady = true;
+        this.transitioning = false;
         this.resolveReady();
+        this.fireReadyListeners();
         if (!this.isFollower) {
           this.initLeaderBroker();
         }