@xnetjs/react 0.0.2 → 0.1.0

package/dist/chunk-6VOICQZ3.js

@@ -0,0 +1,760 @@
+import {
+  useInstrumentation
+} from "./chunk-JCOFKBOB.js";
+import {
+  TRACE_STAGES,
+  XNetContext,
+  useDataBridge,
+  useTelemetryReporter,
+  useTracingReporter
+} from "./chunk-IHTMVTTE.js";
+
+// src/utils/flattenNode.ts
+function flattenNode(node, options) {
+  const { properties, timestamps, deletedAt, documentContent, _unknown, _schemaVersion, ...base } = node;
+  const migrationInfo = options?.migrationInfo ?? node._migrationInfo;
+  return {
+    ...base,
+    ...properties,
+    // Include version compatibility fields if present
+    ...options?.unknownSchema && { _unknownSchema: true },
+    ..._unknown && Object.keys(_unknown).length > 0 && { _unknown },
+    ..._schemaVersion && { _schemaVersion },
+    // Include migration fields if present
+    ...migrationInfo && {
+      _migratedFrom: migrationInfo.from,
+      _migrationInfo: migrationInfo
+    }
+  };
+}
+function flattenNodes(nodes, options) {
+  return nodes.map((node) => flattenNode(node, options));
+}
+function flattenUnknownSchemaNode(node) {
+  return flattenNode(node, { unknownSchema: true });
+}
+function flattenNodesWithSchemaCheck(nodes, isSchemaKnown) {
+  return nodes.map((node) => flattenNode(node, { unknownSchema: !isSchemaKnown(node.schemaId) }));
+}
+
+// src/hooks/useQuery.ts
+import {
+  createQueryDescriptor,
+  queryDescriptorToOptions,
+  serializeQueryDescriptor
+} from "@xnetjs/data-bridge";
+import { useSyncExternalStore, useMemo, useCallback, useEffect, useRef } from "react";
+
+// src/utils/queryResultMeta.ts
+var EMPTY_PAGE_INFO = {
+  totalCount: null,
+  countMode: "none",
+  hasMore: false,
+  hasNextPage: false,
+  hasPreviousPage: false,
+  loadedCount: 0
+};
+function computeFallbackPageInfo(input) {
+  if (input.metadata?.pageInfo) {
+    return input.metadata.pageInfo;
+  }
+  if (input.loading || input.loadedCount === null) {
+    return EMPTY_PAGE_INFO;
+  }
+  const { loadedCount, offset, limit } = input;
+  const totalCount = limit === void 0 && offset === 0 ? loadedCount : null;
+  const countMode = totalCount === null ? "none" : "exact";
+  const hasMore = limit !== void 0 ? totalCount === null ? loadedCount >= limit : offset + loadedCount < totalCount : false;
+  return {
+    totalCount,
+    countMode,
+    hasMore,
+    hasNextPage: hasMore,
+    hasPreviousPage: offset > 0,
+    loadedCount
+  };
+}
+function summarizePlan(metadata) {
+  const plan = metadata?.plan;
+  if (!plan) return null;
+  return {
+    strategy: plan.strategy,
+    candidateNodeCount: plan.candidateNodeCount,
+    hydratedNodeCount: plan.hydratedNodeCount,
+    returnedNodeCount: plan.returnedNodeCount,
+    durationMs: plan.durationMs,
+    descriptorHash: plan.descriptorHash,
+    candidateAccelerators: plan.candidateAccelerators,
+    materializedViewId: plan.materializedViewId,
+    materializedCacheHit: plan.materializedCacheHit,
+    materializedRefreshReason: plan.materializedRefreshReason
+  };
+}
+
+// src/hooks/useQuery.ts
+var EMPTY_QUERY_FILTER = Object.freeze({});
+var DISABLED_QUERY_SNAPSHOT = [];
+var nextQueryInstanceId = 0;
+var flatNodeCache = /* @__PURE__ */ new WeakMap();
+function flattenNodeCached(node) {
+  const cached = flatNodeCache.get(node);
+  if (cached) return cached;
+  const flat = flattenNode(node);
+  flatNodeCache.set(node, flat);
+  return flat;
+}
+var SYSTEM_ORDER_FIELDS = /* @__PURE__ */ new Set(["createdAt", "updatedAt"]);
+var warnedUnboundedSorts = /* @__PURE__ */ new Set();
+function isProductionEnv() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+function isUnboundedListQuery(descriptor) {
+  if (descriptor.nodeId) return false;
+  if (descriptor.limit !== void 0) return false;
+  if (descriptor.after !== void 0) return false;
+  return !descriptor.offset;
+}
+function propertyOrderKeys(descriptor) {
+  return Object.keys(descriptor.orderBy ?? {}).filter((key) => !SYSTEM_ORDER_FIELDS.has(key));
+}
+function unboundedPropertySortKey(schemaId, descriptor) {
+  if (isProductionEnv()) return null;
+  if (!isUnboundedListQuery(descriptor)) return null;
+  const propertyKeys = propertyOrderKeys(descriptor);
+  return propertyKeys.length > 0 ? `${schemaId}:${propertyKeys.join(",")}` : null;
+}
+function warnIfUnboundedPropertySort(schemaId, descriptor) {
+  const warnKey = unboundedPropertySortKey(schemaId, descriptor);
+  if (warnKey === null) return;
+  if (warnedUnboundedSorts.has(warnKey)) return;
+  warnedUnboundedSorts.add(warnKey);
+  console.warn(
+    `[useQuery] Unbounded query on "${schemaId}" ordered by property ${JSON.stringify(propertyOrderKeys(descriptor))} cannot use an index \u2014 it full-scans and JS-sorts the whole schema. Add a \`limit\` and order by a system field (createdAt/updatedAt), then sort in JS if needed (exploration 0184).`
+  );
+}
+function getFallbackPageInfo(input) {
+  return computeFallbackPageInfo({
+    metadata: input.metadata,
+    loading: input.loading,
+    loadedCount: !input.isSingleQuery && Array.isArray(input.data) ? input.data.length : null,
+    offset: input.descriptor.offset ?? 0,
+    limit: input.descriptor.limit
+  });
+}
+function flattenListSnapshot(rawData) {
+  const data = rawData.map((node) => flattenNodeCached(node));
+  return { data, migrationWarnings: collectMigrationWarnings(data) };
+}
+function deriveMetadataSurfaces(metadata) {
+  return {
+    source: metadata?.source ?? "local",
+    materialized: metadata?.materialized ?? null,
+    completeness: metadata?.completeness ?? null,
+    staleness: metadata?.staleness ?? null,
+    verification: metadata?.verification ?? null,
+    stream: metadata?.stream ?? null
+  };
+}
+function deriveTrackedFilter(descriptor) {
+  const next = {
+    ...descriptor.where ? { where: descriptor.where } : {},
+    ...descriptor.spatial ? { spatial: descriptor.spatial } : {},
+    ...descriptor.search ? { search: descriptor.search } : {},
+    ...descriptor.materializedView ? { materializedView: descriptor.materializedView } : {}
+  };
+  return Object.keys(next).length > 0 ? next : void 0;
+}
+function deriveTrackedMode(isSingleQuery, descriptor) {
+  if (isSingleQuery) return "single";
+  return descriptor.where || descriptor.spatial || descriptor.search ? "filtered" : "list";
+}
+function collectMigrationWarnings(flattened) {
+  const warnings = [];
+  for (const flat of flattened) {
+    if (flat._migrationInfo && !flat._migrationInfo.lossless) {
+      warnings.push({
+        nodeId: flat.id,
+        from: flat._migrationInfo.from,
+        to: flat._migrationInfo.to,
+        warnings: flat._migrationInfo.warnings
+      });
+    }
+  }
+  return warnings;
+}
+function useQuery(schema, idOrFilter) {
+  const bridge = useDataBridge();
+  const instrumentation = useInstrumentation();
+  const telemetry = useTelemetryReporter();
+  const tracing = useTracingReporter();
+  const schemaId = schema._schemaId;
+  const queryStartRef = useRef(null);
+  if (queryStartRef.current === null) queryStartRef.current = Date.now();
+  const isSingleQuery = typeof idOrFilter === "string";
+  const filter = typeof idOrFilter === "object" ? idOrFilter : EMPTY_QUERY_FILTER;
+  const nodeId = isSingleQuery ? idOrFilter : null;
+  const enabled = filter.enabled ?? true;
+  const descriptorRef = useRef(null);
+  if (!descriptorRef.current || descriptorRef.current.input !== idOrFilter || descriptorRef.current.schemaId !== schemaId) {
+    const options = isSingleQuery && nodeId ? { nodeId } : filter;
+    const candidate = createQueryDescriptor(schemaId, options);
+    const candidateKey = serializeQueryDescriptor(candidate);
+    const descriptor2 = descriptorRef.current && descriptorRef.current.key === candidateKey ? descriptorRef.current.descriptor : candidate;
+    descriptorRef.current = { input: idOrFilter, schemaId, key: candidateKey, descriptor: descriptor2 };
+    warnIfUnboundedPropertySort(schemaId, descriptor2);
+  }
+  const descriptor = descriptorRef.current.descriptor;
+  const queryKey = descriptorRef.current.key;
+  const subscription = useMemo(() => {
+    if (!enabled) {
+      return {
+        getSnapshot: () => DISABLED_QUERY_SNAPSHOT,
+        getMetadata: () => null,
+        subscribe: () => () => {
+        }
+      };
+    }
+    if (!bridge) {
+      return {
+        getSnapshot: () => null,
+        getMetadata: () => null,
+        subscribe: () => () => {
+        }
+      };
+    }
+    return bridge.query(schema, queryDescriptorToOptions(descriptor));
+  }, [bridge, enabled, schema, queryKey]);
+  const reload = useCallback(() => {
+    if (!enabled || !bridge?.reloadQuery) return;
+    void bridge.reloadQuery(descriptor);
+  }, [bridge, descriptor, enabled]);
+  const combinedSnapshotRef = useRef(null);
+  const getCombinedSnapshot = useCallback(() => {
+    const data2 = subscription.getSnapshot();
+    const metadata2 = subscription.getMetadata?.() ?? null;
+    const previous = combinedSnapshotRef.current;
+    if (previous && previous.data === data2 && previous.metadata === metadata2) {
+      return previous;
+    }
+    const next = { data: data2, metadata: metadata2 };
+    combinedSnapshotRef.current = next;
+    return next;
+  }, [subscription]);
+  const combinedSnapshot = useSyncExternalStore(
+    subscription.subscribe,
+    getCombinedSnapshot,
+    getCombinedSnapshot
+    // Server snapshot (same as client for now)
+  );
+  const rawData = combinedSnapshot.data;
+  const metadata = combinedSnapshot.metadata;
+  const previousListRef = useRef(null);
+  const { data, migrationWarnings } = useMemo(() => {
+    if (rawData === null) {
+      return {
+        data: isSingleQuery ? null : [],
+        migrationWarnings: []
+      };
+    }
+    if (isSingleQuery) {
+      const node = rawData[0] ?? null;
+      const flat = node ? flattenNodeCached(node) : null;
+      return {
+        data: flat,
+        migrationWarnings: flat ? collectMigrationWarnings([flat]) : []
+      };
+    }
+    const next = flattenListSnapshot(rawData);
+    const previous = previousListRef.current;
+    if (previous && previous.data.length === next.data.length && next.data.every((flat, index) => flat === previous.data[index])) {
+      return previous;
+    }
+    previousListRef.current = next;
+    return next;
+  }, [rawData, isSingleQuery]);
+  const loading = rawData === null;
+  const pageInfo = useMemo(
+    () => getFallbackPageInfo({ metadata, loading, isSingleQuery, data, descriptor }),
+    [metadata, loading, isSingleQuery, data, descriptor]
+  );
+  const error = useMemo(
+    () => metadata?.error ? new Error(metadata.error) : null,
+    [metadata?.error]
+  );
+  const status = error ? "error" : loading ? "loading" : "success";
+  const plan = useMemo(() => summarizePlan(metadata), [metadata]);
+  const { source, materialized, completeness, staleness, verification, stream } = deriveMetadataSurfaces(metadata);
+  const trackedFilter = useMemo(
+    () => deriveTrackedFilter(descriptor),
+    // queryKey is the canonical descriptor identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [queryKey]
+  );
+  const trackedMode = useMemo(
+    () => deriveTrackedMode(isSingleQuery, descriptor),
+    // queryKey is the canonical descriptor identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [isSingleQuery, queryKey]
+  );
+  const queryIdRef = useRef(null);
+  if (queryIdRef.current === null) {
+    queryIdRef.current = `useQuery-${schemaId}-${nodeId || "list"}-${(nextQueryInstanceId++).toString(36)}`;
+  }
+  useEffect(() => {
+    if (!instrumentation?.queryTracker) return;
+    const queryId = queryIdRef.current;
+    instrumentation.queryTracker.register(queryId, {
+      type: "useQuery",
+      schemaId,
+      mode: trackedMode,
+      filter: trackedFilter,
+      descriptorKey: queryKey,
+      nodeId: nodeId || void 0
+    });
+    return () => {
+      instrumentation.queryTracker.unregister(queryId);
+    };
+  }, [instrumentation, schemaId, nodeId, trackedMode, trackedFilter, queryKey]);
+  useEffect(() => {
+    if (!instrumentation?.queryTracker || loading) return;
+    const count = isSingleQuery ? data ? 1 : 0 : Array.isArray(data) ? data.length : 0;
+    instrumentation.queryTracker.recordUpdate(queryIdRef.current, count, 0, {
+      source,
+      plan,
+      materialized,
+      completeness,
+      staleness,
+      verification,
+      stream
+    });
+  }, [
+    data,
+    instrumentation,
+    isSingleQuery,
+    loading,
+    source,
+    plan,
+    materialized,
+    completeness,
+    staleness,
+    verification,
+    stream
+  ]);
+  const lastRecordedStreamEventAtRef = useRef(0);
+  useEffect(() => {
+    if (!instrumentation?.queryTracker.recordStreamEvent || !stream) return;
+    if (lastRecordedStreamEventAtRef.current === stream.lastEventAt) return;
+    lastRecordedStreamEventAtRef.current = stream.lastEventAt;
+    const count = isSingleQuery ? data ? 1 : 0 : Array.isArray(data) ? data.length : 0;
+    instrumentation.queryTracker.recordStreamEvent(queryIdRef.current, stream, count, {
+      source
+    });
+  }, [data, instrumentation, isSingleQuery, source, stream]);
+  useEffect(() => {
+    if (!telemetry) return;
+    telemetry.reportUsage("react.useQuery", 1);
+    return () => {
+      telemetry.reportUsage("react.useQuery.unmount", 1);
+    };
+  }, [telemetry]);
+  const hasReportedTimingRef = useRef(false);
+  const queryTraceRef = useRef(null);
+  useEffect(() => {
+    queryStartRef.current = Date.now();
+    hasReportedTimingRef.current = false;
+    queryTraceRef.current?.end();
+    queryTraceRef.current = tracing?.startTrace("query", `query:${schemaId}`) ?? null;
+    return () => {
+      queryTraceRef.current?.end();
+      queryTraceRef.current = null;
+    };
+  }, [queryKey, tracing, schemaId]);
+  useEffect(() => {
+    if (loading || hasReportedTimingRef.current) return;
+    hasReportedTimingRef.current = true;
+    const elapsed = Date.now() - (queryStartRef.current ?? Date.now());
+    if (telemetry) {
+      telemetry.reportPerformance("react.useQuery", elapsed);
+      if (elapsed < 5) {
+        telemetry.reportUsage("react.useQuery.cache_hit", 1);
+      } else {
+        telemetry.reportUsage("react.useQuery.cache_miss", 1);
+      }
+    }
+    const trace = queryTraceRef.current;
+    if (trace) {
+      const rows = isSingleQuery ? data ? 1 : 0 : Array.isArray(data) ? data.length : 0;
+      trace.addSpan({
+        name: TRACE_STAGES.queryCommit,
+        startOffsetMs: 0,
+        durationMs: elapsed,
+        attributes: { returnedRows: rows }
+      });
+      trace.end();
+      queryTraceRef.current = null;
+    }
+  }, [loading, telemetry, data, isSingleQuery]);
+  return {
+    data,
+    status,
+    loading,
+    isLoading: loading,
+    isFetching: loading,
+    isLive: bridge !== null,
+    source,
+    error,
+    reload,
+    migrationWarnings,
+    pageInfo,
+    totalCount: pageInfo.totalCount,
+    hasMore: pageInfo.hasMore,
+    plan,
+    materialized,
+    completeness,
+    staleness,
+    verification,
+    stream
+  };
+}
+
+// src/hooks/useMutate.ts
+import { isTempId } from "@xnetjs/data";
+import { useCallback as useCallback2, useMemo as useMemo2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore2 } from "react";
+function hasTempIdInValue(value) {
+  if (isTempId(value)) return true;
+  if (Array.isArray(value)) {
+    return value.some((item) => hasTempIdInValue(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.values(value).some((item) => hasTempIdInValue(item));
+  }
+  return false;
+}
+function hasTempIdsInOps(ops) {
+  return ops.some((op) => {
+    switch (op.type) {
+      case "create":
+        return Boolean(op.id && isTempId(op.id) || hasTempIdInValue(op.data));
+      case "update":
+        return isTempId(op.id) || hasTempIdInValue(op.data);
+      case "delete":
+      case "restore":
+        return isTempId(op.id);
+    }
+  });
+}
+function toTransactionOperations(ops) {
+  return ops.map((op) => {
+    switch (op.type) {
+      case "create":
+        return {
+          type: "create",
+          options: {
+            id: op.id,
+            schemaId: op.schema._schemaId,
+            properties: op.data
+          }
+        };
+      case "update":
+        return {
+          type: "update",
+          nodeId: op.id,
+          options: {
+            properties: op.data
+          }
+        };
+      case "delete":
+        return {
+          type: "delete",
+          nodeId: op.id
+        };
+      case "restore":
+        return {
+          type: "restore",
+          nodeId: op.id
+        };
+    }
+  });
+}
+function useMutate() {
+  const bridge = useDataBridge();
+  const telemetry = useTelemetryReporter();
+  const tracing = useTracingReporter();
+  const pendingRef = useRef2(0);
+  const pendingListenersRef = useRef2(null);
+  pendingListenersRef.current ??= /* @__PURE__ */ new Set();
+  const pendingReadLevelRef = useRef2(0);
+  const subscribePending = useCallback2((listener) => {
+    const listeners = pendingListenersRef.current;
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }, []);
+  const getPendingSnapshot = useCallback2(() => {
+    if (pendingReadLevelRef.current === 0) return 0;
+    if (pendingReadLevelRef.current === 1) return pendingRef.current > 0 ? 1 : 0;
+    return pendingRef.current;
+  }, []);
+  useSyncExternalStore2(subscribePending, getPendingSnapshot, getPendingSnapshot);
+  const withPending = useCallback2(async (fn) => {
+    const notify = () => {
+      for (const listener of pendingListenersRef.current) {
+        listener();
+      }
+    };
+    pendingRef.current++;
+    notify();
+    try {
+      return await fn();
+    } finally {
+      pendingRef.current--;
+      notify();
+    }
+  }, []);
+  const create = useCallback2(
+    async (schema, data, id) => {
+      if (!bridge) return null;
+      const start = telemetry ? Date.now() : 0;
+      const trace = tracing?.startTrace("mutate", "mutate:create");
+      try {
+        const result = await withPending(async () => {
+          const endBridge = trace?.mark(TRACE_STAGES.mutateBridge);
+          const node = await bridge.create(schema, data, id);
+          endBridge?.();
+          return flattenNode(node);
+        });
+        telemetry?.reportPerformance("react.useMutate.create", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.create.success", 1);
+        trace?.end();
+        return result;
+      } catch (err) {
+        trace?.end();
+        telemetry?.reportUsage("react.useMutate.create.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.create"
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, tracing, withPending]
+  );
+  const update = useCallback2(
+    async (_schema, id, data) => {
+      if (!bridge) return null;
+      const start = telemetry ? Date.now() : 0;
+      const trace = tracing?.startTrace("mutate", "mutate:update");
+      try {
+        const result = await withPending(async () => {
+          const endBridge = trace?.mark(TRACE_STAGES.mutateBridge);
+          const node = await bridge.update(id, data);
+          endBridge?.();
+          return flattenNode(node);
+        });
+        telemetry?.reportPerformance("react.useMutate.update", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.update.success", 1);
+        trace?.end();
+        return result;
+      } catch (err) {
+        trace?.end();
+        telemetry?.reportUsage("react.useMutate.update.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.update",
+          nodeId: id
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, tracing, withPending]
+  );
+  const remove = useCallback2(
+    async (id) => {
+      if (!bridge) return;
+      const start = telemetry ? Date.now() : 0;
+      const trace = tracing?.startTrace("mutate", "mutate:delete");
+      try {
+        await withPending(async () => {
+          const endBridge = trace?.mark(TRACE_STAGES.mutateBridge);
+          await bridge.delete(id);
+          endBridge?.();
+        });
+        telemetry?.reportPerformance("react.useMutate.delete", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.delete.success", 1);
+        trace?.end();
+      } catch (err) {
+        trace?.end();
+        telemetry?.reportUsage("react.useMutate.delete.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.delete",
+          nodeId: id
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, tracing, withPending]
+  );
+  const restore = useCallback2(
+    async (id) => {
+      if (!bridge) return null;
+      const start = telemetry ? Date.now() : 0;
+      const trace = tracing?.startTrace("mutate", "mutate:restore");
+      try {
+        const result = await withPending(async () => {
+          const endBridge = trace?.mark(TRACE_STAGES.mutateBridge);
+          const node = await bridge.restore(id);
+          endBridge?.();
+          return flattenNode(node);
+        });
+        telemetry?.reportPerformance("react.useMutate.restore", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.restore.success", 1);
+        trace?.end();
+        return result;
+      } catch (err) {
+        trace?.end();
+        telemetry?.reportUsage("react.useMutate.restore.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.restore",
+          nodeId: id
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, tracing, withPending]
+  );
+  const mutate = useCallback2(
+    async (ops) => {
+      if (!bridge || ops.length === 0) return null;
+      const start = telemetry ? Date.now() : 0;
+      const trace = tracing?.startTrace("mutate", "mutate:transaction");
+      try {
+        const result = await withPending(async () => {
+          const endBridge = trace?.mark(TRACE_STAGES.mutateBridge);
+          try {
+            const canUseTransactions = typeof bridge.transaction === "function";
+            const usesTempIds = hasTempIdsInOps(ops);
+            if (usesTempIds && !canUseTransactions) {
+              throw new Error(
+                "Temp IDs in useMutate.mutate() require a transaction-capable bridge (DataBridge.transaction). Current bridge executes operations sequentially and cannot resolve temp IDs."
+              );
+            }
+            if (canUseTransactions) {
+              const tx = await bridge.transaction(toTransactionOperations(ops));
+              return {
+                results: tx.results,
+                batchId: tx.batchId,
+                tempIds: tx.tempIds
+              };
+            }
+            const results = [];
+            for (const op of ops) {
+              switch (op.type) {
+                case "create": {
+                  const node = await bridge.create(
+                    op.schema,
+                    op.data,
+                    op.id
+                  );
+                  results.push(node);
+                  break;
+                }
+                case "update": {
+                  const node = await bridge.update(op.id, op.data);
+                  results.push(node);
+                  break;
+                }
+                case "delete": {
+                  await bridge.delete(op.id);
+                  results.push(null);
+                  break;
+                }
+                case "restore": {
+                  const node = await bridge.restore(op.id);
+                  results.push(node);
+                  break;
+                }
+              }
+            }
+            return { results };
+          } finally {
+            endBridge?.();
+          }
+        });
+        telemetry?.reportPerformance("react.useMutate.transaction", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.transaction.success", 1);
+        trace?.end();
+        return result;
+      } catch (err) {
+        trace?.end();
+        telemetry?.reportUsage("react.useMutate.transaction.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.transaction",
+          opCount: ops.length
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, tracing, withPending]
+  );
+  const bulk = useCallback2(
+    async (input) => {
+      if (!bridge) return null;
+      const start = telemetry ? Date.now() : 0;
+      try {
+        const result = await withPending(async () => bridge.bulkWrite(input));
+        telemetry?.reportPerformance("react.useMutate.bulk", Date.now() - start);
+        telemetry?.reportUsage("react.useMutate.bulk.success", 1);
+        return result;
+      } catch (err) {
+        telemetry?.reportUsage("react.useMutate.bulk.failure", 1);
+        telemetry?.reportCrash(err instanceof Error ? err : new Error(String(err)), {
+          codeNamespace: "react.useMutate.bulk",
+          kind: input.kind
+        });
+        throw err;
+      }
+    },
+    [bridge, telemetry, withPending]
+  );
+  return useMemo2(
+    () => ({
+      create,
+      update,
+      remove,
+      restore,
+      mutate,
+      bulk,
+      // Lazy getters record how much pending detail this component reads, so
+      // the external-store snapshot above can avoid re-rendering components
+      // that never look at pending state.
+      get isPending() {
+        pendingReadLevelRef.current = Math.max(pendingReadLevelRef.current, 1);
+        return pendingRef.current > 0;
+      },
+      get pendingCount() {
+        pendingReadLevelRef.current = 2;
+        return pendingRef.current;
+      }
+    }),
+    [create, update, remove, restore, mutate, bulk]
+  );
+}
+
+// src/hooks/useSyncManager.ts
+import { useContext } from "react";
+function useSyncManager() {
+  const context = useContext(XNetContext);
+  return context?.syncManager ?? null;
+}
+
+export {
+  flattenNode,
+  flattenNodes,
+  flattenUnknownSchemaNode,
+  flattenNodesWithSchemaCheck,
+  EMPTY_PAGE_INFO,
+  computeFallbackPageInfo,
+  summarizePlan,
+  useQuery,
+  useMutate,
+  useSyncManager
+};