@lark-sh/client 0.1.10 → 0.1.12

package/dist/index.mjs

@@ -12,7 +12,9 @@ var ErrorCode = {
   INVALID_PATH: "invalid_path",
   INVALID_OPERATION: "invalid_operation",
   INTERNAL_ERROR: "internal_error",
-  CONDITION_FAILED: "condition_failed"
+  CONDITION_FAILED: "condition_failed",
+  INVALID_QUERY: "invalid_query",
+  AUTH_REQUIRED: "auth_required"
 };
 var DEFAULT_COORDINATOR_URL = "https://db.lark.sh";
 
@@ -418,6 +420,9 @@ function isAckMessage(msg) {
 function isJoinCompleteMessage(msg) {
   return "jc" in msg;
 }
+function isAuthCompleteMessage(msg) {
+  return "ac" in msg;
+}
 function isNackMessage(msg) {
   return "n" in msg;
 }
@@ -476,7 +481,20 @@ var MessageQueue = class {
         this.pending.delete(message.jc);
         const response = {
           volatilePaths: message.vp || [],
-          connectionId: message.cid || null
+          connectionId: message.cid || null,
+          serverTime: message.st ?? null
+        };
+        pending.resolve(response);
+        return true;
+      }
+    }
+    if (isAuthCompleteMessage(message)) {
+      const pending = this.pending.get(message.ac);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.ac);
+        const response = {
+          uid: message.au || null
         };
         pending.resolve(response);
         return true;
@@ -505,7 +523,7 @@ var MessageQueue = class {
       if (pending) {
         clearTimeout(pending.timeout);
         this.pending.delete(message.oc);
-        pending.resolve(message.ov);
+        pending.resolve(message.ov ?? null);
         return true;
       }
     }
