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

package/dist/index.js

@@ -1,16 +1,769 @@
+// src/useQueryFilters.ts
+import { useCallback, useMemo } from "react";
+import {
+  isOrGroup,
+  predicatesOf,
+  negateClause,
+  opsForField
+} from "@pythia-software/query-table-core";
+function useQueryFilters(schema, setQuery) {
+  const byName = useMemo(
+    () => new Map(schema.fields.map((field) => [field.name, field])),
+    [schema]
+  );
+  const addFilter = useCallback(
+    (clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })),
+    [setQuery]
+  );
+  const updateFilter = useCallback(
+    (index, clause) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.map((t, i) => i === index ? clause : t)
+    })),
+    [setQuery]
+  );
+  const removeFilter = useCallback(
+    (index) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      where: q.where.filter((_, i) => i !== index)
+    })),
+    [setQuery]
+  );
+  const clearFilters = useCallback(
+    () => setQuery((q) => ({ ...q, offset: 0, where: [] })),
+    [setQuery]
+  );
+  const updatePredicate = useCallback(
+    (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)
+          };
+        return clause;
+      })
+    })),
+    [setQuery]
+  );
+  const removePredicate = useCallback(
+    (termIndex, predIndex) => setQuery((q) => {
+      const where = [];
+      q.where.forEach((term, i) => {
+        if (i !== termIndex) {
+          where.push(term);
+          return;
+        }
+        if (isOrGroup(term)) {
+          const members = term.any.filter((_, j) => j !== predIndex);
+          if (members.length === 1) where.push(members[0]);
+          else if (members.length > 1) where.push({ any: members });
+          return;
+        }
+      });
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  const negateOne = useCallback(
+    (clause) => {
+      const field = byName.get(clause.field);
+      return negateClause(clause, field ? opsForField(field) : void 0);
+    },
+    [byName]
+  );
+  const negatePredicate = useCallback(
+    (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)
+          };
+        return negateOne(term);
+      })
+    })),
+    [setQuery, negateOne]
+  );
+  const reorderFilters = useCallback(
+    (fromIndex, toIndex) => setQuery((q) => {
+      if (fromIndex < 0 || fromIndex >= q.where.length) return q;
+      const where = [...q.where];
+      const [moved] = where.splice(fromIndex, 1);
+      where.splice(Math.max(0, Math.min(toIndex, where.length)), 0, moved);
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  const mergeFilters = useCallback(
+    (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 where = [];
+      q.where.forEach((term, i) => {
+        if (i === sourceIndex) return;
+        where.push(i === targetIndex ? merged : term);
+      });
+      return { ...q, offset: 0, where };
+    }),
+    [setQuery]
+  );
+  return {
+    addFilter,
+    updateFilter,
+    removeFilter,
+    clearFilters,
+    updatePredicate,
+    removePredicate,
+    negatePredicate,
+    reorderFilters,
+    mergeFilters
+  };
+}
+
+// src/useGrouping.ts
+import { useEffect, useRef, useState } from "react";
+import {
+  MAX_SUMMARY_COLUMNS,
+  normalizeQueryState,
+  predicatesOf as predicatesOf2,
+  withoutGrouping,
+  queriesEqual
+} from "@pythia-software/query-table-core";
+function useGroupingController(api, source, model, inputs, supported, viewRevision, execution = {}) {
+  const [notice, setNotice] = useState("");
+  useEffect(() => setNotice(""), [viewRevision]);
+  const previous = useRef(null);
+  const stage = api.query.grouping;
+  const view = {
+    version: 2,
+    mode: stage ? "groups" : "rows",
+    keys: stage?.keys ?? [],
+    summaries: stage?.summaries ?? [],
+    representative: stage?.representative ?? null,
+    input: source.query,
+    result: withoutGrouping(api.query)
+  };
+  const outputSchema = {
+    ...api.schema,
+    fields: api.computed.catalogue
+  };
+  function changeKeys(keys) {
+    if (keys.length && !supported) return;
+    const cached = previous.current?.revision === viewRevision ? previous.current.query : null;
+    const canRestore = (current) => !current.grouping && cached?.grouping && queriesEqual(cached.grouping.source, current) && JSON.stringify(cached.grouping.keys) === JSON.stringify(keys);
+    if (keys.length)
+      model.validate(canRestore(api.query) ? cached.grouping : {
+        ...stage ?? { summaries: [], representative: null },
+        keys
+      });
+    if (!keys.length && stage)
+      previous.current = { query: api.query, revision: viewRevision };
+    api.setQuery((current) => {
+      const before = current.grouping;
+      if (!keys.length) return before ? before.source : current;
+      if (!before) {
+        if (cached?.grouping && canRestore(current))
+          return {
+            ...cached,
+            grouping: { ...cached.grouping, source: current }
+          };
+        const grouping2 = {
+          keys,
+          summaries: [],
+          representative: null,
+          source: current
+        };
+        return {
+          select: keys.map((field) => ({ field })),
+          where: [],
+          orderBy: [],
+          limit: current.limit,
+          offset: 0,
+          grouping: grouping2
+        };
+      }
+      const grouping = { ...before, keys };
+      const removed = new Set(before.keys.filter((key) => !keys.includes(key)));
+      const columns = current.select.length ? current.select : before.keys.map((field) => ({ field }));
+      return {
+        ...current,
+        grouping,
+        offset: 0,
+        aggregations: [],
+        select: [
+          ...keys.filter((key) => !before.keys.includes(key)).map((field) => ({ field })),
+          ...columns.filter((c) => !removed.has(c.field))
+        ],
+        where: current.where.filter(
+          (term) => !predicatesOf2(term).some((p) => removed.has(p.field))
+        ),
+        orderBy: current.orderBy.filter((term) => !removed.has(term.field))
+      };
+    });
+    setNotice(
+      stage && api.query.aggregations?.length && keys.length ? "Grouping changed. Group metrics cleared; Undo restores them." : ""
+    );
+    api.selection.clear();
+  }
+  function applyColumns(summaries, columns) {
+    if (!stage) {
+      api.setQuery((q) => ({ ...q, select: columns }));
+      return;
+    }
+    model.validate({ ...stage, summaries });
+    const changed = new Set(
+      stage.summaries.filter((before) => {
+        const after = summaries.find((column) => column.id === before.id);
+        return !after || before.op !== after.op || before.field !== after.field || before.expression !== after.expression;
+      }).map((column) => column.id)
+    );
+    api.setQuery(
+      (q) => q.grouping ? {
+        ...q,
+        grouping: { ...q.grouping, summaries },
+        select: columns,
+        ...changed.size ? {
+          offset: 0,
+          aggregations: [],
+          where: q.where.filter(
+            (term) => !predicatesOf2(term).some((p) => changed.has(p.field))
+          ),
+          orderBy: q.orderBy.filter((term) => !changed.has(term.field))
+        } : {}
+      } : q
+    );
+    setNotice(
+      changed.size && (api.query.where.some(
+        (term) => predicatesOf2(term).some((p) => changed.has(p.field))
+      ) || api.query.orderBy.some((term) => changed.has(term.field)) || api.query.aggregations?.length) ? "Columns updated. Affected filters, sorts, and metrics cleared; Undo restores them." : ""
+    );
+  }
+  function addSummary(op, field) {
+    if (!stage || op === "row" && !stage.representative) return;
+    const existing = stage.summaries.find(
+      (column2) => column2.op === op && column2.field === field
+    );
+    if (!existing && stage.summaries.length >= MAX_SUMMARY_COLUMNS) {
+      setNotice(
+        `A grouped view supports up to ${MAX_SUMMARY_COLUMNS} aggregate columns.`
+      );
+      return;
+    }
+    const column = existing ?? {
+      id: `summary_${crypto.randomUUID().replace(/-/g, "")}`,
+      op,
+      ...field ? { field } : {}
+    };
+    applyColumns(
+      existing ? stage.summaries : [...stage.summaries, column],
+      api.select.visible.some((c) => c.field === column.id) ? api.select.visible : [...api.select.visible, { field: column.id }]
+    );
+  }
+  function changeSummary(id, op) {
+    if (!stage) return;
+    applyColumns(
+      stage.summaries.map(
+        (column) => column.id === id ? { ...column, op } : column
+      ),
+      api.select.visible
+    );
+  }
+  function representativeImpact() {
+    if (!stage) return "";
+    const before = api.query;
+    const after = model.reconcileRepresentative(
+      before,
+      stage.summaries,
+      outputSchema,
+      false
+    );
+    return [
+      before.where.length !== after.where.length ? "row-value filters" : "",
+      before.orderBy.length !== after.orderBy.length ? "row-value sorts" : "",
+      (before.aggregations?.length ?? 0) !== (after.aggregations?.length ?? 0) ? "dependent metrics" : ""
+    ].filter(Boolean).join(", ");
+  }
+  function changeRepresentative(representative) {
+    if (!stage || JSON.stringify(stage.representative) === JSON.stringify(representative))
+      return;
+    const summaries = representative ? stage.summaries : stage.summaries.filter((column) => column.op !== "row");
+    model.validate({ ...stage, summaries, representative });
+    const impact = representativeImpact();
+    api.setQuery(
+      (q) => q.grouping ? normalizeQueryState({
+        ...model.reconcileRepresentative(
+          q,
+          stage.summaries,
+          outputSchema,
+          !representative
+        ),
+        grouping: { ...q.grouping, summaries, representative }
+      }) : q
+    );
+    setNotice(
+      impact ? `Representative row changed. Cleared ${impact}; Undo restores them.` : ""
+    );
+  }
+  return {
+    ...execution,
+    supported,
+    model,
+    api,
+    source,
+    grouped: api,
+    schema: api.schema,
+    view,
+    inputs,
+    notice,
+    setNotice,
+    changeKeys,
+    addSummary,
+    changeSummary,
+    applyColumns,
+    changeRepresentative,
+    representativeImpact
+  };
+}
+
+// src/useQueryTable.ts
+import {
+  createGroupingModel,
+  prepareGrouping,
+  withoutGrouping as withoutGrouping2,
+  sourceExecutionSchema,
+  toQueryRequestV3,
+  validateQueryResultV3
+} from "@pythia-software/query-table-core";
+import { ITEM_DETAILS_COLUMN, itemPageFields } from "@pythia-software/query-table-core";
+
+// src/useItemDetails.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
+
+// src/usePropertyView.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+import {
+  createPropertyView,
+  memoryPropertyViewStorage,
+  normalizePropertyView
+} from "@pythia-software/query-table-core";
+var asError = (error) => error instanceof Error ? error : new Error(String(error));
+function usePropertyView(options) {
+  const [memory] = useState2(memoryPropertyViewStorage);
+  const storage = options.storage ?? memory;
+  const key = options.key ?? options.schema.name;
+  const schemaDefault = useMemo2(() => createPropertyView(options.schema), [options.schema]);
+  const fallback = useMemo2(
+    () => options.initialView ? normalizePropertyView(options.initialView) : schemaDefault,
+    [options.initialView, schemaDefault]
+  );
+  const defaults = useRef2(schemaDefault);
+  defaults.current = schemaDefault;
+  const initial = useRef2(options.initialView);
+  initial.current = options.initialView;
+  const [state, setState] = useState2({
+    key,
+    storage,
+    history: [fallback],
+    index: 0,
+    loading: true,
+    error: null,
+    saved: [],
+    defaultId: null
+  });
+  const generation = useRef2(0);
+  const edits = useRef2(0);
+  const saveQueue = useRef2(Promise.resolve());
+  const current = state.key === key && state.storage === storage;
+  const view = current ? state.history[state.index] : fallback;
+  useEffect2(() => {
+    const token = ++generation.current;
+    const editToken = edits.current;
+    setState({
+      key,
+      storage,
+      history: [defaults.current],
+      index: 0,
+      loading: true,
+      error: null,
+      saved: [],
+      defaultId: null
+    });
+    void Promise.resolve().then(
+      () => Promise.all([
+        storage.loadLast(key),
+        storage.listSaved(key),
+        storage.loadDefaultSaved(key)
+      ])
+    ).then(([last, saved, defaultView]) => {
+      if (generation.current !== token) return;
+      const restored = normalizePropertyView(
+        initial.current ?? last ?? defaultView?.view ?? defaults.current
+      );
+      const items = saved.map((item) => ({
+        ...item,
+        view: normalizePropertyView(item.view)
+      }));
+      setState((previous) => ({
+        ...previous,
+        ...edits.current === editToken ? { history: [restored], index: 0 } : {},
+        saved: items,
+        defaultId: defaultView?.id ?? null,
+        loading: false
+      }));
+    }).catch((error) => {
+      if (generation.current === token)
+        setState((previous) => ({
+          ...previous,
+          loading: false,
+          error: asError(error)
+        }));
+    });
+    return () => {
+      generation.current++;
+    };
+  }, [key, storage]);
+  useEffect2(() => {
+    if (!current || state.loading || state.error) return;
+    const token = generation.current;
+    const snapshot = normalizePropertyView(view);
+    saveQueue.current = saveQueue.current.then(() => storage.saveLast(key, snapshot)).catch((error) => {
+      if (generation.current === token)
+        setState((previous) => ({ ...previous, error: asError(error) }));
+    });
+  }, [view, current, state.loading, state.error, key, storage]);
+  const setView = useCallback2(
+    (next) => {
+      const normalized = normalizePropertyView(next);
+      edits.current++;
+      setState((previous) => {
+        const history = previous.key === key && previous.storage === storage ? previous.history.slice(0, previous.index + 1) : [defaults.current];
+        if (JSON.stringify(history[history.length - 1]) === JSON.stringify(normalized))
+          return { ...previous, error: null };
+        const nextHistory = [...history, normalized].slice(-50);
+        return {
+          ...previous,
+          key,
+          storage,
+          history: nextHistory,
+          index: nextHistory.length - 1,
+          error: null
+        };
+      });
+    },
+    [key, storage]
+  );
+  const refresh = useCallback2(
+    async (token) => {
+      const [saved, defaultView] = await Promise.all([
+        storage.listSaved(key),
+        storage.loadDefaultSaved(key)
+      ]);
+      if (generation.current === token)
+        setState((previous) => ({
+          ...previous,
+          saved: saved.map((item) => ({
+            ...item,
+            view: normalizePropertyView(item.view)
+          })),
+          defaultId: defaultView?.id ?? null,
+          error: null
+        }));
+    },
+    [key, storage]
+  );
+  return {
+    view,
+    loading: !current || state.loading,
+    error: current ? state.error : null,
+    saved: current ? state.saved : [],
+    defaultId: current ? state.defaultId : null,
+    setView,
+    reset: () => setView(defaults.current),
+    canUndo: current && state.index > 0,
+    canRedo: current && state.index < state.history.length - 1,
+    undo() {
+      edits.current++;
+      setState((previous) => ({
+        ...previous,
+        index: Math.max(0, previous.index - 1),
+        error: null
+      }));
+    },
+    redo() {
+      edits.current++;
+      setState((previous) => ({
+        ...previous,
+        index: Math.min(previous.history.length - 1, previous.index + 1),
+        error: null
+      }));
+    },
+    load(id) {
+      const found = state.saved.find((item) => item.id === id);
+      if (found && current) setView(found.view);
+    },
+    async save(name) {
+      const token = generation.current;
+      const saved = await storage.saveNamed(key, name, view, Date.now());
+      await refresh(token);
+      return saved;
+    },
+    async remove(id) {
+      const token = generation.current;
+      await storage.deleteSaved(key, id);
+      await refresh(token);
+    },
+    async setDefault(id) {
+      const token = generation.current;
+      await storage.setDefaultSaved(key, id);
+      await refresh(token);
+    }
+  };
+}
+
+// src/useItemDetails.ts
+var ALL_MODES = ["hover", "modal", "expand", "page"];
+function initialDetailModes(config) {
+  const available = ALL_MODES.filter((mode) => !config?.modes || config.modes.includes(mode));
+  return config?.defaultModes ? available.filter((mode) => config.defaultModes.includes(mode)) : available.includes("modal") ? ["modal"] : available.slice(0, 1);
+}
+function useDetailProperties(mode, schema, config, query, setQuery, enabled) {
+  const snapshot = query.itemDetails?.views?.[mode] ?? query.itemDetails?.view;
+  const seed = useRef3(snapshot);
+  const properties = usePropertyView({
+    schema,
+    ...config?.storage ? { storage: config.storage } : {},
+    key: `${config?.objectType ?? schema.name}:${mode}`,
+    ...seed.current ? { initialView: seed.current } : {}
+  });
+  const queryViewKey = JSON.stringify(snapshot);
+  const localViewKey = JSON.stringify(properties.view);
+  const previousView = useRef3({ query: queryViewKey, local: localViewKey });
+  const baselineView = useRef3(properties.view);
+  const baselineReady = useRef3(false);
+  const pendingView = useRef3(null);
+  useEffect3(() => {
+    if (!enabled) return;
+    if (!properties.loading && !baselineReady.current) {
+      baselineView.current = properties.view;
+      baselineReady.current = true;
+    }
+    const previous = previousView.current;
+    previousView.current = { query: queryViewKey, local: localViewKey };
+    if (queryViewKey !== previous.query) {
+      const next = snapshot ?? baselineView.current;
+      const target = JSON.stringify(next);
+      pendingView.current = target !== localViewKey ? { query: queryViewKey, local: target } : null;
+      if (target !== localViewKey) properties.setView(next);
+    } else if (pendingView.current && pendingView.current.query === queryViewKey) {
+      if (pendingView.current.local === localViewKey) pendingView.current = null;
+    } else if (!properties.loading && localViewKey !== queryViewKey && (queryViewKey !== void 0 || localViewKey !== previous.local)) {
+      setQuery((current) => ({ ...current, itemDetails: {
+        modes: current.itemDetails?.modes ?? initialDetailModes(config),
+        ...current.itemDetails,
+        views: { ...current.itemDetails?.views, [mode]: properties.view }
+      } }));
+    }
+  }, [enabled, queryViewKey, localViewKey, properties.loading, properties.setView, setQuery]);
+  return properties;
+}
+function useItemDetails({
+  schema,
+  query,
+  setQuery,
+  options,
+  rows,
+  clientRows,
+  rowId,
+  transport,
+  refreshKey,
+  links,
+  queryReady = true,
+  queryParameter: queryParameter2
+}) {
+  const enabled = Boolean(options);
+  const config = typeof options === "object" ? options : void 0;
+  const detailSchema = config?.schema ?? schema;
+  const availableModes = ALL_MODES.filter((mode) => !config?.modes || config.modes.includes(mode));
+  const modes = availableModes.filter((mode) => (query.itemDetails?.modes ?? initialDetailModes(config)).includes(mode));
+  const page = query.itemDetails?.page ?? config?.page ?? { urlTemplate: "", target: "_blank" };
+  const requested = query.itemDetails?.active;
+  const sharedModal = requested?.mode === "modal" && query.itemDetails?.modes.includes("modal") && (availableModes.includes("hover") || availableModes.includes("page") && !page.urlTemplate.trim());
+  const active = requested && (modes.includes(requested.mode) || sharedModal) ? requested : null;
+  const syncProperties = enabled && queryReady;
+  const modalProperties = useDetailProperties("modal", detailSchema, config, query, setQuery, syncProperties);
+  const hoverProperties = useDetailProperties("hover", detailSchema, config, query, setQuery, syncProperties);
+  const expandProperties = useDetailProperties("expand", detailSchema, config, query, setQuery, syncProperties);
+  const propertiesByMode = { modal: modalProperties, hover: hoverProperties, expand: expandProperties };
+  const views = {
+    modal: modalProperties.view,
+    hover: hoverProperties.view,
+    expand: expandProperties.view
+  };
+  const customLoad = config?.loadRow;
+  const customLoadRef = useRef3(customLoad);
+  customLoadRef.current = customLoad;
+  const hasCustomLoad = Boolean(customLoad);
+  const sourceType = config?.objectType ?? detailSchema.name;
+  const fallbackRows = !customLoad && !clientRows && !transport?.fetchRow ? rows : void 0;
+  const loadRow = useCallback3(async (id, signal) => {
+    if (customLoadRef.current) return customLoadRef.current(id, signal);
+    if (clientRows) {
+      const row2 = clientRows.find((row3) => rowId(row3) === id);
+      return row2 ? { row: row2 } : null;
+    }
+    if (transport?.fetchRow) {
+      const row2 = await transport.fetchRow(id, signal);
+      return row2 ? { row: row2 } : null;
+    }
+    const row = rows.find((row2) => rowId(row2) === id);
+    return row ? { row, loadedFields: Object.keys(row) } : null;
+  }, [hasCustomLoad, sourceType, clientRows, transport?.fetchRow, fallbackRows, rowId]);
+  const [retryKey, setRetryKey] = useState3(0);
+  const [result, setResult] = useState3({ source: void 0, epoch: "", id: void 0, record: null, loading: false, error: null });
+  const activeId = enabled ? active?.id : void 0;
+  const epoch = `${refreshKey}:${retryKey}`;
+  const currentResult = result.id === activeId && result.source === loadRow && result.epoch === epoch;
+  useEffect3(() => {
+    const controller = new AbortController();
+    if (activeId === void 0) {
+      setResult((previous) => previous.id === void 0 && !previous.loading && !previous.error && !previous.record ? previous : { source: void 0, epoch: "", id: void 0, record: null, loading: false, error: null });
+      return;
+    }
+    setResult({ source: loadRow, epoch, id: activeId, record: null, loading: true, error: null });
+    void Promise.resolve().then(() => loadRow(activeId, controller.signal)).then((record) => {
+      if (!controller.signal.aborted) setResult({ source: loadRow, epoch, id: activeId, record, loading: false, error: null });
+    }).catch((error) => {
+      if (!controller.signal.aborted) setResult({
+        source: loadRow,
+        epoch,
+        id: activeId,
+        record: null,
+        loading: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    });
+    return () => controller.abort();
+  }, [activeId, loadRow, refreshKey, retryKey]);
+  if (!enabled) return;
+  return {
+    ...links ? { links } : {},
+    schema: detailSchema,
+    queryParameter: queryParameter2 ?? config?.queryParameter ?? "q",
+    properties: modalProperties,
+    propertiesByMode,
+    availableModes,
+    modes,
+    active,
+    page,
+    pageSchema: schema,
+    record: currentResult ? result.record : null,
+    loading: activeId !== void 0 && (!currentResult || result.loading),
+    error: currentResult ? result.error : null,
+    ...config?.relationships ? { relationships: config.relationships } : {},
+    loadRow,
+    retry: () => setRetryKey((value) => value + 1),
+    setModes(next) {
+      setQuery((current) => {
+        const allowed = availableModes.filter((mode) => next.includes(mode));
+        const state = { ...current.itemDetails, modes: allowed, views };
+        if (state.active && !allowed.includes(state.active.mode)) delete state.active;
+        return { ...current, itemDetails: state };
+      });
+    },
+    open(id, mode) {
+      if (!modes.includes(mode)) return;
+      setQuery((current) => ({ ...current, itemDetails: {
+        ...current.itemDetails,
+        modes: current.itemDetails?.modes ?? modes,
+        views,
+        active: { id, mode }
+      } }));
+    },
+    close() {
+      setQuery((current) => {
+        if (!current.itemDetails?.active) return current;
+        const { active: _active, ...state } = current.itemDetails;
+        return { ...current, itemDetails: state };
+      });
+    }
+  };
+}
+
+// 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."
+    );
+  const executed = /* @__PURE__ */ new Set([
+    ...request.select.filter(isComputedField),
+    ...request.orderBy.map((term) => term.field).filter(isComputedField)
+  ]);
+  for (const [name, revision] of Object.entries(request.expectedRevisions)) {
+    const id = name.replace(/^@computed\//, "");
+    if (!executed.has(`@computed/${id}`)) continue;
+    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 { useCallback as useCallback4, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef4, useState as useState4 } from "react";
 import {
   applyQuery,
   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 +804,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 +835,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."));
@@ -103,18 +856,18 @@ function evaluateFormulaRows(ast, inputs, signal, factory = createFormulaWorker)
 // src/useComputedColumns.ts
 function useComputedColumns(options) {
   const { schema, query, rows, transport, clientRows, workerFactory } = options;
-  const store = useMemo(
+  const store = useMemo3(
     () => options.store ?? memoryComputedColumnStore(),
     [options.store]
   );
-  const [catalogue, setCatalogue] = useState(null);
-  const definitions = useMemo(
+  const [catalogue, setCatalogue] = useState4(null);
+  const definitions = useMemo3(
     () => catalogue?.dataset === schema.name && catalogue.store === store ? catalogue.items : [],
     [catalogue, schema.name, store]
   );
-  const [loading, setLoading] = useState(false), [error, setError] = useState(null);
-  const catalogueRequest = useRef(null);
-  const reload = useCallback(async () => {
+  const [loading, setLoading] = useState4(false), [error, setError] = useState4(null);
+  const catalogueRequest = useRef4(null);
+  const reload = useCallback4(async () => {
     catalogueRequest.current?.abort();
     const ac = new AbortController();
     catalogueRequest.current = ac;
@@ -136,35 +889,35 @@ function useComputedColumns(options) {
       if (!ac.signal.aborted) setLoading(false);
     }
   }, [store, schema.name]);
-  useEffect(() => {
+  useEffect4(() => {
     void reload();
     return () => catalogueRequest.current?.abort();
   }, [reload]);
-  useEffect(
+  useEffect4(
     () => store.subscribe?.(schema.name, () => {
       void reload();
     }),
     [store, schema.name, reload]
   );
-  useEffect(() => {
+  useEffect4(() => {
     const focus = () => {
       void reload();
     };
     window.addEventListener("focus", focus);
     return () => window.removeEventListener("focus", focus);
   }, [reload]);
-  const inputFields = useMemo(
+  const inputFields = useMemo3(
     () => schema.fields.filter(isSelectable).filter(
       (f) => f.source.kind === "backend" || f.source.accessor && f.source.dependencies
     ),
     [schema]
   );
-  const compile = useCallback(
+  const compile = useCallback4(
     (source, editingId) => {
       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))
@@ -182,7 +935,7 @@ function useComputedColumns(options) {
     },
     [inputFields, definitions]
   );
-  const plans = useMemo(
+  const plans = useMemo3(
     () => new Map(
       definitions.map((def) => {
         try {
@@ -200,7 +953,7 @@ function useComputedColumns(options) {
     ),
     [definitions, compile]
   );
-  const backendDependencies = useCallback(
+  const backendDependencies = useCallback4(
     (plan) => [
       ...new Set(
         plan.dependencies.flatMap((name) => {
@@ -215,14 +968,14 @@ function useComputedColumns(options) {
     ).sort(),
     [schema, inputFields]
   );
-  const inputsFor = useCallback(
+  const inputsFor = useCallback4(
     (plan, batch) => {
       let size = 0;
       return batch.map((row) => {
         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,13 +989,15 @@ 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 [evaluated, setEvaluated] = useState(null);
-  useEffect(() => {
+  const activeIds = activeSelect.filter((c) => isComputedField2(c.field)).map((c) => c.field.slice("@computed/".length)).sort().join(",");
+  const [evaluated, setEvaluated] = useState4(null);
+  useEffect4(() => {
     const ac = new AbortController();
     const values = /* @__PURE__ */ new Map();
     void (async () => {
       for (const id of activeIds.split(",").filter(Boolean)) {
+        if (options.execution?.fields[computedFieldName(id)]?.select && (transport?.fetchRowsV2 || transport?.fetchQueryV3))
+          continue;
         const entry = plans.get(id);
         if (!entry?.plan) continue;
         try {
@@ -269,8 +1024,16 @@ function useComputedColumns(options) {
       if (!ac.signal.aborted) setEvaluated({ rows, plans, values });
     })();
     return () => ac.abort();
-  }, [activeIds, rows, plans, inputsFor, workerFactory]);
-  const displaySchema = useMemo(() => {
+  }, [
+    activeIds,
+    rows,
+    plans,
+    inputsFor,
+    workerFactory,
+    options.execution,
+    transport
+  ]);
+  const displaySchema = useMemo3(() => {
     const indices = new Map(rows.map((row, i) => [row, i]));
     const fields = definitions.map((def) => {
       const entry = plans.get(def.id);
@@ -285,17 +1048,34 @@ function useComputedColumns(options) {
           dependencies: entry?.plan ? backendDependencies(entry.plan) : [],
           accessor: (row) => {
             if (entry?.error) return { computedError: entry.error };
+            if (options.execution?.fields[computedFieldName(def.id)]?.select && (transport?.fetchRowsV2 || transport?.fetchQueryV3)) {
+              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 }
+        filter: { enabled: options.execution?.fields[computedFieldName(def.id)]?.filter === true && executionRevision(options.execution, def.id) === def.revision && !!entry?.plan && !hasRegex(entry.plan) },
+        sort: {
+          enabled: !!(transport?.fetchRowsV2 || transport?.fetchQueryV3) && !!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 || !!transport?.fetchQueryV3) && !!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,9 +1101,13 @@ function useComputedColumns(options) {
     rows,
     query.select,
     schema.defaultSelect,
-    loading
+    loading,
+    transport,
+    options.execution,
+    options.serverComputed,
+    options.serverExecution
   ]);
-  const save = useCallback(
+  const save = useCallback4(
     async (column, expectedRevision) => {
       compile(column.expression.source, column.id);
       const saved = validateComputedColumn(
@@ -341,7 +1125,7 @@ function useComputedColumns(options) {
     },
     [compile, store, schema.name]
   );
-  const preview = useCallback(
+  const preview = useCallback4(
     async (source, count, signal, editingId, includeInputs = true) => {
       if (!Number.isInteger(count) || count < 1 || count > 1e4)
         throw new Error("Choose between 1 and 10,000 rows.");
@@ -422,137 +1206,602 @@ 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 useCallback12, useEffect as useEffect10, useMemo as useMemo9, useRef as useRef9, useState as useState11 } from "react";
 import {
   EMPTY_QUERY,
   applyQuery as applyQuery2,
-  decodeQuery,
-  encodeQuery,
   memoryStorageAdapter,
-  normalizeQueryState,
-  readFieldValue as readFieldValue2,
+  normalizeQueryState as normalizeQueryState3,
+  readFieldValue as readFieldValue4,
   selectedFields as selectedFields2,
   toServerQuery as toServerQuery2,
-  queriesEqual,
-  isOrGroup,
-  predicatesOf,
-  negateClause,
-  opsForField
+  queriesEqual as queriesEqual2,
+  isOrGroup as isOrGroup2,
+  metricPlans as metricPlans3,
+  validateMetric as validateMetric2,
+  metricDependencies,
+  isComputedField as isComputedField4,
+  computedFieldName as computedFieldName2,
+  toServerQueryV2
 } from "@pythia-software/query-table-core";
 
+// src/useRequestActivity.ts
+import { useCallback as useCallback5, useEffect as useEffect5, useMemo as useMemo4, useRef as useRef5, useState as useState5 } from "react";
+var methods = /* @__PURE__ */ new Set([
+  "fetchRows",
+  "fetchRowsV2",
+  "fetchQueryV3",
+  "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] = useState5([]);
+  const sequence = useRef5(0), mounted = useRef5(true);
+  useEffect5(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const publish = useCallback5((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 = useMemo4(
+    () => source ? observeTransport(source, publish, () => ++sequence.current) : void 0,
+    [source, publish]
+  );
+  const clear = useCallback5(
+    () => setEntries((previous) => previous.filter((e) => e.status === "pending")),
+    []
+  );
+  const activity = useMemo4(
+    () => ({ entries, clear }),
+    [entries, clear]
+  );
+  return { transport, activity };
+}
+
 // 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;
-  useEffect2(() => {
-    if (!hasAggregations) {
+import { useCallback as useCallback6, useEffect as useEffect6, useMemo as useMemo5, useRef as useRef6, useState as useState6 } from "react";
+import {
+  metricComputationKey,
+  metricPlans as metricPlans2,
+  hasRegex as hasRegex3
+} from "@pythia-software/query-table-core";
+
+// src/metricExecution.ts
+import {
+  applyAggregations,
+  normalizeQueryState as normalizeQueryState2,
+  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) => context.strictLocalMetrics || c.dateGrouping || 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 || normalizeQueryState2(query).aggregations?.length !== originalClauses.length))
+    return evaluateMetrics(rows, query, context.schema, {
+      ...context.now !== void 0 ? { now: context.now } : {},
+      ...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,
+    {
+      ...context.now !== void 0 ? { now: context.now } : {},
+      ...signal ? { signal } : {}
+    }
+  );
+  if (!advanced.length) return compatible;
+  query = { ...query, aggregations: advanced };
+  const options = {
+    ...context.now !== void 0 ? { now: context.now } : {},
+    ...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: [] };
+  if (context.executeV3) return context.executeV3(query, signal);
+  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) || !!c.dateGrouping)
+  );
+  const matching = clauses.filter(
+    (c) => c.scope !== "shownRows" || supportsV2 && !needsWorker(c) && !c.dateGrouping
+  );
+  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,
+      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) {
+    if (matching.some((c) => c.dateGrouping))
+      throw Error(
+        "This server does not support calendar grouping. Enable the v3 query executor."
+      );
+    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(
+        "Remote all-matching metrics require 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 = {}, enabled = true) {
+  const [results, setResults] = useState6(null);
+  const [loading, setLoading] = useState6(false);
+  const [error, setError] = useState6(null);
+  const latest = useRef6({
+    query,
+    schema,
+    transport,
+    clientRows,
+    options,
+    validateQuery,
+    enabled
+  });
+  latest.current = {
+    query,
+    schema,
+    transport,
+    clientRows,
+    options,
+    validateQuery,
+    enabled
+  };
+  const preview = useCallback6(
+    async (clauses, signal) => {
+      const current = latest.current;
+      if (!current.enabled) throw Error("Resolve the query link before previewing metrics.");
+      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 = !options.executeV3 && 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 = useMemo5(
+    () => 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,
+    options.now,
+    options.strictLocalMetrics,
+    options.queryContextKey
+  ]);
+  useEffect6(() => {
+    if (!enabled || !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,
+    enabled,
+    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 useCallback7, useEffect as useEffect7, useMemo as useMemo6, useState as useState7 } from "react";
+function sameOrder(left, right) {
+  return left.length === right.length && left.every((id, index) => id === right[index]);
+}
 function useSelection(displayedIds) {
-  const [selected, setSelected] = useState3(() => /* @__PURE__ */ new Set());
-  const anchor = useRef2(null);
-  const toggle = useCallback2(
-    (id, shiftKey = false) => {
-      setSelected((prev) => {
-        const next = new Set(prev);
-        const a = anchor.current;
-        if (shiftKey && a != null) {
-          const i = displayedIds.indexOf(a);
+  const [{ selected }, setState] = useState7(() => ({
+    selected: /* @__PURE__ */ new Set(),
+    range: null
+  }));
+  useEffect7(() => {
+    setState((prev) => prev.range && !sameOrder(prev.range.displayedIds, displayedIds) ? { selected: prev.selected, range: null } : prev);
+  }, [displayedIds]);
+  const toggle = useCallback7(
+    (id, shiftKey = false, additive = false) => {
+      setState((prev) => {
+        const range = prev.range;
+        if (shiftKey && range && sameOrder(range.displayedIds, displayedIds)) {
+          const i = displayedIds.indexOf(range.anchor);
           const j = displayedIds.indexOf(id);
           if (i !== -1 && j !== -1) {
             const [lo, hi] = i <= j ? [i, j] : [j, i];
-            const span = displayedIds.slice(lo, hi + 1);
-            const allChecked = span.every((rowId) => prev.has(rowId));
-            for (const rowId of span) {
-              if (allChecked) next.delete(rowId);
-              else next.add(rowId);
+            const activeRange = additive ? { ...range, baseline: prev.selected, selecting: true } : range;
+            const next2 = new Set(activeRange.baseline);
+            for (const rowId of displayedIds.slice(lo, hi + 1)) {
+              if (activeRange.selecting) next2.add(rowId);
+              else next2.delete(rowId);
             }
-            anchor.current = id;
-            return next;
+            return { selected: next2, range: activeRange };
           }
         }
-        if (next.has(id)) next.delete(id);
-        else next.add(id);
-        anchor.current = id;
-        return next;
+        const next = new Set(prev.selected);
+        const selecting = !next.has(id);
+        if (selecting) next.add(id);
+        else next.delete(id);
+        return {
+          selected: next,
+          range: { anchor: id, baseline: prev.selected, selecting, displayedIds: [...displayedIds] }
+        };
       });
     },
     [displayedIds]
   );
-  const setPage = useCallback2((ids, select) => {
-    setSelected((prev) => {
-      const next = new Set(prev);
+  const setPage = useCallback7((ids, select) => {
+    setState((prev) => {
+      const next = new Set(prev.selected);
       for (const id of ids) {
         if (select) next.add(id);
         else next.delete(id);
       }
-      return next;
+      return { selected: next, range: null };
     });
   }, []);
-  const replace = useCallback2((ids) => {
+  const replace = useCallback7((ids) => {
     const next = new Set(ids);
-    anchor.current = null;
-    setSelected(next);
+    setState({ selected: next, range: null });
   }, []);
-  const retain = useCallback2((ids) => {
+  const retain = useCallback7((ids) => {
     const allowed = new Set(ids);
-    anchor.current = null;
-    setSelected((prev) => {
+    setState((prev) => {
       const next = /* @__PURE__ */ new Set();
-      for (const id of prev) if (allowed.has(id)) next.add(id);
-      return next;
+      for (const id of prev.selected) if (allowed.has(id)) next.add(id);
+      return { selected: next, range: null };
     });
   }, []);
-  const pageState = useCallback2(
+  const pageState = useCallback7(
     (pageIds) => {
       if (pageIds.length === 0) return "none";
       let n = 0;
@@ -561,11 +1810,10 @@ function useSelection(displayedIds) {
     },
     [selected]
   );
-  const clear = useCallback2(() => {
-    anchor.current = null;
-    setSelected(/* @__PURE__ */ new Set());
+  const clear = useCallback7(() => {
+    setState({ selected: /* @__PURE__ */ new Set(), range: null });
   }, []);
-  return useMemo3(
+  return useMemo6(
     () => ({
       selected,
       isSelected: (id) => selected.has(id),
@@ -582,27 +1830,29 @@ function useSelection(displayedIds) {
 }
 
 // src/useSelect.ts
-import { useCallback as useCallback3, useMemo as useMemo4 } from "react";
+import { useCallback as useCallback8, useMemo as useMemo7 } 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 = useMemo7(() => selectedFields(schema, query), [schema, query]);
+  const visible = useMemo7(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
+  const hidden = useMemo7(() => {
     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(
-    (mutate) => {
+  const writeSelect = useCallback8(
+    (mutate, clearFitToScreen = false) => {
       setQuery((prev) => {
         const current = prev.select.length ? prev.select : visible;
-        return { ...prev, select: mutate([...current]) };
+        const next = { ...prev, select: mutate([...current]) };
+        if (clearFitToScreen) delete next.fitToScreen;
+        return next;
       });
     },
     [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 = useCallback8((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
+  const hide = useCallback8((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
+  const move = useCallback8(
     (field, toIndex) => writeSelect((c) => {
       const from = c.findIndex((x) => x.field === field);
       if (from === -1) return c;
@@ -612,11 +1862,11 @@ function useSelect(query, setQuery, schema) {
     }),
     [writeSelect]
   );
-  const setWidth = useCallback3(
-    (field, width) => writeSelect((c) => c.map((x) => x.field === field ? { ...x, width: Math.round(width) } : x)),
+  const setWidth = useCallback8(
+    (field, width) => writeSelect((c) => c.map((x) => x.field === field ? { ...x, width: Math.round(width) } : x), true),
     [writeSelect]
   );
-  const reset = useCallback3(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
+  const reset = useCallback8(() => setQuery((prev) => ({ ...prev, select: [] })), [setQuery]);
   return { visible, fields, hidden, show, hide, move, setWidth, reset };
 }
 function columnFor(select, name) {
@@ -625,92 +1875,139 @@ function columnFor(select, name) {
 }
 
 // src/useColumnDrag.ts
-import { useCallback as useCallback4, useMemo as useMemo5, useState as useState4 } from "react";
+import { useCallback as useCallback9, useMemo as useMemo8, useState as useState8 } 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] = useState8(null);
+  const [dropRevision, setDropRevision] = useState8(0);
+  const start = useCallback9(
+    (field, index, order) => setState({
+      source: field,
+      overIndex: index,
+      order: order?.slice(),
+      moved: false
+    }),
+    []
+  );
+  const over = useCallback9(
+    (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 = useCallback9((committed = false) => {
+    if (committed) setDropRevision((revision) => revision + 1);
+    setState(null);
+  }, []);
+  const preview = useCallback9(
     (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 useMemo8(
     () => ({
       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";
-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 () => {
+import { useCallback as useCallback10, useEffect as useEffect8, useRef as useRef7, useState as useState9 } from "react";
+function useSavedQueries(key, currentQuery, applyQueryState, storage, now, snapshot) {
+  const [items, setItems] = useState9([]);
+  const [defaultId, setDefaultId] = useState9(null);
+  const [loading, setLoading] = useState9(true);
+  const storageRef = useRef7(storage);
+  storageRef.current = storage;
+  const refresh = useCallback10(async () => {
+    const storage2 = storageRef.current;
     setLoading(true);
     try {
-      const [savedItems, defaultSaved] = await Promise.all([
-        storage.listSaved(key),
-        storage.loadDefaultSaved?.(key) ?? Promise.resolve(null)
+      const [savedItems, defaultSaved] = await Promise.allSettled([
+        storage2.listSaved(key),
+        storage2.loadDefaultSaved?.(key) ?? Promise.resolve(null)
       ]);
-      setItems(savedItems);
-      setDefaultId(defaultSaved?.id ?? null);
+      if (savedItems.status === "fulfilled") setItems(savedItems.value);
+      if (defaultSaved.status === "fulfilled") setDefaultId(defaultSaved.value?.id ?? null);
     } finally {
       setLoading(false);
     }
-  }, [storage, key]);
-  useEffect3(() => {
+  }, [key]);
+  useEffect8(() => {
     void refresh();
   }, [refresh]);
-  const save = useCallback5(
+  const save = useCallback10(
     async (name) => {
-      const saved = await storage.saveNamed(key, name, currentQuery, now());
+      name = name.trim();
+      if (!name || name.length > 200) throw Error("Saved query name must be between 1 and 200 characters.");
+      const immutable = await snapshot?.(currentQuery);
+      const saved = await storage.saveNamed(key, name, currentQuery, now(), immutable?.code);
       await refresh();
       return saved;
     },
-    [storage, key, currentQuery, now, refresh]
+    [storage, key, currentQuery, now, refresh, snapshot]
   );
-  const load = useCallback5(
+  const load = useCallback10(
     (id) => {
       const found = items.find((q) => q.id === id);
       if (found) applyQueryState(found.query);
     },
     [items, applyQueryState]
   );
-  const setDefault = useCallback5(
+  const update = useCallback10(
+    async (id) => {
+      if (!storage.updateNamed) throw Error("This storage adapter does not support saved-query updates.");
+      const immutable = await snapshot?.(currentQuery);
+      const saved = await storage.updateNamed(key, id, currentQuery, now(), immutable?.code);
+      await refresh();
+      return saved;
+    },
+    [storage, key, currentQuery, now, refresh, snapshot]
+  );
+  const setDefault = useCallback10(
     async (id) => {
       await storage.setDefaultSaved?.(key, id);
       await refresh();
     },
     [storage, key, refresh]
   );
-  const clearDefault = useCallback5(async () => {
+  const clearDefault = useCallback10(async () => {
     await storage.setDefaultSaved?.(key, null);
     await refresh();
   }, [storage, key, refresh]);
-  const remove = useCallback5(
+  const remove = useCallback10(
     async (id) => {
       if (id === defaultId) await storage.setDefaultSaved?.(key, null);
       await storage.deleteSaved(key, id);
@@ -718,14 +2015,118 @@ function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
     },
     [storage, key, defaultId, refresh]
   );
-  return { items, loading, defaultId, save, load, setDefault, clearDefault, remove };
+  return { items, loading, defaultId, save, canUpdate: Boolean(storage.updateNamed), update, load, setDefault, clearDefault, remove };
+}
+
+// src/useQueryLinks.ts
+import { useCallback as useCallback11, useEffect as useEffect9, useRef as useRef8, useState as useState10 } from "react";
+import { encodeQuery } from "@pythia-software/query-table-core";
+function useQueryLinks(query, service, syncUrl, ready, parameter, maxUrlBytes, onUrlChange) {
+  const latest = useRef8(query);
+  latest.current = query;
+  const [kind, setKind] = useState10(null);
+  const [busy, setBusy] = useState10(false);
+  const [error, setError] = useState10(null);
+  const mounted = useRef8(true);
+  const operations = useRef8(0);
+  useEffect9(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const queryKey = JSON.stringify(query);
+  useEffect9(() => {
+    if (!syncUrl || !ready || typeof window === "undefined") return;
+    try {
+      const result = service.local(query, window.location.href, parameter);
+      window.history.replaceState(window.history.state, "", result.url);
+      onUrlChange(result.url);
+      setKind(result.kind);
+      setError(null);
+    } catch (e) {
+      setError(e instanceof Error ? e : Error(String(e)));
+    }
+  }, [queryKey, syncUrl, ready, service, parameter, onUrlChange]);
+  const snapshot = useCallback11(async (q) => {
+    const captured = encodeQuery(q);
+    const base = typeof window !== "undefined" ? window.location.href : void 0;
+    operations.current++;
+    setBusy(true);
+    setError(null);
+    try {
+      if (!ready) throw Error("Resolve or reset the query link before saving it.");
+      const saved = await service.snapshot(q);
+      if (saved && base && mounted.current && syncUrl && ready && window.location.href === base && encodeQuery(latest.current) === captured) {
+        const url = new URL(base);
+        url.searchParams.set(parameter, "@" + saved.code);
+        const result = service.local(q, url.toString(), parameter);
+        window.history.replaceState(window.history.state, "", result.url);
+        onUrlChange(result.url);
+        setKind("durable");
+      }
+      return saved;
+    } catch (e) {
+      if (mounted.current) setError(e instanceof Error ? e : Error(String(e)));
+      throw e;
+    } finally {
+      operations.current--;
+      if (mounted.current) setBusy(operations.current > 0);
+    }
+  }, [service, syncUrl, ready, parameter, onUrlChange]);
+  const create = useCallback11(async (q = latest.current, options = {}) => {
+    const baseUrl = options.baseUrl ?? window.location.href;
+    const param = options.parameter ?? parameter;
+    const captured = encodeQuery(q);
+    operations.current++;
+    setBusy(true);
+    setError(null);
+    try {
+      if (!ready) throw Error("Resolve or reset the query link before sharing it.");
+      const result = await service.durable(q, baseUrl, param);
+      if (mounted.current && syncUrl && ready && param === parameter && window.location.href === baseUrl && encodeQuery(latest.current) === captured) {
+        window.history.replaceState(window.history.state, "", result.url);
+        onUrlChange(result.url);
+        setKind(result.kind);
+      }
+      return result;
+    } catch (e) {
+      if (mounted.current) setError(e instanceof Error ? e : Error(String(e)));
+      throw e;
+    } finally {
+      operations.current--;
+      if (mounted.current) setBusy(operations.current > 0);
+    }
+  }, [service, syncUrl, ready, parameter, onUrlChange]);
+  const local = useCallback11((q, base = window.location.href, param = parameter) => service.local(q, base, param), [service, parameter]);
+  return { maxUrlBytes, kind, busy, error, create, local, snapshot };
 }
 
 // src/useQueryTable.ts
+import { createQueryLinkService } from "@pythia-software/query-table-core";
 var AUTOCOMPLETE_LIMIT = 50;
 var MAX_AUTO_REFRESH_POLLS = 1e3;
-function defaultsFor(schema) {
-  return normalizeQueryState({
+function detailColumnSchema(schema, enabled) {
+  if (!enabled) return schema;
+  return {
+    ...schema,
+    defaultSelect: [...schema.defaultSelect ?? selectedFields2(schema, { select: [] }).map((field) => ({ field: field.name })), { field: ITEM_DETAILS_COLUMN }],
+    fields: [...schema.fields, {
+      name: ITEM_DETAILS_COLUMN,
+      label: "Detail",
+      type: "text",
+      source: { kind: "derived", accessor: () => null },
+      select: { default: true, width: 112 },
+      filter: { enabled: false },
+      sort: { enabled: false },
+      aggregate: { measure: false, groupable: false },
+      property: { enabled: false }
+    }]
+  };
+}
+function defaultsFor(schema, details = false) {
+  schema = detailColumnSchema(schema, details);
+  return normalizeQueryState3({
     select: schema.defaultSelect ?? [],
     where: [],
     orderBy: schema.defaultSort ?? [],
@@ -734,31 +2135,35 @@ 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] };
+  const copy = isOrGroup2(term) ? { ...term, any: term.any.map((c) => ({ ...c })) } : { ...term };
+  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.fitToScreen) clone.fitToScreen = true;
+  if (q.aggregations)
+    clone.aggregations = JSON.parse(
+      JSON.stringify(q.aggregations)
+    );
+  if (q.grouping) clone.grouping = normalizeQueryState3(q).grouping;
+  if (q.itemDetails) clone.itemDetails = JSON.parse(JSON.stringify(q.itemDetails));
   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 +2178,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,116 +2187,485 @@ 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 hasQueryLink(url, parameter) {
+  const values = new URL(url).searchParams.getAll(parameter);
+  return values.length > 1 || values.length === 1 && values[0] !== "";
+}
+function queryParameter(opts) {
+  return opts.queryParameter ?? (typeof opts.itemDetails === "object" ? opts.itemDetails.queryParameter : void 0) ?? "q";
+}
 function resolveInitial(opts) {
-  const defaults = defaultsFor(opts.schema);
-  if (opts.initialQuery) return { q: normalizeQueryState(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 };
+  const defaults = defaultsFor(opts.schema, Boolean(opts.itemDetails));
+  if (opts.initialQuery)
+    return {
+      q: normalizeQueryState3(opts.initialQuery, defaults),
+      fromUrl: false
+    };
+  if (opts.syncUrl === true && opts.active !== false && typeof window !== "undefined") {
+    const parameter = queryParameter(opts);
+    if (hasQueryLink(window.location.href, parameter))
+      return {
+        q: 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: sourceSchema,
+    transport: sourceTransport,
+    clientRows: providedRows,
+    initialQuery,
+    debounceMs = 200
+  } = opts;
+  const active = opts.active !== false;
+  const urlSyncEnabled = opts.syncUrl === true;
+  const syncUrl = urlSyncEnabled && active;
+  const { transport: metadataTransport, activity: requestActivity } = useRequestActivity(sourceTransport);
+  const transport = metadataTransport;
+  const storage = useMemo9(
+    () => opts.storage ?? memoryStorageAdapter(),
+    [opts.storage]
+  );
+  const parameter = queryParameter(opts);
+  const linkService = useMemo9(
+    () => createQueryLinkService(sourceSchema.name, storage.snapshots, opts.links),
+    [sourceSchema.name, storage.snapshots, opts.links?.cache, opts.links?.maxUrlBytes]
+  );
   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 = useRef9(now);
+  const onRefreshRef = useRef9(opts.onRefresh);
+  const defaults = useMemo9(() => defaultsFor(sourceSchema, Boolean(opts.itemDetails)), [sourceSchema, Boolean(opts.itemDetails)]);
+  const initRef = useRef9(resolveInitial(opts));
+  const [restoration, setRestoration] = useState11({ loading: initRef.current.fromUrl, error: null });
+  const [storageReady, setStorageReady] = useState11(Boolean(initialQuery));
+  const restorationCurrent = useRef9({ storageReady, restoration, active });
+  restorationCurrent.current = { storageReady, restoration, active };
+  const manualQueryEpoch = useRef9(0);
+  const restoreController = useRef9(null);
+  const restoreHandler = useRef9(null);
+  const initialRestore = useRef9(null);
+  const initialRestorationStarted = useRef9(false);
+  const restoreLocation = useCallback12((location, signal) => {
+    if (!restoreHandler.current) return Promise.reject(Error("Query controller is not mounted."));
+    return restoreHandler.current(String(location), signal);
+  }, []);
+  const aggIdRef = useRef9(0);
+  const savedBaseline = useRef9(
+    initRef.current.q.grouping ? { source: sourceSchema.name, query: cloneQueryState(initRef.current.q) } : null
+  );
+  const viewRevision = useRef9(0);
+  const [queryHistory, setQueryHistory] = useState11(
+    () => ({ query: initRef.current.q, past: [], future: [] })
+  );
+  const queryHistoryRef = useRef9(queryHistory);
+  const updateQueryHistory = useCallback12((update) => {
+    const previous = queryHistoryRef.current;
+    const next = update(previous);
+    if (next === previous) return;
+    queryHistoryRef.current = next;
+    setQueryHistory(next);
+  }, []);
+  const storedQuery = queryHistory.query;
+  const [nonce, setNonce] = useState11(0);
+  const query = useMemo9(
+    () => opts.canonicalizeQuery?.(storedQuery) ?? storedQuery,
+    [storedQuery, opts.canonicalizeQuery]
+  );
+  const sourceCatalogue = useMemo9(() => sourceExecutionSchema(sourceSchema, opts.computedExecution), [sourceSchema, opts.computedExecution]);
+  const sourceRows = providedRows;
+  const groupingModel = useMemo9(() => createGroupingModel(sourceCatalogue), [sourceCatalogue]);
+  const remoteGrouping = !!transport?.fetchQueryV3 && transport.queryCapabilities?.version === 3 && transport.queryCapabilities.groupedRows;
+  const groupingSupported = (!transport && sourceRows !== void 0 || remoteGrouping) && opts.grouping !== false;
+  const groupKey = JSON.stringify(query.grouping ?? null);
+  const groupingNow = useMemo9(
+    () => query.grouping ? (opts.evaluationNow ?? Date.now)() : void 0,
+    [sourceRows, sourceSchema, groupingSupported, groupKey, nonce, opts.evaluationNow]
+  );
+  const prepared = useMemo9(() => {
+    if (!query.grouping) return null;
+    try {
+      if (!groupingSupported) throw new Error("Grouped queries require a server with grouped-query support or a dataset already in memory.");
+      if (remoteGrouping) {
+        groupingModel.validate(query.grouping);
+        return { inputs: [], rows: [], error: null };
+      }
+      return { ...prepareGrouping(sourceRows, sourceCatalogue, query.grouping, { now: groupingNow }), error: null };
+    } catch (error2) {
+      return { inputs: [], rows: [], error: error2 };
+    }
+  }, [sourceRows, sourceCatalogue, groupingModel, groupingSupported, groupKey, nonce, groupingNow, remoteGrouping]);
+  const projectionKey = JSON.stringify(query.grouping ? [query.grouping.keys, query.grouping.summaries] : null);
+  const schema = useMemo9(() => query.grouping ? groupingModel.resultSchema(query.grouping.keys, query.grouping.summaries) : sourceSchema, [sourceSchema, groupingModel, projectionKey]);
+  const clientRows = prepared?.rows ?? sourceRows;
+  const executionQuery = useMemo9(() => withoutGrouping2(query), [query]);
+  const byName = useMemo9(() => new Map(schema.fields.map((field) => [field.name, field])), [schema]);
+  const detailsEnabled = Boolean(opts.itemDetails) && !query.grouping;
+  const validateExecution = useCallback12((q) => {
+    if (prepared?.error) throw prepared.error;
+    opts.validateQuery?.(query.grouping ? { ...q, grouping: query.grouping } : q);
+  }, [prepared?.error, opts.validateQuery, groupKey]);
+  const [committedRows, setRows] = useState11([]);
+  const [serverComputed, setServerComputed] = useState11(/* @__PURE__ */ new Map());
+  const [committedFields, setCommittedFields] = useState11([]);
+  const [serverExecution, setServerExecution] = useState11();
+  const [total, setTotal] = useState11(null);
+  const [loading, setLoading] = useState11(false);
+  const [error, setError] = useState11(null);
+  const [committedPage, setCommittedPage] = useState11(null);
+  const [committedSource, setCommittedSource] = useState11(null);
+  const rows = useMemo9(() => committedSource?.schema === schema ? committedRows : [], [committedSource?.schema, schema, committedRows]);
+  const [autoRefreshStatus, setAutoRefreshStatus] = useState11(null);
+  useEffect10(() => {
     nowRef.current = now;
   }, [now]);
-  useEffect4(() => {
+  useEffect10(() => {
     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);
+  const setQuery = useCallback12(
+    (next) => {
+      manualQueryEpoch.current++;
+      initialRestorationStarted.current = true;
+      restoreController.current?.abort();
+      setStorageReady(true);
+      setRestoration((previous) => !previous.loading && !previous.error ? previous : { loading: false, error: null });
+      updateQueryHistory((history) => {
+        const prev = history.query;
+        const candidate = typeof next === "function" ? next(prev) : next;
+        const nextQuery = normalizeQueryState3(candidate, defaults);
+        if (queriesEqual2(prev, nextQuery)) return history;
+        return { query: cloneQueryState(nextQuery), past: [...history.past, cloneQueryState(prev)], future: [] };
+      });
+    },
+    [defaults, updateQueryHistory]
+  );
+  const sourceQuery = query.grouping?.source ?? query;
+  const setSourceQuery = useCallback12((next) => {
+    setQuery((current) => {
+      const previous = current.grouping?.source ?? current;
+      const source = withoutGrouping2(typeof next === "function" ? next(previous) : next);
+      return current.grouping ? { ...current, offset: 0, grouping: { ...current.grouping, source } } : source;
     });
-  }, [defaults]);
-  useEffect4(() => {
-    if (initRef.current.fromUrl || initialQuery) return;
+  }, [setQuery]);
+  const sourceFilters = useQueryFilters(sourceCatalogue, setSourceQuery);
+  const observedQueryUrl = useRef9(null);
+  const recordQueryUrl = useCallback12((url) => {
+    observedQueryUrl.current = JSON.stringify(new URL(url).searchParams.getAll(parameter));
+  }, [parameter]);
+  const links = useQueryLinks(
+    query,
+    linkService,
+    syncUrl,
+    storageReady && !restoration.loading && !restoration.error,
+    parameter,
+    opts.links?.maxUrlBytes ?? 2e3,
+    recordQueryUrl
+  );
+  const restoreSources = useRef9({ storage, linkService, defaults, initialQuery });
+  restoreSources.current = { storage, linkService, defaults, initialQuery };
+  useEffect10(() => {
     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);
-        undoStack.current = [cloneQueryState(normalized)];
-        redoStack.current = [];
-        setQueryState(normalized);
+    let controller = new AbortController();
+    let generation = 0;
+    initialRestorationStarted.current = Boolean(restoreSources.current.initialQuery);
+    async function restore(navigation = false, location = typeof window !== "undefined" ? window.location.href : "", signal) {
+      initialRestorationStarted.current = true;
+      const { storage: storage2, linkService: linkService2, defaults: defaults2 } = restoreSources.current;
+      const run = ++generation;
+      const epoch = manualQueryEpoch.current;
+      controller.abort();
+      controller = new AbortController();
+      restoreController.current = controller;
+      const currentController = controller;
+      const abort2 = () => currentController.abort();
+      signal?.addEventListener("abort", abort2, { once: true });
+      if (signal?.aborted) currentController.abort();
+      setStorageReady(false);
+      const explicitLink = !!location && (navigation || urlSyncEnabled) && hasQueryLink(location, parameter);
+      setRestoration({ loading: true, error: null });
+      try {
+        if (currentController.signal.aborted) throw new DOMException("Query restoration cancelled.", "AbortError");
+        const fromUrl = location && (navigation || urlSyncEnabled) ? await linkService2.resolve(location, parameter, currentController.signal) : null;
+        const defaultSaved = fromUrl ? null : await storage2.loadDefaultSaved?.(sourceSchema.name);
+        const restored = fromUrl ?? defaultSaved?.query ?? (navigation ? defaults2 : await storage2.loadLast(sourceSchema.name));
+        if (currentController.signal.aborted) throw new DOMException("Query restoration cancelled.", "AbortError");
+        if (!cancelled && run === generation && epoch === manualQueryEpoch.current) {
+          if (restored) {
+            const normalized = normalizeQueryState3(restored, defaults2);
+            savedBaseline.current = defaultSaved || fromUrl?.grouping ? { source: sourceSchema.name, query: cloneQueryState(normalized) } : null;
+            viewRevision.current++;
+            updateQueryHistory(() => ({ query: normalized, past: [], future: [] }));
+          }
+          setStorageReady(true);
+          setRestoration((previous) => !previous.loading && !previous.error ? previous : { loading: false, error: null });
+        }
+      } catch (e) {
+        if (!cancelled && run === generation && epoch === manualQueryEpoch.current) {
+          if (explicitLink || navigation && currentController.signal.aborted) {
+            setRestoration({ loading: false, error: e instanceof Error ? e : Error(String(e)) });
+          } else {
+            updateQueryHistory(() => ({ query: defaults2, past: [], future: [] }));
+            setRestoration({ loading: false, error: null });
+          }
+          setStorageReady(true);
+        }
+        if (navigation && !cancelled && run === generation && epoch === manualQueryEpoch.current) throw e;
+      } finally {
+        signal?.removeEventListener("abort", abort2);
       }
-    })();
+    }
+    restoreHandler.current = async (location, signal) => {
+      location = new URL(location, typeof window !== "undefined" ? window.location.href : void 0).href;
+      const key = JSON.stringify(new URL(location).searchParams.getAll(parameter));
+      const current = restorationCurrent.current;
+      if (key === observedQueryUrl.current && current.storageReady && !current.restoration.loading && !current.restoration.error) return;
+      recordQueryUrl(location);
+      await restore(true, location, signal);
+    };
+    initialRestore.current = () => restore();
+    if (typeof window !== "undefined") recordQueryUrl(window.location.href);
+    const navigate = () => {
+      if (!restorationCurrent.current.active) return;
+      const key = JSON.stringify(new URL(window.location.href).searchParams.getAll(parameter));
+      if (key === observedQueryUrl.current) return;
+      observedQueryUrl.current = key;
+      void restore(true).catch(() => {
+      });
+    };
+    if (urlSyncEnabled && typeof window !== "undefined") window.addEventListener("popstate", navigate);
     return () => {
       cancelled = true;
+      controller.abort();
+      restoreHandler.current = null;
+      initialRestore.current = null;
+      if (urlSyncEnabled && typeof window !== "undefined") window.removeEventListener("popstate", navigate);
     };
-  }, []);
+  }, [sourceSchema.name, urlSyncEnabled, parameter, recordQueryUrl, updateQueryHistory]);
+  useEffect10(() => {
+    if (active && !initialRestorationStarted.current) void initialRestore.current?.();
+  }, [active, sourceSchema.name, urlSyncEnabled, parameter, recordQueryUrl]);
   const { api: computed, displaySchema } = useComputedColumns({
     schema,
-    query,
+    query: executionQuery,
     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(
-    () => 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]
+  const resolveComputed = useCallback12(
+    (name) => isComputedField4(name) ? computed.compile(`[${name.replace(/]/g, "]] ".trim())}]`) : void 0,
+    [computed.compile]
   );
-  useEffect4(() => {
+  const metricCompile = useCallback12(
+    (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 = useMemo9(
+    () => Object.fromEntries(computed.definitions.map((d) => [d.id, d.revision])),
+    [computed.definitions]
+  );
+  const definitionKey = JSON.stringify(computedRevisions);
+  const queryKey = useMemo9(() => JSON.stringify(query), [query]);
+  const serverRowQuery = useMemo9(() => {
+    const execution = opts.computedExecution;
+    const detailConfig = typeof opts.itemDetails === "object" ? opts.itemDetails : void 0;
+    const page = query.itemDetails?.page ?? detailConfig?.page;
+    const pageEnabled = Boolean(opts.itemDetails) && (query.itemDetails?.modes ?? initialDetailModes(detailConfig)).includes("page") && (!detailConfig?.modes || detailConfig.modes.includes("page"));
+    const pageFields = pageEnabled ? itemPageFields(page?.urlTemplate ?? "") : [];
+    const requestQuery = pageFields.length ? { ...executionQuery, select: [
+      ...query.select.length ? query.select : defaults.select,
+      ...pageFields.filter((name) => displaySchema.fields.some((field) => field.name === name)).map((field) => ({ field }))
+    ] } : executionQuery;
+    const v2Request = execution && transport?.fetchRowsV2 ? toServerQueryV2(requestQuery, displaySchema, execution) : void 0;
+    const request = v2Request ?? toServerQuery2(requestQuery, displaySchema);
+    if (v2Request)
+      for (const definition of computed.definitions) {
+        if ((execution?.fields[computedFieldName2(definition.id)]?.select || v2Request.orderBy.some(
+          (term) => term.field === computedFieldName2(definition.id)
+        )) && 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,
+    opts.itemDetails,
+    defaults
+  ]);
+  const rowQueryKey = useMemo9(
+    () => transport ? `server:${JSON.stringify(serverRowQuery)}:${transport.fetchQueryV3 ? JSON.stringify([
+      groupKey,
+      groupingNow,
+      query.select.map((column) => column.field),
+      query.where,
+      query.orderBy,
+      query.limit,
+      query.offset
+    ]) : ""}` : `client:${JSON.stringify([query.where, query.orderBy, query.limit, query.offset])}`,
+    [
+      transport,
+      serverRowQuery,
+      groupKey,
+      groupingNow,
+      query.select,
+      query.where,
+      query.orderBy,
+      query.limit,
+      query.offset
+    ]
+  );
+  const executionKey = JSON.stringify(opts.computedExecution ?? null);
+  const pageContext = `${schema.name}:${rowQueryKey}:${nonce}:${executionKey}`;
+  useEffect10(() => {
+    if (!active || !storageReady || restoration.loading || restoration.error) {
+      setRows((previous) => previous.length ? [] : previous);
+      setTotal(null);
+      setCommittedPage(null);
+      setLoading(false);
+      return;
+    }
     const ac = new AbortController();
     let cancelled = false;
     const run = async () => {
       setLoading(true);
       setError(null);
       try {
-        opts.validateQuery?.(query);
+        validateExecution(query);
         if (transport) {
-          const res = await transport.fetchRows(serverRowQuery, ac.signal);
+          if (transport.fetchQueryV3 && transport.queryCapabilities?.version === 3 && (query.grouping || query.select.some((column) => isComputedField4(column.field)) || query.orderBy.some((term) => isComputedField4(term.field)) || query.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => isComputedField4(predicate.field))))) {
+            const request = toQueryRequestV3(
+              { ...query, aggregations: [], select: [
+                ...query.select.filter((column) => isComputedField4(column.field)),
+                ...serverRowQuery.select.map((field) => ({ field }))
+              ] },
+              sourceSchema,
+              transport.queryCapabilities,
+              opts.computedExecution,
+              { now: groupingNow ?? (opts.evaluationNow ?? Date.now)() }
+            );
+            if (request.diagnostics.length) throw Error(request.diagnostics.join(" "));
+            const result = await transport.fetchQueryV3(request, ac.signal);
+            validateQueryResultV3(result, request, query.grouping ? schema : sourceCatalogue);
+            if (!cancelled) {
+              setCommittedFields(request.result.select);
+              setServerExecution(result.execution);
+              setServerComputed(new Map(result.rows.map((row) => [
+                row[schema.idField],
+                Object.fromEntries(Object.entries(row).filter(([name]) => isComputedField4(name)).map(([name, value]) => [name.slice(10), value && typeof value === "object" && "computedError" in value ? { value: null, error: { code: String(value.computedError) } } : { value }]))
+              ])));
+              setRows(result.rows);
+              setTotal(result.total);
+              setCommittedPage(pageContext);
+              setCommittedSource({ schema, transport, clientRows });
+            }
+            return;
+          }
+          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);
+          const res = applyQuery2(
+            clientRows ?? [],
+            executionQuery,
+            schema,
+            groupingNow !== void 0 ? { now: groupingNow } : {}
+          );
           if (!cancelled) {
             setRows(res.rows);
             setTotal(res.total);
+            setCommittedPage(pageContext);
+            setCommittedSource({ schema, transport, clientRows });
           }
         }
       } catch (e) {
@@ -899,6 +2673,7 @@ function useQueryTable(opts) {
           setError(e);
           setRows([]);
           setTotal(null);
+          setCommittedPage(null);
         }
       } finally {
         if (!cancelled) setLoading(false);
@@ -910,159 +2685,211 @@ function useQueryTable(opts) {
       clearTimeout(t);
       ac.abort();
     };
-  }, [rowQueryKey, transport, clientRows, schema, debounceMs, nonce, opts.validateQuery]);
-  useEffect4(() => {
-    if (!syncUrl || typeof window === "undefined") return;
-    const url = new URL(window.location.href);
-    const token = encodeQuery(query);
-    if (token) url.searchParams.set("q", token);
-    else url.searchParams.delete("q");
-    window.history.replaceState(null, "", url.toString());
-  }, [queryKey, syncUrl, query]);
-  useEffect4(() => {
-    const t = setTimeout(() => void storage.saveLast(schema.name, query), 400);
+  }, [
+    rowQueryKey,
+    transport,
+    clientRows,
+    schema,
+    debounceMs,
+    nonce,
+    validateExecution,
+    executionKey,
+    groupingNow,
+    restoration,
+    active,
+    storageReady
+  ]);
+  useEffect10(() => {
+    if (!storageReady || restoration.loading || restoration.error) return;
+    const t = setTimeout(() => void storage.saveLast(sourceSchema.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,
-    [idField]
+  }, [queryKey, storage, sourceSchema.name, query, restoration, storageReady]);
+  const idField = useMemo9(
+    () => schema.fields.find((f) => f.name === schema.idField),
+    [schema]
+  );
+  const rowId = useCallback12(
+    (row) => (() => {
+      const value = idField ? readFieldValue4(idField, row) : row?.[schema.idField];
+      return typeof value === "string" || typeof value === "number" && Number.isFinite(value) ? value : null;
+    })(),
+    [idField, schema.idField]
+  );
+  const displayedIds = useMemo9(
+    () => rows.map(rowId).filter((id) => id != null),
+    [rows, rowId]
   );
-  const displayedIds = useMemo6(() => rows.map(rowId).filter((id) => id != null), [rows, rowId]);
   const selection = useSelection(displayedIds);
-  const select = useSelect(query, setQuery, displaySchema);
+  const identityScope = JSON.stringify([sourceSchema.name, query.grouping?.keys ?? null]);
+  useEffect10(() => {
+    selection.clear();
+  }, [identityScope, selection.clear]);
+  const columnSchema = useMemo9(() => detailColumnSchema(displaySchema, detailsEnabled), [displaySchema, detailsEnabled]);
+  const resultDefaults = useMemo9(() => query.grouping ? defaultsFor(schema) : defaults, [Boolean(query.grouping), schema, defaults]);
+  const select = useSelect(query, setQuery, columnSchema);
   const columnDrag = useColumnDrag();
-  const saved = useSavedQueries(
-    schema.name,
+  const savedQueries = useSavedQueries(
+    sourceSchema.name,
     query,
-    (q) => setQuery(q),
+    (q) => {
+      const normalized = normalizeQueryState3(q, defaults);
+      savedBaseline.current = { source: sourceSchema.name, query: cloneQueryState(normalized) };
+      viewRevision.current++;
+      setQuery(normalized);
+    },
     storage,
-    now
-  );
-  const aggState = useAggregations(query, schema, transport, clientRows, debounceMs, nonce, opts.validateQuery);
-  const canUndo = undoStack.current.length > 0;
-  const canRedo = redoStack.current.length > 0;
-  const undo = useCallback6(() => {
-    setQueryState((prev) => {
-      const previous = undoStack.current.pop();
-      if (!previous) return prev;
-      redoStack.current.push(cloneQueryState(prev));
-      return cloneQueryState(previous);
-    });
-  }, []);
-  const redo = useCallback6(() => {
-    setQueryState((prev) => {
-      const next = redoStack.current.pop();
-      if (!next) return prev;
-      undoStack.current.push(cloneQueryState(prev));
-      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) })),
-    [setQuery]
-  );
-  const removeFilter = useCallback6(
-    (index) => setQuery((q) => ({ ...q, offset: 0, where: q.where.filter((_, i) => i !== index) })),
-    [setQuery]
-  );
-  const clearFilters = useCallback6(() => setQuery((q) => ({ ...q, offset: 0, where: [] })), [setQuery]);
-  const updatePredicate = useCallback6(
-    (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) };
-        return clause;
-      })
-    })),
-    [setQuery]
+    now,
+    links.snapshot
   );
-  const removePredicate = useCallback6(
-    (termIndex, predIndex) => setQuery((q) => {
-      const where = [];
-      q.where.forEach((term, i) => {
-        if (i !== termIndex) {
-          where.push(term);
-          return;
-        }
-        if (isOrGroup(term)) {
-          const members = term.any.filter((_, j) => j !== predIndex);
-          if (members.length === 1) where.push(members[0]);
-          else if (members.length > 1) where.push({ any: members });
-          return;
-        }
-      });
-      return { ...q, offset: 0, where };
-    }),
-    [setQuery]
+  const saved = { ...savedQueries, save: async (name) => {
+    const item = await savedQueries.save(name);
+    savedBaseline.current = { source: sourceSchema.name, query: cloneQueryState(normalizeQueryState3(item.query, defaults)) };
+    viewRevision.current++;
+    return item;
+  } };
+  const pageReady = committedPage === pageContext && committedSource?.schema === schema && committedSource?.transport === transport && committedSource?.clientRows === clientRows && !error;
+  const dataToken = useRef9(0);
+  const dataVersion = useMemo9(
+    () => ++dataToken.current,
+    [schema, transport, clientRows, nonce, definitionKey, executionKey]
   );
-  const negateOne = useCallback6(
-    (clause) => {
-      const field = byName.get(clause.field);
-      return negateClause(clause, field ? opsForField(field) : void 0);
+  const executeV3Metrics = useCallback12(async (metricQuery, signal) => {
+    if (!transport?.fetchQueryV3 || transport.queryCapabilities?.version !== 3) throw Error("The v3 query executor is unavailable.");
+    const request = toQueryRequestV3(
+      query.grouping ? { ...metricQuery, grouping: query.grouping } : metricQuery,
+      sourceSchema,
+      transport.queryCapabilities,
+      opts.computedExecution,
+      { now: groupingNow ?? (opts.evaluationNow ?? Date.now)(), rows: false }
+    );
+    if (request.diagnostics.length) throw Error(request.diagnostics.join(" "));
+    const result = await transport.fetchQueryV3(request, signal);
+    validateQueryResultV3(result, request, query.grouping ? schema : sourceCatalogue);
+    return { metrics: result.metrics };
+  }, [transport, sourceSchema, sourceCatalogue, schema, opts.computedExecution, groupKey, groupingNow, opts.evaluationNow]);
+  const previewGrouping = useCallback12(async (draft, signal) => {
+    if (!active || !storageReady || restoration.loading || restoration.error) throw Error("Wait for query restoration before previewing groups.");
+    if (!transport?.fetchQueryV3 || !transport.queryCapabilities?.groupedRows || !draft.grouping) throw Error("The server group preview is unavailable.");
+    const request = toQueryRequestV3(
+      { ...draft, aggregations: [] },
+      sourceSchema,
+      transport.queryCapabilities,
+      opts.computedExecution,
+      { now: groupingNow ?? (opts.evaluationNow ?? Date.now)() }
+    );
+    if (request.diagnostics.length) throw Error(request.diagnostics.join(" "));
+    const result = await transport.fetchQueryV3(request, signal);
+    validateQueryResultV3(result, request, groupingModel.resultSchema(draft.grouping.keys, draft.grouping.summaries));
+    return { rows: result.rows, total: result.total, sourceTotal: result.sourceTotal };
+  }, [transport, sourceSchema, opts.computedExecution, groupingModel, groupingNow, opts.evaluationNow, active, storageReady, restoration.loading, restoration.error]);
+  const aggState = useAggregations(
+    executionQuery,
+    schema,
+    transport,
+    clientRows,
+    debounceMs,
+    nonce,
+    validateExecution,
+    {
+      ...transport?.fetchQueryV3 && transport.queryCapabilities?.version === 3 && (query.grouping || query.aggregations?.some((metric) => metric.dateGrouping) || query.where.some((term) => ("any" in term ? term.any : [term]).some((predicate) => isComputedField4(predicate.field)))) ? { executeV3: executeV3Metrics, queryContextKey: groupKey } : {},
+      ...groupingNow !== void 0 ? { now: groupingNow, strictLocalMetrics: true } : {},
+      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 } : {}
     },
-    [byName]
+    active && storageReady && !restoration.loading && !restoration.error
   );
-  const negatePredicate = useCallback6(
-    (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) };
-        return negateOne(term);
-      })
-    })),
-    [setQuery, negateOne]
+  const queryRef = useRef9(query);
+  queryRef.current = query;
+  const replaceAggregations = useCallback12(
+    (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 reorderFilters = useCallback6(
-    (fromIndex, toIndex) => setQuery((q) => {
-      if (fromIndex < 0 || fromIndex >= q.where.length) return q;
-      const where = [...q.where];
-      const [moved] = where.splice(fromIndex, 1);
-      where.splice(Math.max(0, Math.min(toIndex, where.length)), 0, moved);
-      return { ...q, offset: 0, where };
-    }),
+  const canUndo = queryHistory.past.length > 0;
+  const canRedo = queryHistory.future.length > 0;
+  const undo = useCallback12(() => {
+    if (!queryHistoryRef.current.past.length) return;
+    manualQueryEpoch.current++;
+    restoreController.current?.abort();
+    setStorageReady(true);
+    setRestoration({ loading: false, error: null });
+    updateQueryHistory((history) => {
+      const previous = history.past[history.past.length - 1];
+      if (!previous) return history;
+      return { query: cloneQueryState(previous), past: history.past.slice(0, -1), future: [...history.future, cloneQueryState(history.query)] };
+    });
+  }, [updateQueryHistory]);
+  const redo = useCallback12(() => {
+    if (!queryHistoryRef.current.future.length) return;
+    manualQueryEpoch.current++;
+    restoreController.current?.abort();
+    setStorageReady(true);
+    setRestoration({ loading: false, error: null });
+    updateQueryHistory((history) => {
+      const next = history.future[history.future.length - 1];
+      if (!next) return history;
+      return { query: cloneQueryState(next), past: [...history.past, cloneQueryState(history.query)], future: history.future.slice(0, -1) };
+    });
+  }, [updateQueryHistory]);
+  const patch = useCallback12(
+    (p) => setQuery((prev) => ({ ...prev, ...p })),
     [setQuery]
   );
-  const mergeFilters = useCallback6(
-    (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 where = [];
-      q.where.forEach((term, i) => {
-        if (i === sourceIndex) return;
-        where.push(i === targetIndex ? merged : term);
-      });
-      return { ...q, offset: 0, where };
-    }),
-    [setQuery]
+  const { addFilter, updateFilter, removeFilter, clearFilters, updatePredicate, removePredicate, negatePredicate, reorderFilters, mergeFilters } = useQueryFilters(schema, setQuery);
+  const resetAll = useCallback12(
+    () => {
+      const baseline = savedBaseline.current;
+      viewRevision.current++;
+      setQuery(cloneQueryState(baseline?.source === sourceSchema.name ? baseline.query : defaults));
+    },
+    [setQuery, defaults, sourceSchema.name]
   );
-  const resetAll = useCallback6(() => setQuery(() => cloneQueryState(defaults)), [setQuery, defaults]);
-  const addAggregation = useCallback6(
+  const addAggregation = useCallback12(
     (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 = useCallback12(
     (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 = useCallback12(
     (id, toIndex) => setQuery((q) => {
       const current = q.aggregations ?? [];
       const from = current.findIndex((a) => a.id === id);
@@ -1074,26 +2901,45 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const removeAggregation = useCallback6(
-    (id) => setQuery((q) => ({ ...q, aggregations: (q.aggregations ?? []).filter((a) => a.id !== id) })),
+  const removeAggregation = useCallback12(
+    (id) => setQuery((q) => ({
+      ...q,
+      aggregations: (q.aggregations ?? []).filter((a) => a.id !== id)
+    })),
     [setQuery]
   );
-  const clearAggregations = useCallback6(
+  const clearAggregations = useCallback12(
     () => 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 = useCallback12(
+    (orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })),
+    [setQuery]
+  );
+  const toggleSort = useCallback12(
+    (field, additive = false) => setQuery((q) => ({
+      ...q,
+      offset: 0,
+      orderBy: nextOrderBy(q.orderBy, field, additive)
+    })),
+    [setQuery]
+  );
+  const setLimit = useCallback12(
+    (limit) => patch({ limit, offset: 0 }),
+    [patch]
+  );
+  const setOffset = useCallback12((offset) => patch({ offset }), [patch]);
+  const nextPage = useCallback12(
+    () => setQuery((q) => ({ ...q, offset: q.offset + q.limit })),
+    [setQuery]
+  );
+  const prevPage = useCallback12(
+    () => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })),
     [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 filterValues = useCallback12(
     async (field, search) => {
-      if (!transport?.fetchDistinctValues) {
+      if (!metadataTransport?.fetchDistinctValues || query.grouping && !query.grouping.keys.includes(field)) {
         const f = byName.get(field);
         if (!f || !clientRows) return { values: [], hasMore: false };
         const fieldHasNull = fieldHasNullInRows(f, clientRows);
@@ -1104,18 +2950,18 @@ function useQueryTable(opts) {
           hasNull: fieldHasNull
         };
       }
-      return transport.fetchDistinctValues({ field, search });
+      return metadataTransport.fetchDistinctValues({ field, search });
     },
-    [transport, byName, clientRows]
+    [metadataTransport, byName, clientRows, groupKey]
   );
-  const fieldStats = useCallback6(
+  const fieldStats = useCallback12(
     async (fields, signal) => {
       const requested = [...new Set(fields)];
-      if (transport?.fetchFieldStats) {
+      if (metadataTransport?.fetchFieldStats && !query.grouping) {
         const backendFields = requested.filter(
           (name) => byName.get(name)?.source.kind === "backend"
         );
-        return backendFields.length ? transport.fetchFieldStats(backendFields, signal) : {};
+        return backendFields.length ? metadataTransport.fetchFieldStats(backendFields, signal) : {};
       }
       if (!clientRows) return {};
       const result = {};
@@ -1125,21 +2971,21 @@ 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 };
       }
       return result;
     },
-    [transport, byName, clientRows]
+    [metadataTransport, byName, clientRows, groupKey]
   );
-  const refresh = useCallback6(() => {
+  const refresh = useCallback12(() => {
     setNonce((n) => n + 1);
     onRefreshRef.current?.();
   }, []);
-  const stopAutoRefresh = useCallback6(() => setAutoRefreshStatus(null), []);
-  const startAutoRefresh = useCallback6(
+  const stopAutoRefresh = useCallback12(() => setAutoRefreshStatus(null), []);
+  const startAutoRefresh = useCallback12(
     ({ frequencyMs, turnOffAfterMs }) => {
       const pollCount = frequencyMs > 0 && turnOffAfterMs > 0 ? Math.floor(turnOffAfterMs / frequencyMs) : 0;
       if (pollCount < 1 || pollCount > MAX_AUTO_REFRESH_POLLS) {
@@ -1159,11 +3005,13 @@ function useQueryTable(opts) {
   );
   const autoRefreshFrequencyMs = autoRefreshStatus?.frequencyMs ?? null;
   const autoRefreshStopsAt = autoRefreshStatus?.stopsAt ?? null;
-  useEffect4(() => {
+  useEffect10(() => {
     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 +3023,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 +3033,7 @@ function useQueryTable(opts) {
       clearTimeout(timeout);
     };
   }, [autoRefreshFrequencyMs, autoRefreshStopsAt, refresh]);
-  const autoRefresh = useMemo6(
+  const autoRefresh = useMemo9(
     () => ({
       status: autoRefreshStatus,
       start: startAutoRefresh,
@@ -1191,16 +3041,25 @@ function useQueryTable(opts) {
     }),
     [autoRefreshStatus, startAutoRefresh, stopAutoRefresh]
   );
-  const refreshRow = useCallback6(
+  const refreshRow = useCallback12(
     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 = useMemo9(
+    () => selectedFields2(columnSchema, query),
+    [columnSchema, query]
   );
-  const visibleFields = useMemo6(() => selectedFields2(displaySchema, query), [displaySchema, query]);
-  const aggregations = useMemo6(
+  const aggregations = useMemo9(
     () => ({
       clauses: query.aggregations ?? [],
       results: aggState.results,
@@ -1210,7 +3069,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,17 +3084,53 @@ function useQueryTable(opts) {
       updateAggregation,
       moveAggregation,
       removeAggregation,
-      clearAggregations
+      clearAggregations,
+      aggState.preview,
+      replaceAggregations,
+      metricCompile,
+      pageContext,
+      pageReady,
+      dataVersion,
+      query.where
     ]
   );
-  return {
+  const sourceRowId = useCallback12((row) => {
+    const field = sourceSchema.fields.find((f) => f.name === sourceSchema.idField);
+    const value = field ? readFieldValue4(field, row) : row[sourceSchema.idField];
+    return typeof value === "string" || typeof value === "number" && Number.isFinite(value) ? value : null;
+  }, [sourceSchema]);
+  const itemDetails = useItemDetails({
+    schema: query.grouping ? sourceSchema : displaySchema,
+    query: sourceQuery,
+    setQuery: setSourceQuery,
+    options: opts.itemDetails,
+    rows: query.grouping ? sourceRows ?? [] : rows,
+    clientRows: sourceRows,
+    rowId: sourceRowId,
+    transport: metadataTransport,
+    refreshKey: nonce,
+    links,
+    queryParameter: parameter,
+    queryReady: storageReady && !restoration.loading && !restoration.error
+  });
+  const api = {
+    restoration: {
+      status: restoration.error ? "error" : !storageReady || restoration.loading ? "resolving" : "ready",
+      ready: active && storageReady && !restoration.loading && !restoration.error,
+      error: restoration.error
+    },
+    restoreLocation,
+    links,
+    schema: columnSchema,
+    ...itemDetails && detailsEnabled ? { itemDetails } : {},
     query,
-    defaults,
+    defaults: resultDefaults,
     setQuery,
     rows,
     total,
-    loading,
-    error,
+    loading: loading || restoration.loading,
+    error: restoration.error ?? error,
+    requestActivity,
     canUndo,
     canRedo,
     undo,
@@ -1266,6 +3165,48 @@ function useQueryTable(opts) {
     visibleFields,
     rowId
   };
+  const sourceApi = {
+    ...sourceFilters,
+    loading,
+    rowId: sourceRowId,
+    query: sourceQuery,
+    setQuery: setSourceQuery,
+    ...itemDetails ? { itemDetails } : {},
+    schema: sourceCatalogue,
+    filterValues: async (name, search) => {
+      if (metadataTransport?.fetchDistinctValues) return metadataTransport.fetchDistinctValues({ field: name, search });
+      const field = groupingModel.sourceField(name);
+      return field && sourceRows ? { ...distinctValuesFromRows(field, sourceRows, search), hasNull: fieldHasNullInRows(field, sourceRows) } : { values: [], hasMore: false };
+    },
+    fieldStats: async (names, signal) => {
+      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+      const requested = [...new Set(names)];
+      if (metadataTransport?.fetchFieldStats) {
+        const backendFields = requested.filter(
+          (name) => sourceCatalogue.fields.find((field) => field.name === name)?.source.kind === "backend"
+        );
+        return backendFields.length ? metadataTransport.fetchFieldStats(backendFields, signal) : {};
+      }
+      return Object.fromEntries(requested.flatMap((name) => {
+        const field = groupingModel.sourceField(name);
+        return field && sourceRows ? [[name, { distinct: new Set(sourceRows.map((row) => JSON.stringify(readFieldValue4(field, row)))).size }]] : [];
+      }));
+    }
+  };
+  const grouping = useGroupingController(
+    api,
+    sourceApi,
+    groupingModel,
+    prepared?.inputs ?? sourceRows ?? [],
+    groupingSupported,
+    viewRevision.current,
+    { inputsReady: !remoteGrouping, ...remoteGrouping ? { preview: previewGrouping } : {} }
+  );
+  return {
+    ...api,
+    ...groupingSupported || query.grouping ? { grouping } : {},
+    select: { ...select, hide: (field) => query.grouping?.keys.includes(field) ? grouping.changeKeys(query.grouping.keys.filter((key) => key !== field)) : select.hide(field) }
+  };
 }
 function nextOrderBy(existing, field, additive) {
   const i = existing.findIndex((s) => s.field === field);
@@ -1285,11 +3226,67 @@ function nextOrderBy(existing, field, additive) {
   }
   return existing.filter((_, k) => k !== i);
 }
+
+// src/useObjectReferences.ts
+import { useEffect as useEffect11, useMemo as useMemo10, useState as useState12 } from "react";
+import {
+  objectReferenceKey
+} from "@pythia-software/query-table-core";
+function useObjectReferences(references, adapter) {
+  const fingerprint = JSON.stringify(references.map(objectReferenceKey).sort());
+  const batch = useMemo10(
+    () => [
+      ...new Map(
+        references.map((reference) => [
+          objectReferenceKey(reference),
+          reference
+        ])
+      ).values()
+    ],
+    [fingerprint]
+  );
+  const [state, setState] = useState12({
+    fingerprint: "",
+    adapter: void 0,
+    values: /* @__PURE__ */ new Map(),
+    error: null
+  });
+  useEffect11(() => {
+    const controller = new AbortController();
+    if (!adapter || batch.length === 0) return;
+    const allowed = new Set(batch.map(objectReferenceKey));
+    void Promise.resolve().then(() => adapter.resolve(batch, controller.signal)).then((results) => {
+      if (controller.signal.aborted) return;
+      const values = /* @__PURE__ */ new Map();
+      for (const result of results) {
+        const key = objectReferenceKey(result.reference);
+        if (allowed.has(key)) values.set(key, result);
+      }
+      setState({ fingerprint, adapter, values, error: null });
+    }).catch((error) => {
+      if (!controller.signal.aborted)
+        setState({
+          fingerprint,
+          adapter,
+          values: /* @__PURE__ */ new Map(),
+          error: error instanceof Error ? error : new Error(String(error))
+        });
+    });
+    return () => controller.abort();
+  }, [batch, adapter]);
+  const current = state.fingerprint === fingerprint && state.adapter === adapter;
+  return {
+    values: current ? state.values : /* @__PURE__ */ new Map(),
+    error: current ? state.error : null
+  };
+}
 export {
   createFormulaWorker,
   evaluateFormulaRows,
   useAggregations,
   useColumnDrag,
+  useObjectReferences,
+  usePropertyView,
   useQueryTable,
   useSavedQueries,
   useSelect,