@pythia-software/query-table-react 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,3 +1,47 @@
+// src/computedExecution.ts
+import {
+  isComputedField,
+  readFieldValue
+} from "@pythia-software/query-table-core";
+function executionRevision(execution, id) {
+  return execution?.resolvedRevisions[id] ?? execution?.resolvedRevisions[`@computed/${id}`];
+}
+function validateComputedResponse(request, result, schema) {
+  const execution = result.execution;
+  if (result.version !== 2 || !execution || execution.profile !== request.profile || request.planToken && execution.planToken !== request.planToken || request.snapshot !== void 0 && execution.snapshot !== request.snapshot)
+    throw Error(
+      "Server computed execution identity changed. Refresh the handshake."
+    );
+  for (const [name, revision] of Object.entries(request.expectedRevisions)) {
+    const id = name.replace(/^@computed\//, "");
+    if (executionRevision(execution, id) !== revision)
+      throw Error(
+        "Server computed definition revision changed. Refresh the handshake."
+      );
+  }
+  const idField = schema.fields.find((f) => f.name === schema.idField);
+  if (!idField)
+    throw Error("Stable row identity is required for computed values.");
+  const ids = new Set(result.rows.map((row) => readFieldValue(idField, row)));
+  if (ids.has(null) || ids.has(void 0) || ids.size !== result.rows.length)
+    throw Error(
+      "Computed response contains missing or duplicate row identities."
+    );
+  const sidecars = new Map(
+    result.computed.map((item) => [item.id, item.values])
+  );
+  if (sidecars.size !== result.computed.length || [...sidecars.keys()].some((id) => !ids.has(id)))
+    throw Error("Computed sidecars do not match returned row identities.");
+  for (const field of request.select.filter(isComputedField)) {
+    const id = field.slice("@computed/".length);
+    for (const rowId of ids) {
+      const value = sidecars.get(rowId)?.[id];
+      if (!value || value.value !== null && !["string", "number", "boolean"].includes(typeof value.value) || typeof value.value === "number" && !Number.isFinite(value.value))
+        throw Error(`Missing or invalid server computed result: ${field}.`);
+    }
+  }
+}
+
 // src/useComputedColumns.ts
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
@@ -5,12 +49,13 @@ import {
   compileFormula,
   computedFieldName,
   groupPreview,
-  isComputedField,
+  isComputedField as isComputedField2,
   memoryComputedColumnStore,
-  readFieldValue,
+  readFieldValue as readFieldValue2,
   toServerQuery,
   validateComputedColumn,
-  isSelectable
+  isSelectable,
+  hasRegex
 } from "@pythia-software/query-table-core";
 
 // src/formulaWorker.ts
@@ -51,9 +96,9 @@ function evaluateFormulaRows(ast, inputs, signal, factory = createFormulaWorker)
     const cleanup = () => {
       clearTimeout(timer);
       worker.terminate();
-      signal?.removeEventListener("abort", abort);
+      signal?.removeEventListener("abort", abort2);
     };
-    const abort = () => {
+    const abort2 = () => {
       cleanup();
       reject(new DOMException("Aborted", "AbortError"));
     };
@@ -82,7 +127,7 @@ function evaluateFormulaRows(ast, inputs, signal, factory = createFormulaWorker)
         reject(e);
       }
     };
