@lark-sh/client 0.1.6 → 0.1.8

package/dist/index.mjs

@@ -89,9 +89,6 @@ function isEventMessage(msg) {
 function isOnceResponseMessage(msg) {
   return "oc" in msg;
 }
-function isPushAckMessage(msg) {
-  return "pa" in msg;
-}
 function isPingMessage(msg) {
   return "o" in msg && msg.o === "pi";
 }
@@ -139,7 +136,11 @@ var MessageQueue = class {
       if (pending) {
         clearTimeout(pending.timeout);
         this.pending.delete(message.jc);
-        pending.resolve(message.vp || []);
+        const response = {
+          volatilePaths: message.vp || [],
+          connectionId: message.cid || null
+        };
+        pending.resolve(response);
         return true;
       }
     }
@@ -170,14 +171,22 @@ var MessageQueue = class {
         return true;
       }
     }
-    if (isPushAckMessage(message)) {
-      const pending = this.pending.get(message.pa);
-      if (pending) {
-        clearTimeout(pending.timeout);
-        this.pending.delete(message.pa);
-        pending.resolve(message.pk);
-        return true;
-      }
+    return false;
+  }
+  /**
+   * Reject a specific pending request locally (without server message).
+   * Used for client-side taint propagation when a write fails and
+   * dependent writes need to be rejected.
+   *
+   * @returns true if the request was pending and rejected, false otherwise
+   */
+  rejectLocally(requestId, error) {
+    const pending = this.pending.get(requestId);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pending.delete(requestId);
+      pending.reject(error);
+      return true;
     }
     return false;
   }
@@ -339,184 +348,560 @@ function setValueAtPath(obj, path, value) {
   current[lastSegment] = value;
 }
 
