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

package/dist/index.js

@@ -1,3 +1,706 @@
+// 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,
@@ -12,8 +715,13 @@ function validateComputedResponse(request, result, schema) {
     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."
@@ -43,7 +751,7 @@ function validateComputedResponse(request, result, schema) {
 }
 
 // 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,
@@ -148,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;
@@ -181,30 +889,30 @@ 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;
@@ -227,7 +935,7 @@ function useComputedColumns(options) {
     },
     [inputFields, definitions]
   );
-  const plans = useMemo(
+  const plans = useMemo3(
     () => new Map(
       definitions.map((def) => {
         try {
@@ -245,7 +953,7 @@ function useComputedColumns(options) {
     ),
     [definitions, compile]
   );
-  const backendDependencies = useCallback(
+  const backendDependencies = useCallback4(
     (plan) => [
       ...new Set(
         plan.dependencies.flatMap((name) => {
@@ -260,7 +968,7 @@ function useComputedColumns(options) {
     ).sort(),
     [schema, inputFields]
   );
-  const inputsFor = useCallback(
+  const inputsFor = useCallback4(
     (plan, batch) => {
       let size = 0;
       return batch.map((row) => {
@@ -282,13 +990,14 @@ function useComputedColumns(options) {
   );
   const activeSelect = query.select.length ? query.select : schema.defaultSelect ?? [];
   const activeIds = activeSelect.filter((c) => isComputedField2(c.field)).map((c) => c.field.slice("@computed/".length)).sort().join(",");
-  const [evaluated, setEvaluated] = useState(null);
-  useEffect(() => {
+  const [evaluated, setEvaluated] = useState4(null);
+  useEffect4(() => {
     const ac = new AbortController();
     const values = /* @__PURE__ */ new Map();
     void (async () => {
-      if (options.execution && transport?.fetchRowsV2) return;
       for (const id of activeIds.split(",").filter(Boolean)) {
+        if (options.execution?.fields[computedFieldName(id)]?.select && (transport?.fetchRowsV2 || transport?.fetchQueryV3))
+          continue;
         const entry = plans.get(id);
         if (!entry?.plan) continue;
         try {
@@ -324,7 +1033,7 @@ function useComputedColumns(options) {
     options.execution,
     transport
   ]);
-  const displaySchema = useMemo(() => {
+  const displaySchema = useMemo3(() => {
     const indices = new Map(rows.map((row, i) => [row, i]));
     const fields = definitions.map((def) => {
       const entry = plans.get(def.id);
@@ -339,7 +1048,7 @@ function useComputedColumns(options) {
           dependencies: entry?.plan ? backendDependencies(entry.plan) : [],
           accessor: (row) => {
             if (entry?.error) return { computedError: entry.error };
-            if (options.execution && transport?.fetchRowsV2) {
+            if (options.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."
@@ -355,13 +1064,13 @@ function useComputedColumns(options) {
             return result?.error ? { computedError: result.error } : result ? result.value : { computedError: "Calculating\u2026" };
           }
         },
-        filter: { enabled: 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 && !!options.execution?.fields[computedFieldName(def.id)]?.sort && executionRevision(options.execution, def.id) === def.revision && !!entry?.plan && !hasRegex(entry.plan)
+          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 && !!options.execution?.fields[computedFieldName(def.id)]?.group && executionRevision(options.execution, def.id) === def.revision && !!entry?.plan && !hasRegex(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)
         }
       };
     });
@@ -398,7 +1107,7 @@ function useComputedColumns(options) {
     options.serverComputed,
     options.serverExecution
   ]);
-  const save = useCallback(
+  const save = useCallback4(
     async (column, expectedRevision) => {
       compile(column.expression.source, column.id);
       const saved = validateComputedColumn(
@@ -416,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.");
@@ -497,34 +1206,31 @@ function useComputedColumns(options) {
 }
 
 // src/useQueryTable.ts
-import { useCallback as useCallback8, useEffect as useEffect5, useMemo as useMemo7, useRef as useRef5, useState as useState7 } 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 as normalizeQueryState2,
+  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 useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+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",
@@ -584,29 +1290,29 @@ function observeTransport(transport, publish, nextId) {
   });
 }
 function useRequestActivity(source) {
-  const [entries, setEntries] = useState2([]);
-  const sequence = useRef2(0), mounted = useRef2(true);
-  useEffect2(() => {
+  const [entries, setEntries] = useState5([]);
+  const sequence = useRef5(0), mounted = useRef5(true);
+  useEffect5(() => {
     mounted.current = true;
     return () => {
       mounted.current = false;
     };
   }, []);
-  const publish = useCallback2((entry) => {
+  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 = useMemo2(
+  const transport = useMemo4(
     () => source ? observeTransport(source, publish, () => ++sequence.current) : void 0,
     [source, publish]
   );
-  const clear = useCallback2(
+  const clear = useCallback5(
     () => setEntries((previous) => previous.filter((e) => e.status === "pending")),
     []
   );
-  const activity = useMemo2(
+  const activity = useMemo4(
     () => ({ entries, clear }),
     [entries, clear]
   );
@@ -614,7 +1320,7 @@ function useRequestActivity(source) {
 }
 
 // src/useAggregations.ts
-import { useCallback as useCallback3, useEffect as useEffect3, useMemo as useMemo3, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback6, useEffect as useEffect6, useMemo as useMemo5, useRef as useRef6, useState as useState6 } from "react";
 import {
   metricComputationKey,
   metricPlans as metricPlans2,
@@ -624,7 +1330,7 @@ import {
 // src/metricExecution.ts
 import {
   applyAggregations,
-  normalizeQueryState,
+  normalizeQueryState as normalizeQueryState2,
   evaluateMetrics,
   metricPlans,
   hasRegex as hasRegex2,
@@ -642,10 +1348,11 @@ var abort = (signal) => {
 async function localMetrics(rows, query, context, signal) {
   const originalClauses = query.aggregations ?? [];
   const advanced = (query.aggregations ?? []).filter(
-    (c) => isComputedField3(c.field ?? "") || c.groupBy.some(isComputedField3) || c.diagnostics?.length || c.expression !== void 0 || c.expressionY !== void 0 || c.scope !== void 0 || c.distribution || c.sort || c.groupLimit !== void 0
+    (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 || normalizeQueryState(query).aggregations?.length !== originalClauses.length))
+  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 } : {}
     });
@@ -657,12 +1364,14 @@ async function localMetrics(rows, query, context, signal) {
     { ...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 } : {}
   };
@@ -749,15 +1458,16 @@ 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) => c.scope === "shownRows" && (!supportsV2 || needsWorker(c) || !!c.dateGrouping)
   );
   const matching = clauses.filter(
-    (c) => c.scope !== "shownRows" || supportsV2 && !needsWorker(c)
+    (c) => c.scope !== "shownRows" || supportsV2 && !needsWorker(c) && !c.dateGrouping
   );
   const results = [];
   if (shown.length) {
@@ -790,7 +1500,6 @@ async function executeMetrics(query, context, signal) {
     }
     const pageQuery = {
       ...query,
-      where: [],
       orderBy: [],
       limit: Math.max(1, context.shownRows.length),
       offset: 0,
@@ -801,6 +1510,10 @@ async function executeMetrics(query, context, signal) {
     );
   }
   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) {
@@ -859,7 +1572,7 @@ async function executeMetrics(query, context, signal) {
       );
     } else
       throw Error(
-        "All-matching metrics require a complete client dataset or a metric-capable server transport."
+        "Remote all-matching metrics require a metric-capable server transport."
       );
   }
   abort(signal);
@@ -887,17 +1600,18 @@ function loadedPath(row, path) {
 }
 
 // src/useAggregations.ts
-function useAggregations(query, schema, transport, clientRows, debounceMs, nonce, validateQuery, options = {}) {
-  const [results, setResults] = useState3(null);
-  const [loading, setLoading] = useState3(false);
-  const [error, setError] = useState3(null);
-  const latest = useRef3({
+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
+    validateQuery,
+    enabled
   });
   latest.current = {
     query,
@@ -905,11 +1619,13 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
     transport,
     clientRows,
     options,
-    validateQuery
+    validateQuery,
+    enabled
   };
-  const preview = useCallback3(
+  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(
@@ -926,7 +1642,7 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
     []
   );
   const shown = (query.aggregations ?? []).some((c) => c.scope === "shownRows");
-  const localPage = shown && (!transport?.fetchMetrics || transport.metricCapabilities?.version !== 2 || (query.aggregations ?? []).some((clause) => {
+  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(
@@ -936,7 +1652,7 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
       return true;
     }
   }));
-  const key = useMemo3(
+  const key = useMemo5(
     () => JSON.stringify([
       query.where,
       metricComputationKey(query.aggregations ?? []),
@@ -953,10 +1669,13 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
   );
   const dependencyKey = JSON.stringify([
     options.revisions ?? {},
-    options.execution ?? null
+    options.execution ?? null,
+    options.now,
+    options.strictLocalMetrics,
+    options.queryContextKey
   ]);
-  useEffect3(() => {
-    if (!latest.current.query.aggregations?.length) {
+  useEffect6(() => {
+    if (!enabled || !latest.current.query.aggregations?.length) {
       setResults(null);
       setLoading(false);
       setError(null);
@@ -1006,6 +1725,7 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
     debounceMs,
     nonce,
     validateQuery,
+    enabled,
     dependencyKey,
     localPage,
     localPage ? options.shownRows : void 0,
@@ -1017,63 +1737,71 @@ function useAggregations(query, schema, transport, clientRows, debounceMs, nonce
 }
 
 // src/useSelection.ts
-import { useCallback as useCallback4, useMemo as useMemo4, useRef as useRef4, useState as useState4 } 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] = useState4(() => /* @__PURE__ */ new Set());
-  const anchor = useRef4(null);
-  const toggle = useCallback4(
-    (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 = useCallback4((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 = useCallback4((ids) => {
+  const replace = useCallback7((ids) => {
     const next = new Set(ids);
-    anchor.current = null;
-    setSelected(next);
+    setState({ selected: next, range: null });
   }, []);
-  const retain = useCallback4((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 = useCallback4(
+  const pageState = useCallback7(
     (pageIds) => {
       if (pageIds.length === 0) return "none";
       let n = 0;
@@ -1082,11 +1810,10 @@ function useSelection(displayedIds) {
     },
     [selected]
   );
-  const clear = useCallback4(() => {
-    anchor.current = null;
-    setSelected(/* @__PURE__ */ new Set());
+  const clear = useCallback7(() => {
+    setState({ selected: /* @__PURE__ */ new Set(), range: null });
   }, []);
-  return useMemo4(
+  return useMemo6(
     () => ({
       selected,
       isSelected: (id) => selected.has(id),
@@ -1103,27 +1830,29 @@ function useSelection(displayedIds) {
 }
 
 // src/useSelect.ts
-import { useCallback as useCallback5, useMemo as useMemo5 } 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 = useMemo5(() => selectedFields(schema, query), [schema, query]);
-  const visible = useMemo5(() => fields.map((f) => columnFor(query.select, f.name)), [fields, query.select]);
-  const hidden = useMemo5(() => {
+  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 = useCallback5(
-    (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 = useCallback5((field) => writeSelect((c) => c.some((x) => x.field === field) ? c : [...c, { field }]), [writeSelect]);
-  const hide = useCallback5((field) => writeSelect((c) => c.filter((x) => x.field !== field)), [writeSelect]);
-  const move = useCallback5(
+  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;
@@ -1133,11 +1862,11 @@ function useSelect(query, setQuery, schema) {
     }),
     [writeSelect]
   );
-  const setWidth = useCallback5(
-    (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 = useCallback5(() => 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) {
@@ -1146,11 +1875,11 @@ function columnFor(select, name) {
 }
 
 // src/useColumnDrag.ts
-import { useCallback as useCallback6, useMemo as useMemo6, useState as useState5 } from "react";
+import { useCallback as useCallback9, useMemo as useMemo8, useState as useState8 } from "react";
 function useColumnDrag() {
-  const [state, setState] = useState5(null);
-  const [dropRevision, setDropRevision] = useState5(0);
-  const start = useCallback6(
+  const [state, setState] = useState8(null);
+  const [dropRevision, setDropRevision] = useState8(0);
+  const start = useCallback9(
     (field, index, order) => setState({
       source: field,
       overIndex: index,
@@ -1159,7 +1888,7 @@ function useColumnDrag() {
     }),
     []
   );
-  const over = useCallback6(
+  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.
@@ -1177,11 +1906,11 @@ function useColumnDrag() {
     ),
     []
   );
-  const end = useCallback6((committed = false) => {
+  const end = useCallback9((committed = false) => {
     if (committed) setDropRevision((revision) => revision + 1);
     setState(null);
   }, []);
-  const preview = useCallback6(
+  const preview = useCallback9(
     (order) => {
       if (!state || state.order && !state.moved) return order;
       const without = order.filter((n) => n !== state.source);
@@ -1199,7 +1928,7 @@ function useColumnDrag() {
     },
     [state]
   );
-  return useMemo6(
+  return useMemo8(
     () => ({
       source: state?.source ?? null,
       overIndex: state?.overIndex ?? null,
@@ -1215,54 +1944,70 @@ function useColumnDrag() {
 }
 
 // src/useSavedQueries.ts
-import { useCallback as useCallback7, useEffect as useEffect4, useState as useState6 } from "react";
-function useSavedQueries(key, currentQuery, applyQueryState, storage, now) {
-  const [items, setItems] = useState6([]);
-  const [defaultId, setDefaultId] = useState6(null);
-  const [loading, setLoading] = useState6(true);
-  const refresh = useCallback7(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]);
-  useEffect4(() => {
+  }, [key]);
+  useEffect8(() => {
     void refresh();
   }, [refresh]);
-  const save = useCallback7(
+  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 = useCallback7(
+  const load = useCallback10(
     (id) => {
       const found = items.find((q) => q.id === id);
       if (found) applyQueryState(found.query);
     },
     [items, applyQueryState]
   );
-  const setDefault = useCallback7(
+  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 = useCallback7(async () => {
+  const clearDefault = useCallback10(async () => {
     await storage.setDefaultSaved?.(key, null);
     await refresh();
   }, [storage, key, refresh]);
-  const remove = useCallback7(
+  const remove = useCallback10(
     async (id) => {
       if (id === defaultId) await storage.setDefaultSaved?.(key, null);
       await storage.deleteSaved(key, id);
@@ -1270,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 normalizeQueryState2({
+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 ?? [],
@@ -1286,7 +2135,7 @@ function defaultsFor(schema) {
   });
 }
 function cloneWhereTerm(term) {
-  const copy = isOrGroup(term) ? { ...term, any: term.any.map((c) => ({ ...c })) } : { ...term };
+  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;
@@ -1301,10 +2150,13 @@ function cloneQueryState(q) {
     limit: q.limit,
     offset: q.offset
   };
+  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) {
@@ -1353,18 +2205,25 @@ function distinctValuesFromRows(field, rows, search) {
   }
   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);
+  const defaults = defaultsFor(opts.schema, Boolean(opts.itemDetails));
   if (opts.initialQuery)
     return {
-      q: normalizeQueryState2(opts.initialQuery, defaults),
+      q: normalizeQueryState3(opts.initialQuery, defaults),
       fromUrl: false
     };
-  if (opts.syncUrl === true && typeof window !== "undefined") {
-    const token = new URLSearchParams(window.location.search).get("q");
-    if (token)
+  if (opts.syncUrl === true && opts.active !== false && typeof window !== "undefined") {
+    const parameter = queryParameter(opts);
+    if (hasQueryLink(window.location.href, parameter))
       return {
-        q: normalizeQueryState2(decodeQuery(token), defaults),
+        q: defaults,
         fromUrl: true
       };
   }
@@ -1372,85 +2231,241 @@ function resolveInitial(opts) {
 }
 function useQueryTable(opts) {
   const {
-    schema,
+    schema: sourceSchema,
     transport: sourceTransport,
-    clientRows,
+    clientRows: providedRows,
     initialQuery,
-    syncUrl = false,
     debounceMs = 200
   } = opts;
-  const { transport, activity: requestActivity } = useRequestActivity(sourceTransport);
-  const storage = useMemo7(
+  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 now = opts.now ?? Date.now;
-  const nowRef = useRef5(now);
-  const onRefreshRef = useRef5(opts.onRefresh);
-  const defaults = useMemo7(() => defaultsFor(schema), [schema]);
-  const byName = useMemo7(
-    () => new Map(schema.fields.map((f) => [f.name, f])),
-    [schema]
+  const parameter = queryParameter(opts);
+  const linkService = useMemo9(
+    () => createQueryLinkService(sourceSchema.name, storage.snapshots, opts.links),
+    [sourceSchema.name, storage.snapshots, opts.links?.cache, opts.links?.maxUrlBytes]
   );
-  const initRef = useRef5(resolveInitial(opts));
-  const aggIdRef = useRef5(0);
-  const [storedQuery, setQueryState] = useState7(initRef.current.q);
-  const query = useMemo7(
+  const now = opts.now ?? Date.now;
+  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 undoStack = useRef5([cloneQueryState(initRef.current.q)]);
-  const redoStack = useRef5([]);
-  const [rows, setRows] = useState7([]);
-  const [serverComputed, setServerComputed] = useState7(/* @__PURE__ */ new Map());
-  const [committedFields, setCommittedFields] = useState7([]);
-  const [serverExecution, setServerExecution] = useState7();
-  const [total, setTotal] = useState7(null);
-  const [loading, setLoading] = useState7(false);
-  const [error, setError] = useState7(null);
-  const [nonce, setNonce] = useState7(0);
-  const [committedPage, setCommittedPage] = useState7(null);
-  const [committedSource, setCommittedSource] = useState7(null);
-  const [autoRefreshStatus, setAutoRefreshStatus] = useState7(null);
-  useEffect5(() => {
+  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]);
-  useEffect5(() => {
+  useEffect10(() => {
     onRefreshRef.current = opts.onRefresh;
   }, [opts.onRefresh]);
-  const setQuery = useCallback8(
+  const setQuery = useCallback12(
     (next) => {
-      setQueryState((prev) => {
+      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 = normalizeQueryState2(candidate, defaults);
-        if (queriesEqual(prev, nextQuery)) return prev;
-        undoStack.current.push(cloneQueryState(prev));
-        redoStack.current = [];
-        return cloneQueryState(nextQuery);
+        const nextQuery = normalizeQueryState3(candidate, defaults);
+        if (queriesEqual2(prev, nextQuery)) return history;
+        return { query: cloneQueryState(nextQuery), past: [...history.past, cloneQueryState(prev)], future: [] };
       });
     },
-    [defaults]
-  );
-  useEffect5(() => {
-    if (initRef.current.fromUrl || initialQuery) return;
+    [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;
+    });
+  }, [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 = normalizeQueryState2(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 } : {},
@@ -1460,11 +2475,11 @@ function useQueryTable(opts) {
     ...transport ? { transport } : {},
     ...clientRows ? { clientRows } : {}
   });
-  const resolveComputed = useCallback8(
+  const resolveComputed = useCallback12(
     (name) => isComputedField4(name) ? computed.compile(`[${name.replace(/]/g, "]] ".trim())}]`) : void 0,
     [computed.compile]
   );
-  const metricCompile = useCallback8(
+  const metricCompile = useCallback12(
     (clause) => {
       const diagnostics = validateMetric2(
         clause,
@@ -1477,19 +2492,29 @@ function useQueryTable(opts) {
     },
     [displaySchema, resolveComputed]
   );
-  const computedRevisions = useMemo7(
+  const computedRevisions = useMemo9(
     () => Object.fromEntries(computed.definitions.map((d) => [d.id, d.revision])),
     [computed.definitions]
   );
   const definitionKey = JSON.stringify(computedRevisions);
-  const queryKey = useMemo7(() => encodeQuery(query), [query]);
-  const serverRowQuery = useMemo7(() => {
+  const queryKey = useMemo9(() => JSON.stringify(query), [query]);
+  const serverRowQuery = useMemo9(() => {
     const execution = opts.computedExecution;
-    const v2Request = execution && transport?.fetchRowsV2 ? toServerQueryV2(query, displaySchema, execution) : void 0;
-    const request = v2Request ?? toServerQuery2(query, displaySchema);
+    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 (executionRevision(execution, definition.id) !== void 0 && executionRevision(execution, definition.id) !== definition.revision)
+        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,
@@ -1523,13 +2548,26 @@ function useQueryTable(opts) {
     computedRevisions,
     schema,
     resolveComputed,
-    opts.computedExecution
+    opts.computedExecution,
+    opts.itemDetails,
+    defaults
   ]);
-  const rowQueryKey = useMemo7(
-    () => transport ? `server:${JSON.stringify(serverRowQuery)}` : `client:${JSON.stringify([query.where, query.orderBy, query.limit, query.offset])}`,
+  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,
@@ -1538,15 +2576,50 @@ function useQueryTable(opts) {
   );
   const executionKey = JSON.stringify(opts.computedExecution ?? null);
   const pageContext = `${schema.name}:${rowQueryKey}:${nonce}:${executionKey}`;
-  useEffect5(() => {
+  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) {
+          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(
@@ -1582,7 +2655,12 @@ function useQueryTable(opts) {
             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);
@@ -1614,58 +2692,107 @@ function useQueryTable(opts) {
     schema,
     debounceMs,
     nonce,
-    opts.validateQuery,
-    executionKey
+    validateExecution,
+    executionKey,
+    groupingNow,
+    restoration,
+    active,
+    storageReady
   ]);
-  useEffect5(() => {
-    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]);
-  useEffect5(() => {
-    const t = setTimeout(() => void storage.saveLast(schema.name, query), 400);
+  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 = useMemo7(
+  }, [queryKey, storage, sourceSchema.name, query, restoration, storageReady]);
+  const idField = useMemo9(
     () => schema.fields.find((f) => f.name === schema.idField),
     [schema]
   );
-  const rowId = useCallback8(
-    (row) => idField ? readFieldValue4(idField, row) : null,
-    [idField]
+  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 = useMemo7(
+  const displayedIds = useMemo9(
     () => 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
-  );
+    now,
+    links.snapshot
+  );
+  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 = useRef5(0);
-  const dataVersion = useMemo7(
+  const dataToken = useRef9(0);
+  const dataVersion = useMemo9(
     () => ++dataToken.current,
     [schema, transport, clientRows, nonce, definitionKey, executionKey]
   );
+  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(
-    query,
+    executionQuery,
     schema,
     transport,
     clientRows,
     debounceMs,
     nonce,
-    opts.validateQuery,
+    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,
@@ -1676,11 +2803,12 @@ function useQueryTable(opts) {
         execution: pageReady && serverExecution ? serverExecution : opts.computedExecution
       } : {},
       ...opts.formulaWorkerFactory ? { workerFactory: opts.formulaWorkerFactory } : {}
-    }
+    },
+    active && storageReady && !restoration.loading && !restoration.error
   );
-  const queryRef = useRef5(query);
+  const queryRef = useRef9(query);
   queryRef.current = query;
-  const replaceAggregations = useCallback8(
+  const replaceAggregations = useCallback12(
     (clauses, expected) => {
       if (expected && JSON.stringify(queryRef.current.aggregations ?? []) !== JSON.stringify(expected))
         throw new Error(
@@ -1696,141 +2824,46 @@ function useQueryTable(opts) {
     },
     [setQuery, metricCompile]
   );
-  const canUndo = undoStack.current.length > 0;
-  const canRedo = redoStack.current.length > 0;
-  const undo = useCallback8(() => {
-    setQueryState((prev) => {
-      const previous = undoStack.current.pop();
-      if (!previous) return prev;
-      redoStack.current.push(cloneQueryState(prev));
-      return cloneQueryState(previous);
+  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)] };
     });
-  }, []);
-  const redo = useCallback8(() => {
-    setQueryState((prev) => {
-      const next = redoStack.current.pop();
-      if (!next) return prev;
-      undoStack.current.push(cloneQueryState(prev));
-      return cloneQueryState(next);
+  }, [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) };
     });
-  }, []);
-  const patch = useCallback8(
+  }, [updateQueryHistory]);
+  const patch = useCallback12(
     (p) => setQuery((prev) => ({ ...prev, ...p })),
     [setQuery]
   );
-  const addFilter = useCallback8(
-    (clause) => setQuery((q) => ({ ...q, offset: 0, where: [...q.where, clause] })),
-    [setQuery]
-  );
-  const updateFilter = useCallback8(
-    (index, clause) => setQuery((q) => ({
-      ...q,
-      offset: 0,
-      where: q.where.map((t, i) => i === index ? clause : t)
-    })),
-    [setQuery]
-  );
-  const removeFilter = useCallback8(
-    (index) => setQuery((q) => ({
-      ...q,
-      offset: 0,
-      where: q.where.filter((_, i) => i !== index)
-    })),
-    [setQuery]
-  );
-  const clearFilters = useCallback8(
-    () => setQuery((q) => ({ ...q, offset: 0, where: [] })),
-    [setQuery]
-  );
-  const updatePredicate = useCallback8(
-    (termIndex, predIndex, clause) => setQuery((q) => ({
-      ...q,
-      offset: 0,
-      where: q.where.map((term, i) => {
-        if (i !== termIndex) return term;
-        if (isOrGroup(term))
-          return {
-            any: term.any.map((c, j) => j === predIndex ? clause : c)
-          };
-        return clause;
-      })
-    })),
-    [setQuery]
-  );
-  const removePredicate = useCallback8(
-    (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 = useCallback8(
-    (clause) => {
-      const field = byName.get(clause.field);
-      return negateClause(clause, field ? opsForField(field) : void 0);
+  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));
     },
-    [byName]
+    [setQuery, defaults, sourceSchema.name]
   );
-  const negatePredicate = useCallback8(
-    (termIndex, predIndex) => setQuery((q) => ({
-      ...q,
-      offset: 0,
-      where: q.where.map((term, i) => {
-        if (i !== termIndex) return term;
-        if (isOrGroup(term))
-          return {
-            any: term.any.map((c, j) => j === predIndex ? negateOne(c) : c)
-          };
-        return negateOne(term);
-      })
-    })),
-    [setQuery, negateOne]
-  );
-  const reorderFilters = useCallback8(
-    (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 = useCallback8(
-    (sourceIndex, targetIndex) => setQuery((q) => {
-      if (sourceIndex === targetIndex) return q;
-      const source = q.where[sourceIndex];
-      const target = q.where[targetIndex];
-      if (!source || !target) return q;
-      const merged = {
-        any: [...predicatesOf(target), ...predicatesOf(source)]
-      };
-      const where = [];
-      q.where.forEach((term, i) => {
-        if (i === sourceIndex) return;
-        where.push(i === targetIndex ? merged : term);
-      });
-      return { ...q, offset: 0, where };
-    }),
-    [setQuery]
-  );
-  const resetAll = useCallback8(
-    () => setQuery(() => cloneQueryState(defaults)),
-    [setQuery, defaults]
-  );
-  const addAggregation = useCallback8(
+  const addAggregation = useCallback12(
     (partial) => {
       const id = `a${nowRef.current()}-${aggIdRef.current++}`;
       const clause = {
@@ -1847,7 +2880,7 @@ function useQueryTable(opts) {
     },
     [setQuery]
   );
-  const updateAggregation = useCallback8(
+  const updateAggregation = useCallback12(
     (id, patch2) => setQuery((q) => ({
       ...q,
       aggregations: (q.aggregations ?? []).map(
@@ -1856,7 +2889,7 @@ function useQueryTable(opts) {
     })),
     [setQuery]
   );
-  const moveAggregation = useCallback8(
+  const moveAggregation = useCallback12(
     (id, toIndex) => setQuery((q) => {
       const current = q.aggregations ?? [];
       const from = current.findIndex((a) => a.id === id);
@@ -1868,22 +2901,22 @@ function useQueryTable(opts) {
     }),
     [setQuery]
   );
-  const removeAggregation = useCallback8(
+  const removeAggregation = useCallback12(
     (id) => setQuery((q) => ({
       ...q,
       aggregations: (q.aggregations ?? []).filter((a) => a.id !== id)
     })),
     [setQuery]
   );
-  const clearAggregations = useCallback8(
+  const clearAggregations = useCallback12(
     () => setQuery((q) => ({ ...q, aggregations: [] })),
     [setQuery]
   );
-  const setSort = useCallback8(
+  const setSort = useCallback12(
     (orderBy) => setQuery((q) => ({ ...q, offset: 0, orderBy })),
     [setQuery]
   );
-  const toggleSort = useCallback8(
+  const toggleSort = useCallback12(
     (field, additive = false) => setQuery((q) => ({
       ...q,
       offset: 0,
@@ -1891,22 +2924,22 @@ function useQueryTable(opts) {
     })),
     [setQuery]
   );
-  const setLimit = useCallback8(
+  const setLimit = useCallback12(
     (limit) => patch({ limit, offset: 0 }),
     [patch]
   );
-  const setOffset = useCallback8((offset) => patch({ offset }), [patch]);
-  const nextPage = useCallback8(
+  const setOffset = useCallback12((offset) => patch({ offset }), [patch]);
+  const nextPage = useCallback12(
     () => setQuery((q) => ({ ...q, offset: q.offset + q.limit })),
     [setQuery]
   );
-  const prevPage = useCallback8(
+  const prevPage = useCallback12(
     () => setQuery((q) => ({ ...q, offset: Math.max(0, q.offset - q.limit) })),
     [setQuery]
   );
-  const filterValues = useCallback8(
+  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);
@@ -1917,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 = useCallback8(
+  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 = {};
@@ -1945,14 +2978,14 @@ function useQueryTable(opts) {
       }
       return result;
     },
-    [transport, byName, clientRows]
+    [metadataTransport, byName, clientRows, groupKey]
   );
-  const refresh = useCallback8(() => {
+  const refresh = useCallback12(() => {
     setNonce((n) => n + 1);
     onRefreshRef.current?.();
   }, []);
-  const stopAutoRefresh = useCallback8(() => setAutoRefreshStatus(null), []);
-  const startAutoRefresh = useCallback8(
+  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) {
@@ -1972,7 +3005,7 @@ function useQueryTable(opts) {
   );
   const autoRefreshFrequencyMs = autoRefreshStatus?.frequencyMs ?? null;
   const autoRefreshStopsAt = autoRefreshStatus?.stopsAt ?? null;
-  useEffect5(() => {
+  useEffect10(() => {
     if (autoRefreshFrequencyMs == null || autoRefreshStopsAt == null) return;
     const tick = () => {
       if (nowRef.current() >= autoRefreshStopsAt) {
@@ -2000,7 +3033,7 @@ function useQueryTable(opts) {
       clearTimeout(timeout);
     };
   }, [autoRefreshFrequencyMs, autoRefreshStopsAt, refresh]);
-  const autoRefresh = useMemo7(
+  const autoRefresh = useMemo9(
     () => ({
       status: autoRefreshStatus,
       start: startAutoRefresh,
@@ -2008,7 +3041,7 @@ function useQueryTable(opts) {
     }),
     [autoRefreshStatus, startAutoRefresh, stopAutoRefresh]
   );
-  const refreshRow = useCallback8(
+  const refreshRow = useCallback12(
     async (id) => {
       if (opts.computedExecution && transport?.fetchRowsV2) {
         refresh();
@@ -2022,11 +3055,11 @@ function useQueryTable(opts) {
     },
     [transport, rowId, opts.computedExecution, refresh]
   );
-  const visibleFields = useMemo7(
-    () => selectedFields2(displaySchema, query),
-    [displaySchema, query]
+  const visibleFields = useMemo9(
+    () => selectedFields2(columnSchema, query),
+    [columnSchema, query]
   );
-  const aggregations = useMemo7(
+  const aggregations = useMemo9(
     () => ({
       clauses: query.aggregations ?? [],
       results: aggState.results,
@@ -2061,14 +3094,42 @@ function useQueryTable(opts) {
       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,
@@ -2104,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);
@@ -2123,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,