-    signal?.addEventListener("abort", abort, { once: true });
+    signal?.addEventListener("abort", abort2, { once: true });
     worker.onerror = () => {
       cleanup();
       reject(new Error("Formula worker failed."));
@@ -164,7 +209,7 @@ function useComputedColumns(options) {
       const stack = new Set(editingId ? [editingId] : []);
       let expanded = 0;
       const resolve = (name) => {
-        if (!isComputedField(name)) return void 0;
+        if (!isComputedField2(name)) return void 0;
         const id = name.slice("@computed/".length), def = definitions.find((d) => d.id === id);
         if (!def) throw new Error(`Computed column unavailable: ${id}`);
         if (stack.has(id))
@@ -222,7 +267,7 @@ function useComputedColumns(options) {
         const values = /* @__PURE__ */ Object.create(null);
         for (const name of plan.dependencies) {
           const field = inputFields.find((f) => f.name === name);
-          const raw = readFieldValue(field, row);
+          const raw = readFieldValue2(field, row);
           values[name] = raw instanceof Date ? raw.toISOString() : raw;
         }
         size += JSON.stringify(values).length;
@@ -236,12 +281,13 @@ function useComputedColumns(options) {
     [inputFields]
   );
   const activeSelect = query.select.length ? query.select : schema.defaultSelect ?? [];
-  const activeIds = activeSelect.filter((c) => isComputedField(c.field)).map((c) => c.field.slice("@computed/".length)).sort().join(",");
+  const activeIds = activeSelect.filter((c) => isComputedField2(c.field)).map((c) => c.field.slice("@computed/".length)).sort().join(",");
   const [evaluated, setEvaluated] = useState(null);
   useEffect(() => {
     const ac = new AbortController();
     const values = /* @__PURE__ */ new Map();
     void (async () => {
+      if (options.execution && transport?.fetchRowsV2) return;
       for (const id of activeIds.split(",").filter(Boolean)) {
         const entry = plans.get(id);
         if (!entry?.plan) continue;
@@ -269,7 +315,15 @@ function useComputedColumns(options) {
       if (!ac.signal.aborted) setEvaluated({ rows, plans, values });
     })();
     return () => ac.abort();
-  }, [activeIds, rows, plans, inputsFor, workerFactory]);
+  }, [
+    activeIds,
+    rows,
+    plans,
+    inputsFor,
+    workerFactory,
+    options.execution,
+    transport
+  ]);
   const displaySchema = useMemo(() => {
     const indices = new Map(rows.map((row, i) => [row, i]));
     const fields = definitions.map((def) => {
@@ -285,17 +339,34 @@ function useComputedColumns(options) {
           dependencies: entry?.plan ? backendDependencies(entry.plan) : [],
           accessor: (row) => {
             if (entry?.error) return { computedError: entry.error };
+            if (options.execution && transport?.fetchRowsV2) {
+              if (options.serverExecution?.profile !== options.execution.profile || options.serverExecution?.planToken !== options.execution.planToken || options.serverExecution?.snapshot !== options.execution.snapshot || executionRevision(options.execution, def.id) !== def.revision || executionRevision(options.serverExecution, def.id) !== def.revision)
+                return {
+                  computedError: "Definition changed or values are pending. Refresh the server handshake."
+                };
+              const idField = schema.fields.find(
+                (f) => f.name === schema.idField
+              );
+              const id = idField ? readFieldValue2(idField, row) : null;
+              const server = id === null ? void 0 : options.serverComputed?.get(id)?.[def.id];
+              return server ? server.error ? { computedError: server.error.code } : server.value : { computedError: "Server computed result unavailable." };
+            }
             const result = evaluated?.rows === rows && evaluated.plans === plans ? evaluated.values.get(def.id)?.[indices.get(row) ?? -1] : void 0;
             return result?.error ? { computedError: result.error } : result ? result.value : { computedError: "Calculating\u2026" };
           }
         },
         filter: { enabled: false },
-        sort: { enabled: false },
-        aggregate: { measure: false, groupable: false }
+        sort: {
+          enabled: !!transport?.fetchRowsV2 && !!options.execution?.fields[computedFieldName(def.id)]?.sort && executionRevision(options.execution, def.id) === def.revision && !!entry?.plan && !hasRegex(entry.plan)
+        },
+        aggregate: {
+          measure: !!entry?.plan,
+          groupable: !!transport?.fetchMetrics && transport.metricCapabilities?.version === 2 && !!options.execution?.fields[computedFieldName(def.id)]?.group && executionRevision(options.execution, def.id) === def.revision && !!entry?.plan && !hasRegex(entry.plan)
+        }
       };
     });
     for (const col of activeSelect)
-      if (isComputedField(col.field) && !fields.some((f) => f.name === col.field))
+      if (isComputedField2(col.field) && !fields.some((f) => f.name === col.field))
         fields.push({
           name: col.field,
           label: col.field.slice(10),
@@ -321,7 +392,11 @@ function useComputedColumns(options) {
     rows,
     query.select,
     schema.defaultSelect,
-    loading
+    loading,
+    transport,
+    options.execution,
+    options.serverComputed,
+    options.serverExecution
   ]);
   const save = useCallback(
     async (column, expectedRevision) => {
@@ -422,85 +497,531 @@ function useComputedColumns(options) {
 }
 
 // src/useQueryTable.ts
-import { useCallback as useCallback6, useEffect as useEffect4, useMemo as useMemo6, useRef as useRef3, useState as useState6 } from "react";
+import { useCallback as useCallback8, useEffect as useEffect5, useMemo as useMemo7, useRef as useRef5, useState as useState7 } from "react";
 import {
   EMPTY_QUERY,
   applyQuery as applyQuery2,
   decodeQuery,
   encodeQuery,
   memoryStorageAdapter,
-  normalizeQueryState,
-  readFieldValue as readFieldValue2,
+  normalizeQueryState as normalizeQueryState2,
+  readFieldValue as readFieldValue4,
   selectedFields as selectedFields2,
   toServerQuery as toServerQuery2,
   queriesEqual,
   isOrGroup,
   predicatesOf,
   negateClause,
-  opsForField
+  opsForField,
+  metricPlans as metricPlans3,
+  validateMetric as validateMetric2,
+  metricDependencies,
+  isComputedField as isComputedField4,
+  toServerQueryV2
 } from "@pythia-software/query-table-core";
 
-// src/useAggregations.ts
-import { useEffect as useEffect2, useMemo as useMemo2, useState as useState2 } from "react";
-import { applyAggregations, toAggregationQuery } from "@pythia-software/query-table-core";
-var EMPTY_RESULT = { metrics: [] };
-function useAggregations(query, schema, transport, clientRows, debounceMs, nonce, validateQuery) {
-  const [results, setResults] = useState2(null);
-  const [loading, setLoading] = useState2(false);
-  const [error, setError] = useState2(null);
-  const key = useMemo2(
-    () => JSON.stringify({ where: query.where, aggregations: query.aggregations ?? [] }),
-    [query.where, query.aggregations]
-  );
-  const hasAggregations = (query.aggregations?.length ?? 0) > 0;
+// src/useRequestActivity.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+var methods = /* @__PURE__ */ new Set([
+  "fetchRows",
+  "fetchRowsV2",
+  "fetchMetrics",
+  "fetchAggregations",
+  "fetchRow",
+  "fetchDistinctValues",
+  "fetchFieldStats"
+]);
+function observeTransport(transport, publish, nextId) {
+  const wrappers = /* @__PURE__ */ new Map();
+  return new Proxy(Object.create(transport), {
+    get(_target, key) {
+      const method = Reflect.get(transport, key, transport);
+      if (!methods.has(String(key)) || typeof method !== "function")
+        return method;
+      if (!wrappers.has(key))
+        wrappers.set(key, async (...args) => {
+          const signal = args[1];
+          const start = performance.now();
+          const entry = {
+            id: nextId(),
+            kind: String(key).replace(/^fetch/, ""),
+            startedAt: Date.now(),
+            status: "pending"
+          };
+          publish(entry);
+          let done = false;
+          const finish = (status, error) => {
+            if (done) return;
+            done = true;
+            publish({
+              ...entry,
+              status,
+              durationMs: Math.max(0, performance.now() - start),
+              ...error !== void 0 ? {
+                error: error instanceof Error ? error.message : String(error)
+              } : {}
+            });
+          };
+          const abort2 = () => finish("aborted");
+          signal?.addEventListener("abort", abort2, { once: true });
+          if (signal?.aborted) abort2();
+          try {
+            const result = await method.apply(transport, args);
+            finish(signal?.aborted ? "aborted" : "success");
+            return result;
+          } catch (error) {
+            finish(
+              signal?.aborted || error instanceof Error && error.name === "AbortError" ? "aborted" : "error",
+              error
+            );
+            throw error;
+          } finally {
+            signal?.removeEventListener("abort", abort2);
+          }
+        });
+      return wrappers.get(key);
+    }
+  });
+}
+function useRequestActivity(source) {
+  const [entries, setEntries] = useState2([]);
+  const sequence = useRef2(0), mounted = useRef2(true);
   useEffect2(() => {
-    if (!hasAggregations) {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const publish = useCallback2((entry) => {
+    if (mounted.current)
+      setEntries(
+        (previous) => [entry, ...previous.filter((e) => e.id !== entry.id)].sort((a, b) => b.id - a.id).slice(0, 100)
+      );
+  }, []);
+  const transport = useMemo2(
+    () => source ? observeTransport(source, publish, () => ++sequence.current) : void 0,
+    [source, publish]
+  );
+  const clear = useCallback2(
+    () => setEntries((previous) => previous.filter((e) => e.status === "pending")),
+    []
+  );
+  const activity = useMemo2(
+    () => ({ entries, clear }),
+    [entries, clear]
+  );
+  return { transport, activity };
+}
+
+// src/useAggregations.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useMemo as useMemo3, useRef as useRef3, useState as useState3 } from "react";
+import {
+  metricComputationKey,
+  metricPlans as metricPlans2,
+  hasRegex as hasRegex3
+} from "@pythia-software/query-table-core";
+
+// src/metricExecution.ts
+import {
+  applyAggregations,
+  normalizeQueryState,
+  evaluateMetrics,
+  metricPlans,
+  hasRegex as hasRegex2,
+  toAggregationQuery,
+  toMetricQuery,
+  validateMetric,
+  selectMetricShownRows,
+  readFieldValue as readFieldValue3,
+  resolveFieldName,
+  isComputedField as isComputedField3
+} from "@pythia-software/query-table-core";
+var abort = (signal) => {
+  if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+};
+async function localMetrics(rows, query, context, signal) {
+  const originalClauses = query.aggregations ?? [];
+  const advanced = (query.aggregations ?? []).filter(
+    (c) => isComputedField3(c.field ?? "") || c.groupBy.some(isComputedField3) || c.diagnostics?.length || c.expression !== void 0 || c.expressionY !== void 0 || c.scope !== void 0 || c.distribution || c.sort || c.groupLimit !== void 0
+  );
+  if (advanced.length && (originalClauses.length > 20 || normalizeQueryState(query).aggregations?.length !== originalClauses.length))
+    return evaluateMetrics(rows, query, context.schema, {
+      ...signal ? { signal } : {},
+      ...context.resolveComputed ? { resolveComputed: context.resolveComputed } : {}
+    });
+  const legacy = (query.aggregations ?? []).filter(
+    (c) => !advanced.includes(c)
+  );
+  const compatible = applyAggregations(
+    rows,
+    { ...query, aggregations: legacy },
+    context.schema,
+    {
+      ...signal ? { signal } : {}
+    }
+  );
+  if (!advanced.length) return compatible;
+  query = { ...query, aggregations: advanced };
+  const options = {
+    ...context.resolveComputed ? { resolveComputed: context.resolveComputed } : {},
+    ...signal ? { signal } : {}
+  };
+  for (const clause of query.aggregations ?? []) {
+    const diagnostics = validateMetric(
+      clause,
+      context.schema,
+      context.resolveComputed
+    );
+    if (diagnostics.length)
+      throw Error(diagnostics.map((d) => d.message).join(" "));
+  }
+  const requiresPage = (query.aggregations ?? []).some(
+    (clause) => clause.scope === "shownRows"
+  );
+  const page = requiresPage ? selectMetricShownRows(rows, query, context.schema, {
+    ...options,
+    ...context.rowsReady && context.shownRows ? { shownRows: context.shownRows } : {}
+  }) : [];
+  const caches = /* @__PURE__ */ new Map();
+  for (const clause of query.aggregations ?? []) {
+    for (const plan of metricPlans(
+      clause,
+      context.schema,
+      context.resolveComputed
+    )) {
+      if (!hasRegex2(plan)) continue;
+      const nodes = "aggregates" in plan ? plan.aggregates.flatMap((a) => a.args) : [plan.ast];
+      for (const node of nodes) {
+        if (!hasRegex2({ ...plan, ast: node })) continue;
+        const key = JSON.stringify(node);
+        if (caches.has(key)) continue;
+        let bytes = 0;
+        const inputs = page.map((row) => {
+          const values2 = /* @__PURE__ */ Object.create(null);
+          for (const name of plan.dependencies) {
+            const field = context.schema.fields.find((f) => f.name === name);
+            if (!field) throw Error(`Unavailable metric input: ${name}`);
+            const raw = readFieldValue3(field, row);
+            values2[name] = raw instanceof Date ? raw.toISOString() : raw ?? null;
+          }
+          bytes += JSON.stringify(values2).length;
+          if (bytes > 16e6)
+            throw Error(
+              "Metric worker input exceeds 16 MB. Reduce the shown rows."
+            );
+          return values2;
+        });
+        const values = await evaluateFormulaRows(
+          node,
+          inputs,
+          signal,
+          context.workerFactory
+        );
+        caches.set(
+          key,
+          new Map(page.map((row, i) => [row, values[i]]))
+        );
+      }
+    }
+  }
+  abort(signal);
+  const typed = evaluateMetrics(rows, query, context.schema, {
+    ...options,
+    shownRows: page,
+    ...caches.size ? {
+      evaluateInput: (node, row, plan) => {
+        const cached = caches.get(JSON.stringify(node));
+        if (cached)
+          return cached.get(row) ?? {
+            value: null,
+            error: "Metric worker result missing."
+          };
+        throw Error("Metric regex input was not evaluated in a worker.");
+      }
+    } : {}
+  });
+  const byId = new Map(
+    [...compatible.metrics, ...typed.metrics].map((m) => [m.id, m])
+  );
+  return { metrics: originalClauses.flatMap((c) => byId.get(c.id) ?? []) };
+}
+async function executeMetrics(query, context, signal) {
+  abort(signal);
+  const clauses = query.aggregations ?? [];
+  if (!clauses.length) return { metrics: [] };
+  const supportsV2 = !!context.transport?.fetchMetrics && context.transport.metricCapabilities?.version === 2;
+  if (context.clientRows && !supportsV2 && !context.transport?.fetchAggregations)
+    return localMetrics(context.clientRows, query, context, signal);
+  const needsWorker = (c) => metricPlans(c, context.schema, context.resolveComputed).some(hasRegex2);
+  const shown = clauses.filter(
+    (c) => c.scope === "shownRows" && (!supportsV2 || needsWorker(c))
+  );
+  const matching = clauses.filter(
+    (c) => c.scope !== "shownRows" || supportsV2 && !needsWorker(c)
+  );
+  const results = [];
+  if (shown.length) {
+    if (!context.rowsReady || !context.shownRows)
+      throw Error(
+        "Wait for the current table page before previewing shown-row metrics."
+      );
+    const names = new Set(
+      shown.flatMap((clause) => [
+        ...clause.groupBy,
+        ...metricPlans(clause, context.schema, context.resolveComputed).flatMap(
+          (p) => p.dependencies
+        )
+      ])
+    );
+    for (const name of names) {
+      const canonical = resolveFieldName(context.schema, name) ?? name;
+      const field = context.schema.fields.find((f) => f.name === canonical);
+      const dependencies = field?.source.kind === "derived" ? field.source.dependencies ?? [] : [canonical];
+      const loaded = context.shownFields ? dependencies.every((dep) => context.shownFields.includes(dep)) : field && context.shownRows.every(
+        (row) => field.source.kind === "derived" || loadedPath(
+          row,
+          field.source.kind === "backend" ? field.source.path ?? field.name : field.name
+        )
+      );
+      if (!field || !loaded)
+        throw Error(
+          `Shown-page input ${name} is not loaded. Add it to the selected columns and refresh, or use a snapshot-capable metric transport.`
+        );
+    }
+    const pageQuery = {
+      ...query,
+      where: [],
+      orderBy: [],
+      limit: Math.max(1, context.shownRows.length),
+      offset: 0,
+      aggregations: shown
+    };
+    results.push(
+      ...(await localMetrics(context.shownRows, pageQuery, context, signal)).metrics
+    );
+  }
+  if (matching.length) {
+    const transport = context.transport;
+    const scoped = { ...query, aggregations: matching };
+    if (transport?.fetchMetrics && transport.metricCapabilities?.version === 2) {
+      const request = toMetricQuery(scoped, context.schema, context.execution);
+      if (request.diagnostics.length)
+        throw Error(request.diagnostics.map((d) => d.message).join(" "));
+      if (matching.some((c) => c.scope === "shownRows") && !transport.metricCapabilities.shownRows)
+        throw Error("This server does not support shown-row metrics.");
+      if (request.profile && transport.metricCapabilities.profile && request.profile !== transport.metricCapabilities.profile)
+        throw Error(
+          "Metric transport and computed execution profiles do not match. Refresh the handshake."
+        );
+      const remoteFields = new Map(
+        context.schema.fields.map((field) => [field.name, field])
+      );
+      for (const [name, capability] of Object.entries(
+        context.execution?.fields ?? {}
+      ))
+        if (isComputedField3(name))
+          remoteFields.set(name, {
+            name,
+            label: name,
+            type: capability.type,
+            source: { kind: "backend" }
+          });
+      const remoteSchema = {
+        ...context.schema,
+        fields: [...remoteFields.values()]
+      };
+      if (matching.some(
+        (clause) => [
+          ...clause.groupBy,
+          ...metricPlans(clause, remoteSchema).flatMap(
+            (plan) => plan.dependencies
+          )
+        ].some(isComputedField3)
+      ) && !transport.metricCapabilities.computedFields)
+        throw Error("This metric server does not support computed fields.");
+      if (request.metrics.some(
+        (c) => !c.distribution && (c.expression !== void 0 || c.expressionY !== void 0)
+      ) && !transport.metricCapabilities.expressions)
+        throw Error(
+          "This server does not support composed metric expressions."
+        );
+      if (matching.some(
+        (c) => c.distribution && (!c.display || ["box", "histogram"].includes(c.display.kind))
+      ) && !transport.metricCapabilities.distributions)
+        throw Error("This server does not support distributions.");
+      results.push(...(await transport.fetchMetrics(request, signal)).metrics);
+    } else if (transport?.fetchAggregations) {
+      const request = toAggregationQuery(scoped, context.schema);
+      if (request.diagnostics?.length)
+        throw Error(request.diagnostics.map((d) => d.message).join(" "));
+      results.push(
+        ...(await transport.fetchAggregations(request, signal)).metrics
+      );
+    } else
+      throw Error(
+        "All-matching metrics require a complete client dataset or a metric-capable server transport."
+      );
+  }
+  abort(signal);
+  const byId = new Map(results.map((r) => [r.id, r]));
+  return {
+    metrics: clauses.map(
+      (c) => byId.get(c.id) ?? {
+        id: c.id,
+        buckets: [],
+        error: "Server omitted this metric."
+      }
+    )
+  };
+}
+function loadedPath(row, path) {
+  if (!row || typeof row !== "object") return false;
+  if (path in row) return true;
+  let value = row;
+  for (const part of path.split(".")) {
+    if (value === null) return true;
+    if (!value || typeof value !== "object" || !(part in value)) return false;
+    value = value[part];
+  }
+  return true;
+}
+
+// src/useAggregations.ts
+function useAggregations(query, schema, transport, clientRows, debounceMs, nonce, validateQuery, options = {}) {
+  const [results, setResults] = useState3(null);
+  const [loading, setLoading] = useState3(false);
+  const [error, setError] = useState3(null);
+  const latest = useRef3({
+    query,
+    schema,
+    transport,
+    clientRows,
+    options,
+    validateQuery
+  });
+  latest.current = {
+    query,
+    schema,
+    transport,
+    clientRows,
+    options,
+    validateQuery
+  };
+  const preview = useCallback3(
+    async (clauses, signal) => {
+      const current = latest.current;
+      const draft = { ...current.query, aggregations: clauses };
+      current.validateQuery?.(draft);
+      return executeMetrics(
+        draft,
+        {
+          schema: current.schema,
+          transport: current.transport,
+          clientRows: current.clientRows,
+          ...current.options
+        },
+        signal
+      );
+    },
+    []
+  );
+  const shown = (query.aggregations ?? []).some((c) => c.scope === "shownRows");
+  const localPage = shown && (!transport?.fetchMetrics || transport.metricCapabilities?.version !== 2 || (query.aggregations ?? []).some((clause) => {
+    if (clause.scope !== "shownRows") return false;
+    try {
+      return metricPlans2(clause, schema, options.resolveComputed).some(
+        hasRegex3
+      );
+    } catch {
+      return true;
+    }
+  }));
+  const key = useMemo3(
+    () => JSON.stringify([
+      query.where,
+      metricComputationKey(query.aggregations ?? []),
+      shown ? [query.orderBy, query.limit, query.offset] : null
+    ]),
+    [
+      query.where,
+      query.aggregations,
+      query.orderBy,
+      query.limit,
+      query.offset,
+      shown
+    ]
+  );
+  const dependencyKey = JSON.stringify([
+    options.revisions ?? {},
+    options.execution ?? null
+  ]);
+  useEffect3(() => {
+    if (!latest.current.query.aggregations?.length) {
       setResults(null);
-      setError(null);
       setLoading(false);
+      setError(null);
       return;
     }
     const ac = new AbortController();
-    let cancelled = false;
-    const run = async () => {
-      setLoading(true);
+    setLoading(true);
+    setResults(null);
+    if (localPage && transport && !options.rowsReady) {
+      try {
+        latest.current.validateQuery?.(latest.current.query);
+        setError(options.rowsError ?? null);
+        if (options.rowsError) setLoading(false);
+      } catch (e) {
+        setError(e instanceof Error ? e : Error(String(e)));
+        setLoading(false);
+      }
+      return;
+    }
+    const timer = setTimeout(() => {
       setError(null);
       try {
-        validateQuery?.(query);
-        let res;
-        if (transport?.fetchAggregations) {
-          res = await transport.fetchAggregations(toAggregationQuery(query, schema), ac.signal);
-        } else if (clientRows) {
-          res = applyAggregations(clientRows, query, schema);
-        } else {
-          res = EMPTY_RESULT;
-        }
-        if (!cancelled) setResults(res);
+        latest.current.validateQuery?.(latest.current.query);
       } catch (e) {
-        if (!cancelled && !ac.signal.aborted) {
-          setError(e);
-          setResults(null);
-        }
-      } finally {
-        if (!cancelled) setLoading(false);
+        setError(e instanceof Error ? e : Error(String(e)));
+        setLoading(false);
+        return;
       }
-    };
-    const t = setTimeout(run, debounceMs);
+      void preview(latest.current.query.aggregations ?? [], ac.signal).then((result) => {
+        if (!ac.signal.aborted) setResults(result);
+      }).catch((e) => {
+        if (!ac.signal.aborted)
+          setError(e instanceof Error ? e : Error(String(e)));
+      }).finally(() => {
+        if (!ac.signal.aborted) setLoading(false);
+      });
+    }, debounceMs);
     return () => {
-      cancelled = true;
-      clearTimeout(t);
       ac.abort();
+      clearTimeout(timer);
     };
-  }, [key, hasAggregations, transport, clientRows, schema, debounceMs, nonce, validateQuery]);
-  return { results, loading, error };
+  }, [
+    key,
+    schema,
+    transport,
+    clientRows,
+    debounceMs,
+    nonce,
+    validateQuery,
+    dependencyKey,
+    localPage,
+    localPage ? options.shownRows : void 0,
+    localPage ? options.rowsReady : void 0,
+    localPage ? options.rowsError : void 0,
+    preview
+  ]);
+  return { results, loading, error, preview };
 }
 
 // src/useSelection.ts
-import { useCallback as useCallback2, useMemo as useMemo3, useRef as useRef2, useState as useState3 } from "react";
+import { useCallback as useCallback4, useMemo as useMemo4, useRef as useRef4, useState as useState4 } from "react";
 function useSelection(displayedIds) {
-  const [selected, setSelected] = useState3(() => /* @__PURE__ */ new Set());
-  const anchor = useRef2(null);
-  const toggle = useCallback2(
+  const [selected, setSelected] = useState4(() => /* @__PURE__ */ new Set());
+  const anchor = useRef4(null);
+  const toggle = useCallback4(
     (id, shiftKey = false) => {
       setSelected((prev) => {
         const next = new Set(prev);
@@ -528,7 +1049,7 @@ function useSelection(displayedIds) {
     },
     [displayedIds]
   );
-  const setPage = useCallback2((ids, select) => {
+  const setPage = useCallback4((ids, select) => {
     setSelected((prev) => {
       const next = new Set(prev);
       for (const id of ids) {
@@ -538,12 +1059,12 @@ function useSelection(displayedIds) {
       return next;
     });
   }, []);
-  const replace = useCallback2((ids) => {
+  const replace = useCallback4((ids) => {
     const next = new Set(ids);
     anchor.current = null;
     setSelected(next);
   }, []);
-  const retain = useCallback2((ids) => {
+  const retain = useCallback4((ids) => {
     const allowed = new Set(ids);
     anchor.current = null;
     setSelected((prev) => {
@@ -552,7 +1073,7 @@ function useSelection(displayedIds) {
       return next;
     });
   }, []);
-  const pageState = useCallback2(
+  const pageState = useCallback4(
     (pageIds) => {
       if (pageIds.length === 0) return "none";
       let n = 0;
@@ -561,11 +1082,11 @@ function useSelection(displayedIds) {
     },
     [selected]
   );
-  const clear = useCallback2(() => {
+  const clear = useCallback4(() => {
     anchor.current = null;
     setSelected(/* @__PURE__ */ new Set());
   }, []);
-  return useMemo3(
+  return useMemo4(
     () => ({
       selected,
       isSelected: (id) => selected.has(id),
@@ -582,16 +1103,16 @@ function useSelection(displayedIds) {
 }
 
 // src/useSelect.ts
-import { useCallback as useCallback3, useMemo as useMemo4 } from "react";
+import { useCallback as useCallback5, useMemo as useMemo5 } from "react";
 import { selectedFields } from "@pythia-software/query-table-core";
 function useSelect(query, setQuery, schema) {
-  const fields = useMemo4(() => selectedFields(schema, query), [schema, query]);
-  const visible = useMemo4(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
-  const hidden = useMemo4(() => {
+  const fields = useMemo5(() => selectedFields(schema, query), [schema, query]);
+  const visible = useMemo5(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
+  const hidden = useMemo5(() => {
     const shown = new Set(fields.map((f) => f.name));
     return schema.fields.filter((f) => !shown.has(f.name) && (f.select?.enabled ?? true));
   }, [schema, fields]);
-  const writeSelect = useCallback3(
+  const writeSelect = useCallback5(
     (mutate) => {
       setQuery((prev) => {
         const current = prev.select.length ? prev.select : visible;
@@ -600,9 +1121,9 @@ function useSelect(query, setQuery, schema) {
     },
     [setQuery, visible]
   );
-  const show = useCallback3((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
-  const hide = useCallback3((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
-  const move = useCallback3(
+  const show = useCallback5((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
+  const hide = useCallback5((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
+  const move = useCallback5(
     (field, toIndex) => writeSelect((c) => {
       const from = c.findIndex((x) => x.field === field);
       if (from === -1) return c;
@@ -612,11 +1133,11 @@ function useSelect(query, setQuery, schema) {
     }),
     [writeSelect]
   );
-  const setWidth = useCallback3(
+  const setWidth = useCallback5(
     (field, width) => writeSelect((c) => c.map((x) => x.field === field ? { ...x, width: Math.round(width) } : x)),
     [writeSelect]
   );
-  const reset = useCallback3(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
+  const reset = useCallback5(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
   return { visible, fields, hidden, show, hide, move, setWidth, reset };
 }
 function columnFor(select, name) {
@@ -625,50 +1146,81 @@ function columnFor(select, name) {
 }
 
 // src/useColumnDrag.ts
-import { useCallback as useCallback4, useMemo as useMemo5, useState as useState4 } from "react";
+import { useCallback as useCallback6, useMemo as useMemo6, useState as useState5 } from "react";
 function useColumnDrag() {
-  const [state, setState] = useState4(null);
-  const start = useCallback4((field, index) => setState({ source: field, overIndex: index }), []);
-  const over = useCallback4(
-    (index) => (
+  const [state, setState] = useState5(null);
+  const [dropRevision, setDropRevision] = useState5(0);
+  const start = useCallback6(
+    (field, index, order) => setState({
+      source: field,
+      overIndex: index,
+      order: order?.slice(),
+      moved: false
+    }),
+    []
+  );
+  const over = useCallback6(
+    (index, order) => (
       // Keep the SAME object reference when unchanged so React can bail out of the
       // re-render — onDragOver fires continuously while the cursor moves.
-      setState((s) => s && s.overIndex !== index ? { source: s.source, overIndex: index } : s)
+      setState((s) => {
+        if (!s) return s;
+        if (s.moved && s.overIndex === index && (!order && !s.order || order && s.order && order.length === s.order.length && order.every((name, i) => name === s.order[i])))
+          return s;
+        return {
+          source: s.source,
+          overIndex: index,
+          order: order?.slice(),
+          moved: true
+        };
+      })
     ),
     []
   );
-  const end = useCallback4(() => setState(null), []);
-  const preview = useCallback4(
+  const end = useCallback6((committed = false) => {
+    if (committed) setDropRevision((revision) => revision + 1);
+    setState(null);
+  }, []);
+  const preview = useCallback6(
     (order) => {
-      if (!state) return order;
+      if (!state || state.order && !state.moved) return order;
       const without = order.filter((n) => n !== state.source);
       if (without.length === order.length) return order;
-      const at = Math.max(0, Math.min(state.overIndex, without.length));
+      let at = Math.max(0, Math.min(state.overIndex, without.length));
+      if (state.order) {
+        const reference = state.order.filter((name) => name !== state.source);
+        const slot = Math.max(0, Math.min(state.overIndex, reference.length));
+        const following = reference.slice(slot).find((name) => without.includes(name));
+        const preceding = reference.slice(0, slot).reverse().find((name) => without.includes(name));
+        if (following != null) at = without.indexOf(following);
+        else if (preceding != null) at = without.indexOf(preceding) + 1;
+      }
       return [...without.slice(0, at), state.source, ...without.slice(at)];
     },
     [state]
   );
-  return useMemo5(
+  return useMemo6(
     () => ({
       source: state?.source ?? null,
       overIndex: state?.overIndex ?? null,
       active: state != null,
+      dropRevision,
       start,
       over,
       end,
       preview
     }),
-    [state, start, over, end, preview]
+    [state, dropRevision, start, over, end, preview]
   );
 }
 
 // src/useSavedQueries.ts
-import { useCallback as useCallback5, useEffect as useEffect3, useState as useState5 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect4, useState as useState6 } from "react";
 function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
-  const [items, setItems] = useState5([]);
-  const [defaultId, setDefaultId] = useState5(null);
-  const [loading, setLoading] = useState5(true);
-  const refresh = useCallback5(async () => {
+  const [items, setItems] = useState6([]);
+  const [defaultId, setDefaultId] = useState6(null);
+  const [loading, setLoading] = useState6(true);
+  const refresh = useCallback7(async () => {
     setLoading(true);
     try {
       const [savedItems, defaultSaved] = await Promise.all([
@@ -681,10 +1233,10 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
       setLoading(false);
     }
   }, [storage, key]);
-  useEffect3(() => {
+  useEffect4(() => {
     void refresh();
   }, [refresh]);
-  const save = useCallback5(
+  const save = useCallback7(
     async (name) => {
       const saved = await storage.saveNamed(key, name, currentQuery, now());
       await refresh();
@@ -692,25 +1244,25 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
     },
     [storage, key, currentQuery, now, refresh]
   );
-  const load = useCallback5(
+  const load = useCallback7(
     (id) => {
       const found = items.find((q) => q.id === id);
       if (found) applyQueryState(found.query);
     },
     [items, applyQueryState]
   );
-  const setDefault = useCallback5(
+  const setDefault = useCallback7(
     async (id) => {
       await storage.setDefaultSaved?.(key, id);
       await refresh();
     },
     [storage, key, refresh]
   );
-  const clearDefault = useCallback5(async () => {
+  const clearDefault = useCallback7(async () => {
     await storage.setDefaultSaved?.(key, null);
     await refresh();
   }, [storage, key, refresh]);
-  const remove = useCallback5(
+  const remove = useCallback7(
     async (id) => {
       if (id === defaultId) await storage.setDefaultSaved?.(key, null);
       await storage.deleteSaved(key, id);
@@ -725,7 +1277,7 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
 var AUTOCOMPLETE_LIMIT = 50;
 var MAX_AUTO_REFRESH_POLLS = 1e3;
 function defaultsFor(schema) {
-  return normalizeQueryState({
+  return normalizeQueryState2({
     select: schema.defaultSelect ?? [],
     where: [],
     orderBy: schema.defaultSort ?? [],
@@ -735,30 +1287,31 @@ function defaultsFor(schema) {
 }
 function cloneWhereTerm(term) {
   const copy = isOrGroup(term) ? { ...term, any: term.any.map((c) => ({ ...c })) } : { ...term };
-  if (term.setFilter) copy.setFilter = { ...term.setFilter, values: [...term.setFilter.values] };
+  if (term.setFilter)
+    copy.setFilter = { ...term.setFilter, values: [...term.setFilter.values] };
   return copy;
 }
 function cloneQueryState(q) {
   const clone = {
     select: q.select.map((column) => ({ ...column })),
     where: q.where.map(cloneWhereTerm),
-    orderBy: q.orderBy.map((term) => term.extract ? { ...term, extract: { ...term.extract } } : { ...term }),
+    orderBy: q.orderBy.map(
+      (term) => term.extract ? { ...term, extract: { ...term.extract } } : { ...term }
+    ),
     limit: q.limit,
     offset: q.offset
   };
-  if (q.aggregations) clone.aggregations = q.aggregations.map((a) => ({ ...a, groupBy: [...a.groupBy] }));
+  if (q.aggregations)
+    clone.aggregations = JSON.parse(
+      JSON.stringify(q.aggregations)
+    );
   return clone;
 }
 function mergeAggregation(a, patch) {
-  const next = {
-    id: a.id,
-    op: patch.op ?? a.op,
-    groupBy: patch.groupBy ?? a.groupBy
-  };
-  const field = "field" in patch ? patch.field : a.field;
-  if (field) next.field = field;
-  const label = "label" in patch ? patch.label : a.label;
-  if (label) next.label = label;
+  const next = { ...a, ...patch };
+  for (const key of Object.keys(next)) {
+    if (next[key] === void 0) delete next[key];
+  }
   return next;
 }
 function isNullLike(value) {
@@ -773,7 +1326,7 @@ function asDistinctValue(value) {
 }
 function fieldHasNullInRows(field, rows) {
   for (const row of rows) {
-    if (isNullLike(readFieldValue2(field, row))) return true;
+    if (isNullLike(readFieldValue4(field, row))) return true;
   }
   return false;
 }
@@ -782,73 +1335,110 @@ function distinctValuesFromRows(field, rows, search) {
   const values = [];
   const seen = /* @__PURE__ */ new Set();
   let hasMore = false;
-  for (const row of rows) {
-    const raw = asDistinctValue(readFieldValue2(field, row));
-    if (raw == null || seen.has(raw)) continue;
-    if (target && !raw.toLowerCase().includes(target)) continue;
-    if (values.length < AUTOCOMPLETE_LIMIT) {
-      seen.add(raw);
-      values.push(raw);
-      continue;
+  rowsLoop: for (const row of rows) {
+    const value = readFieldValue4(field, row);
+    const candidates = field.type === "textarray" && Array.isArray(value) ? value : [value];
+    for (const candidate of candidates) {
+      const raw = asDistinctValue(candidate);
+      if (raw == null || seen.has(raw)) continue;
+      if (target && !raw.toLowerCase().includes(target)) continue;
+      if (values.length < AUTOCOMPLETE_LIMIT) {
+        seen.add(raw);
+        values.push(raw);
+        continue;
+      }
+      hasMore = true;
+      break rowsLoop;
     }
-    hasMore = true;
-    break;
   }
   return { values: values.sort((a, b) => a.localeCompare(b)), hasMore };
 }
 function resolveInitial(opts) {
   const defaults = defaultsFor(opts.schema);
-  if (opts.initialQuery) return { q: normalizeQueryState(opts.initialQuery, defaults), fromUrl: false };
+  if (opts.initialQuery)
+    return {
+      q: normalizeQueryState2(opts.initialQuery, defaults),
+      fromUrl: false
+    };
   if (opts.syncUrl === true && typeof window !== "undefined") {
     const token = new URLSearchParams(window.location.search).get("q");
-    if (token) return { q: normalizeQueryState(decodeQuery(token), defaults), fromUrl: true };
+    if (token)
+      return {
+        q: normalizeQueryState2(decodeQuery(token), defaults),
+        fromUrl: true
+      };
   }
   return { q: defaults, fromUrl: false };
 }
 function useQueryTable(opts) {
-  const { schema, transport, clientRows, initialQuery, syncUrl = false, debounceMs = 200 } = opts;
-  const storage = useMemo6(() => opts.storage ?? memoryStorageAdapter(), [opts.storage]);
+  const {
+    schema,
+    transport: sourceTransport,
+    clientRows,
+    initialQuery,
+    syncUrl = false,
+    debounceMs = 200
+  } = opts;
+  const { transport, activity: requestActivity } = useRequestActivity(sourceTransport);
+  const storage = useMemo7(
+    () => opts.storage ?? memoryStorageAdapter(),
+    [opts.storage]
+  );
   const now = opts.now ?? Date.now;
-  const nowRef = useRef3(now);
-  const onRefreshRef = useRef3(opts.onRefresh);
-  const defaults = useMemo6(() => defaultsFor(schema), [schema]);
-  const byName = useMemo6(() => new Map(schema.fields.map((f) => [f.name, f])), [schema]);
-  const initRef = useRef3(resolveInitial(opts));
-  const aggIdRef = useRef3(0);
-  const [storedQuery, setQueryState] = useState6(initRef.current.q);
-  const query = useMemo6(() => opts.canonicalizeQuery?.(storedQuery) ?? storedQuery, [storedQuery, opts.canonicalizeQuery]);
-  const undoStack = useRef3([cloneQueryState(initRef.current.q)]);
-  const redoStack = useRef3([]);
-  const [rows, setRows] = useState6([]);
-  const [total, setTotal] = useState6(null);
-  const [loading, setLoading] = useState6(false);
-  const [error, setError] = useState6(null);
-  const [nonce, setNonce] = useState6(0);
-  const [autoRefreshStatus, setAutoRefreshStatus] = useState6(null);
-  useEffect4(() => {
+  const nowRef = useRef5(now);
+  const onRefreshRef = useRef5(opts.onRefresh);
+  const defaults = useMemo7(() => defaultsFor(schema), [schema]);
+  const byName = useMemo7(
+    () => new Map(schema.fields.map((f) => [f.name, f])),
+    [schema]
+  );
+  const initRef = useRef5(resolveInitial(opts));
+  const aggIdRef = useRef5(0);
+  const [storedQuery, setQueryState] = useState7(initRef.current.q);
+  const query = useMemo7(
+    () => opts.canonicalizeQuery?.(storedQuery) ?? storedQuery,
+    [storedQuery, opts.canonicalizeQuery]
+  );
+  const undoStack = useRef5([cloneQueryState(initRef.current.q)]);
+  const redoStack = useRef5([]);
+  const [rows, setRows] = useState7([]);
+  const [serverComputed, setServerComputed] = useState7(/* @__PURE__ */ new Map());
+  const [committedFields, setCommittedFields] = useState7([]);
+  const [serverExecution, setServerExecution] = useState7();
+  const [total, setTotal] = useState7(null);
+  const [loading, setLoading] = useState7(false);
+  const [error, setError] = useState7(null);
+  const [nonce, setNonce] = useState7(0);
+  const [committedPage, setCommittedPage] = useState7(null);
+  const [committedSource, setCommittedSource] = useState7(null);
+  const [autoRefreshStatus, setAutoRefreshStatus] = useState7(null);
+  useEffect5(() => {
     nowRef.current = now;
   }, [now]);
-  useEffect4(() => {
+  useEffect5(() => {
     onRefreshRef.current = opts.onRefresh;
   }, [opts.onRefresh]);
-  const setQuery = useCallback6((next) => {
-    setQueryState((prev) => {
-      const candidate = typeof next === "function" ? next(prev) : next;
-      const nextQuery = normalizeQueryState(candidate, defaults);
-      if (queriesEqual(prev, nextQuery)) return prev;
-      undoStack.current.push(cloneQueryState(prev));
-      redoStack.current = [];
-      return cloneQueryState(nextQuery);
-    });
-  }, [defaults]);
-  useEffect4(() => {
+  const setQuery = useCallback8(
+    (next) => {
+      setQueryState((prev) => {
+        const candidate = typeof next === "function" ? next(prev) : next;
+        const nextQuery = normalizeQueryState2(candidate, defaults);
+        if (queriesEqual(prev, nextQuery)) return prev;
+        undoStack.current.push(cloneQueryState(prev));
+        redoStack.current = [];
+        return cloneQueryState(nextQuery);
+      });
+    },
+    [defaults]
+  );
+  useEffect5(() => {
     if (initRef.current.fromUrl || initialQuery) return;
     let cancelled = false;
     void (async () => {
       const defaultSaved = await storage.loadDefaultSaved?.(schema.name);
       const restored = defaultSaved?.query ?? await storage.loadLast(schema.name);
       if (!cancelled && restored) {
-        const normalized = normalizeQueryState(restored, defaults);
+        const normalized = normalizeQueryState2(restored, defaults);
         undoStack.current = [cloneQueryState(normalized)];
         redoStack.current = [];
         setQueryState(normalized);
@@ -862,18 +1452,93 @@ function useQueryTable(opts) {
     schema,
     query,
     rows,
+    serverComputed,
+    ...serverExecution ? { serverExecution } : {},
+    ...opts.computedExecution ? { execution: opts.computedExecution } : {},
     ...opts.computedColumnStore ? { store: opts.computedColumnStore } : {},
     ...opts.formulaWorkerFactory ? { workerFactory: opts.formulaWorkerFactory } : {},
     ...transport ? { transport } : {},
     ...clientRows ? { clientRows } : {}
   });
-  const queryKey = useMemo6(() => encodeQuery(query), [query]);
-  const serverRowQuery = useMemo6(() => toServerQuery2(query, displaySchema), [queryKey, displaySchema]);
-  const rowQueryKey = useMemo6(
+  const resolveComputed = useCallback8(
+    (name) => isComputedField4(name) ? computed.compile(`[${name.replace(/]/g, "]] ".trim())}]`) : void 0,
+    [computed.compile]
+  );
+  const metricCompile = useCallback8(
+    (clause) => {
+      const diagnostics = validateMetric2(
+        clause,
+        displaySchema,
+        resolveComputed
+      );
+      if (diagnostics.length)
+        throw new Error(diagnostics.map((d) => d.message).join(" "));
+      return metricPlans3(clause, displaySchema, resolveComputed);
+    },
+    [displaySchema, resolveComputed]
+  );
+  const computedRevisions = useMemo7(
+    () => Object.fromEntries(computed.definitions.map((d) => [d.id, d.revision])),
+    [computed.definitions]
+  );
+  const definitionKey = JSON.stringify(computedRevisions);
+  const queryKey = useMemo7(() => encodeQuery(query), [query]);
+  const serverRowQuery = useMemo7(() => {
+    const execution = opts.computedExecution;
+    const v2Request = execution && transport?.fetchRowsV2 ? toServerQueryV2(query, displaySchema, execution) : void 0;
+    const request = v2Request ?? toServerQuery2(query, displaySchema);
+    if (v2Request)
+      for (const definition of computed.definitions) {
+        if (executionRevision(execution, definition.id) !== void 0 && executionRevision(execution, definition.id) !== definition.revision)
+          v2Request.diagnostics.push({
+            from: 0,
+            to: 1,
+            code: "definition_changed",
+            message: "Computed definitions changed. Refresh the server execution handshake."
+          });
+      }
+    for (const clause of query.aggregations ?? [])
+      if (clause.scope === "shownRows") {
+        try {
+          for (const name of metricDependencies(
+            clause,
+            schema,
+            resolveComputed
+          )) {
+            const field = schema.fields.find((f) => f.name === name);
+            if (field?.source.kind === "backend") request.select.push(name);
+            else
+              for (const dep of field?.source.kind === "derived" ? field.source.dependencies ?? [] : [])
+                request.select.push(dep);
+          }
+        } catch {
+        }
+      }
+    request.select = [...new Set(request.select)].sort();
+    return request;
+  }, [
+    queryKey,
+    displaySchema,
+    transport,
+    computedRevisions,
+    schema,
+    resolveComputed,
+    opts.computedExecution
+  ]);
+  const rowQueryKey = useMemo7(
     () => transport ? `server:${JSON.stringify(serverRowQuery)}` : `client:${JSON.stringify([query.where, query.orderBy, query.limit, query.offset])}`,
-    [transport, serverRowQuery, query.where, query.orderBy, query.limit, query.offset]
+    [
+      transport,
+      serverRowQuery,
+      query.where,
+      query.orderBy,
+      query.limit,
+      query.offset
+    ]
   );
-  useEffect4(() => {
+  const executionKey = JSON.stringify(opts.computedExecution ?? null);
+  const pageContext = `${schema.name}:${rowQueryKey}:${nonce}:${executionKey}`;
+  useEffect5(() => {
     const ac = new AbortController();
     let cancelled = false;
     const run = async () => {
@@ -882,16 +1547,47 @@ function useQueryTable(opts) {
       try {
         opts.validateQuery?.(query);
         if (transport) {
-          const res = await transport.fetchRows(serverRowQuery, ac.signal);
+          const useV2 = "version" in serverRowQuery && transport.fetchRowsV2;
+          if ("diagnostics" in serverRowQuery && Array.isArray(serverRowQuery.diagnostics) && serverRowQuery.diagnostics.length)
+            throw Error(
+              serverRowQuery.diagnostics.map((d) => d.message).join(" ")
+            );
+          if (!useV2 && query.orderBy.some((s) => isComputedField4(s.field)))
+            throw Error(
+              "Global computed sorting requires a server execution handshake and fetchRowsV2."
+            );
+          const res = useV2 ? await transport.fetchRowsV2(
+            serverRowQuery,
+            ac.signal
+          ) : await transport.fetchRows(serverRowQuery, ac.signal);
+          if (useV2)
+            validateComputedResponse(
+              serverRowQuery,
+              res,
+              schema
+            );
           if (!cancelled) {
+            setCommittedFields(serverRowQuery.select);
+            setServerExecution(
+              useV2 ? res.execution : void 0
+            );
+            if ("computed" in res && Array.isArray(res.computed))
+              setServerComputed(
+                new Map(res.computed.map((c) => [c.id, c.values]))
+              );
+            else setServerComputed(/* @__PURE__ */ new Map());
             setRows(res.rows);
             setTotal(res.total);
+            setCommittedPage(pageContext);
+            setCommittedSource({ schema, transport, clientRows });
           }
         } else {
           const res = applyQuery2(clientRows ?? [], query, schema);
           if (!cancelled) {
             setRows(res.rows);
             setTotal(res.total);
+            setCommittedPage(pageContext);
+            setCommittedSource({ schema, transport, clientRows });
           }
         }
       } catch (e) {
@@ -899,6 +1595,7 @@ function useQueryTable(opts) {
           setError(e);
           setRows([]);
           setTotal(null);
+          setCommittedPage(null);
         }
       } finally {
         if (!cancelled) setLoading(false);
@@ -910,8 +1607,17 @@ function useQueryTable(opts) {
       clearTimeout(t);
       ac.abort();
     };
-  }, [rowQueryKey, transport, clientRows, schema, debounceMs, nonce, opts.validateQuery]);
-  useEffect4(() => {
+  }, [
+    rowQueryKey,
+    transport,
+    clientRows,
+    schema,
+    debounceMs,
+    nonce,
+    opts.validateQuery,
+    executionKey
+  ]);
+  useEffect5(() => {
     if (!syncUrl || typeof window === "undefined") return;
     const url = new URL(window.location.href);
     const token = encodeQuery(query);
@@ -919,16 +1625,22 @@ function useQueryTable(opts) {
     else url.searchParams.delete("q");
     window.history.replaceState(null, "", url.toString());
   }, [queryKey, syncUrl, query]);
-  useEffect4(() => {
+  useEffect5(() => {
     const t = setTimeout(() => void storage.saveLast(schema.name, query), 400);
     return () => clearTimeout(t);
   }, [queryKey, storage, schema.name, query]);
-  const idField = useMemo6(() => schema.fields.find((f) => f.name === schema.idField), [schema]);
-  const rowId = useCallback6(
-    (row) => idField ? readFieldValue2(idField, row) : null,
+  const idField = useMemo7(
+    () => schema.fields.find((f) => f.name === schema.idField),
+    [schema]
+  );
+  const rowId = useCallback8(
+    (row) => idField ? readFieldValue4(idField, row) : null,
     [idField]
   );
-  const displayedIds = useMemo6(() => rows.map(rowId).filter((id) => id != null), [rows, rowId]);
+  const displayedIds = useMemo7(
+    () => rows.map(rowId).filter((id) => id != null),
+    [rows, rowId]
+  );
   const selection = useSelection(displayedIds);
   const select = useSelect(query, setQuery, displaySchema);
   const columnDrag = useColumnDrag();
@@ -939,10 +1651,54 @@ function useQueryTable(opts) {
     storage,
     now
   );
-  const aggState = useAggregations(query, schema, transport, clientRows, debounceMs, nonce, opts.validateQuery);
+  const pageReady = committedPage === pageContext && committedSource?.schema === schema && committedSource?.transport === transport && committedSource?.clientRows === clientRows && !error;
+  const dataToken = useRef5(0);
+  const dataVersion = useMemo7(
+    () => ++dataToken.current,
+    [schema, transport, clientRows, nonce, definitionKey, executionKey]
+  );
+  const aggState = useAggregations(
+    query,
+    schema,
+    transport,
+    clientRows,
+    debounceMs,
+    nonce,
+    opts.validateQuery,
+    {
+      shownRows: rows,
+      rowsReady: pageReady,
+      rowsError: error,
+      ...transport ? { shownFields: committedFields } : {},
+      resolveComputed,
+      revisions: computedRevisions,
+      ...opts.computedExecution ? {
+        execution: pageReady && serverExecution ? serverExecution : opts.computedExecution
+      } : {},
+      ...opts.formulaWorkerFactory ? { workerFactory: opts.formulaWorkerFactory } : {}
+    }
+  );
+  const queryRef = useRef5(query);
+  queryRef.current = query;
+  const replaceAggregations = useCallback8(
+    (clauses, expected) => {
+      if (expected && JSON.stringify(queryRef.current.aggregations ?? []) !== JSON.stringify(expected))
+        throw new Error(
+          "Metrics changed while editing. Reopen the editor to use the latest configuration."
+        );
+      for (const clause of clauses) metricCompile(clause);
+      setQuery((q) => ({
+        ...q,
+        aggregations: JSON.parse(
+          JSON.stringify(clauses)
+        )
+      }));
+    },
+    [setQuery, metricCompile]
+  );
   const canUndo = undoStack.current.length > 0;
   const canRedo = redoStack.current.length > 0;
-  const undo = useCallback6(() => {
+  const undo = useCallback8(() => {
     setQueryState((prev) => {
       const previous = undoStack.current.pop();
       if (!previous) return prev;
@@ -950,7 +1706,7 @@ function useQueryTable(opts) {
       return cloneQueryState(previous);
     });
   }, []);
-  const redo = useCallback6(() => {
+  const redo = useCallback8(() => {
     setQueryState((prev) => {
       const next = redoStack.current.pop();
       if (!next) return prev;
@@ -958,30 +1714,50 @@ function useQueryTable(opts) {
       return cloneQueryState(next);
     });
   }, []);
-  const patch = useCallback6((p) => setQuery((prev) => ({ ...prev, ...p })), [setQuery]);
-  const addFilter = useCallback6((clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })), [setQuery]);
-  const updateFilter = useCallback6(
-    (index, clause) => setQuery((q) => ({ ...q, offset: 0, where: q.where.map((t, i) => i === index ? clause : t) })),
+  const patch = useCallback8(
+    (p) => setQuery((prev) => ({ ...prev, ...p })),
     [setQuery]
   );
-  const removeFilter = useCallback6(
-    (index) => setQuery((q) => ({ ...q, offset: 0, where: q.where.filter((_, i) => i !== index) })),
+  const addFilter = useCallback8(
+    (clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })),
     [setQuery]
   );
-  const clearFilters = useCallback6(() => setQuery((q) => ({ ...q, offset: 0, where: [] })), [setQuery]);
-  const updatePredicate = useCallback6(
+  const updateFilter = useCallback8(
+    (index, clause) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.map((t, i) => i === index ? clause : t)
+    })),
+    [setQuery]
+  );
+  const removeFilter = useCallback8(
+    (index) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.filter((_, i) => i !== index)
+    })),
+    [setQuery]
+  );
+  const clearFilters = useCallback8(
+    () => setQuery((q) => ({ ...q, offset: 0, where: [] })),
+    [setQuery]
+  );
+  const updatePredicate = useCallback8(
     (termIndex, predIndex, clause) => setQuery((q) => ({
       ...q,
       offset: 0,
       where: q.where.map((term, i) => {
         if (i !== termIndex) return term;
-        if (isOrGroup(term)) return { any: term.any.map((c, j) => j === predIndex ? clause : c) };
+        if (isOrGroup(term))
+          return {
+            any: term.any.map((c, j) => j === predIndex ? clause : c)
+          };
         return clause;
       })
     })),
     [setQuery]
   );
-  const removePredicate = useCallback6(
+  const removePredicate = useCallback8(
     (termIndex, predIndex) => setQuery((q) => {
       const where = [];
       q.where.forEach((term, i) => {
@@ -1000,26 +1776,29 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const negateOne = useCallback6(
+  const negateOne = useCallback8(
     (clause) => {
       const field = byName.get(clause.field);
       return negateClause(clause, field ? opsForField(field) : void 0);
     },
     [byName]
   );
-  const negatePredicate = useCallback6(
+  const negatePredicate = useCallback8(
     (termIndex, predIndex) => setQuery((q) => ({
       ...q,
       offset: 0,
       where: q.where.map((term, i) => {
         if (i !== termIndex) return term;
-        if (isOrGroup(term)) return { any: term.any.map((c, j) => j === predIndex ? negateOne(c) : c) };
+        if (isOrGroup(term))
+          return {
+            any: term.any.map((c, j) => j === predIndex ? negateOne(c) : c)
+          };
         return negateOne(term);
       })
     })),
     [setQuery, negateOne]
   );
-  const reorderFilters = useCallback6(
+  const reorderFilters = useCallback8(
     (fromIndex, toIndex) => setQuery((q) => {
       if (fromIndex < 0 || fromIndex >= q.where.length) return q;
       const where = [...q.where];
@@ -1029,13 +1808,15 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const mergeFilters = useCallback6(
+  const mergeFilters = useCallback8(
     (sourceIndex, targetIndex) => setQuery((q) => {
       if (sourceIndex === targetIndex) return q;
       const source = q.where[sourceIndex];
       const target = q.where[targetIndex];
       if (!source || !target) return q;
-      const merged = { any: [...predicatesOf(target), ...predicatesOf(source)] };
+      const merged = {
+        any: [...predicatesOf(target), ...predicatesOf(source)]
+      };
       const where = [];
       q.where.forEach((term, i) => {
         if (i === sourceIndex) return;
@@ -1045,24 +1826,37 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const resetAll = useCallback6(() => setQuery(() => cloneQueryState(defaults)), [setQuery, defaults]);
-  const addAggregation = useCallback6(
+  const resetAll = useCallback8(
+    () => setQuery(() => cloneQueryState(defaults)),
+    [setQuery, defaults]
+  );
+  const addAggregation = useCallback8(
     (partial) => {
       const id = `a${nowRef.current()}-${aggIdRef.current++}`;
-      const clause = { id, op: "count", groupBy: [], ...partial };
-      setQuery((q) => ({ ...q, aggregations: [...q.aggregations ?? [], clause] }));
+      const clause = {
+        id,
+        op: "count",
+        groupBy: [],
+        ...partial
+      };
+      setQuery((q) => ({
+        ...q,
+        aggregations: [...q.aggregations ?? [], clause]
+      }));
       return id;
     },
     [setQuery]
   );
-  const updateAggregation = useCallback6(
+  const updateAggregation = useCallback8(
     (id, patch2) => setQuery((q) => ({
       ...q,
-      aggregations: (q.aggregations ?? []).map((a) => a.id === id ? mergeAggregation(a, patch2) : a)
+      aggregations: (q.aggregations ?? []).map(
+        (a) => a.id === id ? mergeAggregation(a, patch2) : a
+      )
     })),
     [setQuery]
   );
-  const moveAggregation = useCallback6(
+  const moveAggregation = useCallback8(
     (id, toIndex) => setQuery((q) => {
       const current = q.aggregations ?? [];
       const from = current.findIndex((a) => a.id === id);
@@ -1074,24 +1868,43 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const removeAggregation = useCallback6(
-    (id) => setQuery((q) => ({ ...q, aggregations: (q.aggregations ?? []).filter((a) => a.id !== id) })),
+  const removeAggregation = useCallback8(
+    (id) => setQuery((q) => ({
+      ...q,
+      aggregations: (q.aggregations ?? []).filter((a) => a.id !== id)
+    })),
     [setQuery]
   );
-  const clearAggregations = useCallback6(
+  const clearAggregations = useCallback8(
     () => setQuery((q) => ({ ...q, aggregations: [] })),
     [setQuery]
   );
-  const setSort = useCallback6((orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })), [setQuery]);
-  const toggleSort = useCallback6(
-    (field, additive = false) => setQuery((q) => ({ ...q, offset: 0, orderBy: nextOrderBy(q.orderBy, field, additive) })),
+  const setSort = useCallback8(
+    (orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })),
     [setQuery]
   );
-  const setLimit = useCallback6((limit) => patch({ limit, offset: 0 }), [patch]);
-  const setOffset = useCallback6((offset) => patch({ offset }), [patch]);
-  const nextPage = useCallback6(() => setQuery((q) => ({ ...q, offset: q.offset + q.limit })), [setQuery]);
-  const prevPage = useCallback6(() => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })), [setQuery]);
-  const filterValues = useCallback6(
+  const toggleSort = useCallback8(
+    (field, additive = false) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      orderBy: nextOrderBy(q.orderBy, field, additive)
+    })),
+    [setQuery]
+  );
+  const setLimit = useCallback8(
+    (limit) => patch({ limit, offset: 0 }),
+    [patch]
+  );
+  const setOffset = useCallback8((offset) => patch({ offset }), [patch]);
+  const nextPage = useCallback8(
+    () => setQuery((q) => ({ ...q, offset: q.offset + q.limit })),
+    [setQuery]
+  );
+  const prevPage = useCallback8(
+    () => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })),
+    [setQuery]
+  );
+  const filterValues = useCallback8(
     async (field, search) => {
       if (!transport?.fetchDistinctValues) {
         const f = byName.get(field);
@@ -1108,7 +1921,7 @@ function useQueryTable(opts) {
     },
     [transport, byName, clientRows]
   );
-  const fieldStats = useCallback6(
+  const fieldStats = useCallback8(
     async (fields, signal) => {
       const requested = [...new Set(fields)];
       if (transport?.fetchFieldStats) {
@@ -1125,7 +1938,7 @@ function useQueryTable(opts) {
         if (!field) continue;
         const distinct = /* @__PURE__ */ new Set();
         for (const row of clientRows) {
-          const value = readFieldValue2(field, row);
+          const value = readFieldValue4(field, row);
           if (value !== null) distinct.add(JSON.stringify(value));
         }
         result[name] = { distinct: distinct.size };
@@ -1134,12 +1947,12 @@ function useQueryTable(opts) {
     },
     [transport, byName, clientRows]
   );
-  const refresh = useCallback6(() => {
+  const refresh = useCallback8(() => {
     setNonce((n) => n + 1);
     onRefreshRef.current?.();
   }, []);
-  const stopAutoRefresh = useCallback6(() => setAutoRefreshStatus(null), []);
-  const startAutoRefresh = useCallback6(
+  const stopAutoRefresh = useCallback8(() => setAutoRefreshStatus(null), []);
+  const startAutoRefresh = useCallback8(
     ({ frequencyMs, turnOffAfterMs }) => {
       const pollCount = frequencyMs > 0 && turnOffAfterMs > 0 ? Math.floor(turnOffAfterMs / frequencyMs) : 0;
       if (pollCount < 1 || pollCount > MAX_AUTO_REFRESH_POLLS) {
@@ -1159,11 +1972,13 @@ function useQueryTable(opts) {
   );
   const autoRefreshFrequencyMs = autoRefreshStatus?.frequencyMs ?? null;
   const autoRefreshStopsAt = autoRefreshStatus?.stopsAt ?? null;
-  useEffect4(() => {
+  useEffect5(() => {
     if (autoRefreshFrequencyMs == null || autoRefreshStopsAt == null) return;
     const tick = () => {
       if (nowRef.current() >= autoRefreshStopsAt) {
-        setAutoRefreshStatus((current) => current?.stopsAt === autoRefreshStopsAt ? null : current);
+        setAutoRefreshStatus(
+          (current) => current?.stopsAt === autoRefreshStopsAt ? null : current
+        );
         return;
       }
       refresh();
@@ -1175,7 +1990,9 @@ function useQueryTable(opts) {
     };
     const interval = setInterval(tick, autoRefreshFrequencyMs);
     const timeout = setTimeout(
-      () => setAutoRefreshStatus((current) => current?.stopsAt === autoRefreshStopsAt ? null : current),
+      () => setAutoRefreshStatus(
+        (current) => current?.stopsAt === autoRefreshStopsAt ? null : current
+      ),
       Math.max(0, autoRefreshStopsAt - nowRef.current())
     );
     return () => {
@@ -1183,7 +2000,7 @@ function useQueryTable(opts) {
       clearTimeout(timeout);
     };
   }, [autoRefreshFrequencyMs, autoRefreshStopsAt, refresh]);
-  const autoRefresh = useMemo6(
+  const autoRefresh = useMemo7(
     () => ({
       status: autoRefreshStatus,
       start: startAutoRefresh,
@@ -1191,16 +2008,25 @@ function useQueryTable(opts) {
     }),
     [autoRefreshStatus, startAutoRefresh, stopAutoRefresh]
   );
-  const refreshRow = useCallback6(
+  const refreshRow = useCallback8(
     async (id) => {
+      if (opts.computedExecution && transport?.fetchRowsV2) {
+        refresh();
+        return;
+      }
       if (!transport?.fetchRow) return;
       const updated = await transport.fetchRow(id);
-      setRows((prev) => prev.map((r) => rowId(r) === id ? updated ?? r : r));
+      setRows(
+        (prev) => prev.map((r) => rowId(r) === id ? updated ?? r : r)
+      );
     },
-    [transport, rowId]
+    [transport, rowId, opts.computedExecution, refresh]
+  );
+  const visibleFields = useMemo7(
+    () => selectedFields2(displaySchema, query),
+    [displaySchema, query]
   );
-  const visibleFields = useMemo6(() => selectedFields2(displaySchema, query), [displaySchema, query]);
-  const aggregations = useMemo6(
+  const aggregations = useMemo7(
     () => ({
       clauses: query.aggregations ?? [],
       results: aggState.results,
@@ -1210,7 +2036,11 @@ function useQueryTable(opts) {
       update: updateAggregation,
       move: moveAggregation,
       remove: removeAggregation,
-      clear: clearAggregations
+      clear: clearAggregations,
+      preview: aggState.preview,
+      replace: replaceAggregations,
+      compile: metricCompile,
+      contextKey: `${dataVersion}:${pageContext}:${pageReady}:${JSON.stringify(query.where)}`
     }),
     [
       query.aggregations,
@@ -1221,7 +2051,14 @@ function useQueryTable(opts) {
       updateAggregation,
       moveAggregation,
       removeAggregation,
-      clearAggregations
+      clearAggregations,
+      aggState.preview,
+      replaceAggregations,
+      metricCompile,
+      pageContext,
+      pageReady,
+      dataVersion,
+      query.where
     ]
   );
   return {
@@ -1232,6 +2069,7 @@ function useQueryTable(opts) {
     total,
     loading,
     error,
+    requestActivity,
     canUndo,
     canRedo,
     undo,