@abraca/dabra 2.0.7 → 2.0.8

package/dist/index.d.ts

@@ -1089,7 +1089,28 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   private childAccessTimes;
   /** Pinned children that must not be evicted (e.g. actively viewed docs) */
   private pinnedChildren;
-  /** Default cap on simultaneously cached child providers; configurable per-instance via `maxChildren`. */
+  /**
+   * Children explicitly marked as transient (e.g. by a background indexer
+   * that scans the whole tree). They:
+   *   - never count toward the LRU `maxChildren` budget
+   *   - never cause eviction of OTHER children when they're added
+   *   - are eligible for LRU eviction themselves only after they get
+   *     unmarked or explicitly unloaded
+   *
+   * The motivating case: `useSearchIndex` / `useFileIndex` walk every doc
+   * in the tree calling `loadChild`. With a default cap of 20 and a tree
+   * of 76+ subdocs, the LRU silently evicted whichever subdoc the UI was
+   * actually showing — a CLOSE storm and dead awareness for the user.
+   * Transient loads sidestep that pool entirely.
+   */
+  private transientChildren;
+  /**
+   * Default cap on simultaneously cached child providers (excluding
+   * transient ones — see `transientChildren`). Configurable per-instance
+   * via `maxChildren`. Bumped from 20 → 64 because real apps routinely
+   * have trees with dozens of subdocs being touched and 20 caused silent
+   * subdoc eviction (with awareness loss) on perfectly normal load.
+   */
   private static readonly DEFAULT_MAX_CHILDREN;
   private readonly maxChildren;
   private abracadabraConfig;
@@ -1166,10 +1187,21 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   hasChild(childId: string): boolean;
   /**
    * Create (or return cached) a child AbracadabraProvider for a given
-   * child document id.  Each child opens its own WebSocket connection because
-   * the server is document-scoped (one WebSocket ↔ one document).
-   */
-  loadChild(childId: string): Promise<AbracadabraProvider>;
+   * child document id.  Each child shares the parent's WebSocket via
+   * multiplexing.
+   *
+   * `evictable` (default `true`) controls whether the child enters the
+   * LRU pool. Pass `evictable: false` for transient loads — typically
+   * batch indexers (search, file extraction) that touch every doc in
+   * the tree and would otherwise blow out the cache, silently evicting
+   * subdocs the UI is actively using. Transient children are excluded
+   * from the LRU budget AND don't trigger eviction of other children.
+   * Callers MUST pair `loadChild(id, { evictable: false })` with an
+   * explicit `unloadChild(id)` once they're done.
+   */
+  loadChild(childId: string, options?: {
+    evictable?: boolean;
+  }): Promise<AbracadabraProvider>;
   private _doLoadChild;
   unloadChild(childId: string): void;
   /**
@@ -1182,8 +1214,11 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    */
   unpinChild(childId: string): void;
   /**
-   * Evict least-recently-used unpinned child providers until the cache is
-   * at or below MAX_CHILDREN.
+   * Evict least-recently-used unpinned, non-transient child providers
+   * until the cache is at or below MAX_CHILDREN. Transient children
+   * (loaded with `{ evictable: false }`) are excluded from both the
+   * budget *and* the eviction list — they're invisible to the LRU and
+   * only go away when their loader explicitly calls `unloadChild`.
    */
   private evictLRU;
   /** Return all currently-loaded child providers. */
@@ -2280,6 +2315,15 @@ declare class AbracadabraBaseProvider extends EventEmitter {
   isSynced: boolean;
   unsyncedChanges: number;
   isAuthenticated: boolean;
+  /**
+   * True once this provider has received at least one Authenticated frame
+   * on the current socket lifetime. Used by `permissionDeniedHandler` to
+   * tell apart "the entry doc is wrong / unreachable" (first frame is a
+   * denial → config error, give up) from "a mid-session write was denied"
+   * (server keeps the read subscription alive → don't kill the socket).
+   * Reset on close.
+   */
+  private _hasEverAuthenticated;
   /** Current WebSocket connection status. */
   get connectionStatus(): WebSocketStatus;
   authorizedScope: AuthorizedScope | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraProvider.ts

@@ -519,6 +519,23 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			);
 		}
 
+		// Self-load: caller asked for the doc this provider already owns.
+		// Return `this` directly. Without this guard we'd build a sibling
+		// AbracadabraProvider with the same `name` and call attach() on the
+		// shared AbracadabraWS. The wsp's providerMap is keyed by name, so
+		// the sibling silently REPLACES the root in the routing table — its
+		// outgoing messages still reach the wire (send doesn't read the
+		// map), but inbound frames addressed to that doc go to the sibling.
+		// When the borrow ends and the sibling detaches, providerMap is
+		// wiped of that name and the root is left orphaned: the UI still
+		// reports `connected` + `synced`, but no awareness/sync messages
+		// are received. Returning `this` is intentionally not added to
+		// `childProviders` so LRU eviction never destroys the root, and
+		// `unloadChild(self)` becomes a safe no-op (see below).
+		if (childId === this.configuration.name) {
+			return Promise.resolve(this);
+		}
+
 		const evictable = options.evictable !== false;
 
 		if (this.childProviders.has(childId)) {