-// src/cache/DataCache.ts
-var DataCache = class {
-  constructor() {
-    // path -> cached value
-    this.cache = /* @__PURE__ */ new Map();
+// src/utils/sort.ts
+function typeRank(value) {
+  if (value === null || value === void 0) {
+    return 0;
+  }
+  if (typeof value === "boolean") {
+    return value ? 2 : 1;
+  }
+  if (typeof value === "number") {
+    return 3;
+  }
+  if (typeof value === "string") {
+    return 4;
+  }
+  if (typeof value === "object") {
+    return 5;
+  }
+  return 6;
+}
+function compareValues(a, b) {
+  const rankA = typeRank(a);
+  const rankB = typeRank(b);
+  if (rankA !== rankB) {
+    return rankA < rankB ? -1 : 1;
+  }
+  switch (rankA) {
+    case 0:
+      return 0;
+    case 1:
+    // false
+    case 2:
+      return 0;
+    // Same boolean value (rank already differentiated)
+    case 3:
+      const numA = a;
+      const numB = b;
+      if (numA < numB) return -1;
+      if (numA > numB) return 1;
+      return 0;
+    case 4:
+      const strA = a;
+      const strB = b;
+      if (strA < strB) return -1;
+      if (strA > strB) return 1;
+      return 0;
+    case 5:
+      return 0;
+    // Objects are equal for value comparison, sort by key
+    default:
+      return 0;
+  }
+}
+function isInt32Key(key) {
+  if (key.length === 0) {
+    return false;
+  }
+  if (key.length > 1 && key[0] === "0") {
+    return false;
+  }
+  if (key[0] === "-") {
+    if (key.length === 1) {
+      return false;
+    }
+    if (key.length > 2 && key[1] === "0") {
+      return false;
+    }
+    if (key === "-0") {
+      return false;
+    }
+  }
+  const parsed = parseInt(key, 10);
+  if (isNaN(parsed)) {
+    return false;
+  }
+  if (String(parsed) !== key) {
+    return false;
+  }
+  const MIN_INT32 = -2147483648;
+  const MAX_INT32 = 2147483647;
+  return parsed >= MIN_INT32 && parsed <= MAX_INT32;
+}
+function compareKeys(a, b) {
+  const aIsInt = isInt32Key(a);
+  const bIsInt = isInt32Key(b);
+  if (aIsInt && !bIsInt) {
+    return -1;
+  }
+  if (!aIsInt && bIsInt) {
+    return 1;
+  }
+  if (aIsInt && bIsInt) {
+    const aInt = parseInt(a, 10);
+    const bInt = parseInt(b, 10);
+    if (aInt < bInt) return -1;
+    if (aInt > bInt) return 1;
+    return 0;
+  }
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function getNestedValue(obj, path) {
+  if (!obj || typeof obj !== "object") {
+    return void 0;
+  }
+  const segments = path.split("/").filter((s) => s.length > 0);
+  let current = obj;
+  for (const segment of segments) {
+    if (!current || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function getSortValue(value, queryParams) {
+  if (!queryParams) {
+    return null;
+  }
+  if (queryParams.orderBy === "priority") {
+    return getNestedValue(value, ".priority");
+  }
+  if (queryParams.orderByChild) {
+    return getNestedValue(value, queryParams.orderByChild);
+  }
+  if (queryParams.orderBy === "value") {
+    return value;
+  }
+  return null;
+}
+function compareEntries(a, b, queryParams) {
+  if (!queryParams || queryParams.orderBy === "key" || !queryParams.orderBy && !queryParams.orderByChild) {
+    return compareKeys(a.key, b.key);
+  }
+  const cmp = compareValues(a.sortValue, b.sortValue);
+  if (cmp !== 0) {
+    return cmp;
+  }
+  return compareKeys(a.key, b.key);
+}
+function sortEntries(entries, queryParams) {
+  entries.sort((a, b) => compareEntries(a, b, queryParams));
+  return entries;
+}
+function createSortEntries(data, queryParams) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return [];
+  }
+  const obj = data;
+  const entries = [];
+  for (const key of Object.keys(obj)) {
+    if (key === ".priority") {
+      continue;
+    }
+    const value = obj[key];
+    entries.push({
+      key,
+      value,
+      sortValue: getSortValue(value, queryParams)
+    });
+  }
+  return sortEntries(entries, queryParams);
+}
+function getSortedKeys(data, queryParams) {
+  const entries = createSortEntries(data, queryParams);
+  return entries.map((e) => e.key);
+}
+
+// src/connection/View.ts
+var View = class {
+  constructor(path, queryParams) {
+    /** Event callbacks organized by event type */
+    this.eventCallbacks = /* @__PURE__ */ new Map();
+    /** Child keys in sorted order */
+    this._orderedChildren = [];
+    /** Local cache: stores the value at the subscription path */
+    this._cache = void 0;
+    /** Whether we've received the initial snapshot from the server */
+    this._hasReceivedInitialSnapshot = false;
+    /** Pending write request IDs for this View (for local-first recovery) */
+    this._pendingWrites = /* @__PURE__ */ new Set();
+    /** Whether this View is in recovery mode after a nack */
+    this._recovering = false;
+    this.path = normalizePath(path);
+    this._queryParams = queryParams ?? null;
+  }
+  /** Get the current query parameters */
+  get queryParams() {
+    return this._queryParams;
+  }
+  /**
+   * Update query parameters and re-sort cached data.
+   * Returns true if queryParams actually changed.
+   */
+  updateQueryParams(newQueryParams) {
+    const newParams = newQueryParams ?? null;
+    if (this.queryParamsEqual(this._queryParams, newParams)) {
+      return false;
+    }
+    this._queryParams = newParams;
+    if (this._cache && typeof this._cache === "object" && this._cache !== null) {
+      this._orderedChildren = getSortedKeys(this._cache, this._queryParams);
+    }
+    return true;
   }
   /**
-   * Store a value at a path.
-   * Called when we receive data from a subscription event.
+   * Compare two QueryParams objects for equality.
    */
-  set(path, value) {
-    const normalized = normalizePath(path);
-    this.cache.set(normalized, value);
+  queryParamsEqual(a, b) {
+    if (a === b) return true;
+    if (a === null || b === null) return false;
+    return a.orderBy === b.orderBy && a.orderByChild === b.orderByChild && a.limitToFirst === b.limitToFirst && a.limitToLast === b.limitToLast && a.startAt === b.startAt && a.startAtKey === b.startAtKey && a.endAt === b.endAt && a.endAtKey === b.endAtKey && a.equalTo === b.equalTo && a.equalToKey === b.equalToKey;
   }
+  // ============================================
+  // Subscription Management
+  // ============================================
   /**
-   * Get the cached value at a path.
-   * Returns undefined if not in cache.
-   *
-   * This method handles nested lookups:
-   * - If /boxes is cached with {0: true, 1: false}
-   * - get('/boxes/0') returns true (extracted from parent)
+   * Add a callback for an event type.
+   * Returns an unsubscribe function.
    */
-  get(path) {
-    const normalized = normalizePath(path);
-    if (this.cache.has(normalized)) {
-      return { value: this.cache.get(normalized), found: true };
+  addCallback(eventType, callback) {
+    if (!this.eventCallbacks.has(eventType)) {
+      this.eventCallbacks.set(eventType, []);
     }
-    const ancestorResult = this.getFromAncestor(normalized);
-    if (ancestorResult.found) {
-      return ancestorResult;
+    const unsubscribe = () => {
+      this.removeCallback(eventType, callback);
+    };
+    this.eventCallbacks.get(eventType).push({ callback, unsubscribe });
+    return unsubscribe;
+  }
+  /**
+   * Remove a specific callback for an event type.
+   */
+  removeCallback(eventType, callback) {
+    const entries = this.eventCallbacks.get(eventType);
+    if (!entries) return;
+    const index = entries.findIndex((entry) => entry.callback === callback);
+    if (index !== -1) {
+      entries.splice(index, 1);
+    }
+    if (entries.length === 0) {
+      this.eventCallbacks.delete(eventType);
     }
-    return { value: void 0, found: false };
   }
   /**
-   * Check if we have cached data that covers the given path.
-   * This includes exact matches and ancestor paths.
+   * Remove all callbacks for an event type.
    */
-  has(path) {
-    return this.get(path).found;
+  removeAllCallbacks(eventType) {
+    this.eventCallbacks.delete(eventType);
   }
   /**
-   * Try to get data from an ancestor path.
-   * E.g., if /boxes is cached and we want /boxes/5, extract it.
+   * Get all subscribed event types.
    */
-  getFromAncestor(path) {
-    const segments = path.split("/").filter((s) => s.length > 0);
-    for (let i = segments.length - 1; i >= 0; i--) {
-      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
-      if (this.cache.has(ancestorPath)) {
-        const ancestorValue = this.cache.get(ancestorPath);
-        const relativePath = "/" + segments.slice(i).join("/");
-        const extractedValue = getValueAtPath(ancestorValue, relativePath);
-        return { value: extractedValue, found: true };
-      }
-    }
-    if (this.cache.has("/")) {
-      const rootValue = this.cache.get("/");
-      const extractedValue = getValueAtPath(rootValue, path);
-      return { value: extractedValue, found: true };
-    }
-    return { value: void 0, found: false };
+  getEventTypes() {
+    return Array.from(this.eventCallbacks.keys());
   }
   /**
-   * Remove cached data at a path.
-   * Called when unsubscribing from a path that's no longer covered.
+   * Get callbacks for a specific event type.
    */
-  delete(path) {
-    const normalized = normalizePath(path);
-    this.cache.delete(normalized);
+  getCallbacks(eventType) {
+    return this.eventCallbacks.get(eventType) ?? [];
   }
   /**
-   * Remove cached data at a path and all descendant paths.
-   * Called when a subscription is removed and no other subscription covers it.
+   * Check if there are any callbacks registered.
    */
-  deleteTree(path) {
-    const normalized = normalizePath(path);
-    this.cache.delete(normalized);
-    const prefix = normalized === "/" ? "/" : normalized + "/";
-    for (const cachedPath of this.cache.keys()) {
-      if (cachedPath.startsWith(prefix) || normalized === "/" && cachedPath !== "/") {
-        this.cache.delete(cachedPath);
-      }
+  hasCallbacks() {
+    return this.eventCallbacks.size > 0;
+  }
+  /**
+   * Check if there's a callback for a specific event type.
+   */
+  hasCallbacksForType(eventType) {
+    const entries = this.eventCallbacks.get(eventType);
+    return entries !== void 0 && entries.length > 0;
+  }
+  // ============================================
+  // Cache Management
+  // ============================================
+  /**
+   * Set the full cache value (used for initial snapshot).
+   * Children are sorted using client-side sorting rules.
+   */
+  setCache(value) {
+    this._cache = value;
+    this._hasReceivedInitialSnapshot = true;
+    if (value && typeof value === "object" && value !== null && !Array.isArray(value)) {
+      this._orderedChildren = getSortedKeys(value, this.queryParams);
+    } else {
+      this._orderedChildren = [];
     }
   }
   /**
-   * Update cache when a child value changes.
-   * This updates both the child path and any cached ancestor that contains it.
-   *
-   * E.g., if /boxes is cached and /boxes/5 changes:
-   * - Update the /boxes cache to reflect the new /boxes/5 value
-   *
-   * If an ancestor is null, it creates a new object to hold the child.
+   * Get the full cached value at the subscription path.
+   */
+  getCache() {
+    return this._cache;
+  }
+  /**
+   * Get a value from the cache at a relative or absolute path.
+   * If the path is outside this View's scope, returns undefined.
    */
-  updateChild(path, value) {
+  getCacheValue(path) {
     const normalized = normalizePath(path);
-    this.cache.set(normalized, value);
-    const segments = normalized.split("/").filter((s) => s.length > 0);
-    for (let i = segments.length - 1; i >= 1; i--) {
-      const ancestorPath = "/" + segments.slice(0, i).join("/");
-      if (this.cache.has(ancestorPath)) {
-        const ancestorValue = this.cache.get(ancestorPath);
-        const baseValue = ancestorValue !== null && typeof ancestorValue === "object" ? this.deepClone(ancestorValue) : {};
-        const remainingPath = "/" + segments.slice(i).join("/");
-        setValueAtPath(baseValue, remainingPath, value);
-        this.cache.set(ancestorPath, baseValue);
+    if (normalized === this.path) {
+      if (this._cache !== void 0) {
+        return { value: this._cache, found: true };
       }
+      return { value: void 0, found: false };
     }
-    if (this.cache.has("/") && normalized !== "/") {
-      const rootValue = this.cache.get("/");
-      const baseValue = rootValue !== null && typeof rootValue === "object" ? this.deepClone(rootValue) : {};
-      setValueAtPath(baseValue, normalized, value);
-      this.cache.set("/", baseValue);
+    if (normalized.startsWith(this.path + "/") || this.path === "/") {
+      const relativePath = this.path === "/" ? normalized : normalized.slice(this.path.length);
+      if (this._cache !== void 0) {
+        const extractedValue = getValueAtPath(this._cache, relativePath);
+        return { value: extractedValue, found: true };
+      }
     }
+    return { value: void 0, found: false };
   }
   /**
-   * Remove a child from the cache (e.g., on child_removed event).
+   * Update a child value in the cache.
+   * relativePath should be relative to this View's path.
+   * Maintains sorted order of children using client-side sorting.
    */
-  removeChild(path) {
-    const normalized = normalizePath(path);
-    this.deleteTree(normalized);
-    const segments = normalized.split("/").filter((s) => s.length > 0);
-    for (let i = segments.length - 1; i >= 1; i--) {
-      const ancestorPath = "/" + segments.slice(0, i).join("/");
-      if (this.cache.has(ancestorPath)) {
-        const ancestorValue = this.cache.get(ancestorPath);
-        if (ancestorValue !== null && typeof ancestorValue === "object") {
-          const updatedAncestor = this.deepClone(ancestorValue);
-          const parentPath = "/" + segments.slice(i, -1).join("/");
-          const childKey = segments[segments.length - 1];
-          const parent = parentPath === "/" ? updatedAncestor : getValueAtPath(updatedAncestor, parentPath);
-          if (parent && typeof parent === "object") {
-            delete parent[childKey];
-          }
-          this.cache.set(ancestorPath, updatedAncestor);
+  updateCacheChild(relativePath, value) {
+    if (relativePath === "/") {
+      this.setCache(value);
+      return;
+    }
+    const segments = relativePath.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) return;
+    const childKey = segments[0];
+    if (this._cache === null || this._cache === void 0 || typeof this._cache !== "object") {
+      this._cache = {};
+    }
+    const cache = this._cache;
+    if (segments.length === 1) {
+      if (value === null) {
+        delete cache[childKey];
+        const idx = this._orderedChildren.indexOf(childKey);
+        if (idx !== -1) {
+          this._orderedChildren.splice(idx, 1);
+        }
+      } else {
+        const wasPresent = childKey in cache;
+        cache[childKey] = value;
+        if (!wasPresent) {
+          this.insertChildSorted(childKey, value);
+        } else {
+          this.resortChild(childKey);
+        }
+      }
+    } else {
+      if (value === null) {
+        setValueAtPath(cache, relativePath, void 0);
+      } else {
+        const wasPresent = childKey in cache;
+        if (!wasPresent) {
+          cache[childKey] = {};
+        }
+        setValueAtPath(cache, relativePath, value);
+        if (!wasPresent) {
+          this.insertChildSorted(childKey, cache[childKey]);
+        } else {
+          this.resortChild(childKey);
         }
       }
     }
   }
   /**
-   * Clear all cached data.
+   * Insert a child key at the correct sorted position.
    */
-  clear() {
-    this.cache.clear();
+  insertChildSorted(key, value) {
+    if (this._orderedChildren.includes(key)) {
+      this.resortChild(key);
+      return;
+    }
+    const cache = this._cache;
+    const newSortValue = getSortValue(value, this.queryParams);
+    const newEntry = { key, value, sortValue: newSortValue };
+    let insertIdx = this._orderedChildren.length;
+    for (let i = 0; i < this._orderedChildren.length; i++) {
+      const existingKey = this._orderedChildren[i];
+      const existingValue = cache[existingKey];
+      const existingSortValue = getSortValue(existingValue, this.queryParams);
+      const existingEntry = { key: existingKey, value: existingValue, sortValue: existingSortValue };
+      if (compareEntries(newEntry, existingEntry, this.queryParams) < 0) {
+        insertIdx = i;
+        break;
+      }
+    }
+    this._orderedChildren.splice(insertIdx, 0, key);
   }
   /**
-   * Get the number of cached paths (for testing/debugging).
+   * Re-sort a child that already exists (its sort value may have changed).
    */
-  get size() {
-    return this.cache.size;
+  resortChild(key) {
+    const idx = this._orderedChildren.indexOf(key);
+    if (idx === -1) return;
+    this._orderedChildren.splice(idx, 1);
+    const cache = this._cache;
+    const value = cache[key];
+    this.insertChildSorted(key, value);
   }
   /**
-   * Deep clone a value to avoid mutation issues.
+   * Remove a child from the cache.
    */
-  deepClone(value) {
-    if (value === null || typeof value !== "object") {
-      return value;
-    }
-    return JSON.parse(JSON.stringify(value));
+  removeCacheChild(relativePath) {
+    this.updateCacheChild(relativePath, null);
+  }
+  /**
+   * Check if we've received the initial snapshot.
+   */
+  get hasReceivedInitialSnapshot() {
+    return this._hasReceivedInitialSnapshot;
+  }
+  // ============================================
+  // Ordered Children
+  // ============================================
+  /**
+   * Get the ordered children keys.
+   */
+  get orderedChildren() {
+    return [...this._orderedChildren];
+  }
+  /**
+   * Get the previous sibling key for a given key.
+   * Returns null if the key is first or not found.
+   */
+  getPreviousChildKey(key) {
+    const idx = this._orderedChildren.indexOf(key);
+    if (idx <= 0) return null;
+    return this._orderedChildren[idx - 1];
+  }
+  /**
+   * Check if a key exists in the ordered children.
+   */
+  hasChild(key) {
+    return this._orderedChildren.includes(key);
+  }
+  // ============================================
+  // Query Helpers
+  // ============================================
+  /**
+   * Check if this View has query parameters.
+   */
+  hasQuery() {
+    if (!this.queryParams) return false;
+    return !!(this.queryParams.limitToFirst || this.queryParams.limitToLast || this.queryParams.startAt !== void 0 || this.queryParams.endAt !== void 0 || this.queryParams.equalTo !== void 0 || this.queryParams.orderBy || this.queryParams.orderByChild);
+  }
+  /**
+   * Check if this View has limit constraints.
+   */
+  hasLimit() {
+    if (!this.queryParams) return false;
+    return !!(this.queryParams.limitToFirst || this.queryParams.limitToLast);
+  }
+  // ============================================
+  // Pending Writes (for local-first)
+  // ============================================
+  /**
+   * Get current pending write IDs (to include in pw field).
+   * Returns a copy of the set as an array.
+   */
+  getPendingWriteIds() {
+    return Array.from(this._pendingWrites);
+  }
+  /**
+   * Add a pending write request ID.
+   */
+  addPendingWrite(requestId) {
+    this._pendingWrites.add(requestId);
+  }
+  /**
+   * Remove a pending write (on ack or nack).
+   */
+  removePendingWrite(requestId) {
+    return this._pendingWrites.delete(requestId);
+  }
+  /**
+   * Clear all pending writes (on nack recovery).
+   */
+  clearPendingWrites() {
+    this._pendingWrites.clear();
+  }
+  /**
+   * Check if this View has pending writes.
+   */
+  hasPendingWrites() {
+    return this._pendingWrites.size > 0;
+  }
+  /**
+   * Check if a specific write is pending.
+   */
+  isWritePending(requestId) {
+    return this._pendingWrites.has(requestId);
+  }
+  // ============================================
+  // Recovery State (for local-first nack handling)
+  // ============================================
+  /**
+   * Check if this View is in recovery mode.
+   */
+  get recovering() {
+    return this._recovering;
+  }
+  /**
+   * Enter recovery mode (after a nack).
+   */
+  enterRecovery() {
+    this._recovering = true;
+    this.clearPendingWrites();
+  }
+  /**
+   * Exit recovery mode (after fresh snapshot received).
+   */
+  exitRecovery() {
+    this._recovering = false;
+  }
+  // ============================================
+  // Cleanup
+  // ============================================
+  /**
+   * Clear the cache but preserve callbacks and pending writes.
+   * Used during reconnection.
+   */
+  clearCache() {
+    this._cache = void 0;
+    this._orderedChildren = [];
+    this._hasReceivedInitialSnapshot = false;
+  }
+  /**
+   * Clear everything - used when unsubscribing completely.
+   */
+  clear() {
+    this.eventCallbacks.clear();
+    this._cache = void 0;
+    this._orderedChildren = [];
+    this._hasReceivedInitialSnapshot = false;
+    this._pendingWrites.clear();
+    this._recovering = false;
   }
 };
 
 // src/connection/SubscriptionManager.ts
 var SubscriptionManager = class {
   constructor() {
-    // subscriptionPath -> eventType -> array of subscriptions
-    this.subscriptions = /* @__PURE__ */ new Map();
-    // Ordered child keys for each subscription path (for ordered queries)
-    // subscriptionPath -> ordered array of child keys
-    this.orderedChildren = /* @__PURE__ */ new Map();
+    // path -> View (one View per subscribed path)
+    this.views = /* @__PURE__ */ new Map();
     // Callback to send subscribe message to server
     this.sendSubscribe = null;
-    // Query params for each subscription path
-    this.queryParams = /* @__PURE__ */ new Map();
     // Callback to send unsubscribe message to server
     this.sendUnsubscribe = null;
     // Callback to create DataSnapshot from event data
     this.createSnapshot = null;
-    this.cache = new DataCache();
   }
   /**
    * Initialize the manager with server communication callbacks.
@@ -532,53 +917,74 @@ var SubscriptionManager = class {
    */
   subscribe(path, eventType, callback, queryParams) {
     const normalizedPath = path;
-    const isFirstForPath = !this.subscriptions.has(normalizedPath);
-    const existingEventTypes = this.getEventTypesForPath(normalizedPath);
-    const isFirstForEventType = !existingEventTypes.includes(eventType);
-    if (!this.subscriptions.has(normalizedPath)) {
-      this.subscriptions.set(normalizedPath, /* @__PURE__ */ new Map());
-    }
-    const pathSubs = this.subscriptions.get(normalizedPath);
-    if (!pathSubs.has(eventType)) {
-      pathSubs.set(eventType, []);
-    }
-    const eventSubs = pathSubs.get(eventType);
-    if (isFirstForPath && queryParams) {
-      this.queryParams.set(normalizedPath, queryParams);
+    let view = this.views.get(normalizedPath);
+    const isNewView = !view;
+    let queryParamsChanged = false;
+    if (!view) {
+      view = new View(normalizedPath, queryParams);
+      this.views.set(normalizedPath, view);
+    } else {
+      queryParamsChanged = view.updateQueryParams(queryParams);
     }
-    const unsubscribe = () => {
+    const existingEventTypes = view.getEventTypes();
+    const isNewEventType = !existingEventTypes.includes(eventType);
+    const unsubscribe = view.addCallback(eventType, callback);
+    const wrappedUnsubscribe = () => {
       this.unsubscribeCallback(normalizedPath, eventType, callback);
     };
-    eventSubs.push({ callback, unsubscribe });
-    if (isFirstForPath || isFirstForEventType) {
-      const allEventTypes = this.getEventTypesForPath(normalizedPath);
-      const storedQueryParams = this.queryParams.get(normalizedPath);
-      this.sendSubscribe?.(normalizedPath, allEventTypes, storedQueryParams).catch((err) => {
+    if (isNewView || isNewEventType || queryParamsChanged) {
+      const allEventTypes = view.getEventTypes();
+      this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0).catch((err) => {
         console.error("Failed to subscribe:", err);
       });
     }
-    return unsubscribe;
+    if (!isNewView && view.hasReceivedInitialSnapshot) {
+      this.fireInitialEventsToCallback(view, eventType, callback);
+    }
+    return wrappedUnsubscribe;
+  }
+  /**
+   * Fire initial events to a newly added callback from cached data.
+   * This ensures new subscribers get current state even if View already existed.
+   */
+  fireInitialEventsToCallback(view, eventType, callback) {
+    const cache = view.getCache();
+    if (eventType === "value") {
+      const snapshot = this.createSnapshot?.(view.path, cache, false);
+      if (snapshot) {
+        try {
+          callback(snapshot, void 0);
+        } catch (err) {
+          console.error("Error in value subscription callback:", err);
+        }
+      }
+    } else if (eventType === "child_added") {
+      const orderedChildren = view.orderedChildren;
+      for (let i = 0; i < orderedChildren.length; i++) {
+        const childKey = orderedChildren[i];
+        const previousChildKey = i > 0 ? orderedChildren[i - 1] : null;
+        const childPath = joinPath(view.path, childKey);
+        const { value: childValue } = view.getCacheValue(childPath);
+        const snapshot = this.createSnapshot?.(childPath, childValue, false);
+        if (snapshot) {
+          try {
+            callback(snapshot, previousChildKey);
+          } catch (err) {
+            console.error("Error in child_added subscription callback:", err);
+          }
+        }
+      }
+    }
   }
   /**
    * Remove a specific callback from a subscription.
    */
   unsubscribeCallback(path, eventType, callback) {
-    const pathSubs = this.subscriptions.get(path);
-    if (!pathSubs) return;
-    const eventSubs = pathSubs.get(eventType);
-    if (!eventSubs) return;
-    const index = eventSubs.findIndex((entry) => entry.callback === callback);
-    if (index !== -1) {
-      eventSubs.splice(index, 1);
-    }
-    if (eventSubs.length === 0) {
-      pathSubs.delete(eventType);
-    }
-    if (pathSubs.size === 0) {
-      this.subscriptions.delete(path);
-      this.orderedChildren.delete(path);
-      this.queryParams.delete(path);
-      this.cache.deleteTree(path);
+    const view = this.views.get(path);
+    if (!view) return;
+    view.removeCallback(eventType, callback);
+    if (!view.hasCallbacks()) {
+      this.views.delete(path);
       this.sendUnsubscribe?.(path).catch((err) => {
         console.error("Failed to unsubscribe:", err);
       });
@@ -589,21 +995,17 @@ var SubscriptionManager = class {
    */
   unsubscribeEventType(path, eventType) {
     const normalizedPath = path;
-    const pathSubs = this.subscriptions.get(normalizedPath);
-    if (!pathSubs) return;
-    pathSubs.delete(eventType);
-    if (pathSubs.size === 0) {
-      this.subscriptions.delete(normalizedPath);
-      this.orderedChildren.delete(normalizedPath);
-      this.queryParams.delete(normalizedPath);
-      this.cache.deleteTree(normalizedPath);
+    const view = this.views.get(normalizedPath);
+    if (!view) return;
+    view.removeAllCallbacks(eventType);
+    if (!view.hasCallbacks()) {
+      this.views.delete(normalizedPath);
       this.sendUnsubscribe?.(normalizedPath).catch((err) => {
         console.error("Failed to unsubscribe:", err);
       });
     } else {
-      const remainingEventTypes = this.getEventTypesForPath(normalizedPath);
-      const storedQueryParams = this.queryParams.get(normalizedPath);
-      this.sendSubscribe?.(normalizedPath, remainingEventTypes, storedQueryParams).catch((err) => {
+      const remainingEventTypes = view.getEventTypes();
+      this.sendSubscribe?.(normalizedPath, remainingEventTypes, view.queryParams ?? void 0).catch((err) => {
         console.error("Failed to update subscription:", err);
       });
     }
@@ -613,11 +1015,10 @@ var SubscriptionManager = class {
    */
   unsubscribeAll(path) {
     const normalizedPath = path;
-    if (!this.subscriptions.has(normalizedPath)) return;
-    this.subscriptions.delete(normalizedPath);
-    this.orderedChildren.delete(normalizedPath);
-    this.queryParams.delete(normalizedPath);
-    this.cache.deleteTree(normalizedPath);
+    const view = this.views.get(normalizedPath);
+    if (!view) return;
+    view.clear();
+    this.views.delete(normalizedPath);
     this.sendUnsubscribe?.(normalizedPath).catch((err) => {
       console.error("Failed to unsubscribe:", err);
     });
@@ -644,186 +1045,303 @@ var SubscriptionManager = class {
     const value = message.v;
     const isVolatile = message.x ?? false;
     const serverTimestamp = message.ts;
-    const afterKey = message.ak;
-    const orderedKeys = message.k;
-    const pathSubs = this.subscriptions.get(subscriptionPath);
-    if (!pathSubs) return;
-    const absolutePath = relativePath === "/" ? subscriptionPath : joinPath(subscriptionPath, relativePath);
-    const previousOrder = this.orderedChildren.get(subscriptionPath) ?? [];
-    const previousChildSet = new Set(previousOrder);
-    if (value !== void 0) {
-      if (relativePath === "/") {
-        this.cache.set(subscriptionPath, value);
-      } else if (value === null) {
-        this.cache.removeChild(absolutePath);
-      } else {
-        this.cache.updateChild(absolutePath, value);
-      }
-    }
-    if (relativePath === "/") {
-      if (orderedKeys) {
-        this.orderedChildren.set(subscriptionPath, [...orderedKeys]);
-      } else if (value && typeof value === "object" && value !== null) {
-        this.orderedChildren.set(subscriptionPath, Object.keys(value));
-      } else {
-        this.orderedChildren.set(subscriptionPath, []);
-      }
-    } else {
-      const segments = relativePath.split("/").filter((s) => s.length > 0);
-      if (segments.length > 0) {
-        const childKey = segments[0];
-        const currentOrder2 = this.orderedChildren.get(subscriptionPath) ?? [];
-        if (value === null) {
-          const newOrder = currentOrder2.filter((k) => k !== childKey);
-          this.orderedChildren.set(subscriptionPath, newOrder);
-        } else if (!previousChildSet.has(childKey)) {
-          const newOrder = [...currentOrder2];
-          this.insertAfterKey(newOrder, childKey, afterKey);
-          this.orderedChildren.set(subscriptionPath, newOrder);
-        }
+    const view = this.views.get(subscriptionPath);
+    if (!view) return;
+    if (value === void 0) return;
+    if (view.recovering) {
+      if (relativePath !== "/") {
+        return;
       }
+      this.applyWriteToView(view, [{ relativePath, value }], isVolatile, serverTimestamp);
+      view.exitRecovery();
+      return;
     }
-    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
-    const currentChildSet = new Set(currentOrder);
-    this.fireCallbacks(
-      subscriptionPath,
-      pathSubs,
-      relativePath,
-      value,
-      previousOrder,
-      currentOrder,
-      previousChildSet,
-      currentChildSet,
-      afterKey,
-      isVolatile,
-      serverTimestamp
-    );
+    this.applyWriteToView(view, [{ relativePath, value }], isVolatile, serverTimestamp);
   }
   /**
-   * Handle a 'patch' event - multi-path change and/or moves.
+   * Handle a 'patch' event - multi-path change.
    */
   handlePatchEvent(message) {
     const subscriptionPath = message.sp;
     const basePath = message.p;
     const patches = message.v;
-    const moves = message.mv;
-    const orderedKeys = message.k;
     const isVolatile = message.x ?? false;
     const serverTimestamp = message.ts;
-    const pathSubs = this.subscriptions.get(subscriptionPath);
-    if (!pathSubs) return;
-    const previousOrder = this.orderedChildren.get(subscriptionPath) ?? [];
-    const previousChildSet = new Set(previousOrder);
-    const affectedChildren = /* @__PURE__ */ new Set();
-    if (patches) {
-      for (const [relativePath, value] of Object.entries(patches)) {
-        const fullRelativePath = basePath === "/" ? "/" + relativePath : joinPath(basePath, relativePath);
-        const absolutePath = joinPath(subscriptionPath, fullRelativePath);
-        const segments = fullRelativePath.split("/").filter((s) => s.length > 0);
-        if (segments.length > 0) {
-          affectedChildren.add(segments[0]);
-        }
-        if (value === null) {
-          this.cache.removeChild(absolutePath);
-        } else {
-          this.cache.updateChild(absolutePath, value);
-        }
+    const view = this.views.get(subscriptionPath);
+    if (!view) return;
+    if (view.recovering) {
+      return;
+    }
+    if (!patches) return;
+    const updates = [];
+    for (const [relativePath, patchValue] of Object.entries(patches)) {
+      let fullRelativePath;
+      if (basePath === "/") {
+        fullRelativePath = relativePath.startsWith("/") ? relativePath : "/" + relativePath;
+      } else {
+        fullRelativePath = joinPath(basePath, relativePath);
       }
+      updates.push({ relativePath: fullRelativePath, value: patchValue });
     }
-    if (moves && moves.length > 0) {
-      this.handleMoves(subscriptionPath, pathSubs, moves, isVolatile, serverTimestamp);
+    this.applyWriteToView(view, updates, isVolatile, serverTimestamp);
+  }
+  /**
+   * Detect and fire child_moved events for children that changed position.
+   */
+  detectAndFireMoves(view, previousOrder, currentOrder, previousPositions, currentPositions, previousChildSet, currentChildSet, childMovedSubs, isVolatile, serverTimestamp) {
+    if (childMovedSubs.length === 0) return;
+    for (const key of currentOrder) {
+      if (!previousChildSet.has(key) || !currentChildSet.has(key)) {
+        continue;
+      }
+      const oldPos = previousPositions.get(key);
+      const newPos = currentPositions.get(key);
+      const oldPrevKey = oldPos > 0 ? previousOrder[oldPos - 1] : null;
+      const newPrevKey = newPos > 0 ? currentOrder[newPos - 1] : null;
+      if (oldPrevKey !== newPrevKey) {
+        this.fireChildMoved(view, key, childMovedSubs, newPrevKey, isVolatile, serverTimestamp);
+      }
     }
-    if (orderedKeys) {
-      this.orderedChildren.set(subscriptionPath, [...orderedKeys]);
+  }
+  /**
+   * Fire child_added callbacks for a child key.
+   */
+  fireChildAdded(view, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(view.path, childKey);
+    const { value: childValue } = view.getCacheValue(childPath);
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_added subscription callback:", err);
+        }
+      }
     }
-    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
-    const currentChildSet = new Set(currentOrder);
-    const valueSubs = pathSubs.get("value");
-    if (valueSubs && valueSubs.length > 0) {
-      const fullValue = this.cache.get(subscriptionPath).value;
-      const snapshot = this.createSnapshot?.(subscriptionPath, fullValue, isVolatile, serverTimestamp);
-      if (snapshot) {
-        for (const entry of valueSubs) {
-          try {
-            entry.callback(snapshot, void 0);
-          } catch (err) {
-            console.error("Error in value subscription callback:", err);
-          }
+  }
+  /**
+   * Fire child_changed callbacks for a child key.
+   */
+  fireChildChanged(view, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(view.path, childKey);
+    const { value: childValue } = view.getCacheValue(childPath);
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_changed subscription callback:", err);
         }
       }
     }
-    if (patches && affectedChildren.size > 0) {
-      const childAddedSubs = pathSubs.get("child_added") ?? [];
-      const childChangedSubs = pathSubs.get("child_changed") ?? [];
-      const childRemovedSubs = pathSubs.get("child_removed") ?? [];
-      for (const childKey of affectedChildren) {
-        const wasPresent = previousChildSet.has(childKey);
-        const isPresent = currentChildSet.has(childKey);
-        if (!wasPresent && isPresent) {
-          const prevKey = this.getPreviousChildKey(currentOrder, childKey);
-          this.fireChildAdded(subscriptionPath, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
-        } else if (wasPresent && !isPresent) {
-          this.fireChildRemoved(subscriptionPath, childKey, childRemovedSubs, isVolatile, serverTimestamp);
-        } else if (wasPresent && isPresent) {
-          const prevKey = this.getPreviousChildKey(currentOrder, childKey);
-          this.fireChildChanged(subscriptionPath, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
+  }
+  /**
+   * Fire child_removed callbacks for a child key.
+   */
+  fireChildRemoved(view, childKey, subs, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(view.path, childKey);
+    const snapshot = this.createSnapshot?.(childPath, null, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, void 0);
+        } catch (err) {
+          console.error("Error in child_removed subscription callback:", err);
         }
       }
     }
   }
   /**
-   * Handle moves array - update order and fire child_moved events.
+   * Fire child_moved callbacks for a child key.
    */
-  handleMoves(subscriptionPath, pathSubs, moves, isVolatile, serverTimestamp) {
-    const childMovedSubs = pathSubs.get("child_moved") ?? [];
-    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
-    for (const move of moves) {
-      const { k: childKey, ak: afterKey } = move;
-      const idx = currentOrder.indexOf(childKey);
-      if (idx !== -1) {
-        currentOrder.splice(idx, 1);
+  fireChildMoved(view, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(view.path, childKey);
+    const { value: childValue } = view.getCacheValue(childPath);
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_moved subscription callback:", err);
+        }
       }
-      this.insertAfterKey(currentOrder, childKey, afterKey);
-      if (childMovedSubs.length > 0) {
-        const previousChildKey = afterKey === "" ? null : afterKey;
-        this.fireChildMoved(subscriptionPath, childKey, childMovedSubs, previousChildKey, isVolatile, serverTimestamp);
+    }
+  }
+  /**
+   * Clear all subscriptions (e.g., on disconnect).
+   */
+  clear() {
+    for (const view of this.views.values()) {
+      view.clear();
+    }
+    this.views.clear();
+  }
+  /**
+   * Check if there are any subscriptions at a path.
+   */
+  hasSubscriptions(path) {
+    return this.views.has(path);
+  }
+  /**
+   * Check if a path is "covered" by an active subscription.
+   *
+   * A path is covered if:
+   * - There's an active 'value' subscription at that exact path, OR
+   * - There's an active 'value' subscription at an ancestor path
+   */
+  isPathCovered(path) {
+    const normalized = normalizePath(path);
+    if (this.hasValueSubscription(normalized)) {
+      return true;
+    }
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
+      if (this.hasValueSubscription(ancestorPath)) {
+        return true;
       }
     }
-    this.orderedChildren.set(subscriptionPath, currentOrder);
+    if (normalized !== "/" && this.hasValueSubscription("/")) {
+      return true;
+    }
+    return false;
   }
   /**
-   * Insert a key into an ordered array after a specific key.
-   * If afterKey is empty string or undefined, insert at beginning.
-   * If afterKey is not found, append at end.
+   * Check if there's a 'value' subscription at a path.
    */
-  insertAfterKey(order, key, afterKey) {
-    if (afterKey === "" || afterKey === void 0) {
-      order.unshift(key);
-    } else {
-      const afterIdx = order.indexOf(afterKey);
-      if (afterIdx === -1) {
-        order.push(key);
-      } else {
-        order.splice(afterIdx + 1, 0, key);
+  hasValueSubscription(path) {
+    const view = this.views.get(path);
+    return view !== void 0 && view.hasCallbacksForType("value");
+  }
+  /**
+   * Get a cached value if the path is covered by an active subscription.
+   */
+  getCachedValue(path) {
+    const normalized = normalizePath(path);
+    if (!this.isPathCovered(normalized)) {
+      return { value: void 0, found: false };
+    }
+    const exactView = this.views.get(normalized);
+    if (exactView) {
+      return exactView.getCacheValue(normalized);
+    }
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
+      const ancestorView = this.views.get(ancestorPath);
+      if (ancestorView && ancestorView.hasCallbacksForType("value")) {
+        return ancestorView.getCacheValue(normalized);
       }
     }
+    if (normalized !== "/") {
+      const rootView = this.views.get("/");
+      if (rootView && rootView.hasCallbacksForType("value")) {
+        return rootView.getCacheValue(normalized);
+      }
+    }
+    return { value: void 0, found: false };
   }
   /**
-   * Get the previous sibling key for a given key in the ordered array.
+   * Get the cache size (for testing/debugging).
+   * Returns the number of Views.
    */
-  getPreviousChildKey(order, key) {
-    const idx = order.indexOf(key);
-    if (idx <= 0) return null;
-    return order[idx - 1];
+  get cacheSize() {
+    return this.views.size;
   }
   /**
-   * Fire callbacks for subscribed event types.
+   * Clear only the cache, preserving subscription registrations.
+   * Used when preparing for reconnect - we keep subscriptions but will get fresh data.
    */
-  fireCallbacks(subscriptionPath, pathSubs, relativePath, value, previousOrder, currentOrder, previousChildSet, currentChildSet, afterKey, isVolatile, serverTimestamp) {
-    const valueSubs = pathSubs.get("value");
-    if (valueSubs && valueSubs.length > 0) {
-      const fullValue = this.cache.get(subscriptionPath).value;
-      const snapshot = this.createSnapshot?.(subscriptionPath, fullValue, isVolatile, serverTimestamp);
+  clearCacheOnly() {
+    for (const view of this.views.values()) {
+      view.clearCache();
+    }
+  }
+  /**
+   * Re-subscribe to all active subscriptions.
+   * Used after reconnecting to restore subscriptions on the server.
+   */
+  async resubscribeAll() {
+    for (const [path, view] of this.views) {
+      const eventTypes = view.getEventTypes();
+      if (eventTypes.length > 0) {
+        try {
+          await this.sendSubscribe?.(path, eventTypes, view.queryParams ?? void 0);
+        } catch (err) {
+          console.error(`Failed to resubscribe to ${path}:`, err);
+        }
+      }
+    }
+  }
+  /**
+   * Get information about active subscriptions (for debugging).
+   */
+  getActiveSubscriptions() {
+    const result = [];
+    for (const [path, view] of this.views) {
+      const eventTypes = view.getEventTypes();
+      const queryParams = view.queryParams ?? void 0;
+      result.push({ path, eventTypes, queryParams });
+    }
+    return result;
+  }
+  /**
+   * Get a View by path (for testing/debugging).
+   */
+  getView(path) {
+    return this.views.get(path);
+  }
+  // ============================================
+  // Shared Write Application (used by server events and optimistic writes)
+  // ============================================
+  /**
+   * Apply write(s) to a View's cache and fire appropriate events.
+   * This is the core logic shared between server events and optimistic writes.
+   *
+   * @param view - The View to update
+   * @param updates - Array of {relativePath, value} pairs to apply
+   * @param isVolatile - Whether this is a volatile update
+   * @param serverTimestamp - Optional server timestamp
+   */
+  applyWriteToView(view, updates, isVolatile, serverTimestamp) {
+    const previousOrder = view.orderedChildren;
+    const previousChildSet = new Set(previousOrder);
+    const previousCacheJson = JSON.stringify(view.getCache());
+    const affectedChildren = /* @__PURE__ */ new Set();
+    let isFullSnapshot = false;
+    for (const { relativePath, value } of updates) {
+      if (relativePath === "/") {
+        view.setCache(value);
+        isFullSnapshot = true;
+      } else {
+        const segments = relativePath.split("/").filter((s) => s.length > 0);
+        if (segments.length > 0) {
+          affectedChildren.add(segments[0]);
+        }
+        if (value === null) {
+          view.removeCacheChild(relativePath);
+        } else {
+          view.updateCacheChild(relativePath, value);
+        }
+      }
+    }
+    const currentOrder = view.orderedChildren;
+    const currentChildSet = new Set(currentOrder);
+    const currentCacheJson = JSON.stringify(view.getCache());
+    if (previousCacheJson === currentCacheJson) {
+      return;
+    }
+    const valueSubs = view.getCallbacks("value");
+    if (valueSubs.length > 0) {
+      const fullValue = view.getCache();
+      const snapshot = this.createSnapshot?.(view.path, fullValue, isVolatile, serverTimestamp);
       if (snapshot) {
         for (const entry of valueSubs) {
           try {
@@ -834,212 +1352,197 @@ var SubscriptionManager = class {
         }
       }
     }
-    this.fireChildEvents(
-      subscriptionPath,
-      pathSubs,
-      relativePath,
-      value,
-      previousOrder,
-      currentOrder,
-      previousChildSet,
-      currentChildSet,
-      afterKey,
-      isVolatile,
-      serverTimestamp
-    );
-  }
-  /**
-   * Generate and fire child_added, child_changed, child_removed events.
-   * child_moved is handled separately via handleMoves().
-   */
-  fireChildEvents(subscriptionPath, pathSubs, relativePath, value, previousOrder, currentOrder, previousChildSet, currentChildSet, afterKey, isVolatile, serverTimestamp) {
-    const childAddedSubs = pathSubs.get("child_added") ?? [];
-    const childChangedSubs = pathSubs.get("child_changed") ?? [];
-    const childRemovedSubs = pathSubs.get("child_removed") ?? [];
-    if (childAddedSubs.length === 0 && childChangedSubs.length === 0 && childRemovedSubs.length === 0) {
+    const childAddedSubs = view.getCallbacks("child_added");
+    const childChangedSubs = view.getCallbacks("child_changed");
+    const childRemovedSubs = view.getCallbacks("child_removed");
+    const childMovedSubs = view.getCallbacks("child_moved");
+    if (childAddedSubs.length === 0 && childChangedSubs.length === 0 && childRemovedSubs.length === 0 && childMovedSubs.length === 0) {
       return;
     }
-    if (relativePath === "/") {
+    if (isFullSnapshot) {
       for (const key of currentOrder) {
         if (!previousChildSet.has(key)) {
-          const prevKey = this.getPreviousChildKey(currentOrder, key);
-          this.fireChildAdded(subscriptionPath, key, childAddedSubs, prevKey, isVolatile, serverTimestamp);
+          const prevKey = view.getPreviousChildKey(key);
+          this.fireChildAdded(view, key, childAddedSubs, prevKey, isVolatile, serverTimestamp);
         }
       }
       for (const key of previousOrder) {
         if (!currentChildSet.has(key)) {
-          this.fireChildRemoved(subscriptionPath, key, childRemovedSubs, isVolatile, serverTimestamp);
-        }
-      }
-    } else {
-      const segments = relativePath.split("/").filter((s) => s.length > 0);
-      if (segments.length === 0) return;
-      const childKey = segments[0];
-      if (value === null) {
-        if (previousChildSet.has(childKey) && !currentChildSet.has(childKey)) {
-          this.fireChildRemoved(subscriptionPath, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+          this.fireChildRemoved(view, key, childRemovedSubs, isVolatile, serverTimestamp);
         }
-      } else if (!previousChildSet.has(childKey)) {
-        const prevKey = afterKey !== void 0 ? afterKey === "" ? null : afterKey : this.getPreviousChildKey(currentOrder, childKey);
-        this.fireChildAdded(subscriptionPath, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
-      } else {
-        const prevKey = this.getPreviousChildKey(currentOrder, childKey);
-        this.fireChildChanged(subscriptionPath, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
       }
-    }
-  }
-  /**
-   * Fire child_added callbacks for a child key.
-   */
-  fireChildAdded(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
-    if (subs.length === 0) return;
-    const childPath = joinPath(subscriptionPath, childKey);
-    const childValue = this.cache.get(childPath).value;
-    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
-    if (snapshot) {
-      for (const entry of subs) {
-        try {
-          entry.callback(snapshot, previousChildKey);
-        } catch (err) {
-          console.error("Error in child_added subscription callback:", err);
-        }
-      }
-    }
-  }
-  /**
-   * Fire child_changed callbacks for a child key.
-   */
-  fireChildChanged(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
-    if (subs.length === 0) return;
-    const childPath = joinPath(subscriptionPath, childKey);
-    const childValue = this.cache.get(childPath).value;
-    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
-    if (snapshot) {
-      for (const entry of subs) {
-        try {
-          entry.callback(snapshot, previousChildKey);
-        } catch (err) {
-          console.error("Error in child_changed subscription callback:", err);
+    } else {
+      for (const childKey of affectedChildren) {
+        const wasPresent = previousChildSet.has(childKey);
+        const isPresent = currentChildSet.has(childKey);
+        if (!wasPresent && isPresent) {
+          const prevKey = view.getPreviousChildKey(childKey);
+          this.fireChildAdded(view, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
+        } else if (wasPresent && !isPresent) {
+          this.fireChildRemoved(view, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+        } else if (wasPresent && isPresent) {
+          const prevKey = view.getPreviousChildKey(childKey);
+          this.fireChildChanged(view, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
         }
       }
     }
+    const previousPositions = /* @__PURE__ */ new Map();
+    previousOrder.forEach((key, idx) => previousPositions.set(key, idx));
+    const currentPositions = /* @__PURE__ */ new Map();
+    currentOrder.forEach((key, idx) => currentPositions.set(key, idx));
+    this.detectAndFireMoves(
+      view,
+      previousOrder,
+      currentOrder,
+      previousPositions,
+      currentPositions,
+      previousChildSet,
+      currentChildSet,
+      childMovedSubs,
+      isVolatile,
+      serverTimestamp
+    );
   }
+  // ============================================
+  // Pending Writes (for local-first)
+  // ============================================
   /**
-   * Fire child_removed callbacks for a child key.
-   */
-  fireChildRemoved(subscriptionPath, childKey, subs, isVolatile, serverTimestamp) {
-    if (subs.length === 0) return;
-    const childPath = joinPath(subscriptionPath, childKey);
-    const snapshot = this.createSnapshot?.(childPath, null, isVolatile, serverTimestamp);
-    if (snapshot) {
-      for (const entry of subs) {
-        try {
-          entry.callback(snapshot, void 0);
-        } catch (err) {
-          console.error("Error in child_removed subscription callback:", err);
-        }
+   * Find all Views that cover a given write path.
+   * A View covers a path if the View's path is an ancestor of or equal to the write path.
+   */
+  findViewsForWritePath(writePath) {
+    const normalized = normalizePath(writePath);
+    const views = [];
+    for (const [viewPath, view] of this.views) {
+      if (normalized === viewPath) {
+        views.push(view);
+      } else if (normalized.startsWith(viewPath + "/")) {
+        views.push(view);
+      } else if (viewPath === "/") {
+        views.push(view);
       }
     }
+    return views;
   }
   /**
-   * Fire child_moved callbacks for a child key.
+   * Get pending write IDs for a write path.
+   * Returns the union of pending writes from all Views that cover this path.
    */
-  fireChildMoved(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
-    if (subs.length === 0) return;
-    const childPath = joinPath(subscriptionPath, childKey);
-    const childValue = this.cache.get(childPath).value;
-    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
-    if (snapshot) {
-      for (const entry of subs) {
-        try {
-          entry.callback(snapshot, previousChildKey);
-        } catch (err) {
-          console.error("Error in child_moved subscription callback:", err);
-        }
+  getPendingWriteIdsForPath(writePath) {
+    const views = this.findViewsForWritePath(writePath);
+    const allPendingIds = /* @__PURE__ */ new Set();
+    for (const view of views) {
+      for (const id of view.getPendingWriteIds()) {
+        allPendingIds.add(id);
       }
     }
+    return Array.from(allPendingIds);
   }
   /**
-   * Get all event types currently subscribed at a path.
-   */
-  getEventTypesForPath(path) {
-    const pathSubs = this.subscriptions.get(path);
-    if (!pathSubs) return [];
-    return Array.from(pathSubs.keys());
-  }
-  /**
-   * Clear all subscriptions (e.g., on disconnect).
+   * Track a pending write for all Views that cover the write path.
    */
-  clear() {
-    this.subscriptions.clear();
-    this.orderedChildren.clear();
-    this.queryParams.clear();
-    this.cache.clear();
+  trackPendingWrite(writePath, requestId) {
+    const views = this.findViewsForWritePath(writePath);
+    for (const view of views) {
+      view.addPendingWrite(requestId);
+    }
   }
   /**
-   * Check if there are any subscriptions at a path.
+   * Clear a pending write from all Views (on ack).
    */
-  hasSubscriptions(path) {
-    return this.subscriptions.has(path);
+  clearPendingWrite(requestId) {
+    for (const view of this.views.values()) {
+      view.removePendingWrite(requestId);
+    }
   }
   /**
-   * Check if a path is "covered" by an active subscription.
-   *
-   * A path is covered if:
-   * - There's an active 'value' subscription at that exact path, OR
-   * - There's an active 'value' subscription at an ancestor path
-   *
-   * Child event subscriptions (child_added, etc.) don't provide full coverage
-   * because they only notify of changes, not the complete value.
+   * Handle a nack for a pending write.
+   * Collects all tainted request IDs and puts affected Views into recovery mode.
+   * Returns the affected Views and all tainted request IDs for local rejection.
    */
-  isPathCovered(path) {
-    const normalized = normalizePath(path);
-    if (this.hasValueSubscription(normalized)) {
-      return true;
-    }
-    const segments = normalized.split("/").filter((s) => s.length > 0);
-    for (let i = segments.length - 1; i >= 0; i--) {
-      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
-      if (this.hasValueSubscription(ancestorPath)) {
-        return true;
+  handleWriteNack(requestId) {
+    const affectedViews = [];
+    const taintedIds = /* @__PURE__ */ new Set();
+    for (const view of this.views.values()) {
+      if (view.isWritePending(requestId)) {
+        affectedViews.push(view);
+        for (const id of view.getPendingWriteIds()) {
+          taintedIds.add(id);
+        }
       }
     }
-    if (normalized !== "/" && this.hasValueSubscription("/")) {
-      return true;
+    for (const view of affectedViews) {
+      view.enterRecovery();
     }
-    return false;
+    return { affectedViews, taintedIds: Array.from(taintedIds) };
   }
   /**
-   * Check if there's a 'value' subscription at a path.
+   * Check if any View covering a path is in recovery mode.
    */
-  hasValueSubscription(path) {
-    const pathSubs = this.subscriptions.get(path);
-    if (!pathSubs) return false;
-    const valueSubs = pathSubs.get("value");
-    return valueSubs !== void 0 && valueSubs.length > 0;
+  isPathInRecovery(writePath) {
+    const views = this.findViewsForWritePath(writePath);
+    return views.some((view) => view.recovering);
   }
   /**
-   * Get a cached value if the path is covered by an active subscription.
-   *
-   * Returns { value, found: true } if we have cached data for this path
-   * (either exact match or extractable from a cached ancestor).
-   *
-   * Returns { value: undefined, found: false } if:
-   * - The path is not covered by any subscription, OR
-   * - We don't have cached data yet
+   * Re-subscribe a specific View to get a fresh snapshot.
+   * Used during recovery after a nack.
    */
-  getCachedValue(path) {
-    const normalized = normalizePath(path);
-    if (!this.isPathCovered(normalized)) {
-      return { value: void 0, found: false };
+  async resubscribeView(path) {
+    const view = this.views.get(path);
+    if (!view) return;
+    const eventTypes = view.getEventTypes();
+    if (eventTypes.length > 0 && this.sendSubscribe) {
+      await this.sendSubscribe(path, eventTypes, view.queryParams ?? void 0);
     }
-    return this.cache.get(normalized);
   }
+  // ============================================
+  // Optimistic Writes (for local-first)
+  // ============================================
   /**
-   * Get the cache size (for testing/debugging).
-   */
-  get cacheSize() {
-    return this.cache.size;
+   * Apply an optimistic write to local cache and fire events.
+   * Called before sending the write to the server.
+   *
+   * @param writePath - The absolute path being written to
+   * @param value - The value to write (null for delete)
+   * @param requestId - The request ID for pending write tracking
+   * @param operation - The type of operation ('set', 'update', 'delete')
+   * @returns The Views that were updated
+   */
+  applyOptimisticWrite(writePath, value, requestId, operation) {
+    const normalized = normalizePath(writePath);
+    const affectedViews = this.findViewsForWritePath(normalized);
+    if (affectedViews.length === 0) {
+      return [];
+    }
+    const updatedViews = [];
+    for (const view of affectedViews) {
+      if (!view.hasReceivedInitialSnapshot) {
+        continue;
+      }
+      let relativePath;
+      if (normalized === view.path) {
+        relativePath = "/";
+      } else if (view.path === "/") {
+        relativePath = normalized;
+      } else {
+        relativePath = normalized.slice(view.path.length);
+      }
+      const updates = [];
+      if (operation === "delete") {
+        updates.push({ relativePath, value: null });
+      } else if (operation === "update") {
+        const updateObj = value;
+        for (const [key, val] of Object.entries(updateObj)) {
+          const updatePath = relativePath === "/" ? "/" + key : relativePath + "/" + key;
+          updates.push({ relativePath: updatePath, value: val });
+        }
+      } else {
+        updates.push({ relativePath, value });
+      }
+      this.applyWriteToView(view, updates, false, void 0);
+      updatedViews.push(view);
+    }
+    return updatedViews;
   }
 };
 
@@ -1175,9 +1678,18 @@ var OnDisconnect = class {
   }
   /**
    * Set a value with priority when disconnected.
+   * Priority is injected as `.priority` into the value object.
    */
   async setWithPriority(value, priority) {
-    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.SET, value, priority);
+    if (value === null || value === void 0) {
+      await this._db._sendOnDisconnect(this._path, OnDisconnectAction.SET, value);
+      return;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("Priority can only be set on object values");
+    }
+    const valueWithPriority = { ...value, ".priority": priority };
+    await this._db._sendOnDisconnect(this._path, OnDisconnectAction.SET, valueWithPriority);
   }
 };
 
@@ -1265,8 +1777,15 @@ var DatabaseReference = class _DatabaseReference {
   // ============================================
   /**
    * Set the data at this location, overwriting any existing data.
+   *
+   * For volatile paths (high-frequency updates), this is fire-and-forget
+   * and resolves immediately without waiting for server confirmation.
    */
   async set(value) {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileSet(this._path, value);
+      return;
+    }
     await this._db._sendSet(this._path, value);
   }
   /**
@@ -1303,13 +1822,23 @@ var DatabaseReference = class _DatabaseReference {
       }
       await this._db._sendTransaction(ops);
     } else {
+      if (this._db.isVolatilePath(this._path)) {
+        this._db._sendVolatileUpdate(this._path, values);
+        return;
+      }
       await this._db._sendUpdate(this._path, values);
     }
   }
   /**
    * Remove the data at this location.
+   *
+   * For volatile paths, this is fire-and-forget.
    */
   async remove() {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileDelete(this._path);
+      return;
+    }
     await this._db._sendDelete(this._path);
   }
   /**
@@ -1322,27 +1851,43 @@ var DatabaseReference = class _DatabaseReference {
    * push key (you can then call set() on it).
    */
   push(value) {
+    const key = generatePushId();
+    const childRef = this.child(key);
     if (value === void 0) {
-      const key = generatePushId();
-      return this.child(key);
+      return childRef;
     }
-    return this._db._sendPush(this._path, value).then((key) => {
-      return this.child(key);
-    });
+    return childRef.set(value).then(() => childRef);
   }
   /**
    * Set the data with a priority value for ordering.
+   * Priority is injected as `.priority` into the value object.
    */
   async setWithPriority(value, priority) {
-    await this._db._sendSet(this._path, value, priority);
+    if (value === null || value === void 0) {
+      await this._db._sendSet(this._path, value);
+      return;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("Priority can only be set on object values");
+    }
+    const valueWithPriority = { ...value, ".priority": priority };
+    await this._db._sendSet(this._path, valueWithPriority);
   }
   /**
    * Set the priority of the data at this location.
+   * Fetches current value and sets it with the new priority.
    */
   async setPriority(priority) {
-    console.warn("setPriority: fetching current value to preserve it");
     const snapshot = await this.once();
-    await this.setWithPriority(snapshot.val(), priority);
+    const currentVal = snapshot.val();
+    if (currentVal === null || currentVal === void 0) {
+      await this._db._sendSet(this._path, { ".priority": priority });
+      return;
+    }
+    if (typeof currentVal !== "object" || Array.isArray(currentVal)) {
+      throw new Error("Priority can only be set on object values");
+    }
+    await this.setWithPriority(currentVal, priority);
   }
   /**
    * Atomically modify the data at this location using optimistic concurrency.
@@ -1606,7 +2151,6 @@ var DataSnapshot = class _DataSnapshot {
     this._path = normalizePath(path);
     this._db = db;
     this._volatile = options.volatile ?? false;
-    this._priority = options.priority ?? null;
     this._serverTimestamp = options.serverTimestamp ?? null;
   }
   /**
@@ -1622,9 +2166,17 @@ var DataSnapshot = class _DataSnapshot {
     return getKey(this._path);
   }
   /**
-   * Get the raw data value.
+   * Get the data value, with `.priority` stripped if present.
+   * Priority is internal metadata and should not be visible to app code.
    */
   val() {
+    if (this._data && typeof this._data === "object" && !Array.isArray(this._data)) {
+      const data = this._data;
+      if (".priority" in data) {
+        const { ".priority": _, ...rest } = data;
+        return Object.keys(rest).length > 0 ? rest : Object.keys(data).length === 1 ? null : rest;
+      }
+    }
     return this._data;
   }
   /**
@@ -1686,9 +2238,16 @@ var DataSnapshot = class _DataSnapshot {
   }
   /**
    * Get the priority of the data at this location.
+   * Priority is stored as `.priority` in the data object.
    */
   getPriority() {
-    return this._priority;
+    if (this._data && typeof this._data === "object" && !Array.isArray(this._data)) {
+      const priority = this._data[".priority"];
+      if (typeof priority === "number" || typeof priority === "string") {
+        return priority;
+      }
+    }
+    return null;
   }
   /**
    * Check if this snapshot was from a volatile (high-frequency) update.
@@ -1732,7 +2291,32 @@ function decodeJwtPayload(token) {
   return JSON.parse(decoded);
 }
 
+// src/utils/volatile.ts
+function isVolatilePath(path, patterns) {
+  if (!patterns || patterns.length === 0) {
+    return false;
+  }
+  const segments = path.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+  return patterns.some((pattern) => {
+    const patternSegments = pattern.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+    if (segments.length < patternSegments.length) {
+      return false;
+    }
+    for (let i = 0; i < patternSegments.length; i++) {
+      const p = patternSegments[i];
+      const s = segments[i];
+      if (p !== "*" && p !== s) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
 // src/LarkDatabase.ts
+var RECONNECT_BASE_DELAY_MS = 1e3;
+var RECONNECT_MAX_DELAY_MS = 3e4;
+var RECONNECT_JITTER_FACTOR = 0.5;
 var LarkDatabase = class {
   constructor() {
     this._state = "disconnected";
@@ -1740,11 +2324,18 @@ var LarkDatabase = class {
     this._databaseId = null;
     this._coordinatorUrl = null;
     this._volatilePaths = [];
+    // Reconnection state
+    this._connectionId = null;
+    this._connectOptions = null;
+    this._intentionalDisconnect = false;
+    this._reconnectAttempt = 0;
+    this._reconnectTimer = null;
     this.ws = null;
     // Event callbacks
     this.connectCallbacks = /* @__PURE__ */ new Set();
     this.disconnectCallbacks = /* @__PURE__ */ new Set();
     this.errorCallbacks = /* @__PURE__ */ new Set();
+    this.reconnectingCallbacks = /* @__PURE__ */ new Set();
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
     this.pendingWrites = new PendingWriteManager();
@@ -1758,6 +2349,18 @@ var LarkDatabase = class {
   get connected() {
     return this._state === "connected";
   }
+  /**
+   * Whether the database is currently attempting to reconnect.
+   */
+  get reconnecting() {
+    return this._state === "reconnecting";
+  }
+  /**
+   * Current connection state.
+   */
+  get state() {
+    return this._state;
+  }
   /**
    * Current auth info, or null if not connected.
    */
@@ -1814,7 +2417,16 @@ var LarkDatabase = class {
     if (this._state !== "disconnected") {
       throw new Error("Already connected or connecting");
     }
-    this._state = "connecting";
+    this._connectOptions = options;
+    this._intentionalDisconnect = false;
+    await this.performConnect(databaseId, options);
+  }
+  /**
+   * Internal connect implementation used by both initial connect and reconnect.
+   */
+  async performConnect(databaseId, options, isReconnect = false) {
+    const previousState = this._state;
+    this._state = isReconnect ? "reconnecting" : "connecting";
     this._databaseId = databaseId;
     this._coordinatorUrl = options.coordinator || DEFAULT_COORDINATOR_URL;
     try {
@@ -1840,9 +2452,13 @@ var LarkDatabase = class {
         t: connectResponse.token,
         r: requestId
       };
+      if (this._connectionId) {
+        joinMessage.pcid = this._connectionId;
+      }
       this.send(joinMessage);
-      const volatilePaths = await this.messageQueue.registerRequest(requestId);
-      this._volatilePaths = volatilePaths || [];
+      const joinResponse = await this.messageQueue.registerRequest(requestId);
+      this._volatilePaths = joinResponse.volatilePaths;
+      this._connectionId = joinResponse.connectionId;
       const jwtPayload = decodeJwtPayload(connectResponse.token);
       this._auth = {
         uid: jwtPayload.sub,
@@ -1850,16 +2466,29 @@ var LarkDatabase = class {
         token: jwtPayload.claims || {}
       };
       this._state = "connected";
-      this.subscriptionManager.initialize({
-        sendSubscribe: this.sendSubscribeMessage.bind(this),
-        sendUnsubscribe: this.sendUnsubscribeMessage.bind(this),
-        createSnapshot: this.createSnapshot.bind(this)
-      });
+      this._reconnectAttempt = 0;
+      if (!isReconnect) {
+        this.subscriptionManager.initialize({
+          sendSubscribe: this.sendSubscribeMessage.bind(this),
+          sendUnsubscribe: this.sendUnsubscribeMessage.bind(this),
+          createSnapshot: this.createSnapshot.bind(this)
+        });
+      }
+      if (isReconnect) {
+        await this.restoreAfterReconnect();
+      }
       this.connectCallbacks.forEach((cb) => cb());
     } catch (error) {
+      if (isReconnect) {
+        this._state = "reconnecting";
+        this.scheduleReconnect();
+        return;
+      }
       this._state = "disconnected";
       this._auth = null;
       this._databaseId = null;
+      this._connectOptions = null;
+      this._connectionId = null;
       this.ws?.close();
       this.ws = null;
       throw error;
@@ -1873,7 +2502,13 @@ var LarkDatabase = class {
     if (this._state === "disconnected") {
       return;
     }
-    if (this._state === "connected" && this.ws) {
+    const wasConnected = this._state === "connected";
+    this._intentionalDisconnect = true;
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    if (wasConnected && this.ws) {
       try {
         const requestId = this.messageQueue.nextRequestId();
         this.send({ o: "l", r: requestId });
@@ -1884,12 +2519,16 @@ var LarkDatabase = class {
       } catch {
       }
     }
-    this.cleanup();
+    this.cleanupFull();
+    if (wasConnected) {
+      this.disconnectCallbacks.forEach((cb) => cb());
+    }
   }
   /**
-   * Clean up connection state.
+   * Full cleanup - clears all state including subscriptions.
+   * Used for intentional disconnect.
    */
-  cleanup() {
+  cleanupFull() {
     this.ws?.close();
     this.ws = null;
     this._state = "disconnected";
@@ -1897,8 +2536,111 @@ var LarkDatabase = class {
     this._databaseId = null;
     this._volatilePaths = [];
     this._coordinatorUrl = null;
+    this._connectionId = null;
+    this._connectOptions = null;
+    this._reconnectAttempt = 0;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
+    this.pendingWrites.clear();
+  }
+  /**
+   * Partial cleanup - preserves state needed for reconnect.
+   * Used for unexpected disconnect.
+   */
+  cleanupForReconnect() {
+    this.ws?.close();
+    this.ws = null;
+    this._auth = null;
+    this.subscriptionManager.clearCacheOnly();
+    this.messageQueue.rejectAll(new Error("Connection closed"));
+  }
+  /**
+   * Schedule a reconnection attempt with exponential backoff.
+   */
+  scheduleReconnect() {
+    this._reconnectAttempt++;
+    const baseDelay = Math.min(
+      RECONNECT_BASE_DELAY_MS * Math.pow(2, this._reconnectAttempt - 1),
+      RECONNECT_MAX_DELAY_MS
+    );
+    const jitter = baseDelay * RECONNECT_JITTER_FACTOR * Math.random();
+    const delay = baseDelay + jitter;
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.attemptReconnect();
+    }, delay);
+  }
+  /**
+   * Attempt to reconnect to the database.
+   */
+  async attemptReconnect() {
+    if (this._intentionalDisconnect || !this._databaseId || !this._connectOptions) {
+      return;
+    }
+    try {
+      await this.performConnect(this._databaseId, this._connectOptions, true);
+    } catch {
+    }
+  }
+  /**
+   * Restore subscriptions and retry pending writes after reconnect.
+   */
+  async restoreAfterReconnect() {
+    await this.subscriptionManager.resubscribeAll();
+    await this.retryPendingWrites();
+  }
+  /**
+   * Retry all pending writes after reconnect.
+   */
+  async retryPendingWrites() {
+    const pendingWrites = this.pendingWrites.getPendingWrites();
+    for (const write of pendingWrites) {
+      try {
+        switch (write.operation) {
+          case "set": {
+            const message = {
+              o: "s",
+              p: write.path,
+              v: write.value,
+              r: write.oid
+              // Use original request ID
+            };
+            this.send(message);
+            break;
+          }
+          case "update": {
+            const message = {
+              o: "u",
+              p: write.path,
+              v: write.value,
+              r: write.oid
+            };
+            this.send(message);
+            break;
+          }
+          case "delete": {
+            const message = {
+              o: "d",
+              p: write.path,
+              r: write.oid
+            };
+            this.send(message);
+            break;
+          }
+          case "transaction": {
+            const message = {
+              o: "tx",
+              ops: write.value,
+              r: write.oid
+            };
+            this.send(message);
+            break;
+          }
+        }
+      } catch (error) {
+        console.error("Failed to retry pending write:", error);
+      }
+    }
   }
   // ============================================
   // Reference Access
@@ -2024,6 +2766,15 @@ var LarkDatabase = class {
     this.errorCallbacks.add(callback);
     return () => this.errorCallbacks.delete(callback);
   }
+  /**
+   * Register a callback for when reconnection attempts begin.
+   * This fires when an unexpected disconnect occurs and auto-reconnect starts.
+   * Returns an unsubscribe function.
+   */
+  onReconnecting(callback) {
+    this.reconnectingCallbacks.add(callback);
+    return () => this.reconnectingCallbacks.delete(callback);
+  }
   // ============================================
   // Internal: Message Handling
   // ============================================
@@ -2041,8 +2792,31 @@ var LarkDatabase = class {
     }
     if (isAckMessage(message)) {
       this.pendingWrites.onAck(message.a);
+      this.subscriptionManager.clearPendingWrite(message.a);
     } else if (isNackMessage(message)) {
       this.pendingWrites.onNack(message.n);
+      if (message.e !== "condition_failed") {
+        console.error(`Write failed (${message.e}): ${message.m || message.e}`);
+        const { affectedViews, taintedIds } = this.subscriptionManager.handleWriteNack(message.n);
+        if (affectedViews.length > 0) {
+          for (const id of taintedIds) {
+            if (id !== message.n) {
+              this.messageQueue.rejectLocally(
+                id,
+                new LarkError("write_tainted", "Write cancelled: depends on failed write")
+              );
+              this.pendingWrites.onNack(id);
+            }
+          }
+          for (const view of affectedViews) {
+            this.subscriptionManager.resubscribeView(view.path).catch((err) => {
+              console.error(`Failed to re-subscribe ${view.path} during recovery:`, err);
+            });
+          }
+        }
+      } else {
+        this.subscriptionManager.clearPendingWrite(message.n);
+      }
     }
     if (this.messageQueue.handleMessage(message)) {
       return;
@@ -2052,10 +2826,32 @@ var LarkDatabase = class {
     }
   }
   handleClose(code, reason) {
+    if (this._state === "disconnected") {
+      return;
+    }
     const wasConnected = this._state === "connected";
-    this.cleanup();
-    if (wasConnected) {
-      this.disconnectCallbacks.forEach((cb) => cb());
+    const wasReconnecting = this._state === "reconnecting";
+    if (this._intentionalDisconnect) {
+      this.cleanupFull();
+      if (wasConnected) {
+        this.disconnectCallbacks.forEach((cb) => cb());
+      }
+      return;
+    }
+    const canReconnect = this._databaseId && this._connectOptions;
+    if ((wasConnected || wasReconnecting) && canReconnect) {
+      this._state = "reconnecting";
+      this.cleanupForReconnect();
+      this.reconnectingCallbacks.forEach((cb) => cb());
+      if (wasConnected) {
+        this.disconnectCallbacks.forEach((cb) => cb());
+      }
+      this.scheduleReconnect();
+    } else {
+      this.cleanupFull();
+      if (wasConnected) {
+        this.disconnectCallbacks.forEach((cb) => cb());
+      }
     }
   }
   handleError(event) {
@@ -2073,20 +2869,25 @@ var LarkDatabase = class {
   }
   /**
    * @internal Send a set operation.
+   * Note: Priority is now part of the value (as .priority), not a separate field.
    */
-  async _sendSet(path, value, priority) {
-    const requestId = this.messageQueue.nextRequestId();
+  async _sendSet(path, value) {
     const normalizedPath = normalizePath(path) || "/";
+    if (this.subscriptionManager.isPathInRecovery(normalizedPath)) {
+      throw new LarkError("view_recovering", "Cannot write: View is recovering from failed write");
+    }
+    const requestId = this.messageQueue.nextRequestId();
+    const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
     this.pendingWrites.trackWrite(requestId, "set", normalizedPath, value);
+    this.subscriptionManager.trackPendingWrite(normalizedPath, requestId);
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, requestId, "set");
     const message = {
       o: "s",
       p: normalizedPath,
       v: value,
-      r: requestId
+      r: requestId,
+      pw: pendingWriteIds.length > 0 ? pendingWriteIds : void 0
     };
-    if (priority !== void 0) {
-      message.y = priority;
-    }
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
@@ -2094,14 +2895,21 @@ var LarkDatabase = class {
    * @internal Send an update operation.
    */
   async _sendUpdate(path, values) {
-    const requestId = this.messageQueue.nextRequestId();
     const normalizedPath = normalizePath(path) || "/";
+    if (this.subscriptionManager.isPathInRecovery(normalizedPath)) {
+      throw new LarkError("view_recovering", "Cannot write: View is recovering from failed write");
+    }
+    const requestId = this.messageQueue.nextRequestId();
+    const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
     this.pendingWrites.trackWrite(requestId, "update", normalizedPath, values);
+    this.subscriptionManager.trackPendingWrite(normalizedPath, requestId);
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, requestId, "update");
     const message = {
       o: "u",
       p: normalizedPath,
       v: values,
-      r: requestId
+      r: requestId,
+      pw: pendingWriteIds.length > 0 ? pendingWriteIds : void 0
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
@@ -2110,33 +2918,79 @@ var LarkDatabase = class {
    * @internal Send a delete operation.
    */
   async _sendDelete(path) {
-    const requestId = this.messageQueue.nextRequestId();
     const normalizedPath = normalizePath(path) || "/";
+    if (this.subscriptionManager.isPathInRecovery(normalizedPath)) {
+      throw new LarkError("view_recovering", "Cannot write: View is recovering from failed write");
+    }
+    const requestId = this.messageQueue.nextRequestId();
+    const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
     this.pendingWrites.trackWrite(requestId, "delete", normalizedPath);
+    this.subscriptionManager.trackPendingWrite(normalizedPath, requestId);
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, requestId, "delete");
     const message = {
       o: "d",
       p: normalizedPath,
-      r: requestId
+      r: requestId,
+      pw: pendingWriteIds.length > 0 ? pendingWriteIds : void 0
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
+  // ============================================
+  // Volatile Write Operations (Fire-and-Forget)
+  // ============================================
   /**
-   * @internal Send a push operation. Returns the generated key.
+   * @internal Send a volatile set operation (fire-and-forget).
+   *
+   * Volatile writes skip:
+   * - Recovery checks (volatile paths don't participate in recovery)
+   * - Request ID generation (no ack expected)
+   * - Pending write tracking (no retry on reconnect)
+   * - pw field (no dependency tracking)
+   *
+   * The write is applied optimistically to local cache for UI feedback,
+   * but we don't await server confirmation.
    */
-  async _sendPush(path, value) {
-    const requestId = this.messageQueue.nextRequestId();
+  _sendVolatileSet(path, value) {
     const normalizedPath = normalizePath(path) || "/";
-    this.pendingWrites.trackWrite(requestId, "push", normalizedPath, value);
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
     const message = {
-      o: "p",
+      o: "s",
       p: normalizedPath,
-      v: value,
-      r: requestId
+      v: value
     };
     this.send(message);
-    const key = await this.messageQueue.registerRequest(requestId);
-    return key;
+  }
+  /**
+   * @internal Send a volatile update operation (fire-and-forget).
+   */
+  _sendVolatileUpdate(path, values) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
+    const message = {
+      o: "u",
+      p: normalizedPath,
+      v: values
+    };
+    this.send(message);
+  }
+  /**
+   * @internal Send a volatile delete operation (fire-and-forget).
+   */
+  _sendVolatileDelete(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, "", "delete");
+    const message = {
+      o: "d",
+      p: normalizedPath
+    };
+    this.send(message);
+  }
+  /**
+   * Check if a path is a volatile path (high-frequency, fire-and-forget).
+   */
+  isVolatilePath(path) {
+    return isVolatilePath(path, this._volatilePaths);
   }
   /**
    * @internal Send a once (read) operation.
@@ -2173,7 +3027,7 @@ var LarkDatabase = class {
   /**
    * @internal Send an onDisconnect operation.
    */
-  async _sendOnDisconnect(path, action, value, priority) {
+  async _sendOnDisconnect(path, action, value) {
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "od",
@@ -2184,9 +3038,6 @@ var LarkDatabase = class {
     if (value !== void 0) {
       message.v = value;
     }
-    if (priority !== void 0) {
-      message.y = priority;
-    }
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
@@ -2249,21 +3100,6 @@ var LarkDatabase = class {
     this.subscriptionManager.unsubscribeAll(path);
   }
 };
-
-// src/utils/volatile.ts
-function isVolatilePath(path, patterns) {
-  if (!patterns || patterns.length === 0) {
-    return false;
-  }
-  const segments = path.replace(/^\//, "").split("/");
-  return patterns.some((pattern) => {
-    const patternSegments = pattern.split("/");
-    if (segments.length !== patternSegments.length) {
-      return false;
-    }
-    return patternSegments.every((p, i) => p === "*" || p === segments[i]);
-  });
-}
 export {
   DataSnapshot,
   DatabaseReference,