@@ -803,7 +821,7 @@ function getNestedValue(obj, path) {
 }
 function getSortValue(value, queryParams) {
   if (!queryParams) {
-    return null;
+    return getNestedValue(value, ".priority");
   }
   if (queryParams.orderBy === "priority") {
     return getNestedValue(value, ".priority");
@@ -814,10 +832,18 @@ function getSortValue(value, queryParams) {
   if (queryParams.orderBy === "value") {
     return value;
   }
+  if (queryParams.orderBy === "key") {
+    return null;
+  }
+  const hasRangeFilter = queryParams.startAt !== void 0 || queryParams.startAfter !== void 0 || queryParams.endAt !== void 0 || queryParams.endBefore !== void 0 || queryParams.equalTo !== void 0;
+  const hasLimit = queryParams.limitToFirst !== void 0 || queryParams.limitToLast !== void 0;
+  if (hasRangeFilter || hasLimit) {
+    return getNestedValue(value, ".priority");
+  }
   return null;
 }
 function compareEntries(a, b, queryParams) {
-  if (!queryParams || queryParams.orderBy === "key" || !queryParams.orderBy && !queryParams.orderByChild) {
+  if (queryParams?.orderBy === "key") {
     return compareKeys(a.key, b.key);
   }
   const cmp = compareValues(a.sortValue, b.sortValue);
@@ -836,7 +862,11 @@ function createSortEntries(data, queryParams) {
   }
   const obj = data;
   const entries = [];
-  for (const key of Object.keys(obj)) {
+  const keys = Object.keys(obj);
+  if (keys.length === 2 && ".value" in obj && ".priority" in obj) {
+    return [];
+  }
+  for (const key of keys) {
     if (key === ".priority") {
       continue;
     }
@@ -859,16 +889,17 @@ var View = class {
   constructor(path, queryParams) {
     /** Event callbacks organized by event type */
     this.eventCallbacks = /* @__PURE__ */ new Map();
-    /** Child keys in sorted order */
+    /** Child keys in sorted order (computed from display cache) */
     this._orderedChildren = [];
-    /** Local cache: stores the value at the subscription path */
-    this._cache = void 0;
+    /** Server cache: what the server has told us (baseline) */
+    this._serverCache = null;
     /** 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;
+    /** Pending write operations that haven't been ACKed yet (for local-first) */
+    this._pendingWriteData = [];
+    /** Cached display value (server + pending writes merged) - invalidated when either changes */
+    this._displayCacheValid = false;
+    this._displayCache = null;
     this.path = normalizePath(path);
     this._queryParams = queryParams ?? null;
   }
@@ -886,9 +917,8 @@ var View = class {
       return false;
     }
     this._queryParams = newParams;
-    if (this._cache && typeof this._cache === "object" && this._cache !== null) {
-      this._orderedChildren = getSortedKeys(this._cache, this._queryParams);
-    }
+    this._displayCacheValid = false;
+    this.recomputeOrderedChildren();
     return true;
   }
   /**
@@ -962,138 +992,368 @@ var View = class {
     return entries !== void 0 && entries.length > 0;
   }
   // ============================================
-  // Cache Management
+  // Cache Management (Dual Cache: Server + Pending Writes)
   // ============================================
   /**
-   * Set the full cache value (used for initial snapshot).
-   * Children are sorted using client-side sorting rules.
+   * Set the server cache (what the server told us).
+   * This is the baseline before pending writes are applied.
+   * Deep clones the value to ensure each View has its own copy.
    */
-  setCache(value) {
-    this._cache = value;
+  setServerCache(value) {
+    this._serverCache = this.deepClone(value);
     this._hasReceivedInitialSnapshot = true;
-    if (value && typeof value === "object" && value !== null && !Array.isArray(value)) {
-      this._orderedChildren = getSortedKeys(value, this.queryParams);
-    } else {
-      this._orderedChildren = [];
+    this.invalidateDisplayCache();
+  }
+  /**
+   * Get the server cache (baseline without pending writes).
+   */
+  getServerCache() {
+    return this._serverCache;
+  }
+  /**
+   * Get the display cache (server + pending writes merged).
+   * This is what should be shown to the user.
+   */
+  getDisplayCache() {
+    if (!this._displayCacheValid) {
+      this._displayCache = this.computeMergedCache();
+      this._displayCacheValid = true;
     }
+    return this._displayCache;
   }
   /**
-   * Get the full cached value at the subscription path.
+   * Alias for getDisplayCache() - this is what callbacks receive.
    */
   getCache() {
-    return this._cache;
+    return this.getDisplayCache();
+  }
+  /**
+   * Invalidate the display cache (call when serverCache or pendingWrites change).
+   */
+  invalidateDisplayCache() {
+    this._displayCacheValid = false;
+    this.recomputeOrderedChildren();
+  }
+  /**
+   * Compute the merged cache (serverCache + pendingWrites), with query constraints applied.
+   */
+  computeMergedCache() {
+    let result;
+    if (this._pendingWriteData.length === 0) {
+      result = this._serverCache;
+    } else {
+      result = this.deepClone(this._serverCache);
+      for (const write of this._pendingWriteData) {
+        result = this.applyWrite(result, write);
+      }
+    }
+    return this.applyQueryConstraints(result);
+  }
+  /**
+   * Apply query constraints (range filtering and limits) to data.
+   * This ensures the displayCache only contains data matching the query.
+   */
+  applyQueryConstraints(data) {
+    if (!this._queryParams) {
+      return data;
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      return data;
+    }
+    const obj = data;
+    const hasRangeFilter = this._queryParams.startAt !== void 0 || this._queryParams.startAfter !== void 0 || this._queryParams.endAt !== void 0 || this._queryParams.endBefore !== void 0 || this._queryParams.equalTo !== void 0;
+    const hasLimit = this._queryParams.limitToFirst !== void 0 || this._queryParams.limitToLast !== void 0;
+    if (!hasRangeFilter && !hasLimit) {
+      return data;
+    }
+    let entries = createSortEntries(obj, this._queryParams);
+    if (hasRangeFilter) {
+      entries = this.filterByRange(entries);
+    }
+    if (hasLimit) {
+      entries = this.applyLimits(entries);
+    }
+    if (entries.length === 0) {
+      return null;
+    }
+    const result = {};
+    for (const entry of entries) {
+      result[entry.key] = entry.value;
+    }
+    return result;
+  }
+  /**
+   * Filter entries by range constraints (startAt, endAt, startAfter, endBefore, equalTo).
+   */
+  filterByRange(entries) {
+    if (!this._queryParams) return entries;
+    const {
+      orderBy,
+      startAt,
+      startAtKey,
+      startAfter,
+      startAfterKey,
+      endAt,
+      endAtKey,
+      endBefore,
+      endBeforeKey,
+      equalTo,
+      equalToKey
+    } = this._queryParams;
+    const isOrderByKey = orderBy === "key";
+    return entries.filter((entry) => {
+      const compareValue = isOrderByKey ? entry.key : entry.sortValue;
+      const compareFn = isOrderByKey ? (a, b) => compareKeys(a, b) : compareValues;
+      if (equalTo !== void 0) {
+        const cmp = compareFn(compareValue, equalTo);
+        if (cmp !== 0) return false;
+        if (equalToKey !== void 0 && !isOrderByKey) {
+          const keyCmp = compareKeys(entry.key, equalToKey);
+          if (keyCmp !== 0) return false;
+        }
+        return true;
+      }
+      if (startAt !== void 0) {
+        const cmp = compareFn(compareValue, startAt);
+        if (cmp < 0) return false;
+        if (cmp === 0 && startAtKey !== void 0 && !isOrderByKey) {
+          const keyCmp = compareKeys(entry.key, startAtKey);
+          if (keyCmp < 0) return false;
+        }
+      }
+      if (startAfter !== void 0) {
+        const cmp = compareFn(compareValue, startAfter);
+        if (cmp < 0) return false;
+        if (cmp === 0) {
+          if (startAfterKey !== void 0 && !isOrderByKey) {
+            const keyCmp = compareKeys(entry.key, startAfterKey);
+            if (keyCmp <= 0) return false;
+          } else {
+            return false;
+          }
+        }
+      }
+      if (endAt !== void 0) {
+        const cmp = compareFn(compareValue, endAt);
+        if (cmp > 0) return false;
+        if (cmp === 0 && endAtKey !== void 0 && !isOrderByKey) {
+          const keyCmp = compareKeys(entry.key, endAtKey);
+          if (keyCmp > 0) return false;
+        }
+      }
+      if (endBefore !== void 0) {
+        const cmp = compareFn(compareValue, endBefore);
+        if (cmp > 0) return false;
+        if (cmp === 0) {
+          if (endBeforeKey !== void 0 && !isOrderByKey) {
+            const keyCmp = compareKeys(entry.key, endBeforeKey);
+            if (keyCmp >= 0) return false;
+          } else {
+            return false;
+          }
+        }
+      }
+      return true;
+    });
   }
   /**
-   * Get a value from the cache at a relative or absolute path.
+   * Apply limit constraints (limitToFirst, limitToLast) to entries.
+   * Entries are already sorted, so we just slice.
+   */
+  applyLimits(entries) {
+    if (!this._queryParams) return entries;
+    const { limitToFirst, limitToLast } = this._queryParams;
+    if (limitToFirst !== void 0) {
+      return entries.slice(0, limitToFirst);
+    }
+    if (limitToLast !== void 0) {
+      return entries.slice(-limitToLast);
+    }
+    return entries;
+  }
+  /**
+   * Apply a single write operation to a value.
+   */
+  applyWrite(base, write) {
+    const { relativePath, value, operation } = write;
+    if (operation === "delete") {
+      if (relativePath === "/") {
+        return null;
+      }
+      return this.deleteAtPath(base, relativePath);
+    }
+    if (operation === "set") {
+      if (relativePath === "/") {
+        return value;
+      }
+      return this.setAtPath(base, relativePath, value);
+    }
+    if (operation === "update") {
+      if (relativePath === "/") {
+        if (base === null || base === void 0 || typeof base !== "object") {
+          base = {};
+        }
+        const merged2 = { ...base, ...value };
+        for (const key of Object.keys(merged2)) {
+          if (merged2[key] === null) {
+            delete merged2[key];
+          }
+        }
+        return merged2;
+      }
+      const current = getValueAtPath(base, relativePath);
+      let merged;
+      if (current && typeof current === "object") {
+        merged = { ...current, ...value };
+        for (const key of Object.keys(merged)) {
+          if (merged[key] === null) {
+            delete merged[key];
+          }
+        }
+      } else {
+        merged = value;
+      }
+      return this.setAtPath(base, relativePath, merged);
+    }
+    return base;
+  }
+  /**
+   * Set a value at a path in an object, creating intermediate objects as needed.
+   */
+  setAtPath(obj, path, value) {
+    if (path === "/") return value;
+    const segments = path.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) return value;
+    const result = obj === null || obj === void 0 || typeof obj !== "object" ? {} : { ...obj };
+    let current = result;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const key = segments[i];
+      if (current[key] === null || current[key] === void 0 || typeof current[key] !== "object") {
+        current[key] = {};
+      } else {
+        current[key] = { ...current[key] };
+      }
+      current = current[key];
+    }
+    const lastKey = segments[segments.length - 1];
+    current[lastKey] = value;
+    return result;
+  }
+  /**
+   * Delete a value at a path in an object.
+   */
+  deleteAtPath(obj, path) {
+    if (path === "/" || obj === null || obj === void 0 || typeof obj !== "object") {
+      return null;
+    }
+    const segments = path.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) return null;
+    const result = { ...obj };
+    if (segments.length === 1) {
+      delete result[segments[0]];
+      return Object.keys(result).length > 0 ? result : null;
+    }
+    let current = result;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const key = segments[i];
+      if (current[key] === null || current[key] === void 0 || typeof current[key] !== "object") {
+        return result;
+      }
+      current[key] = { ...current[key] };
+      current = current[key];
+    }
+    delete current[segments[segments.length - 1]];
+    return result;
+  }
+  /**
+   * Deep clone a value.
+   */
+  deepClone(value) {
+    if (value === null || value === void 0) return value;
+    if (typeof value !== "object") return value;
+    if (Array.isArray(value)) return value.map((v) => this.deepClone(v));
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = this.deepClone(v);
+    }
+    return result;
+  }
+  /**
+   * Recompute ordered children from display cache.
+   */
+  recomputeOrderedChildren() {
+    const displayCache = this.getDisplayCache();
+    if (displayCache && typeof displayCache === "object" && !Array.isArray(displayCache)) {
+      this._orderedChildren = getSortedKeys(displayCache, this.queryParams);
+    } else {
+      this._orderedChildren = [];
+    }
+  }
+  /**
+   * Get a value from the display cache at a relative or absolute path.
    * If the path is outside this View's scope, returns undefined.
    */
   getCacheValue(path) {
     const normalized = normalizePath(path);
+    const displayCache = this.getDisplayCache();
     if (normalized === this.path) {
-      if (this._cache !== void 0) {
-        return { value: this._cache, found: true };
+      if (displayCache !== void 0 && displayCache !== null) {
+        return { value: displayCache, found: true };
+      }
+      if (this._hasReceivedInitialSnapshot || this._pendingWriteData.length > 0) {
+        return { value: displayCache ?? null, found: true };
       }
       return { value: void 0, found: false };
     }
     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 };
+      if (this._hasReceivedInitialSnapshot || this._pendingWriteData.length > 0) {
+        const extractedValue = getValueAtPath(displayCache, relativePath);
+        return { value: extractedValue ?? null, found: true };
       }
     }
     return { value: void 0, found: false };
   }
   /**
-   * Update a child value in the cache.
+   * Update a child value in the SERVER cache.
    * relativePath should be relative to this View's path.
-   * Maintains sorted order of children using client-side sorting.
+   * Called when server events (put/patch) arrive.
    */
-  updateCacheChild(relativePath, value) {
+  updateServerCacheChild(relativePath, value) {
     if (relativePath === "/") {
-      this.setCache(value);
+      this.setServerCache(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 = {};
+    if (this._serverCache === null || this._serverCache === void 0 || typeof this._serverCache !== "object") {
+      this._serverCache = {};
     }
-    const cache = this._cache;
+    const cache = this._serverCache;
     if (segments.length === 1) {
       if (value === null) {
-        delete cache[childKey];
-        const idx = this._orderedChildren.indexOf(childKey);
-        if (idx !== -1) {
-          this._orderedChildren.splice(idx, 1);
-        }
+        delete cache[segments[0]];
       } else {
-        const wasPresent = childKey in cache;
-        cache[childKey] = value;
-        if (!wasPresent) {
-          this.insertChildSorted(childKey, value);
-        } else {
-          this.resortChild(childKey);
-        }
+        cache[segments[0]] = value;
       }
     } else {
       if (value === null) {
         setValueAtPath(cache, relativePath, void 0);
       } else {
-        const wasPresent = childKey in cache;
-        if (!wasPresent) {
+        const childKey = segments[0];
+        if (!(childKey in cache)) {
           cache[childKey] = {};
         }
         setValueAtPath(cache, relativePath, value);
-        if (!wasPresent) {
-          this.insertChildSorted(childKey, cache[childKey]);
-        } else {
-          this.resortChild(childKey);
-        }
-      }
-    }
-  }
-  /**
-   * Insert a child key at the correct sorted position.
-   */
-  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);
+    this.invalidateDisplayCache();
   }
   /**
-   * Re-sort a child that already exists (its sort value may have changed).
+   * Remove a child from the SERVER cache.
    */
-  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);
-  }
-  /**
-   * Remove a child from the cache.
-   */
-  removeCacheChild(relativePath) {
-    this.updateCacheChild(relativePath, null);
+  removeServerCacheChild(relativePath) {
+    this.updateServerCacheChild(relativePath, null);
   }
   /**
    * Check if we've received the initial snapshot.
@@ -1142,101 +1402,117 @@ var View = class {
     if (!this.queryParams) return false;
     return !!(this.queryParams.limitToFirst || this.queryParams.limitToLast);
   }
+  /**
+   * Check if this View loads all data (no limits, no range filters).
+   * A View that loads all data can serve as a "complete" cache for child paths.
+   * This matches Firebase's loadsAllData() semantics.
+   */
+  loadsAllData() {
+    if (!this.queryParams) return true;
+    const hasLimit = !!(this.queryParams.limitToFirst || this.queryParams.limitToLast);
+    const hasRangeFilter = this.queryParams.startAt !== void 0 || this.queryParams.endAt !== void 0 || this.queryParams.equalTo !== void 0 || this.queryParams.startAfter !== void 0 || this.queryParams.endBefore !== void 0;
+    return !hasLimit && !hasRangeFilter;
+  }
   // ============================================
   // 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);
+    return this._pendingWriteData.filter((w) => w.requestId !== "").map((w) => w.requestId);
   }
   /**
-   * Add a pending write request ID.
+   * Add a pending write with its data.
+   * This is used for local-first writes - the write is applied to displayCache immediately.
    */
-  addPendingWrite(requestId) {
-    this._pendingWrites.add(requestId);
+  addPendingWriteData(requestId, relativePath, value, operation) {
+    this._pendingWriteData.push({ requestId, relativePath, value, operation });
+    this.invalidateDisplayCache();
   }
   /**
-   * Remove a pending write (on ack or nack).
+   * Remove a pending write by request ID (on ack or nack).
+   * Returns true if the write was found and removed.
    */
   removePendingWrite(requestId) {
-    return this._pendingWrites.delete(requestId);
+    const idx = this._pendingWriteData.findIndex((w) => w.requestId === requestId);
+    if (idx === -1) return false;
+    this._pendingWriteData.splice(idx, 1);
+    this.invalidateDisplayCache();
+    return true;
   }
   /**
-   * Clear all pending writes (on nack recovery).
+   * Clear all pending writes.
    */
   clearPendingWrites() {
-    this._pendingWrites.clear();
+    if (this._pendingWriteData.length > 0) {
+      this._pendingWriteData = [];
+      this.invalidateDisplayCache();
+    }
   }
   /**
    * 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;
+    return this._pendingWriteData.some((w) => w.requestId !== "");
   }
   /**
-   * Enter recovery mode (after a nack).
+   * Get the pending write data (for debugging/testing).
    */
-  enterRecovery() {
-    this._recovering = true;
-    this.clearPendingWrites();
+  getPendingWriteData() {
+    return [...this._pendingWriteData];
   }
   /**
-   * Exit recovery mode (after fresh snapshot received).
+   * Check if a specific write is pending.
    */
-  exitRecovery() {
-    this._recovering = false;
+  isWritePending(requestId) {
+    return this._pendingWriteData.some((w) => w.requestId === requestId);
   }
   // ============================================
   // Cleanup
   // ============================================
   /**
-   * Clear the cache but preserve callbacks and pending writes.
+   * Clear the server cache but preserve callbacks and pending writes.
    * Used during reconnection.
    */
-  clearCache() {
-    this._cache = void 0;
-    this._orderedChildren = [];
+  clearServerCache() {
+    this._serverCache = null;
     this._hasReceivedInitialSnapshot = false;
+    this.invalidateDisplayCache();
   }
   /**
    * Clear everything - used when unsubscribing completely.
    */
   clear() {
     this.eventCallbacks.clear();
-    this._cache = void 0;
+    this._serverCache = null;
     this._orderedChildren = [];
     this._hasReceivedInitialSnapshot = false;
-    this._pendingWrites.clear();
-    this._recovering = false;
+    this._pendingWriteData = [];
+    this._displayCacheValid = false;
+    this._displayCache = null;
   }
 };
 
 // src/connection/SubscriptionManager.ts
 var SubscriptionManager = class {
   constructor() {
-    // path -> View (one View per subscribed path)
+    // viewKey (path:queryIdentifier) -> View
+    // Each unique path+query combination gets its own View
     this.views = /* @__PURE__ */ new Map();
+    // path -> Set of queryIdentifiers for that path
+    // Used to find all Views at a path when events arrive
+    this.pathToQueryIds = /* @__PURE__ */ new Map();
+    // Tag counter for generating unique tags per non-default query
+    // Tags are client-local and used to route server events to correct View
+    this.nextTag = 1;
+    // tag -> viewKey mapping for routing tagged events
+    this.tagToViewKey = /* @__PURE__ */ new Map();
+    // viewKey -> tag mapping for unsubscribe
+    this.viewKeyToTag = /* @__PURE__ */ new Map();
     // Callback to send subscribe message to server
     this.sendSubscribe = null;
-    // Callback to send unsubscribe message to server
+    // Callback to send unsubscribe message to server (includes queryParams and tag for server to identify subscription)
     this.sendUnsubscribe = null;
     // Callback to create DataSnapshot from event data
     this.createSnapshot = null;
@@ -1249,32 +1525,73 @@ var SubscriptionManager = class {
     this.sendUnsubscribe = options.sendUnsubscribe;
     this.createSnapshot = options.createSnapshot;
   }
+  /**
+   * Create a view key from path and query identifier.
+   */
+  makeViewKey(path, queryIdentifier) {
+    return `${path}:${queryIdentifier}`;
+  }
+  /**
+   * Get all Views at a given path (across all query identifiers).
+   */
+  getViewsAtPath(path) {
+    const queryIds = this.pathToQueryIds.get(path);
+    if (!queryIds || queryIds.size === 0) {
+      return [];
+    }
+    const views = [];
+    for (const queryId of queryIds) {
+      const viewKey = this.makeViewKey(path, queryId);
+      const view = this.views.get(viewKey);
+      if (view) {
+        views.push(view);
+      }
+    }
+    return views;
+  }
   /**
    * Subscribe to events at a path.
    * Returns an unsubscribe function.
    */
-  subscribe(path, eventType, callback, queryParams) {
+  subscribe(path, eventType, callback, queryParams, queryIdentifier) {
     const normalizedPath = path;
-    let view = this.views.get(normalizedPath);
+    const queryId = queryIdentifier ?? "default";
+    const viewKey = this.makeViewKey(normalizedPath, queryId);
+    const isNonDefaultQuery = queryId !== "default";
+    let view = this.views.get(viewKey);
     const isNewView = !view;
     let queryParamsChanged = false;
+    let tag;
     if (!view) {
       view = new View(normalizedPath, queryParams);
-      this.views.set(normalizedPath, view);
+      this.views.set(viewKey, view);
+      if (!this.pathToQueryIds.has(normalizedPath)) {
+        this.pathToQueryIds.set(normalizedPath, /* @__PURE__ */ new Set());
+      }
+      this.pathToQueryIds.get(normalizedPath).add(queryId);
+      if (isNonDefaultQuery) {
+        tag = this.nextTag++;
+        this.tagToViewKey.set(tag, viewKey);
+        this.viewKeyToTag.set(viewKey, tag);
+      }
     } else {
       queryParamsChanged = view.updateQueryParams(queryParams);
+      tag = this.viewKeyToTag.get(viewKey);
     }
     const existingEventTypes = view.getEventTypes();
     const isNewEventType = !existingEventTypes.includes(eventType);
     const unsubscribe = view.addCallback(eventType, callback);
     const wrappedUnsubscribe = () => {
-      this.unsubscribeCallback(normalizedPath, eventType, callback);
+      this.unsubscribeCallback(normalizedPath, eventType, callback, queryId);
     };
     if (isNewView || isNewEventType || queryParamsChanged) {
-      const allEventTypes = view.getEventTypes();
-      this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0).catch((err) => {
-        console.error("Failed to subscribe:", err);
-      });
+      const hasAncestorComplete = this.hasAncestorCompleteView(normalizedPath);
+      if (!hasAncestorComplete) {
+        const allEventTypes = view.getEventTypes();
+        this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0, tag).catch((err) => {
+          console.error("Failed to subscribe:", err);
+        });
+      }
     }
     if (!isNewView && view.hasReceivedInitialSnapshot) {
       this.fireInitialEventsToCallback(view, eventType, callback);
@@ -1288,7 +1605,7 @@ var SubscriptionManager = class {
   fireInitialEventsToCallback(view, eventType, callback) {
     const cache = view.getCache();
     if (eventType === "value") {
-      const snapshot = this.createSnapshot?.(view.path, cache, false);
+      const snapshot = this.createSnapshot?.(view.path, cache, false, void 0, view.orderedChildren);
       if (snapshot) {
         try {
           callback(snapshot, void 0);
@@ -1317,49 +1634,84 @@ var SubscriptionManager = class {
   /**
    * Remove a specific callback from a subscription.
    */
-  unsubscribeCallback(path, eventType, callback) {
-    const view = this.views.get(path);
+  unsubscribeCallback(path, eventType, callback, queryIdentifier) {
+    const queryId = queryIdentifier ?? "default";
+    const viewKey = this.makeViewKey(path, queryId);
+    const view = this.views.get(viewKey);
     if (!view) return;
+    const queryParams = view.queryParams ?? void 0;
+    const tag = this.viewKeyToTag.get(viewKey);
     view.removeCallback(eventType, callback);
     if (!view.hasCallbacks()) {
-      this.views.delete(path);
-      this.sendUnsubscribe?.(path).catch((err) => {
+      this.views.delete(viewKey);
+      const queryIds = this.pathToQueryIds.get(path);
+      if (queryIds) {
+        queryIds.delete(queryId);
+        if (queryIds.size === 0) {
+          this.pathToQueryIds.delete(path);
+        }
+      }
+      if (tag !== void 0) {
+        this.tagToViewKey.delete(tag);
+        this.viewKeyToTag.delete(viewKey);
+      }
+      this.sendUnsubscribe?.(path, queryParams, tag).catch((err) => {
         console.error("Failed to unsubscribe:", err);
       });
     }
   }
   /**
    * Remove all subscriptions of a specific event type at a path.
+   * This affects ALL Views at the path (across all query identifiers).
    */
   unsubscribeEventType(path, eventType) {
     const normalizedPath = path;
-    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 = view.getEventTypes();
-      this.sendSubscribe?.(normalizedPath, remainingEventTypes, view.queryParams ?? void 0).catch((err) => {
-        console.error("Failed to update subscription:", err);
-      });
+    const queryIds = this.pathToQueryIds.get(normalizedPath);
+    if (!queryIds) return;
+    for (const queryId of Array.from(queryIds)) {
+      const viewKey = this.makeViewKey(normalizedPath, queryId);
+      const view = this.views.get(viewKey);
+      if (!view) continue;
+      const queryParams = view.queryParams ?? void 0;
+      view.removeAllCallbacks(eventType);
+      if (!view.hasCallbacks()) {
+        this.views.delete(viewKey);
+        queryIds.delete(queryId);
+        this.sendUnsubscribe?.(normalizedPath, queryParams).catch((err) => {
+          console.error("Failed to unsubscribe:", err);
+        });
+      } else {
+        const remainingEventTypes = view.getEventTypes();
+        this.sendSubscribe?.(normalizedPath, remainingEventTypes, queryParams).catch((err) => {
+          console.error("Failed to update subscription:", err);
+        });
+      }
+    }
+    if (queryIds.size === 0) {
+      this.pathToQueryIds.delete(normalizedPath);
     }
   }
   /**
    * Remove ALL subscriptions at a path.
+   * This affects ALL Views at the path (across all query identifiers).
    */
   unsubscribeAll(path) {
     const normalizedPath = path;
-    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);
-    });
+    const queryIds = this.pathToQueryIds.get(normalizedPath);
+    if (!queryIds || queryIds.size === 0) return;
+    for (const queryId of queryIds) {
+      const viewKey = this.makeViewKey(normalizedPath, queryId);
+      const view = this.views.get(viewKey);
+      if (view) {
+        const queryParams = view.queryParams ?? void 0;
+        view.clear();
+        this.views.delete(viewKey);
+        this.sendUnsubscribe?.(normalizedPath, queryParams).catch((err) => {
+          console.error("Failed to unsubscribe:", err);
+        });
+      }
+    }
+    this.pathToQueryIds.delete(normalizedPath);
   }
   /**
    * Handle an incoming event message from the server.
@@ -1376,8 +1728,17 @@ var SubscriptionManager = class {
       console.warn("Unknown event type:", message.ev);
     }
   }
+  /**
+   * Get View by tag. Returns undefined if tag not found.
+   */
+  getViewByTag(tag) {
+    const viewKey = this.tagToViewKey.get(tag);
+    if (!viewKey) return void 0;
+    return this.views.get(viewKey);
+  }
   /**
    * Handle a 'put' event - single path change.
+   * Routes to specific View by tag if present, otherwise to default View at path.
    */
   handlePutEvent(message) {
     const subscriptionPath = message.sp;
@@ -1385,21 +1746,24 @@ var SubscriptionManager = class {
     const value = message.v;
     const isVolatile = message.x ?? false;
     const serverTimestamp = message.ts;
-    const view = this.views.get(subscriptionPath);
-    if (!view) return;
+    const tag = message.tag;
     if (value === void 0) return;
-    if (view.recovering) {
-      if (relativePath !== "/") {
-        return;
+    if (tag !== void 0) {
+      const view2 = this.getViewByTag(tag);
+      if (view2) {
+        this.applyServerUpdateToView(view2, [{ relativePath, value }], isVolatile, serverTimestamp);
       }
-      this.applyWriteToView(view, [{ relativePath, value }], isVolatile, serverTimestamp);
-      view.exitRecovery();
       return;
     }
-    this.applyWriteToView(view, [{ relativePath, value }], isVolatile, serverTimestamp);
+    const defaultViewKey = this.makeViewKey(subscriptionPath, "default");
+    const view = this.views.get(defaultViewKey);
+    if (view) {
+      this.applyServerUpdateToView(view, [{ relativePath, value }], isVolatile, serverTimestamp);
+    }
   }
   /**
    * Handle a 'patch' event - multi-path change.
+   * Routes to specific View by tag if present, otherwise to default View at path.
    */
   handlePatchEvent(message) {
     const subscriptionPath = message.sp;
@@ -1407,11 +1771,7 @@ var SubscriptionManager = class {
     const patches = message.v;
     const isVolatile = message.x ?? false;
     const serverTimestamp = message.ts;
-    const view = this.views.get(subscriptionPath);
-    if (!view) return;
-    if (view.recovering) {
-      return;
-    }
+    const tag = message.tag;
     if (!patches) return;
     const updates = [];
     for (const [relativePath, patchValue] of Object.entries(patches)) {
@@ -1423,42 +1783,88 @@ var SubscriptionManager = class {
       }
       updates.push({ relativePath: fullRelativePath, value: patchValue });
     }
-    this.applyWriteToView(view, updates, isVolatile, serverTimestamp);
+    if (tag !== void 0) {
+      const view2 = this.getViewByTag(tag);
+      if (view2) {
+        this.applyServerUpdateToView(view2, updates, isVolatile, serverTimestamp);
+      }
+      return;
+    }
+    const defaultViewKey = this.makeViewKey(subscriptionPath, "default");
+    const view = this.views.get(defaultViewKey);
+    if (view) {
+      this.applyServerUpdateToView(view, updates, isVolatile, serverTimestamp);
+    }
   }
   /**
    * Handle a 'vb' (volatile batch) event - batched volatile updates across subscriptions.
    * Server batches volatile events in 50ms intervals to reduce message overhead.
    * Format: { ev: 'vb', b: { subscriptionPath: { relativePath: value } }, ts: timestamp }
+   * Dispatches to ALL Views at each subscription path.
    */
   handleVolatileBatchEvent(message) {
     const batch = message.b;
     const serverTimestamp = message.ts;
     if (!batch) return;
     for (const [subscriptionPath, updates] of Object.entries(batch)) {
-      const view = this.views.get(subscriptionPath);
-      if (!view) continue;
-      if (view.recovering) continue;
+      const views = this.getViewsAtPath(subscriptionPath);
+      if (views.length === 0) continue;
       const updatesList = [];
       for (const [relativePath, value] of Object.entries(updates)) {
         updatesList.push({ relativePath, value });
       }
-      this.applyWriteToView(view, updatesList, true, serverTimestamp);
+      for (const view of views) {
+        this.applyServerUpdateToView(view, updatesList, true, serverTimestamp);
+      }
     }
   }
   /**
-   * Detect and fire child_moved events for children that changed position.
+   * Detect and fire child_moved events for children that changed position OR sort value.
+   *
+   * Firebase fires child_moved for ANY priority/sort value change, regardless of whether
+   * the position actually changes. This is Case 2003 behavior.
+   *
+   * IMPORTANT: child_moved should only fire for children whose VALUE or PRIORITY changed.
+   * Children that are merely "displaced" by another child moving should NOT fire child_moved.
+   *
+   * @param affectedChildren - Only check these children for moves. If not provided,
+   *                           checks all children (for full snapshots where we compare values).
+   * @param previousDisplayCache - Previous display cache for comparing sort values
+   * @param currentDisplayCache - Current display cache for comparing sort values
    */
-  detectAndFireMoves(view, previousOrder, currentOrder, previousPositions, currentPositions, previousChildSet, currentChildSet, childMovedSubs, isVolatile, serverTimestamp) {
+  detectAndFireMoves(view, previousOrder, currentOrder, previousPositions, currentPositions, previousChildSet, currentChildSet, childMovedSubs, isVolatile, serverTimestamp, affectedChildren, previousDisplayCache, currentDisplayCache) {
     if (childMovedSubs.length === 0) return;
-    for (const key of currentOrder) {
+    const childrenToCheck = affectedChildren ?? new Set(currentOrder);
+    const queryParams = view.queryParams;
+    for (const key of childrenToCheck) {
       if (!previousChildSet.has(key) || !currentChildSet.has(key)) {
         continue;
       }
       const oldPos = previousPositions.get(key);
       const newPos = currentPositions.get(key);
+      if (oldPos === void 0 || newPos === void 0) {
+        continue;
+      }
       const oldPrevKey = oldPos > 0 ? previousOrder[oldPos - 1] : null;
       const newPrevKey = newPos > 0 ? currentOrder[newPos - 1] : null;
-      if (oldPrevKey !== newPrevKey) {
+      let positionChanged = oldPrevKey !== newPrevKey;
+      let sortValueChanged = false;
+      let isPriorityOrdering = false;
+      if (previousDisplayCache && currentDisplayCache) {
+        const prevValue = previousDisplayCache[key];
+        const currValue = currentDisplayCache[key];
+        const prevSortValue = getSortValue(prevValue, queryParams);
+        const currSortValue = getSortValue(currValue, queryParams);
+        sortValueChanged = JSON.stringify(prevSortValue) !== JSON.stringify(currSortValue);
+        isPriorityOrdering = !queryParams?.orderBy || queryParams.orderBy === "priority";
+      }
+      let shouldFire;
+      if (affectedChildren) {
+        shouldFire = positionChanged || isPriorityOrdering && sortValueChanged;
+      } else {
+        shouldFire = isPriorityOrdering && sortValueChanged;
+      }
+      if (shouldFire) {
         this.fireChildMoved(view, key, childMovedSubs, newPrevKey, isVolatile, serverTimestamp);
       }
     }
@@ -1502,10 +1908,10 @@ var SubscriptionManager = class {
   /**
    * Fire child_removed callbacks for a child key.
    */
-  fireChildRemoved(view, childKey, subs, isVolatile, serverTimestamp) {
+  fireChildRemoved(view, childKey, subs, isVolatile, serverTimestamp, previousValue) {
     if (subs.length === 0) return;
     const childPath = joinPath(view.path, childKey);
-    const snapshot = this.createSnapshot?.(childPath, null, isVolatile, serverTimestamp);
+    const snapshot = this.createSnapshot?.(childPath, previousValue ?? null, isVolatile, serverTimestamp);
     if (snapshot) {
       for (const entry of subs) {
         try {
@@ -1534,6 +1940,30 @@ var SubscriptionManager = class {
       }
     }
   }
+  /**
+   * Handle subscription revocation due to auth change.
+   * The server has already removed the subscription, so we just clean up locally.
+   * This is different from unsubscribeAll which sends an unsubscribe message.
+   */
+  handleSubscriptionRevoked(path) {
+    const normalizedPath = path;
+    const queryIds = this.pathToQueryIds.get(normalizedPath);
+    if (!queryIds || queryIds.size === 0) return;
+    for (const queryId of queryIds) {
+      const viewKey = this.makeViewKey(normalizedPath, queryId);
+      const view = this.views.get(viewKey);
+      if (view) {
+        const tag = this.viewKeyToTag.get(viewKey);
+        if (tag !== void 0) {
+          this.tagToViewKey.delete(tag);
+          this.viewKeyToTag.delete(viewKey);
+        }
+        view.clear();
+        this.views.delete(viewKey);
+      }
+    }
+    this.pathToQueryIds.delete(normalizedPath);
+  }
   /**
    * Clear all subscriptions (e.g., on disconnect).
    */
@@ -1542,68 +1972,123 @@ var SubscriptionManager = class {
       view.clear();
     }
     this.views.clear();
+    this.pathToQueryIds.clear();
+    this.tagToViewKey.clear();
+    this.viewKeyToTag.clear();
+    this.nextTag = 1;
   }
   /**
-   * Check if there are any subscriptions at a path.
+   * Check if there are any subscriptions at a path (across all query identifiers).
    */
   hasSubscriptions(path) {
-    return this.views.has(path);
+    const queryIds = this.pathToQueryIds.get(path);
+    return queryIds !== void 0 && queryIds.size > 0;
   }
   /**
-   * Check if a path is "covered" by an active subscription.
+   * Check if a path is "covered" by an active subscription that has received data.
    *
    * 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
+   * - There's an active subscription at that exact path that has data, OR
+   * - There's an active subscription at an ancestor path that has data
+   *
+   * Note: Any subscription type (value, child_added, child_moved, etc.) receives
+   * the initial snapshot from the server and thus has cached data.
    */
   isPathCovered(path) {
     const normalized = normalizePath(path);
-    if (this.hasValueSubscription(normalized)) {
+    if (this.hasActiveSubscriptionWithData(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)) {
+      if (this.hasActiveSubscriptionWithData(ancestorPath)) {
         return true;
       }
     }
-    if (normalized !== "/" && this.hasValueSubscription("/")) {
+    if (normalized !== "/" && this.hasActiveSubscriptionWithData("/")) {
       return true;
     }
     return false;
   }
   /**
-   * Check if there's a 'value' subscription at a path.
+   * Check if there's an active subscription at a path that has data.
+   * A View has data if it has received the initial snapshot OR has pending writes.
+   * Any subscription type (value, child_added, child_moved, etc.) counts.
+   */
+  hasActiveSubscriptionWithData(path) {
+    const views = this.getViewsAtPath(path);
+    return views.some((view) => view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites()));
+  }
+  /**
+   * Check if any ancestor path has a "complete" View (one that loadsAllData).
+   * A complete View has no limits and no range filters, so it contains all data
+   * for its subtree. Child subscriptions can use the ancestor's data instead
+   * of creating their own server subscription.
+   *
+   * This matches Firebase's behavior where child listeners don't need their own
+   * server subscription if an ancestor has an unlimited listener.
    */
-  hasValueSubscription(path) {
-    const view = this.views.get(path);
-    return view !== void 0 && view.hasCallbacksForType("value");
+  hasAncestorCompleteView(path) {
+    const normalized = normalizePath(path);
+    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 views = this.getViewsAtPath(ancestorPath);
+      for (const view of views) {
+        if (view.hasCallbacks() && view.loadsAllData() && view.hasReceivedInitialSnapshot) {
+          return true;
+        }
+      }
+    }
+    if (normalized !== "/") {
+      const rootViews = this.getViewsAtPath("/");
+      for (const view of rootViews) {
+        if (view.hasCallbacks() && view.loadsAllData() && view.hasReceivedInitialSnapshot) {
+          return true;
+        }
+      }
+    }
+    return false;
   }
   /**
    * Get a cached value if the path is covered by an active subscription.
+   * Returns the value from the first View that has it (typically the default/unfiltered one).
    */
   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 exactViews = this.getViewsAtPath(normalized);
+    for (const view of exactViews) {
+      const result = view.getCacheValue(normalized);
+      if (result.found) {
+        return result;
+      }
     }
     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);
+      const ancestorViews = this.getViewsAtPath(ancestorPath);
+      for (const view of ancestorViews) {
+        if (view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites())) {
+          const result = view.getCacheValue(normalized);
+          if (result.found) {
+            return result;
+          }
+        }
       }
     }
     if (normalized !== "/") {
-      const rootView = this.views.get("/");
-      if (rootView && rootView.hasCallbacksForType("value")) {
-        return rootView.getCacheValue(normalized);
+      const rootViews = this.getViewsAtPath("/");
+      for (const view of rootViews) {
+        if (view.hasCallbacks() && (view.hasReceivedInitialSnapshot || view.hasPendingWrites())) {
+          const result = view.getCacheValue(normalized);
+          if (result.found) {
+            return result;
+          }
+        }
       }
     }
     return { value: void 0, found: false };
@@ -1621,7 +2106,7 @@ var SubscriptionManager = class {
    */
   clearCacheOnly() {
     for (const view of this.views.values()) {
-      view.clearCache();
+      view.clearServerCache();
     }
   }
   /**
@@ -1629,13 +2114,13 @@ var SubscriptionManager = class {
    * Used after reconnecting to restore subscriptions on the server.
    */
   async resubscribeAll() {
-    for (const [path, view] of this.views) {
+    for (const view of this.views.values()) {
       const eventTypes = view.getEventTypes();
       if (eventTypes.length > 0) {
         try {
-          await this.sendSubscribe?.(path, eventTypes, view.queryParams ?? void 0);
+          await this.sendSubscribe?.(view.path, eventTypes, view.queryParams ?? void 0);
         } catch (err) {
-          console.error(`Failed to resubscribe to ${path}:`, err);
+          console.error(`Failed to resubscribe to ${view.path}:`, err);
         }
       }
     }
@@ -1645,18 +2130,22 @@ var SubscriptionManager = class {
    */
   getActiveSubscriptions() {
     const result = [];
-    for (const [path, view] of this.views) {
+    for (const view of this.views.values()) {
       const eventTypes = view.getEventTypes();
       const queryParams = view.queryParams ?? void 0;
-      result.push({ path, eventTypes, queryParams });
+      result.push({ path: view.path, eventTypes, queryParams });
     }
     return result;
   }
   /**
    * Get a View by path (for testing/debugging).
+   * Returns the first View at this path (default query identifier).
    */
   getView(path) {
-    return this.views.get(path);
+    const defaultView = this.views.get(this.makeViewKey(path, "default"));
+    if (defaultView) return defaultView;
+    const views = this.getViewsAtPath(path);
+    return views.length > 0 ? views[0] : void 0;
   }
   // ============================================
   // Shared Write Application (used by server events and optimistic writes)
@@ -1698,19 +2187,22 @@ var SubscriptionManager = class {
    * @param isVolatile - Whether this is a volatile update
    * @param serverTimestamp - Optional server timestamp
    */
-  applyWriteToView(view, updates, isVolatile, serverTimestamp) {
+  applyServerUpdateToView(view, updates, isVolatile, serverTimestamp) {
     const previousOrder = view.orderedChildren;
     const previousChildSet = new Set(previousOrder);
-    const isFirstSnapshot = !view.hasReceivedInitialSnapshot;
+    const isFirstSnapshot = !view.hasReceivedInitialSnapshot && !view.hasPendingWrites();
     let previousCacheJson = null;
+    let previousDisplayCache = null;
     if (!isVolatile) {
-      previousCacheJson = this.serializeCacheForComparison(view.getCache());
+      const cache = view.getDisplayCache();
+      previousDisplayCache = cache && typeof cache === "object" && !Array.isArray(cache) ? cache : null;
+      previousCacheJson = this.serializeCacheForComparison(cache);
     }
     const affectedChildren = /* @__PURE__ */ new Set();
     let isFullSnapshot = false;
     for (const { relativePath, value } of updates) {
       if (relativePath === "/") {
-        view.setCache(value);
+        view.setServerCache(value);
         isFullSnapshot = true;
       } else {
         const segments = relativePath.split("/").filter((s) => s.length > 0);
@@ -1718,24 +2210,24 @@ var SubscriptionManager = class {
           affectedChildren.add(segments[0]);
         }
         if (value === null) {
-          view.removeCacheChild(relativePath);
+          view.removeServerCacheChild(relativePath);
         } else {
-          view.updateCacheChild(relativePath, value);
+          view.updateServerCacheChild(relativePath, value);
         }
       }
     }
     const currentOrder = view.orderedChildren;
     const currentChildSet = new Set(currentOrder);
     if (!isVolatile && !isFirstSnapshot && previousCacheJson !== null) {
-      const currentCacheJson = this.serializeCacheForComparison(view.getCache());
+      const currentCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
       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);
+      const fullValue = view.getDisplayCache();
+      const snapshot = this.createSnapshot?.(view.path, fullValue, isVolatile, serverTimestamp, view.orderedChildren);
       if (snapshot) {
         for (const entry of valueSubs) {
           try {
@@ -1762,7 +2254,8 @@ var SubscriptionManager = class {
       }
       for (const key of previousOrder) {
         if (!currentChildSet.has(key)) {
-          this.fireChildRemoved(view, key, childRemovedSubs, isVolatile, serverTimestamp);
+          const prevValue = previousDisplayCache?.[key];
+          this.fireChildRemoved(view, key, childRemovedSubs, isVolatile, serverTimestamp, prevValue);
         }
       }
     } else {
@@ -1773,7 +2266,8 @@ var SubscriptionManager = class {
           const prevKey = view.getPreviousChildKey(childKey);
           this.fireChildAdded(view, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
         } else if (wasPresent && !isPresent) {
-          this.fireChildRemoved(view, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+          const prevValue = previousDisplayCache?.[childKey];
+          this.fireChildRemoved(view, childKey, childRemovedSubs, isVolatile, serverTimestamp, prevValue);
         } else if (wasPresent && isPresent) {
           const prevKey = view.getPreviousChildKey(childKey);
           this.fireChildChanged(view, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
@@ -1784,6 +2278,8 @@ var SubscriptionManager = class {
     previousOrder.forEach((key, idx) => previousPositions.set(key, idx));
     const currentPositions = /* @__PURE__ */ new Map();
     currentOrder.forEach((key, idx) => currentPositions.set(key, idx));
+    const currentCache = view.getDisplayCache();
+    const currentDisplayCache = currentCache && typeof currentCache === "object" && !Array.isArray(currentCache) ? currentCache : null;
     this.detectAndFireMoves(
       view,
       previousOrder,
@@ -1794,7 +2290,10 @@ var SubscriptionManager = class {
       currentChildSet,
       childMovedSubs,
       isVolatile,
-      serverTimestamp
+      serverTimestamp,
+      isFullSnapshot ? void 0 : affectedChildren,
+      previousDisplayCache,
+      currentDisplayCache
     );
   }
   // ============================================
@@ -1807,13 +2306,18 @@ var SubscriptionManager = class {
   findViewsForWritePath(writePath) {
     const normalized = normalizePath(writePath);
     const views = [];
-    for (const [viewPath, view] of this.views) {
+    for (const view of this.views.values()) {
+      const viewPath = view.path;
       if (normalized === viewPath) {
         views.push(view);
       } else if (normalized.startsWith(viewPath + "/")) {
         views.push(view);
+      } else if (viewPath.startsWith(normalized + "/")) {
+        views.push(view);
       } else if (viewPath === "/") {
         views.push(view);
+      } else if (normalized === "/") {
+        views.push(view);
       }
     }
     return views;
@@ -1835,59 +2339,135 @@ var SubscriptionManager = class {
   /**
    * Track a pending write for all Views that cover the write path.
    */
-  trackPendingWrite(writePath, requestId) {
-    const views = this.findViewsForWritePath(writePath);
-    for (const view of views) {
-      view.addPendingWrite(requestId);
-    }
+  /**
+   * Track a pending write by request ID.
+   * Note: With the dual-cache system, this is now handled by applyOptimisticWrite
+   * via addPendingWriteData. This method is kept for API compatibility but is a no-op.
+   */
+  trackPendingWrite(_writePath, _requestId) {
   }
   /**
    * Clear a pending write from all Views (on ack).
+   * Fires callbacks only if displayCache changed (e.g., server modified the data).
+   * With PUT-before-ACK ordering, this handles the case where server data differs from optimistic.
    */
   clearPendingWrite(requestId) {
     for (const view of this.views.values()) {
+      if (!view.isWritePending(requestId)) {
+        continue;
+      }
+      const previousDisplayCache = view.getDisplayCache();
+      const previousCacheJson = this.serializeCacheForComparison(previousDisplayCache);
+      const previousOrder = view.orderedChildren;
+      const previousChildSet = new Set(previousOrder);
       view.removePendingWrite(requestId);
-    }
+      const currentCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
+      if (previousCacheJson === currentCacheJson) {
+        continue;
+      }
+      const currentOrder = view.orderedChildren;
+      const currentChildSet = new Set(currentOrder);
+      const valueSubs = view.getCallbacks("value");
+      if (valueSubs.length > 0) {
+        const fullValue = view.getDisplayCache();
+        const snapshot = this.createSnapshot?.(view.path, fullValue, false, void 0, view.orderedChildren);
+        if (snapshot) {
+          for (const entry of valueSubs) {
+            try {
+              entry.callback(snapshot, void 0);
+            } catch (err) {
+              console.error("Error in value subscription callback:", err);
+            }
+          }
+        }
+      }
+      this.fireChildEventsForAck(view, previousOrder, previousChildSet, currentOrder, currentChildSet, previousDisplayCache);
+    }
   }
   /**
-   * 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.
+   * Fire child events for ACK handling, skipping child_moved.
+   * This is a variant of fireChildEvents that doesn't fire moves because:
+   * 1. Moves were already fired optimistically
+   * 2. If server modifies data, PUT event will fire correct moves
+   * 3. ACK can arrive before PUT, causing incorrect intermediate state
    */
-  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);
+  fireChildEventsForAck(view, previousOrder, previousChildSet, currentOrder, currentChildSet, previousDisplayCache) {
+    const childAddedSubs = view.getCallbacks("child_added");
+    const childChangedSubs = view.getCallbacks("child_changed");
+    const childRemovedSubs = view.getCallbacks("child_removed");
+    if (childAddedSubs.length === 0 && childChangedSubs.length === 0 && childRemovedSubs.length === 0) {
+      return;
+    }
+    const displayCache = view.getDisplayCache();
+    for (const key of currentOrder) {
+      if (!previousChildSet.has(key)) {
+        if (childAddedSubs.length > 0 && displayCache) {
+          const prevKey = view.getPreviousChildKey(key);
+          this.fireChildAdded(view, key, childAddedSubs, prevKey, false, void 0);
+        }
+      } else if (previousDisplayCache && childChangedSubs.length > 0 && displayCache) {
+        const prevValue = previousDisplayCache[key];
+        const currentValue = displayCache[key];
+        const prevJson = this.serializeCacheForComparison(prevValue);
+        const currJson = this.serializeCacheForComparison(currentValue);
+        if (prevJson !== currJson) {
+          const prevKey = view.getPreviousChildKey(key);
+          this.fireChildChanged(view, key, childChangedSubs, prevKey, false, void 0);
         }
       }
     }
-    for (const view of affectedViews) {
-      view.enterRecovery();
+    for (const key of previousOrder) {
+      if (!currentChildSet.has(key)) {
+        if (childRemovedSubs.length > 0) {
+          const prevValue = previousDisplayCache?.[key];
+          this.fireChildRemoved(view, key, childRemovedSubs, false, void 0, prevValue);
+        }
+      }
     }
-    return { affectedViews, taintedIds: Array.from(taintedIds) };
   }
   /**
-   * Check if any View covering a path is in recovery mode.
+   * 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.
    */
-  isPathInRecovery(writePath) {
-    const views = this.findViewsForWritePath(writePath);
-    return views.some((view) => view.recovering);
-  }
   /**
-   * Re-subscribe a specific View to get a fresh snapshot.
-   * Used during recovery after a nack.
+   * Handle a write NACK by removing the pending write from affected Views.
+   * With the dual-cache system, this automatically reverts to server truth.
+   * Returns the affected Views so callbacks can be fired if data changed.
    */
-  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);
+  handleWriteNack(requestId) {
+    const affectedViews = [];
+    for (const view of this.views.values()) {
+      if (view.isWritePending(requestId)) {
+        const previousDisplayCache = view.getDisplayCache();
+        const previousCacheJson = this.serializeCacheForComparison(previousDisplayCache);
+        const previousOrder = view.orderedChildren;
+        const previousChildSet = new Set(previousOrder);
+        view.removePendingWrite(requestId);
+        const currentCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
+        if (previousCacheJson !== currentCacheJson) {
+          affectedViews.push(view);
+          const currentOrder = view.orderedChildren;
+          const currentChildSet = new Set(currentOrder);
+          const valueSubs = view.getCallbacks("value");
+          if (valueSubs.length > 0) {
+            const fullValue = view.getDisplayCache();
+            const snapshot = this.createSnapshot?.(view.path, fullValue, false, void 0, view.orderedChildren);
+            if (snapshot) {
+              for (const entry of valueSubs) {
+                try {
+                  entry.callback(snapshot, void 0);
+                } catch (err) {
+                  console.error("Error in value subscription callback:", err);
+                }
+              }
+            }
+          }
+          this.fireChildEvents(view, previousOrder, previousChildSet, currentOrder, currentChildSet, "/", false, void 0, previousDisplayCache);
+        }
+      }
     }
+    return affectedViews;
   }
   // ============================================
   // Optimistic Writes (for local-first)
@@ -1910,34 +2490,262 @@ var SubscriptionManager = class {
     }
     const updatedViews = [];
     for (const view of affectedViews) {
-      if (!view.hasReceivedInitialSnapshot) {
-        continue;
-      }
       let relativePath;
+      let effectiveValue = value;
       if (normalized === view.path) {
         relativePath = "/";
       } else if (view.path === "/") {
         relativePath = normalized;
-      } else {
+      } else if (normalized.startsWith(view.path + "/")) {
         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 if (view.path.startsWith(normalized + "/")) {
+        const pathDiff = view.path.slice(normalized.length);
+        effectiveValue = getValueAtPath(value, pathDiff);
+        if (operation === "update" && effectiveValue === void 0) {
+          continue;
         }
+        relativePath = "/";
       } else {
-        updates.push({ relativePath, value });
+        continue;
+      }
+      const previousDisplayCache = view.getDisplayCache();
+      const previousOrder = view.orderedChildren;
+      const previousChildSet = new Set(previousOrder);
+      const previousCacheJson = this.serializeCacheForComparison(previousDisplayCache);
+      view.addPendingWriteData(requestId, relativePath, effectiveValue, operation);
+      const currentOrder = view.orderedChildren;
+      const currentChildSet = new Set(currentOrder);
+      const currentCacheJson = this.serializeCacheForComparison(view.getDisplayCache());
+      if (previousCacheJson === currentCacheJson) {
+        continue;
       }
-      this.applyWriteToView(view, updates, false, void 0);
       updatedViews.push(view);
+      const valueSubs = view.getCallbacks("value");
+      if (valueSubs.length > 0) {
+        const fullValue = view.getDisplayCache();
+        const snapshot = this.createSnapshot?.(view.path, fullValue, false, void 0, view.orderedChildren);
+        if (snapshot) {
+          for (const entry of valueSubs) {
+            try {
+              entry.callback(snapshot, void 0);
+            } catch (err) {
+              console.error("Error in value subscription callback:", err);
+            }
+          }
+        }
+      }
+      this.fireChildEvents(view, previousOrder, previousChildSet, currentOrder, currentChildSet, relativePath, false, void 0, previousDisplayCache);
     }
     return updatedViews;
   }
+  /**
+   * Fire child_added/child_changed/child_removed/child_moved events.
+   * Extracted as helper since it's used by both server updates and optimistic writes.
+   */
+  fireChildEvents(view, previousOrder, previousChildSet, currentOrder, currentChildSet, affectedPath, isVolatile, serverTimestamp, previousDisplayCache) {
+    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;
+    }
+    const displayCache = view.getDisplayCache();
+    const affectedChildren = /* @__PURE__ */ new Set();
+    if (affectedPath !== "/") {
+      const segments = affectedPath.split("/").filter((s) => s.length > 0);
+      if (segments.length > 0) {
+        affectedChildren.add(segments[0]);
+      }
+    }
+    const isFullSnapshot = affectedPath === "/";
+    if (isFullSnapshot) {
+      for (const key of currentOrder) {
+        if (!previousChildSet.has(key)) {
+          if (childAddedSubs.length > 0 && displayCache) {
+            const childValue = displayCache[key];
+            const snapshot = this.createSnapshot?.(
+              joinPath(view.path, key),
+              childValue,
+              isVolatile,
+              serverTimestamp
+            );
+            if (snapshot) {
+              const prevKey = view.getPreviousChildKey(key);
+              for (const entry of childAddedSubs) {
+                try {
+                  entry.callback(snapshot, prevKey);
+                } catch (err) {
+                  console.error("Error in child_added callback:", err);
+                }
+              }
+            }
+          }
+        } else if (previousDisplayCache && childChangedSubs.length > 0 && displayCache) {
+          const prevValue = previousDisplayCache[key];
+          const currentValue = displayCache[key];
+          const prevJson = this.serializeCacheForComparison(prevValue);
+          const currJson = this.serializeCacheForComparison(currentValue);
+          if (prevJson !== currJson) {
+            const snapshot = this.createSnapshot?.(
+              joinPath(view.path, key),
+              currentValue,
+              isVolatile,
+              serverTimestamp
+            );
+            if (snapshot) {
+              const prevKey = view.getPreviousChildKey(key);
+              for (const entry of childChangedSubs) {
+                try {
+                  entry.callback(snapshot, prevKey);
+                } catch (err) {
+                  console.error("Error in child_changed callback:", err);
+                }
+              }
+            }
+          }
+        }
+      }
+      for (const key of previousOrder) {
+        if (!currentChildSet.has(key)) {
+          if (childRemovedSubs.length > 0) {
+            const prevValue = previousDisplayCache?.[key];
+            const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue ?? null, isVolatile, serverTimestamp);
+            if (snapshot) {
+              for (const entry of childRemovedSubs) {
+                try {
+                  entry.callback(snapshot, void 0);
+                } catch (err) {
+                  console.error("Error in child_removed callback:", err);
+                }
+              }
+            }
+          }
+        }
+      }
+    } else {
+      if (childRemovedSubs.length > 0) {
+        for (const key of previousOrder) {
+          if (affectedChildren.has(key)) continue;
+          if (currentChildSet.has(key)) continue;
+          const prevValue = previousDisplayCache ? previousDisplayCache[key] : null;
+          const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue, isVolatile, serverTimestamp);
+          if (snapshot) {
+            for (const entry of childRemovedSubs) {
+              try {
+                entry.callback(snapshot, void 0);
+              } catch (err) {
+                console.error("Error in child_removed callback:", err);
+              }
+            }
+          }
+        }
+      }
+      for (const key of affectedChildren) {
+        const wasPresent = previousChildSet.has(key);
+        const isPresent = currentChildSet.has(key);
+        if (!wasPresent && isPresent) {
+          if (childAddedSubs.length > 0 && displayCache) {
+            const childValue = displayCache[key];
+            const snapshot = this.createSnapshot?.(
+              joinPath(view.path, key),
+              childValue,
+              isVolatile,
+              serverTimestamp
+            );
+            if (snapshot) {
+              const prevKey = view.getPreviousChildKey(key);
+              for (const entry of childAddedSubs) {
+                try {
+                  entry.callback(snapshot, prevKey);
+                } catch (err) {
+                  console.error("Error in child_added callback:", err);
+                }
+              }
+            }
+          }
+        } else if (wasPresent && !isPresent) {
+          if (childRemovedSubs.length > 0) {
+            const prevValue = previousDisplayCache ? previousDisplayCache[key] : null;
+            const snapshot = this.createSnapshot?.(joinPath(view.path, key), prevValue, isVolatile, serverTimestamp);
+            if (snapshot) {
+              for (const entry of childRemovedSubs) {
+                try {
+                  entry.callback(snapshot, void 0);
+                } catch (err) {
+                  console.error("Error in child_removed callback:", err);
+                }
+              }
+            }
+          }
+        } else if (wasPresent && isPresent) {
+          if (childChangedSubs.length > 0 && displayCache) {
+            const childValue = displayCache[key];
+            const snapshot = this.createSnapshot?.(
+              joinPath(view.path, key),
+              childValue,
+              isVolatile,
+              serverTimestamp
+            );
+            if (snapshot) {
+              const prevKey = view.getPreviousChildKey(key);
+              for (const entry of childChangedSubs) {
+                try {
+                  entry.callback(snapshot, prevKey);
+                } catch (err) {
+                  console.error("Error in child_changed callback:", err);
+                }
+              }
+            }
+          }
+        }
+      }
+      if (childAddedSubs.length > 0 && displayCache) {
+        for (const key of currentOrder) {
+          if (previousChildSet.has(key)) continue;
+          if (affectedChildren.has(key)) continue;
+          const childValue = displayCache[key];
+          const snapshot = this.createSnapshot?.(
+            joinPath(view.path, key),
+            childValue,
+            isVolatile,
+            serverTimestamp
+          );
+          if (snapshot) {
+            const prevKey = view.getPreviousChildKey(key);
+            for (const entry of childAddedSubs) {
+              try {
+                entry.callback(snapshot, prevKey);
+              } catch (err) {
+                console.error("Error in child_added callback:", err);
+              }
+            }
+          }
+        }
+      }
+    }
+    if (childMovedSubs.length > 0) {
+      const previousPositions = /* @__PURE__ */ new Map();
+      previousOrder.forEach((key, i) => previousPositions.set(key, i));
+      const currentPositions = /* @__PURE__ */ new Map();
+      currentOrder.forEach((key, i) => currentPositions.set(key, i));
+      this.detectAndFireMoves(
+        view,
+        previousOrder,
+        currentOrder,
+        previousPositions,
+        currentPositions,
+        previousChildSet,
+        currentChildSet,
+        childMovedSubs,
+        isVolatile,
+        serverTimestamp,
+        isFullSnapshot ? void 0 : affectedChildren,
+        previousDisplayCache,
+        displayCache
+      );
+    }
+  }
 };
 
 // src/OnDisconnect.ts
@@ -2044,7 +2852,37 @@ function generatePushId() {
 }
 
 // src/DatabaseReference.ts
+function isInfoPath(path) {
+  return path === "/.info" || path.startsWith("/.info/");
+}
+function validateNotInfoPath(path, operation) {
+  if (isInfoPath(path)) {
+    throw new LarkError(
+      ErrorCode.INVALID_PATH,
+      `Cannot ${operation} on .info paths - they are read-only system paths`
+    );
+  }
+}
 var DEFAULT_MAX_RETRIES = 25;
+var WIRE_PROTOCOL_CONSTANTS = {
+  INDEX_START_VALUE: "sp",
+  INDEX_START_NAME: "sn",
+  INDEX_START_IS_INCLUSIVE: "sin",
+  INDEX_END_VALUE: "ep",
+  INDEX_END_NAME: "en",
+  INDEX_END_IS_INCLUSIVE: "ein",
+  LIMIT: "l",
+  VIEW_FROM: "vf",
+  INDEX: "i"
+};
+function objectToUniqueKey(obj) {
+  const sortedKeys = Object.keys(obj).sort();
+  const sorted = {};
+  for (const key of sortedKeys) {
+    sorted[key] = obj[key];
+  }
+  return JSON.stringify(sorted);
+}
 var DatabaseReference = class _DatabaseReference {
   constructor(db, path, query = {}) {
     this._db = db;
@@ -2077,6 +2915,110 @@ var DatabaseReference = class _DatabaseReference {
   get root() {
     return new _DatabaseReference(this._db, "");
   }
+  /**
+   * Get the LarkDatabase instance this reference belongs to.
+   */
+  get database() {
+    return this._db;
+  }
+  /**
+   * Get the underlying reference for a query.
+   * For queries (created via orderBy*, limitTo*, startAt, etc.), this returns
+   * a reference to the same path without query constraints.
+   * For non-query references, this returns the reference itself.
+   * This matches Firebase's Query.ref behavior.
+   */
+  get ref() {
+    if (Object.keys(this._query).length === 0) {
+      return this;
+    }
+    return new _DatabaseReference(this._db, this._path);
+  }
+  /**
+   * Check if this reference/query is equal to another.
+   * Two references are equal if they have the same database, path, and query constraints.
+   */
+  isEqual(other) {
+    if (!other) return false;
+    if (this._db !== other._db) return false;
+    if (this._path !== other._path) return false;
+    return JSON.stringify(this._query) === JSON.stringify(other._query);
+  }
+  /**
+   * Get the unique identifier for this query's parameters.
+   * Used to differentiate multiple queries on the same path.
+   *
+   * Returns "default" for non-query references (no constraints).
+   * Returns a sorted JSON string of wire-format params for queries.
+   *
+   * This matches Firebase's queryIdentifier format for wire compatibility.
+   */
+  get queryIdentifier() {
+    const queryObj = {};
+    if (this._query.orderBy === "key") {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX] = ".key";
+    } else if (this._query.orderBy === "value") {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX] = ".value";
+    } else if (this._query.orderBy === "priority") {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX] = ".priority";
+    } else if (this._query.orderBy === "child" && this._query.orderByChildPath) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX] = this._query.orderByChildPath;
+    }
+    if (this._query.startAt !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAt.value ?? null;
+      if (this._query.startAt.key !== void 0) {
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_NAME] = this._query.startAt.key;
+      }
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_IS_INCLUSIVE] = true;
+    } else if (this._query.startAfter !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.startAfter.value ?? null;
+      if (this._query.startAfter.key !== void 0) {
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_NAME] = this._query.startAfter.key;
+      }
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_IS_INCLUSIVE] = false;
+    }
+    if (this._query.endAt !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endAt.value ?? null;
+      if (this._query.endAt.key !== void 0) {
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_NAME] = this._query.endAt.key;
+      }
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_IS_INCLUSIVE] = true;
+    } else if (this._query.endBefore !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.endBefore.value ?? null;
+      if (this._query.endBefore.key !== void 0) {
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_NAME] = this._query.endBefore.key;
+      }
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_IS_INCLUSIVE] = false;
+    }
+    if (this._query.equalTo !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_VALUE] = this._query.equalTo.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_VALUE] = this._query.equalTo.value;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_IS_INCLUSIVE] = true;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_IS_INCLUSIVE] = true;
+      if (this._query.equalTo.key !== void 0) {
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_START_NAME] = this._query.equalTo.key;
+        queryObj[WIRE_PROTOCOL_CONSTANTS.INDEX_END_NAME] = this._query.equalTo.key;
+      }
+    }
+    if (this._query.limitToFirst !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.LIMIT] = this._query.limitToFirst;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.VIEW_FROM] = "l";
+    } else if (this._query.limitToLast !== void 0) {
+      queryObj[WIRE_PROTOCOL_CONSTANTS.LIMIT] = this._query.limitToLast;
+      queryObj[WIRE_PROTOCOL_CONSTANTS.VIEW_FROM] = "r";
+    }
+    if (Object.keys(queryObj).length === 0) {
+      return "default";
+    }
+    return objectToUniqueKey(queryObj);
+  }
+  /**
+   * Get the data at this location. Alias for once('value').
+   * This is Firebase's newer API for reading data.
+   */
+  async get() {
+    return this.once("value");
+  }
   // ============================================
   // Navigation
   // ============================================
@@ -2095,8 +3037,11 @@ var DatabaseReference = class _DatabaseReference {
    *
    * For volatile paths (high-frequency updates), this is fire-and-forget
    * and resolves immediately without waiting for server confirmation.
+   *
+   * @param value - The value to write
    */
   async set(value) {
+    validateNotInfoPath(this._path, "set");
     if (this._db.isVolatilePath(this._path)) {
       this._db._sendVolatileSet(this._path, value);
       return;
@@ -2121,8 +3066,11 @@ var DatabaseReference = class _DatabaseReference {
    *   '/leaderboard/alice': null  // null = delete
    * });
    * ```
+   *
+   * @param values - The values to update
    */
   async update(values) {
+    validateNotInfoPath(this._path, "update");
     const hasPathKeys = Object.keys(values).some((key) => key.startsWith("/"));
     if (hasPathKeys) {
       const ops = [];
@@ -2150,59 +3098,84 @@ var DatabaseReference = class _DatabaseReference {
    * For volatile paths, this is fire-and-forget.
    */
   async remove() {
+    validateNotInfoPath(this._path, "remove");
     if (this._db.isVolatilePath(this._path)) {
       this._db._sendVolatileDelete(this._path);
       return;
     }
     await this._db._sendDelete(this._path);
   }
-  /**
-   * Generate a new child location with a unique key and optionally set its value.
-   *
-   * If value is provided, sets the value and returns a Promise that resolves
-   * to the new reference.
-   *
-   * If no value is provided, returns a reference immediately with a client-generated
-   * push key (you can then call set() on it).
-   */
   push(value) {
+    validateNotInfoPath(this._path, "push");
     const key = generatePushId();
     const childRef = this.child(key);
     if (value === void 0) {
-      return childRef;
+      return new ThenableReference(this._db, childRef.path);
     }
-    return childRef.set(value).then(() => childRef);
+    const setPromise = childRef.set(value);
+    const writePromise = setPromise.then(() => childRef);
+    return new ThenableReference(this._db, childRef.path, writePromise);
   }
   /**
    * Set the data with a priority value for ordering.
-   * Priority is injected as `.priority` into the value object.
+   *
+   * For objects: injects `.priority` into the value object.
+   * For primitives: wraps as `{ '.value': primitive, '.priority': priority }`.
+   *
+   * This follows Firebase's wire format for primitives with priority.
+   *
+   * @param value - The value to write
+   * @param priority - The priority for ordering
    */
   async setWithPriority(value, priority) {
+    validateNotInfoPath(this._path, "setWithPriority");
     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 wrappedValue = { ".value": value, ".priority": priority };
+      await this._db._sendSet(this._path, wrappedValue);
+      return;
     }
     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) {
-    const snapshot = await this.once();
-    const currentVal = snapshot.val();
-    if (currentVal === null || currentVal === void 0) {
-      await this._db._sendSet(this._path, { ".priority": priority });
-      return;
+   * Uses cached value for optimistic behavior (local effects are immediate).
+   * The optimistic update happens synchronously, Promise resolves after server ack.
+   */
+  setPriority(priority) {
+    validateNotInfoPath(this._path, "setPriority");
+    const { value: cachedValue, found } = this._db._getCachedValue(this._path);
+    if (!found) {
+      return this.once().then((snapshot) => {
+        const actualValue2 = snapshot.val();
+        if (actualValue2 === null || actualValue2 === void 0) {
+          return this._db._sendSet(this._path, { ".priority": priority });
+        }
+        return this.setWithPriority(actualValue2, priority);
+      });
     }
-    if (typeof currentVal !== "object" || Array.isArray(currentVal)) {
-      throw new Error("Priority can only be set on object values");
+    let actualValue;
+    if (cachedValue === null || cachedValue === void 0) {
+      actualValue = null;
+    } else if (typeof cachedValue === "object" && !Array.isArray(cachedValue)) {
+      const obj = cachedValue;
+      if (".value" in obj && Object.keys(obj).every((k) => k === ".value" || k === ".priority")) {
+        actualValue = obj[".value"];
+      } else {
+        const { ".priority": _oldPriority, ...rest } = obj;
+        actualValue = Object.keys(rest).length > 0 ? rest : null;
+      }
+    } else {
+      actualValue = cachedValue;
     }
-    await this.setWithPriority(currentVal, priority);
+    if (actualValue === null || actualValue === void 0) {
+      return this._db._sendSet(this._path, { ".priority": priority });
+    }
+    return this.setWithPriority(actualValue, priority);
   }
   /**
    * Atomically modify the data at this location using optimistic concurrency.
@@ -2227,6 +3200,7 @@ var DatabaseReference = class _DatabaseReference {
    * @returns TransactionResult with committed status and final snapshot
    */
   async transaction(updateFunction, maxRetries = DEFAULT_MAX_RETRIES) {
+    validateNotInfoPath(this._path, "transaction");
     let retries = 0;
     while (retries < maxRetries) {
       const currentSnapshot = await this.once();
@@ -2271,12 +3245,24 @@ var DatabaseReference = class _DatabaseReference {
   // ============================================
   /**
    * Read the data at this location once.
+   *
+   * For 'value' events, this fetches data directly from the server.
+   * For child events ('child_added', 'child_changed', 'child_removed', 'child_moved'),
+   * this subscribes, waits for the first event, then unsubscribes.
+   *
+   * @param eventType - The event type
+   * @returns Promise that resolves to the DataSnapshot
    */
-  async once(eventType = "value") {
-    if (eventType !== "value") {
-      throw new Error('once() only supports "value" event type');
+  once(eventType = "value") {
+    if (eventType === "value") {
+      return this._db._sendOnce(this._path, this._buildQueryParams());
     }
-    return this._db._sendOnce(this._path, this._buildQueryParams());
+    return new Promise((resolve) => {
+      const unsubscribe = this.on(eventType, (snapshot) => {
+        unsubscribe();
+        resolve(snapshot);
+      });
+    });
   }
   // ============================================
   // Subscriptions
@@ -2286,12 +3272,18 @@ var DatabaseReference = class _DatabaseReference {
    * Returns an unsubscribe function.
    */
   on(eventType, callback) {
-    return this._db._subscribe(this._path, eventType, callback, this._buildQueryParams());
+    return this._db._subscribe(this._path, eventType, callback, this._buildQueryParams(), this.queryIdentifier);
   }
   /**
    * Unsubscribe from events.
-   * If eventType is specified, removes all listeners of that type.
-   * If no eventType, removes ALL listeners at this path.
+   *
+   * - `off()` - removes ALL listeners at this path
+   * - `off('value')` - removes all 'value' listeners at this path
+   *
+   * Note: To unsubscribe a specific callback, use the unsubscribe function
+   * returned by `on()`.
+   *
+   * @param eventType - Optional event type to unsubscribe from
    */
   off(eventType) {
     if (eventType) {
@@ -2316,6 +3308,9 @@ var DatabaseReference = class _DatabaseReference {
    * Order results by key.
    */
   orderByKey() {
+    this._validateNoOrderBy("orderByKey");
+    this._validateNoKeyParameterForOrderByKey("orderByKey");
+    this._validateStringValuesForOrderByKey("orderByKey");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "key"
@@ -2325,6 +3320,7 @@ var DatabaseReference = class _DatabaseReference {
    * Order results by priority.
    */
   orderByPriority() {
+    this._validateNoOrderBy("orderByPriority");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "priority"
@@ -2334,6 +3330,13 @@ var DatabaseReference = class _DatabaseReference {
    * Order results by a child key.
    */
   orderByChild(path) {
+    this._validateNoOrderBy("orderByChild");
+    if (path.startsWith("$") || path.includes("/$")) {
+      throw new LarkError(
+        ErrorCode.INVALID_PATH,
+        `orderByChild: Invalid path '${path}'. Paths cannot contain '$' prefix (reserved for internal use)`
+      );
+    }
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "child",
@@ -2344,6 +3347,7 @@ var DatabaseReference = class _DatabaseReference {
    * Order results by value.
    */
   orderByValue() {
+    this._validateNoOrderBy("orderByValue");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "value"
@@ -2353,6 +3357,30 @@ var DatabaseReference = class _DatabaseReference {
    * Limit to the first N results.
    */
   limitToFirst(limit) {
+    if (limit === void 0 || limit === null) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToFirst: a limit must be provided"
+      );
+    }
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToFirst: limit must be a positive integer"
+      );
+    }
+    if (this._query.limitToFirst !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToFirst: limitToFirst() cannot be called multiple times"
+      );
+    }
+    if (this._query.limitToLast !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToFirst: cannot use limitToFirst() with limitToLast()"
+      );
+    }
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       limitToFirst: limit
@@ -2362,6 +3390,30 @@ var DatabaseReference = class _DatabaseReference {
    * Limit to the last N results.
    */
   limitToLast(limit) {
+    if (limit === void 0 || limit === null) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToLast: a limit must be provided"
+      );
+    }
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToLast: limit must be a positive integer"
+      );
+    }
+    if (this._query.limitToLast !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToLast: limitToLast() cannot be called multiple times"
+      );
+    }
+    if (this._query.limitToFirst !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.limitToLast: cannot use limitToLast() with limitToFirst()"
+      );
+    }
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       limitToLast: limit
@@ -2369,30 +3421,260 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Start at a specific value/key.
+   * If no value is provided, starts at the beginning (null priority).
    */
   startAt(value, key) {
+    if (this._query.startAt !== void 0 || this._query.startAfter !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.startAt: startAt()/startAfter() cannot be called multiple times"
+      );
+    }
+    if (this._query.equalTo !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.startAt: cannot use startAt() with equalTo()"
+      );
+    }
+    this._validateQueryValue("startAt", value, key);
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       startAt: { value, key }
     });
   }
   /**
-   * End at a specific value/key.
+   * Start after a specific value/key (exclusive).
+   * Like startAt() but excludes the starting point.
+   */
+  startAfter(value, key) {
+    if (this._query.startAfter !== void 0 || this._query.startAt !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.startAfter: startAfter()/startAt() cannot be called multiple times"
+      );
+    }
+    if (this._query.equalTo !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.startAfter: cannot use startAfter() with equalTo()"
+      );
+    }
+    this._validateQueryValue("startAfter", value, key);
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      startAfter: { value, key }
+    });
+  }
+  /**
+   * End at a specific value/key.
+   * If no value is provided, ends at the end (null priority).
+   */
+  endAt(value, key) {
+    if (this._query.endAt !== void 0 || this._query.endBefore !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.endAt: endAt()/endBefore() cannot be called multiple times"
+      );
+    }
+    if (this._query.equalTo !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.endAt: cannot use endAt() with equalTo()"
+      );
+    }
+    this._validateQueryValue("endAt", value, key);
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      endAt: { value, key }
+    });
+  }
+  /**
+   * End before a specific value/key (exclusive).
+   * Like endAt() but excludes the ending point.
+   */
+  endBefore(value, key) {
+    if (this._query.endBefore !== void 0 || this._query.endAt !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.endBefore: endBefore()/endAt() cannot be called multiple times"
+      );
+    }
+    if (this._query.equalTo !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.endBefore: cannot use endBefore() with equalTo()"
+      );
+    }
+    this._validateQueryValue("endBefore", value, key);
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      endBefore: { value, key }
+    });
+  }
+  /**
+   * Filter to items equal to a specific value.
+   */
+  equalTo(value, key) {
+    if (this._query.equalTo !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.equalTo: equalTo() cannot be called multiple times"
+      );
+    }
+    if (this._query.startAt !== void 0 || this._query.startAfter !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.equalTo: cannot use equalTo() with startAt()/startAfter()"
+      );
+    }
+    if (this._query.endAt !== void 0 || this._query.endBefore !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        "Query.equalTo: cannot use equalTo() with endAt()/endBefore()"
+      );
+    }
+    this._validateQueryValue("equalTo", value, key);
+    return new _DatabaseReference(this._db, this._path, {
+      ...this._query,
+      equalTo: { value, key }
+    });
+  }
+  // ============================================
+  // Query Validation Helpers
+  // ============================================
+  /**
+   * Validate that no orderBy has been set yet.
+   */
+  _validateNoOrderBy(methodName) {
+    if (this._query.orderBy !== void 0) {
+      const existingMethod = this._query.orderBy === "child" ? `orderByChild('${this._query.orderByChildPath}')` : `orderBy${this._query.orderBy.charAt(0).toUpperCase()}${this._query.orderBy.slice(1)}()`;
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: cannot use ${methodName}() with ${existingMethod}`
+      );
+    }
+  }
+  /**
+   * Validate that no key parameter has been set on startAt/endAt/equalTo.
+   * Used when calling orderByKey() after startAt/endAt/equalTo.
+   */
+  _validateNoKeyParameterForOrderByKey(methodName) {
+    if (this._query.startAt?.key !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter in startAt()`
+      );
+    }
+    if (this._query.startAfter?.key !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter in startAfter()`
+      );
+    }
+    if (this._query.endAt?.key !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter in endAt()`
+      );
+    }
+    if (this._query.endBefore?.key !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter in endBefore()`
+      );
+    }
+    if (this._query.equalTo?.key !== void 0) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter in equalTo()`
+      );
+    }
+  }
+  /**
+   * Validate that startAt/endAt/equalTo values are strings.
+   * Used when calling orderByKey() after startAt/endAt/equalTo.
+   */
+  _validateStringValuesForOrderByKey(methodName) {
+    if (this._query.startAt !== void 0 && typeof this._query.startAt.value !== "string") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), startAt() value must be a string`
+      );
+    }
+    if (this._query.startAfter !== void 0 && typeof this._query.startAfter.value !== "string") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), startAfter() value must be a string`
+      );
+    }
+    if (this._query.endAt !== void 0 && typeof this._query.endAt.value !== "string") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), endAt() value must be a string`
+      );
+    }
+    if (this._query.endBefore !== void 0 && typeof this._query.endBefore.value !== "string") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), endBefore() value must be a string`
+      );
+    }
+    if (this._query.equalTo !== void 0 && typeof this._query.equalTo.value !== "string") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: when using orderByKey(), equalTo() value must be a string`
+      );
+    }
+  }
+  /**
+   * Validate value and key types for query methods (startAt, endAt, equalTo, etc.)
    */
-  endAt(value, key) {
-    return new _DatabaseReference(this._db, this._path, {
-      ...this._query,
-      endAt: { value, key }
-    });
+  _validateQueryValue(methodName, value, key) {
+    if (key !== void 0) {
+      this._validateKeyFormat(methodName, key);
+    }
+    if (this._query.orderBy === "key") {
+      if (typeof value !== "string") {
+        throw new LarkError(
+          ErrorCode.INVALID_QUERY,
+          `Query.${methodName}: when using orderByKey(), the value must be a string`
+        );
+      }
+      if (key !== void 0) {
+        throw new LarkError(
+          ErrorCode.INVALID_QUERY,
+          `Query.${methodName}: when using orderByKey(), you cannot specify a key parameter`
+        );
+      }
+      return;
+    }
+    if (this._query.orderBy === "priority") {
+      if (typeof value === "boolean") {
+        throw new LarkError(
+          ErrorCode.INVALID_QUERY,
+          `Query.${methodName}: when using orderByPriority(), the value must be a valid priority (null, number, or string)`
+        );
+      }
+    }
+    if (value !== null && typeof value === "object") {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: the value argument cannot be an object`
+      );
+    }
   }
   /**
-   * Filter to items equal to a specific value.
+   * Validate that a key is a valid Firebase key format.
+   * Invalid characters: . $ # [ ] /
+   * Also cannot start or end with .
    */
-  equalTo(value, key) {
-    return new _DatabaseReference(this._db, this._path, {
-      ...this._query,
-      equalTo: { value, key }
-    });
+  _validateKeyFormat(methodName, key) {
+    if (/[.#$\[\]\/]/.test(key)) {
+      throw new LarkError(
+        ErrorCode.INVALID_QUERY,
+        `Query.${methodName}: invalid key "${key}" - keys cannot contain . # $ [ ] /`
+      );
+    }
   }
   // ============================================
   // Internal Helpers
@@ -2428,21 +3710,35 @@ var DatabaseReference = class _DatabaseReference {
       hasParams = true;
     }
     if (this._query.startAt !== void 0) {
-      params.startAt = this._query.startAt.value;
+      params.startAt = this._query.startAt.value ?? null;
       if (this._query.startAt.key !== void 0) {
         params.startAtKey = this._query.startAt.key;
       }
       hasParams = true;
     }
+    if (this._query.startAfter !== void 0) {
+      params.startAfter = this._query.startAfter.value ?? null;
+      if (this._query.startAfter.key !== void 0) {
+        params.startAfterKey = this._query.startAfter.key;
+      }
+      hasParams = true;
+    }
     if (this._query.endAt !== void 0) {
-      params.endAt = this._query.endAt.value;
+      params.endAt = this._query.endAt.value ?? null;
       if (this._query.endAt.key !== void 0) {
         params.endAtKey = this._query.endAt.key;
       }
       hasParams = true;
     }
+    if (this._query.endBefore !== void 0) {
+      params.endBefore = this._query.endBefore.value ?? null;
+      if (this._query.endBefore.key !== void 0) {
+        params.endBeforeKey = this._query.endBefore.key;
+      }
+      hasParams = true;
+    }
     if (this._query.equalTo !== void 0) {
-      params.equalTo = this._query.equalTo.value;
+      params.equalTo = this._query.equalTo.value ?? null;
       if (this._query.equalTo.key !== void 0) {
         params.equalToKey = this._query.equalTo.key;
       }
@@ -2461,9 +3757,63 @@ var DatabaseReference = class _DatabaseReference {
     }
     return `${baseUrl}${this._path}`;
   }
+  /**
+   * Returns the URL for JSON serialization.
+   * This allows refs to be serialized with JSON.stringify().
+   */
+  toJSON() {
+    return this.toString();
+  }
+};
+var ThenableReference = class extends DatabaseReference {
+  constructor(db, path, promise) {
+    super(db, path);
+    this._promise = promise ?? Promise.resolve(this);
+  }
+  then(onfulfilled, onrejected) {
+    return this._promise.then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this._promise.catch(onrejected);
+  }
 };
 
 // src/DataSnapshot.ts
+function isWrappedPrimitive(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return false;
+  }
+  const keys = Object.keys(data);
+  if (keys.length === 2 && ".value" in data && ".priority" in data) {
+    return true;
+  }
+  if (keys.length === 1 && ".value" in data) {
+    return true;
+  }
+  return false;
+}
+function stripPriorityMetadata(data) {
+  if (data === null || data === void 0) {
+    return null;
+  }
+  if (typeof data !== "object") {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map(stripPriorityMetadata);
+  }
+  if (isWrappedPrimitive(data)) {
+    return stripPriorityMetadata(data[".value"]);
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === ".priority") {
+      continue;
+    }
+    result[key] = stripPriorityMetadata(value);
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
 var DataSnapshot = class _DataSnapshot {
   constructor(data, path, db, options = {}) {
     this._data = data;
@@ -2471,6 +3821,8 @@ var DataSnapshot = class _DataSnapshot {
     this._db = db;
     this._volatile = options.volatile ?? false;
     this._serverTimestamp = options.serverTimestamp ?? null;
+    this._queryParams = options.queryParams ?? null;
+    this._orderedKeys = options.orderedKeys ?? null;
   }
   /**
    * Get a DatabaseReference for the location of this snapshot.
@@ -2485,69 +3837,128 @@ var DataSnapshot = class _DataSnapshot {
     return getKey(this._path);
   }
   /**
-   * Get the data value, with `.priority` stripped if present.
-   * Priority is internal metadata and should not be visible to app code.
+   * Get the data value, with metadata stripped.
+   *
+   * - Strips `.priority` from objects (it's metadata, not user data)
+   * - Unwraps `{ '.value': x, '.priority': y }` to just `x` (wrapped primitives)
+   *
+   * @typeParam T - Optional type for the returned value. Defaults to `any`.
+   * @example
+   * ```typescript
+   * // Untyped (returns any)
+   * const data = snapshot.val();
+   *
+   * // Typed (returns User)
+   * const user = snapshot.val<User>();
+   * ```
    */
   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;
+    return stripPriorityMetadata(this._data);
   }
   /**
    * Check if data exists at this location (is not null/undefined).
+   * Returns false for priority-only nodes (only .priority, no actual value).
    */
   exists() {
-    return this._data !== null && this._data !== void 0;
+    if (this._data === null || this._data === void 0) {
+      return false;
+    }
+    if (typeof this._data === "object" && !Array.isArray(this._data)) {
+      const keys = Object.keys(this._data);
+      if (keys.length === 1 && keys[0] === ".priority") {
+        return false;
+      }
+    }
+    return true;
   }
   /**
    * Get a child snapshot at the specified path.
+   *
+   * Special handling:
+   * - `.priority` returns the priority value (Firebase compatible)
+   * - For wrapped primitives, only `.priority` returns data; other paths return null
+   * - Non-existent paths return a snapshot with val() === null (Firebase compatible)
    */
   child(path) {
     const childPath = joinPath(this._path, path);
+    if (path === ".priority") {
+      const priority = this.getPriority();
+      return new _DataSnapshot(priority, childPath, this._db, {
+        volatile: this._volatile,
+        serverTimestamp: this._serverTimestamp
+      });
+    }
+    if (isWrappedPrimitive(this._data)) {
+      return new _DataSnapshot(null, childPath, this._db, {
+        volatile: this._volatile,
+        serverTimestamp: this._serverTimestamp
+      });
+    }
     const childData = getValueAtPath(this._data, path);
-    return new _DataSnapshot(childData, childPath, this._db, {
+    return new _DataSnapshot(childData ?? null, childPath, this._db, {
       volatile: this._volatile,
       serverTimestamp: this._serverTimestamp
     });
   }
   /**
    * Check if this snapshot has any children.
+   * Excludes `.priority` metadata from consideration.
+   * Wrapped primitives have no children.
    */
   hasChildren() {
     if (typeof this._data !== "object" || this._data === null) {
       return false;
     }
-    return Object.keys(this._data).length > 0;
+    if (isWrappedPrimitive(this._data)) {
+      return false;
+    }
+    const keys = Object.keys(this._data).filter((k) => k !== ".priority");
+    return keys.length > 0;
   }
   /**
    * Check if this snapshot has a specific child.
+   * `.priority` is always accessible if it exists.
+   * Wrapped primitives have no children except `.priority`.
    */
   hasChild(path) {
+    if (path === ".priority") {
+      return this.getPriority() !== null;
+    }
+    if (isWrappedPrimitive(this._data)) {
+      return false;
+    }
     const childData = getValueAtPath(this._data, path);
     return childData !== void 0 && childData !== null;
   }
   /**
    * Get the number of children.
+   * Excludes `.priority` metadata from count.
+   * Wrapped primitives have 0 children.
    */
   numChildren() {
     if (typeof this._data !== "object" || this._data === null) {
       return 0;
     }
-    return Object.keys(this._data).length;
+    if (isWrappedPrimitive(this._data)) {
+      return 0;
+    }
+    return Object.keys(this._data).filter((k) => k !== ".priority").length;
   }
   /**
-   * Iterate over children. Return true from callback to stop iteration.
+   * Iterate over children in the correct order.
+   * Uses pre-computed orderedKeys if available (from subscription View),
+   * otherwise computes sorted keys based on query params.
+   * Excludes `.priority` metadata from iteration.
+   * Wrapped primitives have no children to iterate.
    */
   forEach(callback) {
     if (typeof this._data !== "object" || this._data === null) {
       return;
     }
-    const keys = Object.keys(this._data);
+    if (isWrappedPrimitive(this._data)) {
+      return;
+    }
+    const keys = this._orderedKeys ?? getSortedKeys(this._data, this._queryParams);
     for (const key of keys) {
       const childSnap = this.child(key);
       if (callback(childSnap) === true) {
@@ -2585,31 +3996,26 @@ var DataSnapshot = class _DataSnapshot {
     return this._serverTimestamp;
   }
   /**
-   * Export the snapshot data as JSON (alias for val()).
+   * Export the snapshot data with priority metadata intact.
+   * Unlike val(), this preserves `.value` and `.priority` wrappers.
+   * Useful for serializing data while preserving priorities.
+   *
+   * @typeParam T - Optional type for the returned value. Defaults to `any`.
+   */
+  exportVal() {
+    return this._data;
+  }
+  /**
+   * Export the snapshot data as JSON.
+   * Same as exportVal() - preserves priority metadata.
+   *
+   * @typeParam T - Optional type for the returned value. Defaults to `any`.
    */
   toJSON() {
     return this._data;
   }
 };
 
-// src/utils/jwt.ts
-function decodeJwtPayload(token) {
-  const parts = token.split(".");
-  if (parts.length !== 3) {
-    throw new Error("Invalid JWT format");
-  }
-  const payload = parts[1];
-  const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
-  let decoded;
-  if (typeof atob === "function") {
-    decoded = atob(padded);
-  } else {
-    decoded = Buffer.from(padded, "base64").toString("utf-8");
-  }
-  return JSON.parse(decoded);
-}
-
 // src/utils/volatile.ts
 function isVolatilePath(path, patterns) {
   if (!patterns || patterns.length === 0) {
@@ -2633,9 +4039,97 @@ function isVolatilePath(path, patterns) {
 }
 
 // src/LarkDatabase.ts
+function validateWriteData(data, path = "") {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return;
+  }
+  const obj = data;
+  const keys = Object.keys(obj);
+  if (".value" in obj) {
+    const otherKeys = keys.filter((k) => k !== ".value" && k !== ".priority");
+    if (otherKeys.length > 0) {
+      const location = path || "/";
+      throw new LarkError(
+        "invalid_data",
+        `Data at ${location} contains ".value" alongside other children (${otherKeys.join(", ")}). ".value" can only be used with ".priority" for primitives with priority.`
+      );
+    }
+  }
+  for (const key of keys) {
+    if (key !== ".priority" && key !== ".value") {
+      validateWriteData(obj[key], path ? `${path}/${key}` : `/${key}`);
+    }
+  }
+}
 var RECONNECT_BASE_DELAY_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
 var RECONNECT_JITTER_FACTOR = 0.5;
+function isServerValue(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && ".sv" in value;
+}
+function resolveServerValuesLocally(value, currentValue) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (isServerValue(value)) {
+    const sv = value[".sv"];
+    if (sv === "timestamp") {
+      return Date.now();
+    }
+    if (typeof sv === "object" && sv !== null && "increment" in sv) {
+      const delta = sv.increment;
+      if (typeof currentValue === "number") {
+        return currentValue + delta;
+      }
+      return delta;
+    }
+    return value;
+  }
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const result = {};
+    const currentObj = currentValue !== null && typeof currentValue === "object" && !Array.isArray(currentValue) ? currentValue : {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = resolveServerValuesLocally(val, currentObj[key]);
+    }
+    return result;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item, index) => {
+      const currentArr = Array.isArray(currentValue) ? currentValue : [];
+      return resolveServerValuesLocally(item, currentArr[index]);
+    });
+  }
+  return value;
+}
+var ServerValue = {
+  /**
+   * A placeholder value for auto-populating the current server timestamp.
+   * The server will replace this with the actual Unix timestamp in milliseconds.
+   *
+   * @example
+   * ```javascript
+   * import { ServerValue } from '@lark-sh/client';
+   * await ref.set({ createdAt: ServerValue.TIMESTAMP });
+   * // Server stores: { createdAt: 1704067200000 }
+   * ```
+   */
+  TIMESTAMP: { ".sv": "timestamp" },
+  /**
+   * Returns a placeholder value for atomically incrementing a numeric field.
+   * If the field doesn't exist or isn't a number, it's treated as 0.
+   *
+   * @param delta - The amount to increment by (can be negative to decrement)
+   * @returns A server value placeholder
+   *
+   * @example
+   * ```javascript
+   * import { ServerValue } from '@lark-sh/client';
+   * await ref.child('score').set(ServerValue.increment(10));
+   * // Atomically adds 10 to the current score
+   * ```
+   */
+  increment: (delta) => ({ ".sv": { increment: delta } })
+};
 var LarkDatabase = class {
   constructor() {
     this._state = "disconnected";
@@ -2644,6 +4138,11 @@ var LarkDatabase = class {
     this._coordinatorUrl = null;
     this._volatilePaths = [];
     this._transportType = null;
+    // Auth state
+    this._currentToken = null;
+    // Token for auth (empty string = anonymous)
+    this._isAnonymous = false;
+    // True if connected anonymously
     // Reconnection state
     this._connectionId = null;
     this._connectOptions = null;
@@ -2656,6 +4155,13 @@ var LarkDatabase = class {
     this.disconnectCallbacks = /* @__PURE__ */ new Set();
     this.errorCallbacks = /* @__PURE__ */ new Set();
     this.reconnectingCallbacks = /* @__PURE__ */ new Set();
+    this.authStateChangedCallbacks = /* @__PURE__ */ new Set();
+    // .info path subscriptions (handled locally, not sent to server)
+    this.infoSubscriptions = [];
+    // Authentication promise - resolves when auth completes, allows operations to queue
+    this.authenticationPromise = null;
+    this.authenticationResolve = null;
+    this._serverTimeOffset = 0;
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
     this.pendingWrites = new PendingWriteManager();
@@ -2664,10 +4170,11 @@ var LarkDatabase = class {
   // Connection State
   // ============================================
   /**
-   * Whether the database is currently connected.
+   * Whether the database is fully connected and authenticated.
+   * Returns true when ready to perform database operations.
    */
   get connected() {
-    return this._state === "connected";
+    return this._state === "authenticated";
   }
   /**
    * Whether the database is currently attempting to reconnect.
@@ -2710,6 +4217,13 @@ var LarkDatabase = class {
   get transportType() {
     return this._transportType;
   }
+  /**
+   * Get the estimated server time offset in milliseconds.
+   * Add this to Date.now() to get approximate server time.
+   */
+  get serverTimeOffset() {
+    return this._serverTimeOffset;
+  }
   /**
    * Check if there are any pending writes waiting for acknowledgment.
    * Useful for showing "saving..." indicators in UI.
@@ -2745,16 +4259,27 @@ var LarkDatabase = class {
     }
     this._connectOptions = options;
     this._intentionalDisconnect = false;
+    this.authenticationPromise = new Promise((resolve) => {
+      this.authenticationResolve = resolve;
+    });
     await this.performConnect(databaseId, options);
   }
   /**
    * Internal connect implementation used by both initial connect and reconnect.
+   * Implements the Join → Auth flow:
+   * 1. Connect WebSocket
+   * 2. Send join (identifies database)
+   * 3. Send auth (authenticates user - required even for anonymous)
    */
   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;
+    if (!isReconnect) {
+      this._currentToken = options.token || "";
+      this._isAnonymous = !options.token && options.anonymous !== false;
+    }
     try {
       const coordinatorUrl = this._coordinatorUrl;
       const coordinator = new Coordinator(coordinatorUrl);
@@ -2780,27 +4305,45 @@ var LarkDatabase = class {
       );
       this.transport = transportResult.transport;
       this._transportType = transportResult.type;
-      const requestId = this.messageQueue.nextRequestId();
+      this._state = "connected";
+      const joinRequestId = this.messageQueue.nextRequestId();
       const joinMessage = {
         o: "j",
-        t: connectResponse.token,
-        r: requestId
+        d: databaseId,
+        r: joinRequestId
       };
       if (this._connectionId) {
         joinMessage.pcid = this._connectionId;
       }
       this.send(joinMessage);
-      const joinResponse = await this.messageQueue.registerRequest(requestId);
+      const joinResponse = await this.messageQueue.registerRequest(joinRequestId);
       this._volatilePaths = joinResponse.volatilePaths;
       this._connectionId = joinResponse.connectionId;
-      const jwtPayload = decodeJwtPayload(connectResponse.token);
+      if (joinResponse.serverTime != null) {
+        this._serverTimeOffset = joinResponse.serverTime - Date.now();
+      }
+      this._state = "joined";
+      const authRequestId = this.messageQueue.nextRequestId();
+      const authMessage = {
+        o: "au",
+        t: this._currentToken ?? "",
+        r: authRequestId
+      };
+      this.send(authMessage);
+      const authResponse = await this.messageQueue.registerRequest(authRequestId);
       this._auth = {
-        uid: jwtPayload.sub,
-        provider: jwtPayload.provider,
-        token: jwtPayload.claims || {}
+        uid: authResponse.uid || "",
+        provider: this._isAnonymous ? "anonymous" : "custom",
+        token: {}
+        // Token claims would need to be decoded from the token if needed
       };
-      this._state = "connected";
+      this._state = "authenticated";
       this._reconnectAttempt = 0;
+      if (this.authenticationResolve) {
+        this.authenticationResolve();
+        this.authenticationResolve = null;
+      }
+      this.fireConnectionStateChange();
       if (!isReconnect) {
         this.subscriptionManager.initialize({
           sendSubscribe: this.sendSubscribeMessage.bind(this),
@@ -2812,6 +4355,7 @@ var LarkDatabase = class {
         await this.restoreAfterReconnect();
       }
       this.connectCallbacks.forEach((cb) => cb());
+      this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
     } catch (error) {
       if (isReconnect) {
         this._state = "reconnecting";
@@ -2824,6 +4368,8 @@ var LarkDatabase = class {
       this._connectOptions = null;
       this._connectionId = null;
       this._transportType = null;
+      this._currentToken = null;
+      this._isAnonymous = false;
       this.transport?.close();
       this.transport = null;
       throw error;
@@ -2837,13 +4383,14 @@ var LarkDatabase = class {
     if (this._state === "disconnected") {
       return;
     }
-    const wasConnected = this._state === "connected";
+    const wasAuthenticated = this._state === "authenticated";
+    const wasPartiallyConnected = this._state === "connected" || this._state === "joined";
     this._intentionalDisconnect = true;
     if (this._reconnectTimer) {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
     }
-    if (wasConnected && this.transport) {
+    if ((wasAuthenticated || wasPartiallyConnected) && this.transport) {
       try {
         const requestId = this.messageQueue.nextRequestId();
         this.send({ o: "l", r: requestId });
@@ -2855,15 +4402,47 @@ var LarkDatabase = class {
       }
     }
     this.cleanupFull();
-    if (wasConnected) {
+    if (wasAuthenticated || wasPartiallyConnected) {
       this.disconnectCallbacks.forEach((cb) => cb());
     }
   }
+  /**
+   * Temporarily disable the connection.
+   * Disconnects from the server but preserves subscriptions for later reconnection via goOnline().
+   */
+  goOffline() {
+    if (this._state === "authenticated" || this._state === "joined" || this._state === "connected" || this._state === "reconnecting") {
+      this._intentionalDisconnect = true;
+      if (this._reconnectTimer) {
+        clearTimeout(this._reconnectTimer);
+        this._reconnectTimer = null;
+      }
+      this.transport?.close();
+      this.transport = null;
+      this._state = "disconnected";
+      this.subscriptionManager.clearCacheOnly();
+      this.fireConnectionStateChange();
+    }
+  }
+  /**
+   * Re-enable the connection after goOffline().
+   * Reconnects to the database and restores subscriptions.
+   */
+  goOnline() {
+    this._intentionalDisconnect = false;
+    if (this._state === "disconnected" && this._databaseId && this._connectOptions) {
+      this._state = "reconnecting";
+      this.reconnectingCallbacks.forEach((cb) => cb());
+      this._reconnectAttempt = 0;
+      this.attemptReconnect();
+    }
+  }
   /**
    * Full cleanup - clears all state including subscriptions.
    * Used for intentional disconnect.
    */
   cleanupFull() {
+    const wasAuthenticated = this._state === "authenticated";
     this.transport?.close();
     this.transport = null;
     this._state = "disconnected";
@@ -2874,10 +4453,18 @@ var LarkDatabase = class {
     this._connectionId = null;
     this._connectOptions = null;
     this._transportType = null;
+    this._currentToken = null;
+    this._isAnonymous = false;
     this._reconnectAttempt = 0;
+    this.authenticationPromise = null;
+    this.authenticationResolve = null;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
     this.pendingWrites.clear();
+    if (wasAuthenticated) {
+      this.fireConnectionStateChange();
+    }
+    this.infoSubscriptions = [];
   }
   /**
    * Partial cleanup - preserves state needed for reconnect.
@@ -2889,6 +4476,67 @@ var LarkDatabase = class {
     this._auth = null;
     this.subscriptionManager.clearCacheOnly();
     this.messageQueue.rejectAll(new Error("Connection closed"));
+    this.fireConnectionStateChange();
+  }
+  // ============================================
+  // .info Path Handling
+  // ============================================
+  /**
+   * Check if a path is a .info path (handled locally).
+   */
+  isInfoPath(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    return normalizedPath === "/.info" || normalizedPath.startsWith("/.info/");
+  }
+  /**
+   * Get the current value for a .info path.
+   */
+  getInfoValue(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    if (normalizedPath === "/.info/connected") {
+      return this._state === "authenticated";
+    }
+    if (normalizedPath === "/.info/serverTimeOffset") {
+      return this._serverTimeOffset;
+    }
+    return null;
+  }
+  /**
+   * Subscribe to a .info path.
+   * Returns an unsubscribe function.
+   */
+  subscribeToInfo(path, callback) {
+    const normalizedPath = normalizePath(path) || "/";
+    const subscription = { path: normalizedPath, callback };
+    this.infoSubscriptions.push(subscription);
+    const value = this.getInfoValue(normalizedPath);
+    const snapshot = new DataSnapshot(value, normalizedPath, this);
+    setTimeout(() => callback(snapshot), 0);
+    return () => {
+      const index = this.infoSubscriptions.indexOf(subscription);
+      if (index !== -1) {
+        this.infoSubscriptions.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Fire events for .info path changes.
+   */
+  fireInfoEvents(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    const value = this.getInfoValue(normalizedPath);
+    for (const sub of this.infoSubscriptions) {
+      if (sub.path === normalizedPath) {
+        const snapshot = new DataSnapshot(value, normalizedPath, this);
+        sub.callback(snapshot);
+      }
+    }
+  }
+  /**
+   * Fire connection state change events to .info/connected subscribers.
+   */
+  fireConnectionStateChange() {
+    this.fireInfoEvents("/.info/connected");
   }
   /**
    * Schedule a reconnection attempt with exponential backoff.
@@ -2913,6 +4561,9 @@ var LarkDatabase = class {
     if (this._intentionalDisconnect || !this._databaseId || !this._connectOptions) {
       return;
     }
+    this.authenticationPromise = new Promise((resolve) => {
+      this.authenticationResolve = resolve;
+    });
     try {
       await this.performConnect(this._databaseId, this._connectOptions, true);
     } catch {
@@ -3071,6 +4722,9 @@ var LarkDatabase = class {
    * @internal Send a transaction to the server.
    */
   async _sendTransaction(ops) {
+    if (!this.isAuthenticatedOrThrow()) {
+      if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    }
     const requestId = this.messageQueue.nextRequestId();
     this.pendingWrites.trackWrite(requestId, "transaction", "/", ops);
     const message = {
@@ -3117,6 +4771,76 @@ var LarkDatabase = class {
     this.reconnectingCallbacks.add(callback);
     return () => this.reconnectingCallbacks.delete(callback);
   }
+  /**
+   * Register a callback for auth state changes.
+   * Fires when user signs in, signs out, or auth changes.
+   * Returns an unsubscribe function.
+   */
+  onAuthStateChanged(callback) {
+    this.authStateChangedCallbacks.add(callback);
+    return () => this.authStateChangedCallbacks.delete(callback);
+  }
+  // ============================================
+  // Authentication Management
+  // ============================================
+  /**
+   * Sign in with a new auth token while connected.
+   * Changes the authenticated user without disconnecting.
+   *
+   * Note: Some subscriptions may be revoked if the new user doesn't have
+   * permission. Listen for 'permission_denied' errors on your subscriptions.
+   *
+   * @param token - The auth token for the new user
+   * @throws Error if not connected (must call connect() first)
+   */
+  async signIn(token) {
+    if (this._state !== "authenticated" && this._state !== "joined") {
+      throw new LarkError("not_connected", "Must be connected first - call connect()");
+    }
+    const authRequestId = this.messageQueue.nextRequestId();
+    const authMessage = {
+      o: "au",
+      t: token,
+      r: authRequestId
+    };
+    this.send(authMessage);
+    const authResponse = await this.messageQueue.registerRequest(authRequestId);
+    this._currentToken = token;
+    this._isAnonymous = false;
+    this._auth = {
+      uid: authResponse.uid || "",
+      provider: "custom",
+      token: {}
+    };
+    this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
+  }
+  /**
+   * Sign out the current user.
+   * Reverts to anonymous authentication.
+   *
+   * Note: Some subscriptions may be revoked if anonymous users don't have
+   * permission. Listen for 'permission_denied' errors on your subscriptions.
+   */
+  async signOut() {
+    if (this._state !== "authenticated") {
+      return;
+    }
+    const unauthRequestId = this.messageQueue.nextRequestId();
+    const unauthMessage = {
+      o: "ua",
+      r: unauthRequestId
+    };
+    this.send(unauthMessage);
+    const authResponse = await this.messageQueue.registerRequest(unauthRequestId);
+    this._currentToken = "";
+    this._isAnonymous = true;
+    this._auth = {
+      uid: authResponse.uid || "",
+      provider: "anonymous",
+      token: {}
+    };
+    this.authStateChangedCallbacks.forEach((cb) => cb(this._auth));
+  }
   // ============================================
   // Internal: Message Handling
   // ============================================
@@ -3128,6 +4852,9 @@ var LarkDatabase = class {
       console.error("Failed to parse message:", data);
       return;
     }
+    if (process.env.LARK_DEBUG) {
+      console.log("[LARK] <<< SERVER:", JSON.stringify(message, null, 2));
+    }
     if (isPingMessage(message)) {
       this.transport?.send(JSON.stringify({ o: "po" }));
       return;
@@ -3137,28 +4864,16 @@ var LarkDatabase = class {
       this.subscriptionManager.clearPendingWrite(message.a);
     } else if (isNackMessage(message)) {
       this.pendingWrites.onNack(message.n);
+      if (message.e === "permission_denied" && message.sp) {
+        const path = message.sp;
+        console.warn(`Subscription revoked at ${path}: permission_denied`);
+        this.subscriptionManager.handleSubscriptionRevoked(path);
+        return;
+      }
       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);
       }
+      this.subscriptionManager.handleWriteNack(message.n);
     }
     if (this.messageQueue.handleMessage(message)) {
       return;
@@ -3171,27 +4886,28 @@ var LarkDatabase = class {
     if (this._state === "disconnected") {
       return;
     }
-    const wasConnected = this._state === "connected";
+    const wasAuthenticated = this._state === "authenticated";
     const wasReconnecting = this._state === "reconnecting";
+    const wasPartiallyConnected = this._state === "connected" || this._state === "joined";
     if (this._intentionalDisconnect) {
       this.cleanupFull();
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
       return;
     }
     const canReconnect = this._databaseId && this._connectOptions;
-    if ((wasConnected || wasReconnecting) && canReconnect) {
+    if ((wasAuthenticated || wasPartiallyConnected || wasReconnecting) && canReconnect) {
       this._state = "reconnecting";
       this.cleanupForReconnect();
       this.reconnectingCallbacks.forEach((cb) => cb());
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
       this.scheduleReconnect();
     } else {
       this.cleanupFull();
-      if (wasConnected) {
+      if (wasAuthenticated || wasPartiallyConnected) {
         this.disconnectCallbacks.forEach((cb) => cb());
       }
     }
@@ -3202,10 +4918,48 @@ var LarkDatabase = class {
   // ============================================
   // Internal: Sending Messages
   // ============================================
+  /**
+   * Check if authenticated synchronously.
+   * Returns true if authenticated, false if connecting (should wait), throws if disconnected.
+   */
+  isAuthenticatedOrThrow() {
+    if (this._state === "authenticated") {
+      return true;
+    }
+    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
+      return false;
+    }
+    throw new LarkError("not_connected", "Not connected - call connect() first");
+  }
+  /**
+   * Wait for authentication to complete before performing an operation.
+   * If already authenticated, returns immediately (synchronously).
+   * If connecting/reconnecting, waits for auth to complete.
+   * If disconnected and no connect in progress, throws.
+   *
+   * IMPORTANT: This returns a Promise only if waiting is needed.
+   * Callers should use: `if (!this.isAuthenticatedOrThrow()) if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();`
+   * to preserve synchronous execution when already authenticated.
+   */
+  async waitForAuthenticated() {
+    if (this._state === "authenticated") {
+      return;
+    }
+    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
+      if (this.authenticationPromise) {
+        await this.authenticationPromise;
+        return;
+      }
+    }
+    throw new LarkError("not_connected", "Not connected - call connect() first");
+  }
   send(message) {
     if (!this.transport || !this.transport.connected) {
       throw new LarkError("not_connected", "Not connected to database");
     }
+    if (process.env.LARK_DEBUG) {
+      console.log("[LARK] >>> CLIENT:", JSON.stringify(message, null, 2));
+    }
     this.transport.send(JSON.stringify(message));
   }
   /**
@@ -3213,19 +4967,21 @@ var LarkDatabase = class {
    * Note: Priority is now part of the value (as .priority), not a separate field.
    */
   async _sendSet(path, value) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const normalizedPath = normalizePath(path) || "/";
-    if (this.subscriptionManager.isPathInRecovery(normalizedPath)) {
-      throw new LarkError("view_recovering", "Cannot write: View is recovering from failed write");
-    }
+    validateWriteData(value, normalizedPath);
     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 { value: currentValue } = this.subscriptionManager.getCachedValue(normalizedPath);
+    const resolvedValue = resolveServerValuesLocally(value, currentValue);
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, resolvedValue, requestId, "set");
     const message = {
       o: "s",
       p: normalizedPath,
       v: value,
+      // Send original value with ServerValue placeholders to server
       r: requestId,
       pw: pendingWriteIds.length > 0 ? pendingWriteIds : void 0
     };
@@ -3236,19 +4992,28 @@ var LarkDatabase = class {
    * @internal Send an update operation.
    */
   async _sendUpdate(path, values) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const normalizedPath = normalizePath(path) || "/";
-    if (this.subscriptionManager.isPathInRecovery(normalizedPath)) {
-      throw new LarkError("view_recovering", "Cannot write: View is recovering from failed write");
+    for (const [key, value] of Object.entries(values)) {
+      const fullPath = key.startsWith("/") ? key : `${normalizedPath}/${key}`;
+      validateWriteData(value, fullPath);
     }
     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 resolvedValues = {};
+    for (const [key, value] of Object.entries(values)) {
+      const fullPath = key.startsWith("/") ? key : `${normalizedPath}/${key}`;
+      const { value: currentValue } = this.subscriptionManager.getCachedValue(fullPath);
+      resolvedValues[key] = resolveServerValuesLocally(value, currentValue);
+    }
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, resolvedValues, requestId, "update");
     const message = {
       o: "u",
       p: normalizedPath,
       v: values,
+      // Send original value with ServerValue placeholders to server
       r: requestId,
       pw: pendingWriteIds.length > 0 ? pendingWriteIds : void 0
     };
@@ -3259,10 +5024,8 @@ var LarkDatabase = class {
    * @internal Send a delete operation.
    */
   async _sendDelete(path) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     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);
@@ -3297,7 +5060,7 @@ var LarkDatabase = class {
   _sendVolatileSet(path, value) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -3313,7 +5076,7 @@ var LarkDatabase = class {
   _sendVolatileUpdate(path, values) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -3329,7 +5092,7 @@ var LarkDatabase = class {
   _sendVolatileDelete(path) {
     const normalizedPath = normalizePath(path) || "/";
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, "", "delete");
-    if (!this.transport || !this.transport.connected) {
+    if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
     }
     const message = {
@@ -3358,12 +5121,17 @@ var LarkDatabase = class {
    */
   async _sendOnce(path, query) {
     const normalizedPath = normalizePath(path) || "/";
+    if (this.isInfoPath(normalizedPath)) {
+      const value2 = this.getInfoValue(normalizedPath);
+      return new DataSnapshot(value2, path, this);
+    }
     if (!query) {
       const cached = this.subscriptionManager.getCachedValue(normalizedPath);
       if (cached.found) {
         return new DataSnapshot(cached.value, path, this);
       }
     }
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "o",
@@ -3374,12 +5142,13 @@ var LarkDatabase = class {
     };
     this.send(message);
     const value = await this.messageQueue.registerRequest(requestId);
-    return new DataSnapshot(value, path, this);
+    return new DataSnapshot(value, path, this, { queryParams: query ?? null });
   }
   /**
    * @internal Send an onDisconnect operation.
    */
   async _sendOnDisconnect(path, action, value) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "od",
@@ -3393,30 +5162,45 @@ var LarkDatabase = class {
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
+  /**
+   * @internal Get a cached value from the subscription manager.
+   * Used for optimistic writes where we need the current value without a network fetch.
+   */
+  _getCachedValue(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    return this.subscriptionManager.getCachedValue(normalizedPath);
+  }
   /**
    * @internal Send a subscribe message to server.
+   * Includes tag for non-default queries to enable proper event routing.
    */
-  async sendSubscribeMessage(path, eventTypes, queryParams) {
+  async sendSubscribeMessage(path, eventTypes, queryParams, tag) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "sb",
       p: normalizePath(path) || "/",
       e: eventTypes,
       r: requestId,
-      ...queryParams
+      ...queryParams,
+      ...tag !== void 0 ? { tag } : {}
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
   /**
    * @internal Send an unsubscribe message to server.
+   * Includes query params and tag so server can identify which specific subscription to remove.
    */
-  async sendUnsubscribeMessage(path) {
+  async sendUnsubscribeMessage(path, queryParams, tag) {
+    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "us",
       p: normalizePath(path) || "/",
-      r: requestId
+      r: requestId,
+      ...queryParams,
+      ...tag !== void 0 ? { tag } : {}
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
@@ -3424,10 +5208,11 @@ var LarkDatabase = class {
   /**
    * @internal Create a DataSnapshot from event data.
    */
-  createSnapshot(path, value, volatile, serverTimestamp) {
+  createSnapshot(path, value, volatile, serverTimestamp, orderedKeys) {
     return new DataSnapshot(value, path, this, {
       volatile,
-      serverTimestamp: serverTimestamp ?? null
+      serverTimestamp: serverTimestamp ?? null,
+      orderedKeys: orderedKeys ?? null
     });
   }
   // ============================================
@@ -3436,8 +5221,11 @@ var LarkDatabase = class {
   /**
    * @internal Subscribe to events at a path.
    */
-  _subscribe(path, eventType, callback, queryParams) {
-    return this.subscriptionManager.subscribe(path, eventType, callback, queryParams);
+  _subscribe(path, eventType, callback, queryParams, queryIdentifier) {
+    if (this.isInfoPath(path)) {
+      return this.subscribeToInfo(path, callback);
+    }
+    return this.subscriptionManager.subscribe(path, eventType, callback, queryParams, queryIdentifier);
   }
   /**
    * @internal Unsubscribe from a specific event type at a path.
@@ -3452,6 +5240,11 @@ var LarkDatabase = class {
     this.subscriptionManager.unsubscribeAll(path);
   }
 };
+/**
+ * Server values that are resolved by the server when a write is committed.
+ * Alias for the exported ServerValue object.
+ */
+LarkDatabase.ServerValue = ServerValue;
 export {
   DataSnapshot,
   DatabaseReference,
@@ -3459,6 +5252,8 @@ export {
   LarkError,
   OnDisconnect,
   PendingWriteManager,
+  ServerValue,
+  ThenableReference,
   generatePushId,
   isVolatilePath
 };