@pythia-software/query-table-core 0.6.0 → 0.7.1

package/dist/index.js

@@ -1,13 +1,438 @@
+// src/cellDisplay.ts
+var calendarOptions = {
+  style: ["human", "iso", "custom"],
+  pattern: "string",
+  timeZone: "string",
+  locale: "string"
+};
+var numberOptions = { decimals: [0, 20], locale: "string" };
+var calendarUnits = ["iso", "epochSeconds", "epochMilliseconds"];
+var options = {
+  json: { encoding: ["auto", "value", "json", "escaped"], maxDecodeDepth: [1, 8], previewLength: [20, 500], expandDepth: [0, 8] },
+  date: { ...calendarOptions, sourceUnit: calendarUnits },
+  datetime: { ...calendarOptions, sourceUnit: calendarUnits },
+  time: { ...calendarOptions, sourceUnit: [...calendarUnits, "secondsOfDay", "millisecondsOfDay"] },
+  duration: { sourceUnit: ["milliseconds", "seconds", "minutes", "hours", "days"], style: ["human", "long", "clock", "custom"], pattern: "string", decimals: [0, 20] },
+  number: numberOptions,
+  percent: numberOptions,
+  chip: { labels: "labels", tones: "tones" },
+  text: { truncate: "boolean" }
+};
+function parseCellDisplay(raw, context = "cell display") {
+  const fail = (reason) => {
+    throw Error(`${context}: ${reason}`);
+  };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail("expected an object");
+  const record2 = raw;
+  if (typeof record2.kind !== "string" || !Object.prototype.hasOwnProperty.call(options, record2.kind)) return fail("unsupported kind");
+  const allowed = options[record2.kind];
+  for (const [key, value] of Object.entries(record2)) {
+    if (key === "kind") continue;
+    const rule = Object.prototype.hasOwnProperty.call(allowed, key) ? allowed[key] : void 0;
+    if (!rule) return fail(`unsupported option ${key}`);
+    if (Array.isArray(rule)) {
+      if (typeof rule[0] === "number") {
+        if (typeof value !== "number" || !Number.isInteger(value) || value < Number(rule[0]) || value > Number(rule[1])) return fail(`${key} must be an integer from ${rule[0]} to ${rule[1]}`);
+      } else if (!rule.includes(value)) return fail(`unsupported ${key}`);
+    } else if (rule === "labels" || rule === "tones") {
+      if (!value || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((item) => typeof item === "string" && (rule === "labels" || ["neutral", "success", "warning", "danger"].includes(item)))) return fail(`invalid ${key} map`);
+    } else if (typeof value !== rule) return fail(`${key} must be ${rule}`);
+    if (key === "pattern" && value.length > 160) return fail("pattern must be at most 160 characters");
+  }
+  return {
+    ...record2,
+    ...record2.labels ? { labels: { ...record2.labels } } : {},
+    ...record2.tones ? { tones: { ...record2.tones } } : {}
+  };
+}
+
+// src/properties.ts
+var MAX_PROPERTIES = 200;
+var string = (value, max = 256) => typeof value === "string" && value.length > 0 && value.length <= max;
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function normalizePropertyFormat(input) {
+  if (!record(input)) return;
+  const kind = input.kind;
+  if (kind === "json" || kind === "chip") {
+    try {
+      return parseCellDisplay(input);
+    } catch {
+      return;
+    }
+  }
+  if (input.decimals !== void 0 && !(typeof input.decimals === "number" && Number.isInteger(input.decimals) && input.decimals >= 0 && input.decimals <= 20))
+    return;
+  if (["text", "code", "boolean", "chips"].includes(String(kind)))
+    return { kind };
+  if (kind === "relative") {
+    if (input.sourceUnit !== void 0 && !["iso", "epochSeconds", "epochMilliseconds"].includes(
+      String(input.sourceUnit)
+    ))
+      return;
+    return {
+      kind,
+      ...input.sourceUnit ? { sourceUnit: input.sourceUnit } : {}
+    };
+  }
+  if (kind === "currency") {
+    if (typeof input.currency !== "string" || !/^[A-Z]{3}$/.test(input.currency))
+      return;
+    return {
+      kind,
+      currency: input.currency,
+      ...typeof input.decimals === "number" && Number.isInteger(input.decimals) && input.decimals >= 0 && input.decimals <= 20 ? { decimals: input.decimals } : {}
+    };
+  }
+  if (!["number", "percent", "duration", "date", "time", "datetime"].includes(
+    String(kind)
+  ))
+    return;
+  if (input.sourceUnit !== void 0 && ![
+    "milliseconds",
+    "seconds",
+    "minutes",
+    "hours",
+    "days",
+    "iso",
+    "epochSeconds",
+    "epochMilliseconds",
+    "secondsOfDay",
+    "millisecondsOfDay"
+  ].includes(String(input.sourceUnit)))
+    return;
+  if (input.style !== void 0 && !["human", "long", "clock", "custom", "iso"].includes(String(input.style)))
+    return;
+  if (input.pattern !== void 0 && !string(input.pattern, 1e3)) return;
+  if (input.timeZone !== void 0 && !string(input.timeZone)) return;
+  const out = { kind };
+  if (typeof input.decimals === "number" && Number.isInteger(input.decimals) && input.decimals >= 0 && input.decimals <= 20)
+    out.decimals = input.decimals;
+  if ([
+    "milliseconds",
+    "seconds",
+    "minutes",
+    "hours",
+    "days",
+    "iso",
+    "epochSeconds",
+    "epochMilliseconds",
+    "secondsOfDay",
+    "millisecondsOfDay"
+  ].includes(String(input.sourceUnit)))
+    out.sourceUnit = input.sourceUnit;
+  if (["human", "long", "clock", "custom", "iso"].includes(String(input.style)))
+    out.style = input.style;
+  if (string(input.pattern, 1e3)) out.pattern = input.pattern;
+  if (string(input.timeZone)) out.timeZone = input.timeZone;
+  return out;
+}
+function normalizePropertyView(input) {
+  if (!record(input) || input.version !== 1 || !Array.isArray(input.properties))
+    throw new Error(
+      "Unsupported or invalid property view (expected version 1)."
+    );
+  if (input.properties.length > MAX_PROPERTIES)
+    throw new Error(`At most ${MAX_PROPERTIES} properties are allowed.`);
+  const ids = /* @__PURE__ */ new Set();
+  const properties = input.properties.map((item) => {
+    if (!record(item) || !string(item.id) || !string(item.field) || ids.has(item.id))
+      throw new Error("Property fields and unique instance IDs are required.");
+    ids.add(item.id);
+    const property = { id: item.id, field: item.field };
+    if (string(item.label, 1e3)) property.label = item.label;
+    if (string(item.render)) property.render = item.render;
+    if (item.format !== void 0) {
+      const format = normalizePropertyFormat(item.format);
+      if (!format) throw new Error(`Invalid format for property ${item.id}.`);
+      property.format = format;
+    }
+    return property;
+  });
+  const labelWidth = typeof input.labelWidth === "number" && Number.isFinite(input.labelWidth) ? Math.max(15, Math.min(75, Math.round(input.labelWidth))) : void 0;
+  return { version: 1, properties, ...labelWidth !== void 0 ? { labelWidth } : {} };
+}
+function createPropertyView(schema, names) {
+  const enabled = schema.fields.filter((f2) => f2.property?.enabled !== false);
+  const hasPropertyDefaults = enabled.some(
+    (f2) => f2.property?.default !== void 0
+  );
+  const defaults = hasPropertyDefaults ? enabled.filter((f2) => f2.property?.default).map((f2) => f2.name) : schema.defaultSelect?.map((column) => column.field) ?? enabled.filter((f2) => f2.select?.default).map((f2) => f2.name);
+  const fields = names ?? (hasPropertyDefaults || defaults.length ? defaults.filter((name) => enabled.some((field) => field.name === name)) : enabled.map((f2) => f2.name));
+  return normalizePropertyView({
+    version: 1,
+    properties: fields.map((field, i) => ({ id: `property-${i}`, field }))
+  });
+}
+function objectReferenceKey(reference) {
+  return JSON.stringify([
+    reference.objectType,
+    Object.entries(reference.key).sort(([a], [b]) => a.localeCompare(b))
+  ]);
+}
+function readObjectReference(field, fields, row) {
+  const relationship = field.relationship;
+  if (!relationship) return null;
+  const key = /* @__PURE__ */ Object.create(null);
+  for (const [target, local] of Object.entries(relationship.key)) {
+    const source = fields.find((f2) => f2.name === local);
+    if (!source) return null;
+    const value = readFieldValue(source, row);
+    if (!(typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value)))
+      return null;
+    key[target] = value;
+  }
+  return Object.keys(key).length ? { objectType: relationship.objectType, key } : null;
+}
+function discoverFieldRelationships(fields, keys, types) {
+  return fields.map((field) => {
+    if (field.relationship || !field.origin) return field;
+    const candidates = [];
+    for (const fk of keys) {
+      if (fk.sourceTable !== field.origin.table || !fk.sourceColumns.includes(field.origin.column) || fk.sourceColumns.length === 0 || fk.sourceColumns.length !== fk.targetColumns.length)
+        continue;
+      const targets = types.filter(
+        (type) => type.table === fk.targetTable && type.keyFields.length === fk.targetColumns.length && type.keyFields.every((k) => fk.targetColumns.includes(k))
+      );
+      if (targets.length !== 1) continue;
+      const key = /* @__PURE__ */ Object.create(null);
+      let complete = true;
+      fk.sourceColumns.forEach((column, i) => {
+        const local = fields.filter(
+          (f2) => f2.origin?.table === fk.sourceTable && f2.origin.column === column
+        );
+        if (local.length !== 1) complete = false;
+        else key[fk.targetColumns[i]] = local[0].name;
+      });
+      if (complete) candidates.push({ objectType: targets[0].name, key });
+    }
+    return candidates.length === 1 ? { ...field, relationship: candidates[0] } : field;
+  });
+}
+
+// src/schema.ts
+function isFilterable(f2) {
+  if (f2.source.kind === "derived" && f2.source.computedId) return false;
+  return f2.filter?.enabled ?? f2.source.kind === "backend";
+}
+function isPushdownFilter(f2) {
+  return isFilterable(f2) && (f2.filter?.pushdown ?? f2.source.kind === "backend");
+}
+function isSortable(f2) {
+  if (f2.source.kind === "derived" && f2.source.computedId) return f2.sort?.enabled === true;
+  return f2.sort?.enabled ?? f2.source.kind === "backend";
+}
+function isSelectable(f2) {
+  return f2.select?.enabled ?? true;
+}
+function filterValues(f2) {
+  return f2.filter?.values ?? { source: "autocomplete" };
+}
+function indexFields(schema) {
+  return new Map(schema.fields.map((f2) => [f2.name, f2]));
+}
+function selectedFields(schema, q) {
+  const order = q.select.length > 0 ? q.select.map((c) => c.field) : (schema.defaultSelect ?? schema.fields.filter((f2) => f2.select?.default).map((f2) => ({ field: f2.name }))).map(
+    (c) => c.field
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const name of order) {
+    if (seen.has(name)) continue;
+    const f2 = resolveField(schema, name);
+    if (!f2 || !isSelectable(f2)) continue;
+    seen.add(name);
+    seen.add(f2.name);
+    out.push(f2);
+  }
+  return out;
+}
+function resolveField(schema, field) {
+  const token = field.trim();
+  if (!token) return void 0;
+  const byName = indexFields(schema);
+  const byExactName = byName.get(token);
+  if (byExactName) return byExactName;
+  const needle = token.toLowerCase();
+  for (const f2 of schema.fields) {
+    if (f2.name.toLowerCase() === needle) return f2;
+    if (aliasMatches(f2, needle)) return f2;
+  }
+  return void 0;
+}
+function resolveFieldName(schema, field) {
+  return resolveField(schema, field)?.name;
+}
+function aliasTermsFor(field) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (raw) => {
+    if (typeof raw !== "string") return;
+    const value = raw.trim();
+    if (!value) return;
+    const key = value.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(value);
+  };
+  add(field.alias);
+  if (field.aliases) {
+    for (const alias of field.aliases) add(alias);
+  }
+  return out;
+}
+function aliasMatches(field, needle) {
+  for (const alias of aliasTermsFor(field)) {
+    if (alias.toLowerCase() === needle) return true;
+  }
+  return false;
+}
+function readFieldValue(field, row) {
+  if (row == null) return null;
+  if (field.source.kind === "derived" && field.source.accessor) {
+    return field.source.accessor(row);
+  }
+  const path = field.source.kind === "backend" && field.source.path || field.name;
+  const r = row;
+  if (path in r) return r[path] ?? null;
+  let cur = row;
+  for (const part of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return null;
+    cur = cur[part];
+  }
+  return cur ?? null;
+}
+function loadSchema(doc) {
+  const d = doc;
+  if (!d || typeof d !== "object") throw new Error("schema: document is not an object");
+  if (typeof d.name !== "string") throw new Error("schema: missing `name`");
+  if (typeof d.idField !== "string") throw new Error("schema: missing `idField`");
+  if (!Array.isArray(d.fields) || d.fields.length === 0) throw new Error("schema: `fields` must be a non-empty array");
+  const fields = d.fields.map((raw, i) => projectField(raw, i));
+  return {
+    name: d.name,
+    idField: d.idField,
+    fields,
+    defaultSort: d.defaultSort,
+    defaultSelect: d.defaultSelect,
+    defaultLimit: d.defaultLimit
+  };
+}
+function projectField(raw, i) {
+  if (!raw || typeof raw.name !== "string") throw new Error(`schema: field[${i}] missing \`name\``);
+  if (typeof raw.label !== "string") throw new Error(`schema: field ${raw.name} missing \`label\``);
+  if (typeof raw.type !== "string") throw new Error(`schema: field ${raw.name} missing \`type\``);
+  if (raw.property !== void 0) {
+    const property = raw.property;
+    if (!property || typeof property !== "object" || Array.isArray(property) || property.enabled !== void 0 && typeof property.enabled !== "boolean" || property.default !== void 0 && typeof property.default !== "boolean" || property.render !== void 0 && (typeof property.render !== "string" || !property.render)) {
+      throw new Error(`schema: field ${raw.name} has invalid property metadata`);
+    }
+    if (property.format !== void 0 && !normalizePropertyFormat(property.format)) {
+      throw new Error(`schema: field ${raw.name} has an invalid property format`);
+    }
+  }
+  if (raw.origin !== void 0 && (!raw.origin || typeof raw.origin.table !== "string" || !raw.origin.table || typeof raw.origin.column !== "string" || !raw.origin.column)) {
+    throw new Error(`schema: field ${raw.name} has an invalid origin`);
+  }
+  if (raw.relationship !== void 0 && (!raw.relationship || typeof raw.relationship.objectType !== "string" || !raw.relationship.objectType || !raw.relationship.key || typeof raw.relationship.key !== "object" || Array.isArray(raw.relationship.key) || Object.keys(raw.relationship.key).length === 0 || Object.entries(raw.relationship.key).some(([key, value]) => !key || typeof value !== "string" || !value))) {
+    throw new Error(`schema: field ${raw.name} has an invalid relationship`);
+  }
+  const rs = raw.source ?? (raw.bindings ? "backend" : "derived");
+  let source;
+  if (typeof rs === "string") {
+    source = rs === "derived" ? { kind: "derived" } : { kind: "backend" };
+  } else if (rs.kind === "derived") {
+    source = { kind: "derived" };
+  } else {
+    source = { kind: "backend", path: rs.path, synthetic: rs.synthetic };
+  }
+  return {
+    name: raw.name,
+    label: raw.label,
+    type: raw.type,
+    source,
+    filter: raw.filter,
+    sort: raw.sort,
+    select: raw.select,
+    aggregate: raw.aggregate,
+    group: raw.group,
+    alias: raw.alias,
+    aliases: normalizeAliases(raw.aliases, raw.alias),
+    ...raw.display === void 0 ? {} : { display: parseCellDisplay(raw.display, `schema: field ${raw.name} display`) },
+    render: raw.render,
+    // string key from JSON; consumer may override with a fn
+    property: raw.property ? { ...raw.property, format: raw.property.format === void 0 ? void 0 : normalizePropertyFormat(raw.property.format) } : void 0,
+    origin: raw.origin,
+    relationship: raw.relationship
+  };
+}
+function normalizeAliases(rawAliases, rawAlias) {
+  const aliases = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (raw) => {
+    if (typeof raw !== "string") return;
+    const value = raw.trim();
+    if (!value) return;
+    const key = value.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    aliases.push(value);
+  };
+  add(rawAlias);
+  if (Array.isArray(rawAliases)) {
+    for (const item of rawAliases) add(item);
+  }
+  return aliases;
+}
+
+// src/itemPage.ts
+function itemPageFields(template) {
+  return [...new Set(Array.from(template.matchAll(/\{field:([^{}]+)\}/g), (match) => match[1]))];
+}
+function validateItemPageTemplate(template, schema) {
+  if (template.length > 8e3) return "Use a URL template of at most 8,000 characters.";
+  if (!template.trim()) return null;
+  const remainder = template.replace(/\{(id|query|field:[^{}]+)\}/g, "value");
+  if (/[{}]/.test(remainder)) return "Use {id}, {query}, or {field:field_name} placeholders.";
+  for (const name of itemPageFields(template)) {
+    if (!schema.fields.some((field) => field.name === name)) return `Unknown URL field: ${name}.`;
+  }
+  try {
+    if (!["http:", "https:"].includes(new URL(remainder, "https://query-table.invalid/").protocol))
+      return "Use an HTTP, HTTPS, or relative page URL.";
+  } catch {
+    return "Enter a valid page URL.";
+  }
+  return null;
+}
+function renderItemPageTemplate(template, schema, row, id, query) {
+  if (!template.trim() || validateItemPageTemplate(template, schema)) return null;
+  let missing = false;
+  const href = template.replace(/\{(id|query|field:[^{}]+)\}/g, (_match, token) => {
+    const value = token === "id" ? id : token === "query" ? query : readFieldValue(schema.fields.find((field) => field.name === token.slice(6)), row);
+    if (value == null || !["string", "number", "boolean"].includes(typeof value)) {
+      missing = true;
+      return "";
+    }
+    return encodeURIComponent(String(value));
+  });
+  try {
+    if (missing || !["http:", "https:"].includes(new URL(href, "https://query-table.invalid/").protocol)) return null;
+  } catch {
+    return null;
+  }
+  return href;
+}
+
 // src/metricNormalize.ts
 function normalizeMetricOptions(raw) {
   const out = {}, diagnostics = [];
-  const record = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+  const record2 = (x) => !!x && typeof x === "object" && !Array.isArray(x);
   const copy = (input, specs) => {
     const result = {};
     for (const [key, spec] of Object.entries(specs)) {
       const v = input[key];
       if (v === void 0) continue;
-      if (spec === "string" ? typeof v === "string" && v.length <= 1e4 : spec === "number" ? typeof v === "number" && Number.isFinite(v) : spec === "boolean" ? typeof v === "boolean" : spec === "integer" ? typeof v === "number" && Number.isSafeInteger(v) && v >= 0 && v <= 1e6 : typeof v === "string" && spec.includes(v))
+      if (spec === "string" ? typeof v === "string" && v.length <= 1e4 : spec === "number" ? typeof v === "number" && Number.isFinite(v) : spec === "boolean" ? typeof v === "boolean" : spec === "integer" || spec === "positiveInteger" ? typeof v === "number" && Number.isSafeInteger(v) && v >= (spec === "positiveInteger" ? 1 : 0) && v <= 1e6 : typeof v === "string" && spec.includes(v))
         result[key] = v;
       else diagnostics.push(`Invalid metric ${key}.`);
     }
@@ -22,8 +447,24 @@ function normalizeMetricOptions(raw) {
       groupLimit: "integer"
     })
   );
+  if (raw.dateGrouping !== void 0) {
+    if (record2(raw.dateGrouping)) {
+      const d = copy(raw.dateGrouping, {
+        field: "string",
+        interval: ["hour", "day", "week", "month", "year"],
+        timeZone: "string",
+        includeEmpty: "boolean",
+        range: ["query", "observed", "custom"],
+        start: "string",
+        end: "string"
+      });
+      if (typeof d.field !== "string" || !d.field || d.field.length > 256 || !d.interval || typeof d.includeEmpty !== "boolean" || !d.range)
+        diagnostics.push("Invalid metric date grouping.");
+      out.dateGrouping = d;
+    } else diagnostics.push("Invalid metric date grouping.");
+  }
   if (raw.display !== void 0) {
-    if (record(raw.display)) {
+    if (record2(raw.display)) {
       if (typeof raw.display.kind !== "string")
         diagnostics.push("Invalid metric display kind.");
       const d = copy(raw.display, {
@@ -45,10 +486,12 @@ function normalizeMetricOptions(raw) {
         xLabel: "string",
         yLabel: "string",
         legendPosition: ["left", "right", "top", "bottom", "none"],
+        maxGroups: "positiveInteger",
+        showOther: "boolean",
         boxMean: "boolean"
       });
       for (const k of ["xScale", "yScale"]) {
-        if (record(raw.display[k]))
+        if (record2(raw.display[k]))
           d[k] = copy(raw.display[k], {
             mode: ["linear", "log"],
             min: "number",
@@ -58,228 +501,88 @@ function normalizeMetricOptions(raw) {
           diagnostics.push(`Invalid metric ${k}.`);
       }
       for (const k of ["format", "xFormat", "yFormat"])
-        if (record(raw.display[k]))
+        if (record2(raw.display[k]))
           d[k] = copy(raw.display[k], {
             kind: ["number", "percent", "duration", "date", "time", "datetime"],
             decimals: "integer",
-            sourceUnit: [
-              "milliseconds",
-              "seconds",
-              "minutes",
-              "hours",
-              "days",
-              "iso",
-              "epochSeconds",
-              "epochMilliseconds",
-              "secondsOfDay",
-              "millisecondsOfDay"
-            ],
-            style: ["human", "long", "clock", "custom", "iso"],
-            pattern: "string",
-            timeZone: "string"
-          });
-      if (record(raw.display.list))
-        d.list = copy(raw.display.list, {
-          showBars: "boolean",
-          useGroupColors: "boolean",
-          showValues: "boolean"
-        });
-      if (record(raw.display.pivot))
-        d.pivot = copy(raw.display.pivot, {
-          swap: "boolean",
-          rowDir: ["asc", "desc"],
-          columnDir: ["asc", "desc"]
-        });
-      out.display = { kind: "auto", ...d };
-    } else diagnostics.push("Invalid metric display.");
-  }
-  if (raw.distribution !== void 0) {
-    if (record(raw.distribution))
-      out.distribution = copy(raw.distribution, {
-        kind: ["box", "histogram"],
-        input: "string",
-        whiskers: ["minmax", "tukey"],
-        bins: "integer"
-      });
-    else diagnostics.push("Invalid metric distribution.");
-  }
-  if (record(raw.layout)) {
-    const l = copy(raw.layout, {
-      widthRem: "integer",
-      heightRem: "integer",
-      minWidthRem: "integer",
-      minHeightRem: "integer"
-    });
-    for (const k of ["widthRem", "heightRem", "minWidthRem", "minHeightRem"])
-      l[k] = Math.max(1, Math.min(1e3, Number(l[k] ?? 1)));
-    l.widthRem = Math.max(Number(l.widthRem), Number(l.minWidthRem));
-    l.heightRem = Math.max(Number(l.heightRem), Number(l.minHeightRem));
-    out.layout = l;
-  }
-  if (raw.sort !== void 0 && !Array.isArray(raw.sort))
-    diagnostics.push("Invalid metric sort.");
-  if (Array.isArray(raw.sort))
-    out.sort = raw.sort.slice(0, 20).flatMap((s) => {
-      if (!record(s) || typeof s.key !== "string" || !/^(value|y|count|samples|group(?:0|[1-9][0-9]?))$/.test(s.key) || !["asc", "desc"].includes(String(s.dir))) {
-        diagnostics.push("Invalid metric sort.");
-        return [];
-      }
-      return [
-        copy(s, {
-          key: [s.key],
-          dir: ["asc", "desc"],
-          nulls: ["first", "last"]
-        })
-      ];
-    });
-  if (Array.isArray(raw.diagnostics))
-    diagnostics.push(
-      ...raw.diagnostics.filter((s) => typeof s === "string" && s.length <= 1e3).slice(0, 20)
-    );
-  if (diagnostics.length) out.diagnostics = [...new Set(diagnostics)];
-  return out;
-}
-
-// src/computed.ts
-var COMPUTED_PREFIX = "@computed/";
-var computedFieldName = (id) => COMPUTED_PREFIX + id;
-var isComputedField = (name) => name.trim().toLowerCase().startsWith(COMPUTED_PREFIX);
-function validateComputedColumn(input) {
-  const c = input;
-  if (!c || typeof c.id !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(c.id) || typeof c.label !== "string" || !c.label.trim() || c.label.length > 200 || typeof c.revision !== "string" || !c.revision || c.revision.length > 256 || c.expression?.language !== "qt-expr" || c.expression.version !== 1 || typeof c.expression.source !== "string" || !c.expression.source.trim() || c.expression.source.length > 1e4) {
-    throw new Error(
-      "Invalid computed column definition or unsupported formula version."
-    );
-  }
-  return {
-    id: c.id,
-    label: c.label,
-    revision: c.revision,
-    expression: { ...c.expression }
-  };
-}
-function memoryComputedColumnStore(seed = {}) {
-  const data = new Map(
-    Object.entries(seed).map(([k, v]) => [
-      k,
-      new Map(v.map((c) => [c.id, validateComputedColumn(c)]))
-    ])
-  );
-  const seedRevisions = new Set(
-    [...data.values()].flatMap(
-      (entries) => [...entries.values()].map((c) => c.revision)
-    )
-  );
-  let revisionSequence = 0n;
-  function freshRevision() {
-    let revision;
-    do {
-      revision = `memory:${++revisionSequence}`;
-    } while (seedRevisions.has(revision));
-    return revision;
-  }
-  const listeners = /* @__PURE__ */ new Map();
-  return {
-    async list(dataset) {
-      return [...data.get(dataset)?.values() ?? []].map(
-        validateComputedColumn
-      );
-    },
-    async save(dataset, column, expectedRevision) {
-      const entries = data.get(dataset) ?? /* @__PURE__ */ new Map();
-      const current = entries.get(column.id);
-      if ((current?.revision ?? null) !== expectedRevision)
-        throw new Error(
-          "This definition changed. Reload it before saving again."
-        );
-      const next = validateComputedColumn({
-        ...column,
-        revision: freshRevision()
-      });
-      entries.set(next.id, next);
-      data.set(dataset, entries);
-      listeners.get(dataset)?.forEach((fn) => fn());
-      return validateComputedColumn(next);
-    },
-    subscribe(dataset, listener) {
-      const set = listeners.get(dataset) ?? /* @__PURE__ */ new Set();
-      set.add(listener);
-      listeners.set(dataset, set);
-      return () => {
-        set.delete(listener);
-      };
-    }
-  };
-}
-function httpComputedColumnStore(base, fetcher = fetch) {
-  const listeners = /* @__PURE__ */ new Map();
-  const url = (dataset) => `${base}${base.includes("?") ? "&" : "?"}dataset=${encodeURIComponent(dataset)}`;
-  async function read(response) {
-    if (response.status === 409)
-      throw new Error(
-        "This definition changed. Reload it before saving again."
-      );
-    if (!response.ok)
-      throw new Error(
-        `Computed column store request failed (${response.status}).`
-      );
-    return response.json();
-  }
-  return {
-    async list(dataset, signal) {
-      const raw = await read(
-        await fetcher(url(dataset), { ...signal ? { signal } : {} })
-      );
-      if (!Array.isArray(raw))
-        throw new Error("Invalid computed column catalogue.");
-      return raw.map(validateComputedColumn);
-    },
-    async save(dataset, column, expectedRevision) {
-      const result = validateComputedColumn(
-        await read(
-          await fetcher(url(dataset), {
-            method: "PUT",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ column, expectedRevision })
-          })
-        )
-      );
-      listeners.get(dataset)?.forEach((fn) => fn());
-      return result;
-    },
-    subscribe(dataset, listener) {
-      const set = listeners.get(dataset) ?? /* @__PURE__ */ new Set();
-      set.add(listener);
-      listeners.set(dataset, set);
-      return () => {
-        set.delete(listener);
-      };
-    }
-  };
-}
-function isComputedCellError(value) {
-  return value !== null && typeof value === "object" && "computedError" in value && typeof value.computedError === "string";
-}
-function groupPreview(dependencies, inputs, results, total) {
-  const groups = /* @__PURE__ */ new Map();
-  let nulls = 0, errors = 0;
-  inputs.forEach((row, i) => {
-    const values = dependencies.map((name) => row[name] ?? null), result = results[i] ?? { value: null, error: "No result." };
-    const key = JSON.stringify([values, result.value, result.error ?? null]);
-    const group = groups.get(key);
-    if (group) group.count++;
-    else groups.set(key, { inputs: values, result, count: 1 });
-    if (result.error) errors++;
-    else if (result.value === null) nulls++;
-  });
-  return {
-    dependencies,
-    groups: [...groups.values()].sort((a, b) => b.count - a.count),
-    processed: inputs.length,
-    total,
-    nulls,
-    errors
-  };
+            sourceUnit: [
+              "milliseconds",
+              "seconds",
+              "minutes",
+              "hours",
+              "days",
+              "iso",
+              "epochSeconds",
+              "epochMilliseconds",
+              "secondsOfDay",
+              "millisecondsOfDay"
+            ],
+            style: ["human", "long", "clock", "custom", "iso"],
+            pattern: "string",
+            timeZone: "string"
+          });
+      if (record2(raw.display.list))
+        d.list = copy(raw.display.list, {
+          showBars: "boolean",
+          useGroupColors: "boolean",
+          showValues: "boolean",
+          barPosition: ["inline", "below"],
+          maxLabelLines: "positiveInteger"
+        });
+      if (record2(raw.display.pivot))
+        d.pivot = copy(raw.display.pivot, {
+          swap: "boolean",
+          rowDir: ["asc", "desc"],
+          columnDir: ["asc", "desc"]
+        });
+      out.display = { kind: "auto", ...d };
+    } else diagnostics.push("Invalid metric display.");
+  }
+  if (raw.distribution !== void 0) {
+    if (record2(raw.distribution))
+      out.distribution = copy(raw.distribution, {
+        kind: ["box", "histogram"],
+        input: "string",
+        whiskers: ["minmax", "tukey"],
+        bins: "integer"
+      });
+    else diagnostics.push("Invalid metric distribution.");
+  }
+  if (record2(raw.layout)) {
+    const l = copy(raw.layout, {
+      widthRem: "integer",
+      heightRem: "integer",
+      minWidthRem: "integer",
+      minHeightRem: "integer"
+    });
+    for (const k of ["widthRem", "heightRem", "minWidthRem", "minHeightRem"])
+      l[k] = Math.max(1, Math.min(1e3, Number(l[k] ?? 1)));
+    l.widthRem = Math.max(Number(l.widthRem), Number(l.minWidthRem));
+    l.heightRem = Math.max(Number(l.heightRem), Number(l.minHeightRem));
+    out.layout = l;
+  }
+  if (raw.sort !== void 0 && !Array.isArray(raw.sort))
+    diagnostics.push("Invalid metric sort.");
+  if (Array.isArray(raw.sort))
+    out.sort = raw.sort.slice(0, 20).flatMap((s) => {
+      if (!record2(s) || typeof s.key !== "string" || !/^(value|y|count|samples|group(?:0|[1-9][0-9]?))$/.test(s.key) || !["asc", "desc"].includes(String(s.dir))) {
+        diagnostics.push("Invalid metric sort.");
+        return [];
+      }
+      return [
+        copy(s, {
+          key: [s.key],
+          dir: ["asc", "desc"],
+          nulls: ["first", "last"]
+        })
+      ];
+    });
+  if (Array.isArray(raw.diagnostics))
+    diagnostics.push(
+      ...raw.diagnostics.filter((s) => typeof s === "string" && s.length <= 1e3).slice(0, 20)
+    );
+  if (diagnostics.length) out.diagnostics = [...new Set(diagnostics)];
+  return out;
 }
 
 // src/query.ts
@@ -289,6 +592,7 @@ function isOrGroup(term) {
 function predicatesOf(term) {
   return isOrGroup(term) ? term.any : [term];
 }
+var ITEM_DETAILS_COLUMN = "__qt_item_details__";
 var EMPTY_QUERY = {
   select: [],
   where: [],
@@ -343,7 +647,7 @@ function normalizeWhereClause(item) {
   if (!isRecord(item)) return null;
   const field = boundedString(item.field, MAX_FIELD_NAME_LENGTH);
   const value = typeof item.value === "string" && item.value.length <= MAX_FILTER_VALUE_LENGTH ? item.value : null;
-  if (!field || isComputedField(field) || typeof item.op !== "string" || !FILTER_OPS.has(item.op) || value == null) {
+  if (!field || typeof item.op !== "string" || !FILTER_OPS.has(item.op) || value == null) {
     return null;
   }
   const clause = { field, op: item.op, value };
@@ -437,6 +741,8 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
     limit: boundedInteger(raw.limit, fallback.limit, 1, MAX_QUERY_LIMIT),
     offset: boundedInteger(raw.offset, fallback.offset, 0, MAX_QUERY_OFFSET)
   };
+  if (raw.fitToScreen === true) out.fitToScreen = true;
+  if (raw.grouping != null) out.grouping = normalizeGroupingState(raw.grouping);
   if (Array.isArray(raw.aggregations)) {
     const aggregations = [];
     for (const item of raw.aggregations.slice(0, MAX_AGGREGATIONS)) {
@@ -463,179 +769,113 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
   } else if (fallback.aggregations?.length) {
     out.aggregations = normalizeQueryState({ aggregations: fallback.aggregations }).aggregations;
   }
-  return out;
-}
-function queriesEqual(a, b) {
-  if (a === b) return true;
-  if (a.limit !== b.limit || a.offset !== b.offset) return false;
-  if (!sameArray(a.where, b.where)) return false;
-  if (!sameArray(a.orderBy, b.orderBy)) return false;
-  if (!sameArray(a.select, b.select)) return false;
-  if (!sameArray(a.aggregations ?? [], b.aggregations ?? [])) return false;
-  return true;
-}
-function sameArray(a, b) {
-  if (a.length !== b.length) return false;
-  for (let i = 0; i < a.length; i++) {
-    if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return false;
-  }
-  return true;
-}
-
-// src/schema.ts
-function isFilterable(f2) {
-  if (f2.source.kind === "derived" && f2.source.computedId) return false;
-  return f2.filter?.enabled ?? f2.source.kind === "backend";
-}
-function isPushdownFilter(f2) {
-  return isFilterable(f2) && (f2.filter?.pushdown ?? f2.source.kind === "backend");
-}
-function isSortable(f2) {
-  if (f2.source.kind === "derived" && f2.source.computedId) return f2.sort?.enabled === true;
-  return f2.sort?.enabled ?? f2.source.kind === "backend";
-}
-function isSelectable(f2) {
-  return f2.select?.enabled ?? true;
-}
-function filterValues(f2) {
-  return f2.filter?.values ?? { source: "autocomplete" };
-}
-function indexFields(schema) {
-  return new Map(schema.fields.map((f2) => [f2.name, f2]));
-}
-function selectedFields(schema, q) {
-  const order = q.select.length > 0 ? q.select.map((c) => c.field) : (schema.defaultSelect ?? schema.fields.filter((f2) => f2.select?.default).map((f2) => ({ field: f2.name }))).map(
-    (c) => c.field
-  );
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const name of order) {
-    if (seen.has(name)) continue;
-    const f2 = resolveField(schema, name);
-    if (!f2 || !isSelectable(f2)) continue;
-    seen.add(name);
-    seen.add(f2.name);
-    out.push(f2);
+  if (isRecord(raw.itemDetails) && Array.isArray(raw.itemDetails.modes)) {
+    const modes = [...new Set(raw.itemDetails.modes.filter(
+      (mode) => typeof mode === "string" && ["hover", "modal", "expand", "page"].includes(mode)
+    ))];
+    const details = { modes };
+    if (isRecord(raw.itemDetails.page) && typeof raw.itemDetails.page.urlTemplate === "string" && raw.itemDetails.page.urlTemplate.length <= 8e3) {
+      details.page = {
+        urlTemplate: raw.itemDetails.page.urlTemplate,
+        target: raw.itemDetails.page.target === "_self" ? "_self" : "_blank"
+      };
+    }
+    if (raw.itemDetails.view !== void 0) {
+      try {
+        details.view = normalizePropertyView(raw.itemDetails.view);
+      } catch {
+      }
+    }
+    if (isRecord(raw.itemDetails.views)) {
+      const views = {};
+      for (const mode of ["hover", "modal", "expand"]) {
+        try {
+          if (raw.itemDetails.views[mode] !== void 0) views[mode] = normalizePropertyView(raw.itemDetails.views[mode]);
+        } catch {
+        }
+      }
+      if (Object.keys(views).length) details.views = views;
+    }
+    const active = raw.itemDetails.active;
+    if (isRecord(active) && (active.mode === "modal" || active.mode === "expand") && modes.includes(active.mode) && (typeof active.id === "string" && active.id.length > 0 && active.id.length <= 1e3 || typeof active.id === "number" && Number.isFinite(active.id))) {
+      details.active = { id: active.id, mode: active.mode };
+    }
+    out.itemDetails = details;
   }
   return out;
 }
-function resolveField(schema, field) {
-  const token = field.trim();
-  if (!token) return void 0;
-  const byName = indexFields(schema);
-  const byExactName = byName.get(token);
-  if (byExactName) return byExactName;
-  const needle = token.toLowerCase();
-  for (const f2 of schema.fields) {
-    if (f2.name.toLowerCase() === needle) return f2;
-    if (aliasMatches(f2, needle)) return f2;
-  }
-  return void 0;
-}
-function resolveFieldName(schema, field) {
-  return resolveField(schema, field)?.name;
-}
-function aliasTermsFor(field) {
-  const out = [];
-  const seen = /* @__PURE__ */ new Set();
-  const add = (raw) => {
-    if (typeof raw !== "string") return;
-    const value = raw.trim();
-    if (!value) return;
-    const key = value.toLowerCase();
-    if (seen.has(key)) return;
-    seen.add(key);
-    out.push(value);
+function normalizeGroupingState(value) {
+  const raw = isRecord(value) ? value : {};
+  const diagnostics = [];
+  const fail = () => {
+    diagnostics.push("Invalid grouping definition.");
   };
-  add(field.alias);
-  if (field.aliases) {
-    for (const alias of field.aliases) add(alias);
-  }
-  return out;
-}
-function aliasMatches(field, needle) {
-  for (const alias of aliasTermsFor(field)) {
-    if (alias.toLowerCase() === needle) return true;
-  }
-  return false;
-}
-function readFieldValue(field, row) {
-  if (row == null) return null;
-  if (field.source.kind === "derived" && field.source.accessor) {
-    return field.source.accessor(row);
+  const keys = Array.isArray(raw.keys) ? raw.keys.slice(0, MAX_GROUP_BY_FIELDS).filter((key) => !!boundedString(key, MAX_FIELD_NAME_LENGTH)) : [];
+  if (!Array.isArray(raw.keys) || !keys.length || keys.length !== raw.keys.length || new Set(keys).size !== keys.length) fail();
+  const summaries = [];
+  if (!Array.isArray(raw.summaries) || raw.summaries.length > 64) fail();
+  for (const item of Array.isArray(raw.summaries) ? raw.summaries.slice(0, 64) : []) {
+    if (!isRecord(item) || !boundedString(item.id, MAX_FIELD_NAME_LENGTH) || typeof item.op !== "string" || !AGG_OPS.has(item.op) && item.op !== "row" && item.op !== "formula") {
+      fail();
+      continue;
+    }
+    const column = { id: item.id, op: item.op };
+    if (item.field !== void 0) {
+      if (!boundedString(item.field, MAX_FIELD_NAME_LENGTH)) fail();
+      else column.field = item.field;
+    }
+    if (item.op === "formula") {
+      if (typeof item.expression !== "string" || item.expression.length > 1e4) fail();
+      else column.expression = item.expression;
+    }
+    if (item.label !== void 0) {
+      if (typeof item.label !== "string" || item.label.length > MAX_LABEL_LENGTH) fail();
+      else column.label = item.label;
+    }
+    summaries.push(column);
   }
-  const path = field.source.kind === "backend" && field.source.path || field.name;
-  const r = row;
-  if (path in r) return r[path] ?? null;
-  let cur = row;
-  for (const part of path.split(".")) {
-    if (cur == null || typeof cur !== "object") return null;
-    cur = cur[part];
+  let representative = null;
+  if (raw.representative != null) {
+    const ordering = isRecord(raw.representative) ? raw.representative.orderBy : void 0;
+    const orderBy = [];
+    if (!Array.isArray(ordering) || !ordering.length || ordering.length > 8) fail();
+    for (const term of Array.isArray(ordering) ? ordering.slice(0, 8) : []) {
+      if (!isRecord(term) || !boundedString(term.field, MAX_FIELD_NAME_LENGTH) || !["asc", "desc"].includes(String(term.dir)) || term.nulls !== void 0 && !["first", "last"].includes(String(term.nulls))) {
+        fail();
+        continue;
+      }
+      orderBy.push({ field: term.field, dir: term.dir, nulls: term.nulls === "first" ? "first" : "last" });
+    }
+    representative = { orderBy };
   }
-  return cur ?? null;
-}
-function loadSchema(doc) {
-  const d = doc;
-  if (!d || typeof d !== "object") throw new Error("schema: document is not an object");
-  if (typeof d.name !== "string") throw new Error("schema: missing `name`");
-  if (typeof d.idField !== "string") throw new Error("schema: missing `idField`");
-  if (!Array.isArray(d.fields) || d.fields.length === 0) throw new Error("schema: `fields` must be a non-empty array");
-  const fields = d.fields.map((raw, i) => projectField(raw, i));
-  return {
-    name: d.name,
-    idField: d.idField,
-    fields,
-    defaultSort: d.defaultSort,
-    defaultSelect: d.defaultSelect,
-    defaultLimit: d.defaultLimit
-  };
-}
-function projectField(raw, i) {
-  if (!raw || typeof raw.name !== "string") throw new Error(`schema: field[${i}] missing \`name\``);
-  if (typeof raw.label !== "string") throw new Error(`schema: field ${raw.name} missing \`label\``);
-  if (typeof raw.type !== "string") throw new Error(`schema: field ${raw.name} missing \`type\``);
-  const rs = raw.source ?? (raw.bindings ? "backend" : "derived");
-  let source;
-  if (typeof rs === "string") {
-    source = rs === "derived" ? { kind: "derived" } : { kind: "backend" };
-  } else if (rs.kind === "derived") {
-    source = { kind: "derived" };
-  } else {
-    source = { kind: "backend", path: rs.path, synthetic: rs.synthetic };
+  if (!isRecord(raw.source) || raw.source.grouping != null) fail();
+  const { grouping: _nested, ...source } = isRecord(raw.source) ? raw.source : {};
+  if (Array.isArray(raw.diagnostics) && raw.diagnostics.length) fail();
+  const normalizedSource = normalizeQueryState(source);
+  if (Array.isArray(source.where)) {
+    const supplied = source.where.reduce((count, term) => count + (isRecord(term) && Array.isArray(term.any) ? term.any.length : 1), 0);
+    if (supplied !== normalizedSource.where.reduce((count, term) => count + predicatesOf(term).length, 0)) fail();
   }
-  return {
-    name: raw.name,
-    label: raw.label,
-    type: raw.type,
-    source,
-    filter: raw.filter,
-    sort: raw.sort,
-    select: raw.select,
-    aggregate: raw.aggregate,
-    group: raw.group,
-    alias: raw.alias,
-    aliases: normalizeAliases(raw.aliases, raw.alias),
-    render: raw.render
-    // string key from JSON; consumer may override with a fn
-  };
+  return { keys, summaries, representative, source: normalizedSource, ...diagnostics.length ? { diagnostics: [...new Set(diagnostics)] } : {} };
 }
-function normalizeAliases(rawAliases, rawAlias) {
-  const aliases = [];
-  const seen = /* @__PURE__ */ new Set();
-  const add = (raw) => {
-    if (typeof raw !== "string") return;
-    const value = raw.trim();
-    if (!value) return;
-    const key = value.toLowerCase();
-    if (seen.has(key)) return;
-    seen.add(key);
-    aliases.push(value);
-  };
-  add(rawAlias);
-  if (Array.isArray(rawAliases)) {
-    for (const item of rawAliases) add(item);
+function queriesEqual(a, b) {
+  if (a === b) return true;
+  if (a.limit !== b.limit || a.offset !== b.offset) return false;
+  if (a.fitToScreen === true !== (b.fitToScreen === true)) return false;
+  if (!sameArray(a.where, b.where)) return false;
+  if (!sameArray(a.orderBy, b.orderBy)) return false;
+  if (!sameArray(a.select, b.select)) return false;
+  if (!sameArray(a.aggregations ?? [], b.aggregations ?? [])) return false;
+  if (JSON.stringify(a.itemDetails) !== JSON.stringify(b.itemDetails)) return false;
+  if (JSON.stringify(a.grouping) !== JSON.stringify(b.grouping)) return false;
+  return true;
+}
+function sameArray(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) return false;
   }
-  return aliases;
+  return true;
 }
 
 // src/relativeTime.ts
@@ -655,8 +895,8 @@ function parseRelativeDuration(value) {
   }
   return value[0] === "-" && total !== 0 ? -total : total;
 }
-function evaluationTime(options) {
-  const now = options.now ?? Date.now();
+function evaluationTime(options2) {
+  const now = options2.now ?? Date.now();
   if (!Number.isSafeInteger(now) || Math.abs(now) > MAX_RELATIVE_TIME_MS) throw new Error("Invalid query evaluation time");
   return now;
 }
@@ -807,6 +1047,9 @@ function isGroupable(field) {
   return field.type === "enum" || field.type === "text" || field.type === "bool";
 }
 
+// src/encode.ts
+import { deflateSync, Inflate } from "fflate";
+
 // src/setFilter.ts
 function createSetFilter(field, mode, values, id) {
   const keys = [...new Set(values)];
@@ -872,7 +1115,7 @@ function fromBase64Url(s) {
   const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
   return new TextDecoder().decode(bytes);
 }
-function encodeQuery(q) {
+function compactQuery(q) {
   q = normalizeQueryState(q);
   const c = {};
   if (q.select.length)
@@ -882,25 +1125,157 @@ function encodeQuery(q) {
   c.l = q.limit;
   if (q.offset) c.f = q.offset;
   if (q.aggregations?.length) c.g = q.aggregations;
-  if (Object.keys(c).length === 0) return "";
-  return toBase64Url(JSON.stringify(c));
+  if (q.itemDetails) c.d = q.itemDetails;
+  if (q.fitToScreen) c.fs = true;
+  if (q.grouping) c.b = q.grouping;
+  return c;
+}
+var MAX_QUERY_STATE_BYTES = 4 * 1024 * 1024;
+var QueryDecodeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "QueryDecodeError";
+  }
+};
+function packQuery(c) {
+  const packed = { ...c };
+  if (c.l === EMPTY_QUERY.limit) delete packed.l;
+  if (c.w) {
+    const terms = [];
+    for (let i = 0; i < c.w.length; i++) {
+      const set = readSetFilter(c.w, i);
+      if (set) {
+        terms.push(["set", set.field, set.metadata.mode, set.metadata.values, set.metadata.id]);
+        i += set.count - 1;
+      } else terms.push(c.w[i]);
+    }
+    packed.w = terms;
+  }
+  if (c.d?.views) {
+    const pool = [];
+    const refs = {};
+    for (const [mode, view] of Object.entries(c.d.views)) {
+      let index = pool.findIndex((v) => JSON.stringify(v) === JSON.stringify(view));
+      if (index < 0) {
+        index = pool.length;
+        pool.push(view);
+      }
+      refs[mode] = index;
+    }
+    packed.d = { ...c.d, views: { pool, refs } };
+  }
+  return packed;
+}
+function unpackQuery(c) {
+  if (Array.isArray(c.w)) c.w = c.w.flatMap((term) => {
+    if (!Array.isArray(term)) return [term];
+    if (term.length !== 5 || term[0] !== "set" || typeof term[1] !== "string" || typeof term[2] !== "string" || !["any", "all", "none", "empty"].includes(term[2]) || !Array.isArray(term[3]) || term[3].length > 100 || !term[3].every((v) => typeof v === "string" && v.length <= 1e4) || typeof term[4] !== "string")
+      throw new QueryDecodeError("invalid", "Invalid set filter in query link.");
+    return createSetFilter(term[1], term[2], term[3], term[4]);
+  });
+  const details = c.d;
+  const views = details && typeof details === "object" && "views" in details ? details.views : void 0;
+  if (details && typeof details === "object" && views && typeof views === "object" && "pool" in views) {
+    const pool = views.pool;
+    const refs = "refs" in views ? views.refs : void 0;
+    if (!Array.isArray(pool) || pool.length > 3 || !refs || typeof refs !== "object" || Array.isArray(refs))
+      throw new QueryDecodeError("invalid", "Invalid property views in query link.");
+    c.d = { ...details, views: Object.fromEntries(Object.entries(refs).map(([mode, index]) => {
+      if (!["hover", "modal", "expand"].includes(mode) || !Number.isInteger(index) || index < 0 || index >= pool.length)
+        throw new QueryDecodeError("invalid", "Invalid property view reference.");
+      return [mode, pool[index]];
+    })) };
+  }
+  return c;
+}
+function encodeQuery(q) {
+  const json = JSON.stringify(packQuery(compactQuery(q)));
+  const bytes = new TextEncoder().encode(json);
+  if (bytes.length > MAX_QUERY_STATE_BYTES) throw new QueryDecodeError("too_large", "Query state exceeds the storage limit.");
+  const plain = "2j." + toBase64Url(json);
+  const compressed = "2d." + bytesToBase64(deflateSync(bytes));
+  const token = compressed.length < plain.length ? compressed : plain;
+  if (token.length > MAX_QUERY_TOKEN_LENGTH) throw new QueryDecodeError("too_large", "Encoded query state exceeds the storage limit.");
+  return token;
+}
+function bytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64").replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+  let bin = "";
+  for (const byte of bytes) bin += String.fromCharCode(byte);
+  return btoa(bin).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function inflateToken(token) {
+  const bin = atob(token.replace(/-/g, "+").replace(/_/g, "/"));
+  const input = Uint8Array.from(bin, (c) => c.charCodeAt(0));
+  const chunks = [];
+  let size = 0;
+  let complete = false;
+  const stream = new Inflate((chunk, final) => {
+    size += chunk.length;
+    if (size > MAX_QUERY_STATE_BYTES) throw new QueryDecodeError("too_large", "Expanded query state exceeds the storage limit.");
+    chunks.push(chunk);
+    complete = final;
+  });
+  for (let i = 0; i < input.length; i += 256) stream.push(input.subarray(i, i + 256), i + 256 >= input.length);
+  if (!complete) throw new QueryDecodeError("invalid", "Incomplete compressed query link.");
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
 }
 function decodeQuery(token) {
+  try {
+    return decodeToken(token, false);
+  } catch {
+    return { ...EMPTY_QUERY };
+  }
+}
+function decodeQueryStrict(token) {
+  return decodeToken(token, true);
+}
+function decodeToken(token, strict) {
   if (!token) return { ...EMPTY_QUERY };
-  if (token.length > MAX_QUERY_TOKEN_LENGTH) return { ...EMPTY_QUERY };
+  if (token.length > MAX_QUERY_TOKEN_LENGTH) throw new QueryDecodeError("too_large", "Query link exceeds the storage limit.");
   try {
-    const c = JSON.parse(fromBase64Url(token));
+    const versioned = token.includes(".");
+    if (versioned && !token.startsWith("2j.") && !token.startsWith("2d."))
+      throw new QueryDecodeError("unsupported_version", "Unsupported query link version.");
+    const payload = versioned ? token.slice(3) : token;
+    if (!/^[A-Za-z0-9_-]+$/.test(payload) || payload.length % 4 === 1) throw new QueryDecodeError("invalid", "Invalid query link encoding.");
+    const json = token.startsWith("2d.") ? inflateToken(payload) : fromBase64Url(payload);
+    if (new TextEncoder().encode(json).length > MAX_QUERY_STATE_BYTES) throw new QueryDecodeError("too_large", "Query state exceeds the storage limit.");
+    const raw = JSON.parse(json);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw) || ["w", "g"].some((k) => raw[k] !== void 0 && !Array.isArray(raw[k])))
+      throw new QueryDecodeError("invalid", "Invalid query link state.");
+    const c = versioned ? unpackQuery(raw) : raw;
+    if (strict && c.w) {
+      if (c.w.some((term) => !term || typeof term !== "object")) throw new QueryDecodeError("invalid", "Invalid query predicates.");
+      const count = c.w.reduce((n, term) => n + predicatesOf(term).length, 0);
+      const normalized = normalizeQueryState({ where: c.w });
+      const normalizedCount = normalized.where.reduce((n, term) => n + predicatesOf(term).length, 0);
+      if (count > 100 || count !== normalizedCount || c.w.some((term) => predicatesOf(term).some((clause) => !clause || typeof clause !== "object" || clause.negated !== void 0 && typeof clause.negated !== "boolean")))
+        throw new QueryDecodeError("invalid", "Invalid query predicates or predicate budget exceeded.");
+    }
     const out = normalizeQueryState({
       select: normalizeSelect(c.s ?? c.c),
       where: Array.isArray(c.w) ? c.w : [],
       orderBy: normalizeOrderBy(c.o),
       limit: c.l,
       offset: c.f,
-      aggregations: c.g
+      aggregations: c.g,
+      itemDetails: c.d,
+      fitToScreen: c.fs,
+      grouping: c.b
     });
+    if (strict && c.g && out.aggregations?.length !== c.g.length) throw new QueryDecodeError("invalid", "Invalid query metrics.");
     return out;
-  } catch {
-    return { ...EMPTY_QUERY };
+  } catch (error) {
+    if (error instanceof QueryDecodeError) throw error;
+    throw new QueryDecodeError("invalid", "Invalid or incomplete query link.");
   }
 }
 function normalizeSelect(s) {
@@ -919,6 +1294,7 @@ function normalizeOrderBy(o) {
   return [o];
 }
 function toServerQuery(q, schema) {
+  if (q.grouping) throw new Error("This transport does not support grouped queries. Enable the v3 query executor.");
   q = normalizeQueryState(q);
   const byName = indexFields(schema);
   const resolveField2 = (name) => resolveFieldName(schema, name) ?? name;
@@ -957,8 +1333,10 @@ function termIsPushdown(term, byName, resolveField2) {
   });
 }
 function toAggregationQuery(q, schema) {
+  if (q.grouping) throw new Error("Metrics over grouped rows require grouped-query execution.");
   const suppliedPredicateCount = q.where.reduce((n, t) => n + predicatesOf(t).length, 0);
   q = normalizeQueryState(q);
+  if (q.aggregations?.some((a) => a.dateGrouping)) throw new Error("Date grouping currently requires local metric execution.");
   if (q.aggregations?.some((a) => a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.distribution || a.scope === "shownRows" || a.sort?.length || a.groupLimit)) throw new Error("Metric definition requires the version 2 metric transport.");
   const byName = indexFields(schema);
   const resolveField2 = (name) => resolveFieldName(schema, name) ?? name;
@@ -969,13 +1347,453 @@ function toAggregationQuery(q, schema) {
     const f2 = byName.get(field);
     return f2 != null && f2.source.kind === "backend";
   };
-  const aggregations = (q.aggregations ?? []).filter(
-    (a) => isBackend(a.field) && a.groupBy.every((g) => isBackend(g))
-  );
-  const diagnostics = [];
-  for (const c of q.aggregations ?? []) if (!aggregations.includes(c)) diagnostics.push({ metricId: c.id, code: "unsupported_metric", message: "Metric requires unavailable backend fields.", from: 0, to: 1 });
-  if (where.length !== q.where.length || suppliedPredicateCount !== q.where.reduce((n, t) => n + predicatesOf(t).length, 0)) diagnostics.push({ code: "residual_filter", message: "All-matching metrics are unavailable with residual client-only filters.", from: 0, to: 1 });
-  return { where, aggregations, ...diagnostics.length ? { diagnostics } : {} };
+  const aggregations = (q.aggregations ?? []).filter(
+    (a) => isBackend(a.field) && a.groupBy.every((g) => isBackend(g))
+  );
+  const diagnostics = [];
+  for (const c of q.aggregations ?? []) if (!aggregations.includes(c)) diagnostics.push({ metricId: c.id, code: "unsupported_metric", message: "Metric requires unavailable backend fields.", from: 0, to: 1 });
+  if (where.length !== q.where.length || suppliedPredicateCount !== q.where.reduce((n, t) => n + predicatesOf(t).length, 0)) diagnostics.push({ code: "residual_filter", message: "All-matching metrics are unavailable with residual client-only filters.", from: 0, to: 1 });
+  return { where, aggregations, ...diagnostics.length ? { diagnostics } : {} };
+}
+
+// src/queryLinks.ts
+var codePattern = /^[A-Za-z0-9_-]{22}$/;
+function validateQuerySnapshot(input) {
+  const s = input;
+  if (!s || s.version !== 1 || !codePattern.test(s.code) || typeof s.token !== "string" || s.token.length > MAX_QUERY_TOKEN_LENGTH || !Number.isFinite(s.createdAt)) throw Error("Invalid query snapshot.");
+  decodeQueryStrict(s.token);
+  return { version: 1, code: s.code, token: s.token, createdAt: s.createdAt };
+}
+function newSnapshot(token) {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return { version: 1, code: btoa(bin).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_"), token, createdAt: Date.now() };
+}
+function localQuerySnapshotCache(options2 = {}) {
+  const storageKey = options2.storageKey ?? "query-table:link-cache:v1";
+  const maxEntries = options2.maxEntries ?? 100;
+  const maxBytes = options2.maxBytes ?? 2 * 1024 * 1024;
+  if (!Number.isInteger(maxEntries) || maxEntries < 1 || !Number.isFinite(maxBytes) || maxBytes < 1) throw Error("Invalid query link cache limits.");
+  const storage = () => options2.storage ?? globalThis.localStorage;
+  function read() {
+    const text = storage().getItem(storageKey);
+    if (!text) return [];
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      return [];
+    }
+    if (!Array.isArray(raw)) return [];
+    const entries = raw.filter((e) => e && typeof e.key === "string" && e.snapshot && e.snapshot.version === 1 && codePattern.test(e.snapshot.code) && typeof e.snapshot.token === "string" && e.snapshot.token.length <= MAX_QUERY_TOKEN_LENGTH && Number.isFinite(e.snapshot.createdAt)).slice(-maxEntries);
+    while (entries.length && JSON.stringify(entries).length * 2 > maxBytes) entries.shift();
+    return entries;
+  }
+  return {
+    isDurable(key, code) {
+      return read().some((e) => e.key === key && e.snapshot.code === code && e.durable);
+    },
+    markDurable(key, code) {
+      const entries = read();
+      const entry = entries.find((e) => e.key === key && e.snapshot.code === code);
+      if (entry) {
+        entry.durable = true;
+        let text = JSON.stringify(entries);
+        while (text.length * 2 > maxBytes && entries.length > 1) {
+          entries.splice(entries[0] === entry ? 1 : 0, 1);
+          text = JSON.stringify(entries);
+        }
+        if (text.length * 2 <= maxBytes) storage().setItem(storageKey, text);
+      }
+    },
+    get(key, code) {
+      return read().find((e) => e.key === key && e.snapshot.code === code)?.snapshot ?? null;
+    },
+    find(key, token) {
+      return read().find((e) => e.key === key && e.snapshot.token === token)?.snapshot ?? null;
+    },
+    put(key, snapshot) {
+      const entries = read();
+      const old = entries.find((e) => e.key === key && e.snapshot.code === snapshot.code);
+      if (old) {
+        if (old.snapshot.token !== snapshot.token) throw Error("A query link code cannot be overwritten.");
+        const text2 = JSON.stringify(entries);
+        if (storage().getItem(storageKey) !== text2) storage().setItem(storageKey, text2);
+        return;
+      }
+      entries.push({ key, snapshot: validateQuerySnapshot(snapshot) });
+      while (entries.length > maxEntries) entries.shift();
+      let text = JSON.stringify(entries);
+      while (text.length * 2 > maxBytes && entries.length > 1) {
+        entries.shift();
+        text = JSON.stringify(entries);
+      }
+      if (text.length * 2 > maxBytes) throw Error("This query is too large for the local link cache.");
+      storage().setItem(storageKey, text);
+    }
+  };
+}
+function memoryQuerySnapshotCache() {
+  let text = null;
+  return localQuerySnapshotCache({ storage: { getItem: () => text, setItem: (_key, value) => {
+    text = value;
+  } } });
+}
+var QuerySnapshotHttpError = class extends Error {
+  constructor(status, code, message, detail, serverCode) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.detail = detail;
+    this.serverCode = serverCode;
+    this.name = "QuerySnapshotHttpError";
+  }
+};
+async function snapshotHttpError(response) {
+  let detail;
+  let serverCode;
+  const type = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+  if (response.body && (type === "text/plain" || type === "application/json")) {
+    const reader = response.body.getReader();
+    try {
+      const chunks = [];
+      let size = 0;
+      let complete = false;
+      while (size <= 4096) {
+        const next = await reader.read();
+        if (next.done) {
+          complete = true;
+          break;
+        }
+        size += next.value.byteLength;
+        if (size <= 4096) chunks.push(next.value);
+      }
+      if (complete) {
+        const bytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.length;
+        }
+        const text = new TextDecoder().decode(bytes);
+        let reason = text;
+        if (type === "application/json") {
+          const body = JSON.parse(text);
+          reason = body?.message ?? body?.error?.message ?? body?.error;
+          const code2 = body?.code ?? body?.error?.code;
+          if (typeof code2 === "string" && /^[A-Za-z0-9_.-]{1,64}$/.test(code2)) serverCode = code2;
+        }
+        if (typeof reason === "string" && !/[<>]/.test(reason)) {
+          const safe = reason.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+          if (safe) detail = safe.slice(0, 512);
+        }
+      }
+    } catch {
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+      }
+      reader.releaseLock();
+    }
+  }
+  const status = response.status;
+  const code = status === 507 ? "quota" : status === 401 || status === 403 ? "forbidden" : status === 409 ? "conflict" : status === 404 ? "unavailable" : status >= 500 ? "storage" : "http";
+  const messages = {
+    quota: "Query snapshot storage is full. Ask your host to increase its quota, then retry saving. Existing links still work.",
+    forbidden: "You do not have permission to save or open this query link. Sign in or ask your host for access.",
+    conflict: "This query link code already identifies different state. Ask your host to check its snapshot store.",
+    unavailable: "This query link is unavailable. Check its address or ask its author for a new link.",
+    storage: "Query snapshot storage is temporarily unavailable. Retry later; your previous saved query is unchanged.",
+    http: `Query snapshot request failed (${status}). Check the request or retry later.`
+  };
+  const message = messages[code] + (code !== "http" ? ` (HTTP ${status})` : "") + (detail && (status < 500 || status === 507) ? ` ${detail}` : "");
+  return new QuerySnapshotHttpError(status, code, message, detail, serverCode);
+}
+function httpQuerySnapshotStore(base, fetcher = fetch) {
+  const url = (key, code) => `${base}${base.includes("?") ? "&" : "?"}dataset=${encodeURIComponent(key)}&code=${encodeURIComponent(code)}`;
+  async function responseSnapshot(response) {
+    if (!response.ok) throw await snapshotHttpError(response);
+    return validateQuerySnapshot(await response.json());
+  }
+  return {
+    async save(key, snapshot, signal) {
+      const result = await responseSnapshot(await fetcher(url(key, snapshot.code), {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(snapshot),
+        ...signal ? { signal } : {}
+      }));
+      if (result.code !== snapshot.code || result.token !== snapshot.token) throw Error("The snapshot store changed this immutable query link.");
+      return result;
+    },
+    async resolve(key, code, signal) {
+      const response = await fetcher(url(key, code), signal ? { signal } : {});
+      if (response.status === 404) return null;
+      const result = await responseSnapshot(response);
+      if (result.code !== code) throw Error("The snapshot store returned a different query link.");
+      return result;
+    }
+  };
+}
+function createQueryLinkService(key, store, options2 = {}) {
+  const budget = options2.maxUrlBytes ?? 2e3;
+  if (!Number.isInteger(budget) || budget < 1) throw Error("Invalid query URL budget.");
+  const cache = options2.cache ?? localQuerySnapshotCache();
+  const promoted = /* @__PURE__ */ new Map();
+  const attempts = /* @__PURE__ */ new Map();
+  const known = /* @__PURE__ */ new Map();
+  function remember(snapshot2) {
+    known.set(snapshot2.code, snapshot2);
+    while (known.size > 100) known.delete(known.keys().next().value);
+    try {
+      cache.put(key, snapshot2);
+      cache.markDurable?.(key, snapshot2.code);
+    } catch {
+    }
+  }
+  function link(base, parameter, value, kind) {
+    const url = new URL(base);
+    url.searchParams.set(parameter, value);
+    const bytes = new TextEncoder().encode(url.toString()).length;
+    if (bytes > budget) throw Error("The query link exceeds the URL budget, including the page address.");
+    return { url: url.toString(), kind, bytes, ...kind !== "inline" ? { snapshotCode: value.slice(1) } : {} };
+  }
+  function cached(token) {
+    try {
+      return cache.find(key, token);
+    } catch {
+      return null;
+    }
+  }
+  async function snapshot(query) {
+    if (!store) return null;
+    const token = encodeQuery(query);
+    const existing = promoted.get(token);
+    if (existing) return existing;
+    const local = attempts.get(token) ?? cached(token) ?? newSnapshot(token);
+    attempts.set(token, local);
+    while (attempts.size > 100) attempts.delete(attempts.keys().next().value);
+    try {
+      cache.put(key, local);
+    } catch {
+    }
+    const pending = store.save(key, local).then((result) => {
+      const valid = validateQuerySnapshot(result);
+      if (valid.code !== local.code || valid.token !== token) throw Error("The snapshot store changed this immutable query link.");
+      remember(valid);
+      return valid;
+    });
+    promoted.set(token, pending);
+    while (promoted.size > 100) promoted.delete(promoted.keys().next().value);
+    try {
+      return await pending;
+    } catch (error) {
+      promoted.delete(token);
+      throw error;
+    }
+  }
+  return {
+    local(query, baseUrl, parameter = "q") {
+      const token = encodeQuery(query);
+      const current = new URL(baseUrl).searchParams.get(parameter);
+      if (current?.startsWith("@") && known.get(current.slice(1))?.token === token)
+        return link(baseUrl, parameter, current, "durable");
+      if (current?.startsWith("@")) {
+        try {
+          const code = current.slice(1);
+          if (cache.isDurable?.(key, code) && cache.get(key, code)?.token === token)
+            return link(baseUrl, parameter, current, "durable");
+        } catch {
+        }
+      }
+      const url = new URL(baseUrl);
+      url.searchParams.set(parameter, token);
+      if (new TextEncoder().encode(url.toString()).length <= budget) return link(baseUrl, parameter, token, "inline");
+      const local = cached(token) ?? newSnapshot(token);
+      const result = link(baseUrl, parameter, "@" + local.code, "local");
+      cache.put(key, local);
+      return result;
+    },
+    async durable(query, baseUrl, parameter = "q") {
+      const saved = await snapshot(query);
+      if (saved) return link(baseUrl, parameter, "@" + saved.code, "durable");
+      const token = encodeQuery(query);
+      return link(baseUrl, parameter, token, "inline");
+    },
+    snapshot,
+    async resolve(baseUrl, parameter = "q", signal) {
+      const values = new URL(baseUrl).searchParams.getAll(parameter);
+      if (!values.length || values.length === 1 && values[0] === "") return null;
+      if (values.length !== 1) throw Error("Invalid or conflicting query link parameters.");
+      const value = values[0];
+      if (!value.startsWith("@")) return decodeQueryStrict(value);
+      const code = value.slice(1);
+      if (!codePattern.test(code)) throw Error("Invalid query link code.");
+      let local = null;
+      try {
+        local = cache.get(key, code);
+        if (local) local = validateQuerySnapshot(local);
+      } catch {
+        local = null;
+      }
+      const result = local ?? (store ? await store.resolve(key, code, signal) : null);
+      if (!result) throw Error("This query link is unavailable. Its local cache entry may have expired; use a saved or shared link for permanent access.");
+      const valid = validateQuerySnapshot(result);
+      if (valid.code !== code) throw Error("Invalid query snapshot code.");
+      if (!local) remember(valid);
+      else {
+        try {
+          if (cache.isDurable?.(key, code)) remember(valid);
+        } catch {
+        }
+      }
+      return decodeQueryStrict(valid.token);
+    }
+  };
+}
+
+// src/computed.ts
+var COMPUTED_PREFIX = "@computed/";
+var computedFieldName = (id) => COMPUTED_PREFIX + id;
+var isComputedField = (name) => name.trim().toLowerCase().startsWith(COMPUTED_PREFIX);
+function validateComputedColumn(input) {
+  const c = input;
+  if (!c || typeof c.id !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(c.id) || typeof c.label !== "string" || !c.label.trim() || c.label.length > 200 || typeof c.revision !== "string" || !c.revision || c.revision.length > 256 || c.expression?.language !== "qt-expr" || c.expression.version !== 1 || typeof c.expression.source !== "string" || !c.expression.source.trim() || c.expression.source.length > 1e4) {
+    throw new Error(
+      "Invalid computed column definition or unsupported formula version."
+    );
+  }
+  return {
+    id: c.id,
+    label: c.label,
+    revision: c.revision,
+    expression: { ...c.expression }
+  };
+}
+function memoryComputedColumnStore(seed = {}) {
+  const data = new Map(
+    Object.entries(seed).map(([k, v]) => [
+      k,
+      new Map(v.map((c) => [c.id, validateComputedColumn(c)]))
+    ])
+  );
+  const seedRevisions = new Set(
+    [...data.values()].flatMap(
+      (entries) => [...entries.values()].map((c) => c.revision)
+    )
+  );
+  let revisionSequence = 0n;
+  function freshRevision() {
+    let revision;
+    do {
+      revision = `memory:${++revisionSequence}`;
+    } while (seedRevisions.has(revision));
+    return revision;
+  }
+  const listeners = /* @__PURE__ */ new Map();
+  return {
+    async list(dataset) {
+      return [...data.get(dataset)?.values() ?? []].map(
+        validateComputedColumn
+      );
+    },
+    async save(dataset, column, expectedRevision) {
+      const entries = data.get(dataset) ?? /* @__PURE__ */ new Map();
+      const current = entries.get(column.id);
+      if ((current?.revision ?? null) !== expectedRevision)
+        throw new Error(
+          "This definition changed. Reload it before saving again."
+        );
+      const next = validateComputedColumn({
+        ...column,
+        revision: freshRevision()
+      });
+      entries.set(next.id, next);
+      data.set(dataset, entries);
+      listeners.get(dataset)?.forEach((fn) => fn());
+      return validateComputedColumn(next);
+    },
+    subscribe(dataset, listener) {
+      const set = listeners.get(dataset) ?? /* @__PURE__ */ new Set();
+      set.add(listener);
+      listeners.set(dataset, set);
+      return () => {
+        set.delete(listener);
+      };
+    }
+  };
+}
+function httpComputedColumnStore(base, fetcher = fetch) {
+  const listeners = /* @__PURE__ */ new Map();
+  const url = (dataset) => `${base}${base.includes("?") ? "&" : "?"}dataset=${encodeURIComponent(dataset)}`;
+  async function read(response) {
+    if (response.status === 409)
+      throw new Error(
+        "This definition changed. Reload it before saving again."
+      );
+    if (!response.ok)
+      throw new Error(
+        `Computed column store request failed (${response.status}).`
+      );
+    return response.json();
+  }
+  return {
+    async list(dataset, signal) {
+      const raw = await read(
+        await fetcher(url(dataset), { ...signal ? { signal } : {} })
+      );
+      if (!Array.isArray(raw))
+        throw new Error("Invalid computed column catalogue.");
+      return raw.map(validateComputedColumn);
+    },
+    async save(dataset, column, expectedRevision) {
+      const result = validateComputedColumn(
+        await read(
+          await fetcher(url(dataset), {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ column, expectedRevision })
+          })
+        )
+      );
+      listeners.get(dataset)?.forEach((fn) => fn());
+      return result;
+    },
+    subscribe(dataset, listener) {
+      const set = listeners.get(dataset) ?? /* @__PURE__ */ new Set();
+      set.add(listener);
+      listeners.set(dataset, set);
+      return () => {
+        set.delete(listener);
+      };
+    }
+  };
+}
+function isComputedCellError(value) {
+  return value !== null && typeof value === "object" && "computedError" in value && typeof value.computedError === "string";
+}
+function groupPreview(dependencies, inputs, results, total) {
+  const groups = /* @__PURE__ */ new Map();
+  let nulls = 0, errors = 0;
+  inputs.forEach((row, i) => {
+    const values = dependencies.map((name) => row[name] ?? null), result = results[i] ?? { value: null, error: "No result." };
+    const key = JSON.stringify([values, result.value, result.error ?? null]);
+    const group = groups.get(key);
+    if (group) group.count++;
+    else groups.set(key, { inputs: values, result, count: 1 });
+    if (result.error) errors++;
+    else if (result.value === null) nulls++;
+  });
+  return {
+    dependencies,
+    groups: [...groups.values()].sort((a, b) => b.count - a.count),
+    processed: inputs.length,
+    total,
+    nulls,
+    errors
+  };
 }
 
 // src/formula.ts
@@ -2089,6 +2907,455 @@ function formulaRuntime(ast, inputs, extension) {
   }
 }
 
+// src/grouping.ts
+var GROUP_ID_FIELD = "__qt_group_id__";
+var MAX_REPRESENTATIVE_SORTS = 8;
+var MAX_SUMMARY_COLUMNS = 64;
+var MAX_RESULT_GROUPS = 1e4;
+function withoutGrouping(query) {
+  const { grouping: _grouping, ...result } = query;
+  return result;
+}
+var OP_LABEL = {
+  count: "COUNT",
+  count_distinct: "DISTINCT",
+  sum: "SUM",
+  avg: "AVG",
+  min: "MIN",
+  max: "MAX",
+  row: "ROW",
+  formula: "\u0192x"
+};
+function createGroupingModel(inputSchema) {
+  const sourceField = (name) => inputSchema.fields.find((f2) => f2.name === name);
+  const groupableFields = inputSchema.fields.filter(
+    (field) => isGroupable(field) && isSelectable(field)
+  );
+  const summaryFields = inputSchema.fields.filter(
+    (f2) => f2.type !== "textarray" && isSelectable(f2)
+  );
+  const representativeFields = inputSchema.fields.filter(
+    (field) => isSortable(field) && field.type !== "textarray"
+  );
+  function representativeLabel(rule) {
+    return rule.orderBy.map(
+      (term) => `${sourceField(term.field)?.label ?? term.field} ${term.dir === "asc" ? "\u2191" : "\u2193"}${term.nulls === "first" ? " (empty first)" : ""}`
+    ).join(", ");
+  }
+  function allowedOps(field) {
+    if (!field) return ["count"];
+    const f2 = sourceField(field);
+    return f2 && isSelectable(f2) ? [...isMeasurable(f2) ? aggOpsForField(f2) : [], "row"] : [];
+  }
+  function summaryExpression(column) {
+    if (column.op === "formula") return column.expression ?? "";
+    const field = column.field ? `[${column.field.replace(/\]/g, "]]")}]` : "";
+    return `${column.op === "row" ? "COUNT" : column.op.toUpperCase()}(${field})`;
+  }
+  function summaryProblem(column) {
+    if (column.op !== "formula") return null;
+    try {
+      const plan = compileMetric(summaryExpression(column), inputSchema);
+      if (plan.dependencies.some((name) => !isSelectable(sourceField(name))))
+        throw new Error("Aggregate fields must be selectable.");
+      if (hasRegex(plan))
+        throw new Error(
+          "Regex aggregate formulas require isolated execution and are not supported in grouped columns."
+        );
+      return null;
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+  }
+  function summaryLabel(column) {
+    if (column.op === "formula")
+      return column.label?.trim() || "Custom aggregate";
+    if (!column.field) return "Row count";
+    const label = sourceField(column.field)?.label ?? column.field;
+    const prefix = {
+      count: "Count of",
+      count_distinct: "Distinct",
+      sum: "Total",
+      avg: "Average",
+      min: "Min",
+      max: "Max",
+      row: "Representative \xB7",
+      formula: ""
+    };
+    return `${prefix[column.op]} ${label}`;
+  }
+  function resultSchema(keys, summaries) {
+    const fields = [
+      {
+        name: GROUP_ID_FIELD,
+        label: "Group identity",
+        type: "text",
+        source: { kind: "backend" },
+        select: { enabled: false },
+        filter: { enabled: false },
+        sort: { enabled: false },
+        aggregate: { measure: false, groupable: false }
+      },
+      ...keys.flatMap((key) => {
+        const field = sourceField(key);
+        if (!field) return [];
+        return [{
+          name: key,
+          label: field.label,
+          type: field.type,
+          source: { kind: "backend" },
+          ...field.select ? { select: { ...field.select } } : {},
+          ...field.filter ? { filter: { ...field.filter } } : {},
+          ...field.aggregate ? { aggregate: { ...field.aggregate } } : {},
+          ...field.sort?.enabled !== void 0 ? { sort: { enabled: field.sort.enabled } } : {},
+          ...typeof field.render === "string" ? { render: field.render } : {},
+          ...field.display ? { display: field.display } : {},
+          group: "Group keys"
+        }];
+      })
+    ];
+    for (const column of summaries) {
+      if (column.op === "formula") {
+        let type = "number";
+        try {
+          const compiled = compileMetric(
+            summaryExpression(column),
+            inputSchema
+          );
+          type = compiled.type === "null" ? "number" : compiled.type;
+        } catch {
+        }
+        fields.push({
+          name: column.id,
+          label: summaryLabel(column),
+          type,
+          source: { kind: "backend" },
+          group: "Aggregates",
+          select: { align: type === "number" ? "right" : "left" }
+        });
+        continue;
+      }
+      const input = column.field ? sourceField(column.field) : void 0;
+      const counting = column.op === "count" || column.op === "count_distinct";
+      const numeric = counting || column.op === "sum" || column.op === "avg";
+      const example = column.op === "row";
+      fields.push({
+        name: column.id,
+        label: summaryLabel(column),
+        type: numeric ? "number" : input?.type ?? "number",
+        source: { kind: "backend" },
+        select: {
+          align: numeric || input?.type === "number" ? "right" : "left"
+        },
+        group: example ? "Representative row" : "Summaries",
+        ...!numeric && input?.aggregate?.groupable !== void 0 ? { aggregate: { groupable: input.aggregate.groupable } } : {},
+        ...typeof input?.render === "string" && !counting ? { render: input.render } : {},
+        ...input?.display && !counting ? { display: input.display } : {}
+      });
+    }
+    return {
+      name: `${inputSchema.name}:groups`,
+      idField: GROUP_ID_FIELD,
+      fields,
+      defaultSelect: keys.filter((key) => sourceField(key)).map((field) => ({ field })),
+      defaultLimit: 25
+    };
+  }
+  function keyValue(value) {
+    if (value == null) return null;
+    if (value instanceof Date) return value.toISOString();
+    if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value))
+      return value;
+    throw new Error("Group keys must be finite scalar values.");
+  }
+  function groupId(row, keys, schema) {
+    const tuple = [...keys].sort().map((key) => [
+      key,
+      keyValue(
+        readFieldValue(schema.fields.find((f2) => f2.name === key), row)
+      )
+    ]);
+    if (tuple.some(
+      ([key, value]) => String(key).length + String(value).length > 1e4
+    ))
+      throw new Error("Grouping key length budget exceeded.");
+    const id = JSON.stringify(tuple);
+    if (id.length > 65536)
+      throw new Error("Grouping key length budget exceeded.");
+    return id;
+  }
+  function compare2(a, b) {
+    if (a === b) return 0;
+    if (a == null) return -1;
+    if (b == null) return 1;
+    return a < b ? -1 : 1;
+  }
+  function representative(rows, rule, schema) {
+    const identityField = schema.fields.find(
+      (field) => field.name === schema.idField
+    );
+    const identities = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      const id = identityField ? readFieldValue(identityField, row) : row[schema.idField];
+      if (!(typeof id === "string" || typeof id === "number" && Number.isFinite(id)) || identities.has(id))
+        throw new Error(
+          "Representative rows require unique string or finite numeric source IDs."
+        );
+      identities.add(id);
+    }
+    const order = rule.orderBy.some((term) => term.field === schema.idField) ? rule.orderBy : [
+      ...rule.orderBy,
+      { field: schema.idField, dir: "desc", nulls: "last" }
+    ];
+    const terms = order.map((term) => ({
+      ...term,
+      def: schema.fields.find((field) => field.name === term.field)
+    }));
+    return rows.reduce((best, row) => {
+      for (const term of terms) {
+        const value = (record2) => {
+          const raw = term.def ? readFieldValue(term.def, record2) : record2[schema.idField];
+          if (raw == null || term.def?.type !== "datetime") return raw;
+          const instant = Date.parse(String(raw));
+          return Number.isFinite(instant) ? instant : null;
+        };
+        const a = value(row), b = value(best);
+        if (a == null || b == null) {
+          if (a == null && b == null) continue;
+          return a == null === (term.nulls === "first") ? row : best;
+        }
+        const rank = compare2(a, b);
+        if (rank !== 0)
+          return (term.dir === "asc" ? rank < 0 : rank > 0) ? row : best;
+      }
+      return best;
+    });
+  }
+  function groupRows(rows, schema, keys, summaries, rule = null) {
+    if (!rule && summaries.some((column) => column.op === "row"))
+      throw new Error(
+        "Configure representative-row ordering before selecting row values."
+      );
+    if (keys.length === 0) return [];
+    if (keys.length > MAX_GROUP_BY_FIELDS || summaries.length > MAX_SUMMARY_COLUMNS)
+      throw new Error("Grouping definition exceeds column limits.");
+    if (rows.length > 1e6)
+      throw new Error("Grouping row budget exceeded.");
+    let bytes = rows.length * 16;
+    let operations = 0;
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      const id = groupId(row, keys, schema);
+      const bucket = groups.get(id);
+      if (bucket) bucket.push(row);
+      else {
+        if (groups.size >= MAX_RESULT_GROUPS)
+          throw new Error(
+            `Grouping exceeds ${MAX_RESULT_GROUPS.toLocaleString()} groups.`
+          );
+        bytes += id.length * 2 + 256;
+        if (bytes > 16e6)
+          throw new Error("Grouping retained-memory budget exceeded.");
+        groups.set(id, [row]);
+      }
+    }
+    const formulas = new Map(
+      summaries.filter((c) => c.op !== "row").map((column) => {
+        try {
+          const problem = summaryProblem(column);
+          if (problem) throw new Error(problem);
+          return [
+            column.id,
+            { plan: compileMetric(summaryExpression(column), schema) }
+          ];
+        } catch (error) {
+          return [
+            column.id,
+            { error: error instanceof Error ? error.message : String(error) }
+          ];
+        }
+      })
+    );
+    const nodeCost = (node) => 1 + (node.kind === "call" ? node.args.reduce((cost, child) => cost + nodeCost(child), 0) : 0);
+    const costs = new Map(
+      [...formulas].map(([id, compiled]) => [
+        id,
+        compiled.plan?.aggregates.map(nodeCost) ?? []
+      ])
+    );
+    return [...groups].map(([id, members]) => {
+      const output = Object.assign(/* @__PURE__ */ Object.create(null), {
+        [GROUP_ID_FIELD]: id
+      });
+      for (const key of keys)
+        output[key] = readFieldValue(
+          schema.fields.find((f2) => f2.name === key),
+          members[0]
+        );
+      const chosen = rule && summaries.some((column) => column.op === "row") ? representative(members, rule, schema) : null;
+      for (const column of summaries) {
+        if (column.op !== "row") {
+          const compiled = formulas.get(column.id);
+          if (!compiled.plan) {
+            output[column.id] = { computedError: compiled.error };
+            continue;
+          }
+          const plan = compiled.plan;
+          const rowPlans = metricAggregatePlans(plan);
+          const reductions = plan.aggregates.map(
+            (node, i) => reduceMetricValues(
+              node,
+              members.map((row) => {
+                if ((operations += costs.get(column.id)?.[i] ?? 1) > 1e7)
+                  throw new Error("Grouping operation budget exceeded.");
+                const rowPlan = rowPlans[i];
+                if (!rowPlan) return { value: 1 };
+                const values = Object.fromEntries(
+                  rowPlan.dependencies.map((name) => {
+                    const value = readFieldValue(
+                      schema.fields.find((f2) => f2.name === name),
+                      row
+                    );
+                    return [
+                      name,
+                      value instanceof Date ? value.toISOString() : value ?? null
+                    ];
+                  })
+                );
+                return formulaRuntime(rowPlan.ast, values);
+              })
+            )
+          );
+          const result = evaluateMetricReductions(plan, reductions);
+          output[column.id] = result.error ? { computedError: result.error } : result.value;
+          continue;
+        }
+        const field = schema.fields.find((f2) => f2.name === column.field);
+        if (column.op === "row") {
+          output[column.id] = field && chosen ? readFieldValue(field, chosen) : null;
+          continue;
+        }
+      }
+      return output;
+    });
+  }
+  function filteredInput(rows, query, schema, options2 = {}) {
+    return selectMetricShownRows(
+      rows,
+      {
+        ...withoutGrouping(query),
+        aggregations: [],
+        orderBy: [],
+        offset: 0,
+        limit: Math.max(1, rows.length)
+      },
+      { ...schema, defaultSort: [] },
+      options2
+    );
+  }
+  function reconcileRepresentative(query, summaries, schema, remove) {
+    const affected = new Set(
+      summaries.filter((s) => s.op === "row").map((s) => s.id)
+    );
+    if (!affected.size) return query;
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const f2 of schema.fields) {
+        if (!affected.has(f2.name) && f2.source.kind === "derived" && f2.source.dependencies?.some((name) => affected.has(name))) {
+          affected.add(f2.name);
+          grew = true;
+        }
+      }
+    }
+    return {
+      ...query,
+      offset: 0,
+      select: remove ? query.select.filter((c) => !affected.has(c.field)) : query.select,
+      where: query.where.filter(
+        (term) => !predicatesOf(term).some((p) => affected.has(p.field))
+      ),
+      orderBy: query.orderBy.filter((term) => !affected.has(term.field)),
+      aggregations: (query.aggregations ?? []).filter((metric) => {
+        if (metric.groupBy.some((name) => affected.has(name))) return false;
+        try {
+          return !metricPlans(metric, schema).some(
+            (plan) => plan.dependencies.some((name) => affected.has(name))
+          );
+        } catch {
+          return false;
+        }
+      })
+    };
+  }
+  function validate(definition) {
+    if (definition.diagnostics?.length)
+      throw new Error(definition.diagnostics.join(" "));
+    if (!definition.keys.length || definition.keys.length > MAX_GROUP_BY_FIELDS || new Set(definition.keys).size !== definition.keys.length || definition.keys.some(
+      (key) => key === GROUP_ID_FIELD || !groupableFields.some((f2) => f2.name === key)
+    ))
+      throw new Error("Choose valid group keys from the source schema.");
+    if (definition.summaries.length > MAX_SUMMARY_COLUMNS)
+      throw new Error("Too many aggregate columns.");
+    const ids = /* @__PURE__ */ new Set([
+      GROUP_ID_FIELD,
+      ...inputSchema.fields.map((field) => field.name)
+    ]);
+    for (const column of definition.summaries) {
+      if (!column.id || column.id.length > 256 || ids.has(column.id) || isComputedField(column.id) || ["__proto__", "constructor", "prototype"].includes(column.id))
+        throw new Error(
+          "Aggregate column IDs must be unique and distinct from source fields."
+        );
+      ids.add(column.id);
+      if (column.op === "formula") {
+        const error = summaryProblem(column);
+        if (error) throw new Error(error);
+      } else if (!allowedOps(column.field).includes(column.op) || column.op === "row" && (!column.field || !definition.representative))
+        throw new Error("Invalid aggregate or representative column.");
+    }
+    const rule = definition.representative;
+    if (rule && (!rule.orderBy.length || rule.orderBy.length > MAX_REPRESENTATIVE_SORTS || new Set(rule.orderBy.map((t) => t.field)).size !== rule.orderBy.length || rule.orderBy.some(
+      (t) => !representativeFields.some((f2) => f2.name === t.field) || !["asc", "desc"].includes(t.dir) || !["first", "last"].includes(t.nulls)
+    )))
+      throw new Error("Choose valid representative-row ordering.");
+  }
+  return {
+    inputSchema,
+    sourceField,
+    groupableFields,
+    summaryFields,
+    representativeFields,
+    representativeLabel,
+    allowedOps,
+    summaryExpression,
+    summaryProblem,
+    summaryLabel,
+    resultSchema,
+    groupRows,
+    filteredInput,
+    reconcileRepresentative,
+    validate
+  };
+}
+function prepareGrouping(rows, schema, grouping, options2 = {}) {
+  const model = createGroupingModel(schema);
+  if (grouping.source.grouping)
+    throw new Error("Only one grouping stage is supported.");
+  model.validate(grouping);
+  const inputs = model.filteredInput(rows, grouping.source, schema, options2);
+  return {
+    inputs,
+    rows: model.groupRows(
+      inputs,
+      schema,
+      grouping.keys,
+      grouping.summaries,
+      grouping.representative
+    ),
+    schema: model.resultSchema(grouping.keys, grouping.summaries)
+  };
+}
+
 // src/execution.ts
 function toServerQueryV2(q, schema, execution) {
   const normalized = normalizeQueryState(q), legacy = toServerQuery(normalized, schema);
@@ -2115,7 +3382,7 @@ function toServerQueryV2(q, schema, execution) {
   }
   const select = [...legacy.select];
   for (const c of normalized.select.length ? normalized.select : selectedFields(schema, normalized).map((f2) => ({ field: f2.name })))
-    if (isComputedField(c.field) && requireField(c.field, "select"))
+    if (isComputedField(c.field) && execution.fields[c.field]?.select && requireField(c.field, "select"))
       select.push(c.field);
   const orderBy = [];
   for (const term of normalized.orderBy.length ? normalized.orderBy : schema.defaultSort ?? []) {
@@ -2286,6 +3553,171 @@ function histogramCounts(values, edges) {
   return counts;
 }
 
+// src/metricDates.ts
+import { Temporal } from "temporal-polyfill";
+var METRIC_DATE_INTERVALS = [
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year"
+];
+function metricDateTime(value, timeZone = "UTC") {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(
+    value
+  ))
+    throw Error(
+      "Date grouping requires ISO dates or timestamps with a timezone."
+    );
+  const time = Date.parse(value), month = Number(value.slice(5, 7)), day = Number(value.slice(8, 10));
+  const calendar = /* @__PURE__ */ new Date(0);
+  calendar.setUTCFullYear(Number(value.slice(0, 4)), month, 0);
+  if (!Number.isFinite(time) || month < 1 || month > 12 || day < 1 || day > calendar.getUTCDate())
+    throw Error("Invalid date grouping value.");
+  return value.length === 10 && timeZone !== "UTC" ? Temporal.PlainDate.from(value).toZonedDateTime(timeZone).epochMilliseconds : time;
+}
+function metricOffsetTransition(start, end, timeZone) {
+  if (end <= start) return void 0;
+  const offset = (time) => Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone).offsetNanoseconds;
+  const before = offset(start);
+  if (before === offset(end)) return void 0;
+  while (end - start > 1) {
+    const middle = Math.floor((start + end) / 2);
+    if (offset(middle) === before) start = middle;
+    else end = middle;
+  }
+  return end;
+}
+function metricDateFloor(time, interval, timeZone = "UTC") {
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const floor = time - zoned.minute * 6e4 - zoned.second * 1e3 - zoned.millisecond;
+      return metricOffsetTransition(floor, time, timeZone) ?? floor;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "week") date2 = date2.subtract({ days: date2.dayOfWeek - 1 });
+    if (interval === "month" || interval === "year")
+      date2 = date2.with({ day: 1 });
+    if (interval === "year") date2 = date2.with({ month: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  date.setUTCMinutes(0, 0, 0);
+  if (interval !== "hour") date.setUTCHours(0);
+  if (interval === "week")
+    date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
+  if (interval === "month" || interval === "year") date.setUTCDate(1);
+  if (interval === "year") date.setUTCMonth(0);
+  return date.getTime();
+}
+function metricDateNext(time, interval, timeZone = "UTC") {
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const target = zoned.toPlainDateTime().with({
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+        microsecond: 0,
+        nanosecond: 0
+      }).add({ hours: 1 });
+      let next = target.toZonedDateTime(timeZone).epochMilliseconds;
+      if (next <= time)
+        next = target.toZonedDateTime(timeZone, {
+          disambiguation: "later"
+        }).epochMilliseconds;
+      return metricOffsetTransition(time, next, timeZone) ?? next;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "month") date2 = date2.with({ day: 1 }).add({ months: 1 });
+    else if (interval === "year")
+      date2 = date2.with({ month: 1, day: 1 }).add({ years: 1 });
+    else if (interval === "week")
+      date2 = date2.subtract({ days: date2.dayOfWeek - 1 }).add({ weeks: 1 });
+    else date2 = date2.add({ days: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  if (interval === "hour") date.setUTCHours(date.getUTCHours() + 1);
+  else if (interval === "month") date.setUTCMonth(date.getUTCMonth() + 1);
+  else if (interval === "year") date.setUTCFullYear(date.getUTCFullYear() + 1);
+  else date.setUTCDate(date.getUTCDate() + (interval === "week" ? 7 : 1));
+  return date.getTime();
+}
+function customEndTime(value, timeZone = "UTC") {
+  const time = metricDateTime(value, timeZone);
+  return value.length === 10 ? metricDateNext(time, "day", timeZone) - 1 : time;
+}
+function validateDateGrouping(config) {
+  if (typeof config.field !== "string" || !config.field || config.field.length > 256 || !METRIC_DATE_INTERVALS.includes(config.interval) || typeof config.includeEmpty !== "boolean" || !["query", "observed", "custom"].includes(config.range))
+    throw Error("Invalid date grouping definition.");
+  if (config.timeZone !== void 0) {
+    if (typeof config.timeZone !== "string" || !config.timeZone || config.timeZone.length > 80 || /^[+-]/.test(config.timeZone))
+      throw Error(
+        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
+      );
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: config.timeZone });
+    } catch {
+      throw Error(
+        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
+      );
+    }
+  }
+  if (config.includeEmpty && config.range === "custom") {
+    const start = metricDateTime(config.start ?? "", config.timeZone), end = customEndTime(config.end ?? "", config.timeZone);
+    if (end < start)
+      throw Error("The end date must be on or after the start date.");
+  }
+}
+function metricDateRange(config, query, observed, now, canonical) {
+  let min = Infinity, max = -Infinity;
+  for (const time of observed) {
+    min = Math.min(min, time);
+    max = Math.max(max, time);
+  }
+  if (config.range === "observed")
+    return observed.length ? [min, max] : void 0;
+  if (config.range === "custom") {
+    const start2 = metricDateFloor(
+      metricDateTime(config.start ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    const end2 = metricDateFloor(
+      customEndTime(config.end ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    if (observed.length && (start2 > min || end2 < max))
+      throw Error(
+        "Custom date bounds must include all observed buckets. Narrow the query filters to exclude data."
+      );
+    return [start2, end2];
+  }
+  let start = -Infinity, end = Infinity;
+  for (const term of query.where) {
+    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(config.field))
+      continue;
+    if (!["=", ">", ">=", "<", "<="].includes(term.op)) continue;
+    const time = Number(coerceValue("datetime", term.value, now));
+    if (term.op === ">" || term.op === ">=" || term.op === "=")
+      start = Math.max(start, time + (term.op === ">" ? 1 : 0));
+    if (term.op === "<" || term.op === "<=" || term.op === "=")
+      end = Math.min(end, time - (term.op === "<" ? 1 : 0));
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end))
+    throw Error(
+      "Include empty dates needs a bounded date filter. Choose observed dates or a custom range."
+    );
+  if (end < start) return void 0;
+  return [
+    metricDateFloor(start, config.interval, config.timeZone),
+    metricDateFloor(end, config.interval, config.timeZone)
+  ];
+}
+
 // src/metrics.ts
 var aggregates = /* @__PURE__ */ new Set([
   "COUNT",
@@ -2293,8 +3725,29 @@ var aggregates = /* @__PURE__ */ new Set([
   "SUM",
   "AVG",
   "MIN",
-  "MAX"
+  "MAX",
+  "MEDIAN"
 ]);
+var METRIC_FUNCTIONS = [
+  ["COUNT", "Count rows, or non-empty values."],
+  ["COUNT_DISTINCT", "Count distinct non-empty values."],
+  ["SUM", "Total numeric values in each group."],
+  ["AVG", "Average numeric values in each group."],
+  ["MIN", "Smallest non-empty value in each group."],
+  ["MAX", "Largest non-empty value in each group."],
+  [
+    "MEDIAN",
+    "Middle numeric value; averages the middle pair. Ignores empty values."
+  ]
+].map(([name, description]) => ({
+  name,
+  description,
+  signature: `${name}(row expression${name === "COUNT" ? "?" : ""})`,
+  min: name === "COUNT" ? 0 : 1,
+  max: 1,
+  result: name === "MIN" || name === "MAX" ? "branch" : "number",
+  args: ["SUM", "AVG", "MEDIAN"].includes(name) ? ["number"] : "any"
+}));
 function compileMetric(expression, schema, resolve) {
   const fields = Array.isArray(schema) ? schema : schema.fields;
   const nodes = [];
@@ -2336,7 +3789,7 @@ function compileMetric(expression, schema, resolve) {
               n.from,
               n.to
             );
-          if (!isMeasurable(field) || (field.aggregate?.ops !== void 0 || node.args[0] === n) && !aggOpsForField(field).includes(node.name.toLowerCase()))
+          if (!isMeasurable(field) || (field.aggregate?.ops !== void 0 || node.args[0] === n && node.name !== "MEDIAN") && !aggOpsForField(field).includes(node.name.toLowerCase()))
             throw new FormulaError(
               `Field ${n.name} does not allow ${node.name}.`,
               n.from,
@@ -2353,7 +3806,7 @@ function compileMetric(expression, schema, resolve) {
         }
       };
       node.args.forEach(visit);
-      if (["SUM", "AVG"].includes(node.name) && !["number", "null"].includes(type))
+      if (["SUM", "AVG", "MEDIAN"].includes(node.name) && !["number", "null"].includes(type))
         throw new FormulaError(
           `${node.name} requires numeric input.`,
           node.from,
@@ -2367,7 +3820,9 @@ function compileMetric(expression, schema, resolve) {
         );
       nodes.push(node);
       aggregateTypes.push(type);
-      return ["COUNT", "COUNT_DISTINCT", "SUM", "AVG"].includes(node.name) ? "number" : type;
+      return ["COUNT", "COUNT_DISTINCT", "SUM", "AVG", "MEDIAN"].includes(
+        node.name
+      ) ? "number" : type;
     }
   );
   const groupCheck = (node) => {
@@ -2410,11 +3865,11 @@ function metricAggregatePlans(plan) {
     };
   });
 }
-function distinctAccumulator(options) {
+function distinctAccumulator(options2) {
   const values = /* @__PURE__ */ new Set();
   let bytes = 0;
-  const cardinality = options.maxDistinctValues ?? 1e5;
-  const byteLimit = options.maxDistinctBytes ?? 16e6;
+  const cardinality = options2.maxDistinctValues ?? 1e5;
+  const byteLimit = options2.maxDistinctBytes ?? 16e6;
   if (!Number.isSafeInteger(cardinality) || cardinality < 0 || !Number.isSafeInteger(byteLimit) || byteLimit < 0)
     throw Error("Invalid distinct budget.");
   return {
@@ -2431,13 +3886,13 @@ function distinctAccumulator(options) {
     result: () => ({ value: values.size })
   };
 }
-function reduceMetricValues(node, results, options = {}) {
-  return reduceResults(node, results, options);
+function reduceMetricValues(node, results, options2 = {}) {
+  return reduceResults(node, results, options2);
 }
-function reduceResults(node, results, options) {
+function reduceResults(node, results, options2) {
   try {
     if (!aggregates.has(node.name)) throw Error("Expected an aggregate node.");
-    const distinct = node.name === "COUNT_DISTINCT" ? distinctAccumulator(options) : void 0;
+    const distinct = node.name === "COUNT_DISTINCT" ? distinctAccumulator(options2) : void 0;
     const values = [];
     let count = 0, nonnull = 0, error;
     for (const r of results) {
@@ -2458,6 +3913,17 @@ function reduceResults(node, results, options) {
     if (node.name === "COUNT")
       return { value: node.args.length ? nonnull : count };
     if (!values.length) return { value: null };
+    if (node.name === "MEDIAN") {
+      const sorted = values.map((value2) => {
+        if (typeof value2 !== "number" || !Number.isFinite(value2))
+          throw Error("Expected a finite number.");
+        return value2;
+      }).sort((a, b) => a - b);
+      const mid = Math.floor(sorted.length / 2);
+      const value = sorted.length % 2 ? sorted[mid] : sorted[mid - 1] / 2 + sorted[mid] / 2;
+      assertMetricNumber(value);
+      return { value };
+    }
     if (node.name === "SUM" || node.name === "AVG") {
       let sum = 0;
       for (const v of values) {
@@ -2559,6 +4025,18 @@ function validateMetric(c, schema, resolve) {
       if (!f2 || !isGroupable(f2))
         throw new FormulaError(`Field ${key} cannot group metrics.`);
     }
+    if (c.dateGrouping) {
+      validateDateGrouping(c.dateGrouping);
+      const field = resolveFieldName(schema, c.dateGrouping.field) ?? c.dateGrouping.field;
+      if (field !== (resolveFieldName(schema, c.groupBy[0] ?? "") ?? c.groupBy[0]) || schema.fields.find((f2) => f2.name === field)?.type !== "datetime")
+        throw new FormulaError(
+          "Date grouping must use the first grouping field, with a datetime type."
+        );
+      if (distributionActive(c))
+        throw new FormulaError(
+          "Date grouping currently supports scalar metrics, not distributions."
+        );
+    }
     if (c.groupLimit !== void 0 && (!Number.isInteger(c.groupLimit) || c.groupLimit < 1 || c.groupLimit > 1e4))
       throw new FormulaError("Group limit must be 1\u201310,000.");
     for (const s of c.sort ?? []) {
@@ -2603,6 +4081,7 @@ function metricComputationKey(clauses) {
       expressionY: c.display?.kind === "scatter" ? c.expressionY : void 0,
       scope: c.scope ?? "allMatching",
       groupBy: c.groupBy,
+      dateGrouping: c.dateGrouping,
       sort: c.sort,
       groupLimit: c.groupLimit,
       distribution: distributionActive(c) ? c.distribution : void 0
@@ -2648,6 +4127,7 @@ function toMetricQuery(q, schema, execution) {
       distribution,
       expression,
       expressionY,
+      dateGrouping,
       ...rest
     } = c;
     return {
@@ -2667,6 +4147,15 @@ function toMetricQuery(q, schema, execution) {
       code: "invalid_metric"
     }))
   );
+  for (const c of q.aggregations ?? [])
+    if (c.dateGrouping)
+      diagnostics.push({
+        metricId: c.id,
+        code: "unsupported_date_grouping",
+        from: 0,
+        to: 1,
+        message: "Date grouping currently requires local metric execution."
+      });
   try {
     assertMetricQueryState(raw, originalSchema);
   } catch (e) {
@@ -2774,24 +4263,23 @@ function assertMetricQueryState(q, schema) {
   if (queryStateKey(q.where) !== queryStateKey(normalized.where) || queryStateKey(orderBy) !== queryStateKey(normalizedOrder) || q.limit !== normalized.limit || q.offset !== normalized.offset)
     throw Error("Malformed metric query state cannot be executed exactly.");
 }
-function selectMetricShownRows(rows, q, schema, options = {}) {
-  if (options.signal?.aborted) throw Error("Metric evaluation cancelled.");
+function selectMetricShownRows(rows, q, schema, options2 = {}) {
+  if (options2.signal?.aborted) throw Error("Metric evaluation cancelled.");
   assertMetricQueryState(q, schema);
-  if (options.shownRows) return options.shownRows;
+  if (options2.shownRows) return options2.shownRows;
   const orderBy = q.orderBy.length ? q.orderBy : schema.defaultSort ?? [];
   assertMetricPopulation(q, schema, orderBy);
-  if (rows.length > (options.maxRows ?? 1e6))
+  if (rows.length > (options2.maxRows ?? 1e6))
     throw Error("Metric row budget exceeded.");
-  if ((options.maxOperations ?? 1e7) <= 0)
+  if ((options2.maxOperations ?? 1e7) <= 0)
     throw Error("Metric operation budget exceeded.");
   return applyQuery(
     rows,
-    {
-      ...q,
-      orderBy: orderBy.some((s) => s.field === schema.idField) ? orderBy : [...orderBy, { field: schema.idField, dir: "asc" }]
-    },
+    // Local tables use a stable sort: ties retain input order. An extra ID
+    // sort here would choose a different page than the one the table shows.
+    { ...q, orderBy },
     schema,
-    options
+    options2
   ).rows;
 }
 function assertMetricPopulation(q, schema, orderBy) {
@@ -2806,12 +4294,12 @@ function assertMetricPopulation(q, schema, orderBy) {
     );
   if (q.where.some(
     (t) => predicatesOf(t).some(
-      (p) => isComputedField(p.field) || !fields.has(resolveFieldName(schema, p.field) ?? p.field)
+      (p) => isComputedField(p.field) && !computedInputAllowed(schema, p.field, "filter") || !fields.has(resolveFieldName(schema, p.field) ?? p.field)
     )
   ))
     throw Error("Metric filter references an unavailable field.");
   if (orderBy.some(
-    (s) => isComputedField(s.field) || !fields.has(resolveFieldName(schema, s.field) ?? s.field)
+    (s) => isComputedField(s.field) && !computedInputAllowed(schema, s.field, "sort") || !fields.has(resolveFieldName(schema, s.field) ?? s.field)
   ))
     throw Error("Shown-row ordering requires an authoritative committed page.");
 }
@@ -2854,39 +4342,53 @@ function compareMetricValues(a, b) {
   }
   return a < b ? -1 : 1;
 }
-function evaluateMetrics(rows, q, schema, options = {}) {
-  const now = evaluationTime(options), fields = indexFields(schema);
+function evaluateMetrics(rows, q, schema, options2 = {}) {
+  if (q.grouping) {
+    try {
+      if (options2.signal?.aborted) throw new Error("Metric evaluation cancelled.");
+      if (rows.length > (options2.maxRows ?? 1e6)) throw new Error("Metric row budget exceeded.");
+      const now2 = evaluationTime(options2);
+      const prepared = prepareGrouping(rows, schema, q.grouping, { now: now2 });
+      return evaluateMetrics(prepared.rows, withoutGrouping(q), prepared.schema, {
+        ...options2,
+        now: now2
+      });
+    } catch (error) {
+      return { metrics: (q.aggregations ?? []).map((metric) => ({ id: metric.id, buckets: [], error: error instanceof Error ? error.message : String(error) })) };
+    }
+  }
+  const now = evaluationTime(options2), fields = indexFields(schema);
   let matching;
   let shown;
   return {
     metrics: (q.aggregations ?? []).map((c) => {
-      let budget = options.maxOperations ?? 1e7;
+      let budget = options2.maxOperations ?? 1e7;
       const tick = () => {
         if (--budget < 0) throw Error("Metric operation budget exceeded.");
-        if (options.signal?.aborted)
+        if (options2.signal?.aborted)
           throw Error("Metric evaluation cancelled.");
       };
       try {
-        if (options.signal?.aborted)
+        if (options2.signal?.aborted)
           throw Error("Metric evaluation cancelled.");
         assertMetricQueryState(q, schema);
         if ((q.aggregations?.length ?? 0) > 20)
           throw Error("At most 20 metrics are allowed.");
-        const diagnostics = validateMetric(c, schema, options.resolveComputed);
+        const diagnostics = validateMetric(c, schema, options2.resolveComputed);
         if (diagnostics.length)
           throw Error(diagnostics.map((d) => d.message).join(" "));
-        const ps = metricPlans(c, schema, options.resolveComputed);
-        if (ps.some(hasRegex) && !options.evaluateInput)
+        const ps = metricPlans(c, schema, options2.resolveComputed);
+        if (ps.some(hasRegex) && !options2.evaluateInput)
           throw Error(
             "Regex metrics require an isolated worker with a watchdog."
           );
         let inputRows;
         if (c.scope === "shownRows")
-          inputRows = shown ?? (shown = selectMetricShownRows(rows, q, schema, options));
+          inputRows = shown ?? (shown = selectMetricShownRows(rows, q, schema, options2));
         else {
           if (!matching) {
             assertMetricPopulation(q, schema, []);
-            if (rows.length > (options.maxRows ?? 1e6))
+            if (rows.length > (options2.maxRows ?? 1e6))
               throw Error("Metric row budget exceeded.");
             matching = applyQuery(
               rows,
@@ -2897,10 +4399,10 @@ function evaluateMetrics(rows, q, schema, options = {}) {
           }
           inputRows = matching;
         }
-        if (inputRows.length > (options.maxRows ?? 1e6))
+        if (inputRows.length > (options2.maxRows ?? 1e6))
           throw Error("Metric row budget exceeded.");
         const groups = /* @__PURE__ */ new Map();
-        const keyLimit = options.maxGroupKeyLength ?? 65536, byteLimit = options.maxGroupBytes ?? 16e6;
+        const keyLimit = options2.maxGroupKeyLength ?? 65536, byteLimit = options2.maxGroupBytes ?? 16e6;
         if (![keyLimit, byteLimit].every((v) => Number.isSafeInteger(v) && v >= 0))
           throw Error("Invalid grouping budget.");
         let groupBytes = 0;
@@ -2915,6 +4417,8 @@ function evaluateMetrics(rows, q, schema, options = {}) {
           groupBytes = 256;
           groups.set("[]", { keys: [], rows: [] });
         }
+        let dateStart = Infinity, dateEnd = -Infinity, dateKey = "";
+        let dateInput, dateTime = NaN;
         for (const row of inputRows) {
           tick();
           if (!c.groupBy.length) {
@@ -2931,6 +4435,27 @@ function evaluateMetrics(rows, q, schema, options = {}) {
               )
             )
           );
+          if (c.dateGrouping && keys[0] !== null) {
+            const config = c.dateGrouping;
+            if (keys[0] !== dateInput) {
+              dateTime = metricDateTime(keys[0], config.timeZone);
+              dateInput = keys[0];
+            }
+            if (dateTime < dateStart || dateTime >= dateEnd) {
+              dateStart = metricDateFloor(
+                dateTime,
+                config.interval,
+                config.timeZone
+              );
+              dateEnd = metricDateNext(
+                dateStart,
+                config.interval,
+                config.timeZone
+              );
+              dateKey = new Date(dateStart).toISOString();
+            }
+            keys[0] = dateKey;
+          }
           let keyLength = 1, payloadBytes = 0;
           for (const value of keys) {
             keyLength += 1 + (typeof value === "string" ? groupStringLength(value, keyLimit - keyLength - 1) : value === null ? 4 : typeof value === "boolean" ? value ? 4 : 5 : String(value).length);
@@ -2943,7 +4468,7 @@ function evaluateMetrics(rows, q, schema, options = {}) {
           const key = JSON.stringify(keys);
           let g = groups.get(key);
           if (!g) {
-            if (groups.size >= (options.maxGroups ?? 1e4))
+            if (groups.size >= (options2.maxGroups ?? 1e4))
               throw Error("Metric group budget exceeded.");
             g = { keys, rows: [] };
             groups.set(key, g);
@@ -2952,6 +4477,68 @@ function evaluateMetrics(rows, q, schema, options = {}) {
           groupBytes += 16;
           g.rows.push(row);
         }
+        if (c.dateGrouping?.includeEmpty) {
+          const config = c.dateGrouping;
+          const observed = [];
+          const series = /* @__PURE__ */ new Map();
+          for (const group of groups.values())
+            if (group.keys[0] !== null) {
+              tick();
+              reserve(8);
+              groupBytes += 8;
+              observed.push(metricDateTime(group.keys[0]));
+              const tuple = group.keys.slice(1);
+              const key = JSON.stringify(tuple);
+              if (!series.has(key)) {
+                const bytes = 128 + 16 * tuple.length + 2 * key.length;
+                reserve(bytes);
+                groupBytes += bytes;
+                series.set(key, tuple);
+              }
+            }
+          if (c.groupBy.length === 1 && !series.size) {
+            reserve(132);
+            groupBytes += 132;
+            series.set("[]", []);
+          }
+          const range = metricDateRange(
+            config,
+            q,
+            observed,
+            now,
+            (name) => resolveFieldName(schema, name) ?? name
+          );
+          if (range)
+            for (let time = range[0]; time <= range[1]; ) {
+              tick();
+              for (const tuple of series.values()) {
+                tick();
+                const keys = [
+                  new Date(time).toISOString(),
+                  ...tuple
+                ];
+                const key = JSON.stringify(keys);
+                if (key.length > keyLimit)
+                  throw Error("Metric grouping key length budget exceeded.");
+                if (!groups.has(key)) {
+                  if (groups.size >= (options2.maxGroups ?? 1e4))
+                    throw Error("Metric group budget exceeded.");
+                  const bytes = 256 + 16 * keys.length + 4 * key.length;
+                  reserve(bytes);
+                  groupBytes += bytes;
+                  groups.set(key, { keys, rows: [] });
+                }
+              }
+              const next = metricDateNext(
+                time,
+                config.interval,
+                config.timeZone
+              );
+              if (!Number.isFinite(next) || next <= time)
+                throw Error("Date grouping exceeds calendar limits.");
+              time = next;
+            }
+        }
         const inputs = (row, p) => Object.fromEntries(
           p.dependencies.map((name) => [
             name,
@@ -2972,7 +4559,13 @@ function evaluateMetrics(rows, q, schema, options = {}) {
         const rowEval = (node, row, p) => {
           budget -= cost(node);
           tick();
-          return options.evaluateInput && hasRegex({ ...p, ast: node }) ? options.evaluateInput(node, row, p) : formulaRuntime(node, inputs(row, p));
+          if (node.kind === "field") {
+            const value = readFieldValue(fields.get(node.name), row);
+            return formulaRuntime(node, {
+              [node.name]: value instanceof Date ? value.toISOString() : value ?? null
+            });
+          }
+          return options2.evaluateInput && hasRegex({ ...p, ast: node }) ? options2.evaluateInput(node, row, p) : formulaRuntime(node, inputs(row, p));
         };
         const reduce = (p, rs, inputErrors) => {
           const cache = /* @__PURE__ */ new Map();
@@ -2990,7 +4583,7 @@ function evaluateMetrics(rows, q, schema, options = {}) {
                     yield v;
                   }
                 }
-                result = reduceResults(node, results(), options);
+                result = reduceResults(node, results(), options2);
               } catch (e) {
                 result = {
                   value: null,
@@ -3023,6 +4616,12 @@ function evaluateMetrics(rows, q, schema, options = {}) {
             }
             populations.set(bucket, values);
           } else {
+            if (c.dateGrouping && !g.rows.length) {
+              const empty2 = (p) => p.ast.kind === "call" && ["COUNT", "COUNT_DISTINCT", "SUM"].includes(p.ast.name) ? 0 : null;
+              bucket.value = empty2(ps[0]);
+              if (ps[1]) bucket.y = empty2(ps[1]);
+              return bucket;
+            }
             const inputErrors = /* @__PURE__ */ new Set();
             const x = reduce(ps[0], g.rows, inputErrors);
             bucket.value = scalar(x.value);
@@ -3064,7 +4663,7 @@ function evaluateMetrics(rows, q, schema, options = {}) {
             }
           }
         }
-        const ordering = c.sort?.length ? c.sort : [{ key: "value", dir: "desc", nulls: "last" }];
+        const ordering = c.sort?.length ? c.sort : c.dateGrouping ? [{ key: "group0", dir: "asc", nulls: "last" }] : [{ key: "value", dir: "desc", nulls: "last" }];
         const target = (b, s) => s.key === "samples" ? b.count - (b.nullCount ?? 0) - (b.inputErrorCount ?? 0) : s.key.startsWith("group") ? b.keys[Number(s.key.slice(5))] ?? null : s.key === "count" ? b.count : s.key === "y" ? b.y ?? null : b.value;
         buckets.sort((a, b) => {
           if (!!(a.error || a.yError) !== !!(b.error || b.yError))
@@ -3119,13 +4718,17 @@ function evaluateMetrics(rows, q, schema, options = {}) {
 }
 
 // src/apply.ts
-function applyQuery(rows, q, schema, options = {}) {
-  const now = evaluationTime(options);
+function applyQuery(rows, q, schema, options2 = {}) {
+  const now = evaluationTime(options2);
+  if (q.grouping) {
+    const grouped = prepareGrouping(rows, schema, q.grouping, { now });
+    return applyQuery(grouped.rows, withoutGrouping(q), grouped.schema, { now });
+  }
   const byName = indexFields(schema);
   const resolveField2 = (name) => resolveFieldName(schema, name) ?? name;
-  const whereTerms = q.where.filter((term) => !predicatesOf(term).some((c) => isComputedField(c.field))).map((term) => prepareWhereTerm(term, resolveField2, now));
+  const whereTerms = q.where.filter((term) => !predicatesOf(term).some((c) => isComputedField(c.field) && !computedInputAllowed(schema, c.field, "filter"))).map((term) => prepareWhereTerm(term, resolveField2, now));
   prepareDatetimePredicates(whereTerms, byName);
-  const orderBy = q.orderBy.filter((term) => !isComputedField(term.field)).map((term) => ({ ...term, field: resolveField2(term.field) }));
+  const orderBy = q.orderBy.filter((term) => !isComputedField(term.field) || computedInputAllowed(schema, term.field, "sort")).map((term) => ({ ...term, field: resolveField2(term.field) }));
   let out = rows.filter(
     (row) => whereTerms.every((term) => matchesTerm(byName, row, term))
   );
@@ -3159,42 +4762,47 @@ function applyQuery(rows, q, schema, options = {}) {
   const end = q.limit > 0 ? start + q.limit : out.length;
   return { rows: out.slice(start, end), total };
 }
-function matchesClause(row, clause, schema, options = {}) {
+function computedInputAllowed(schema, name, operation) {
+  const field = schema.fields.find((field2) => field2.name === name);
+  return !!field && (field.source.kind === "backend" && field[operation]?.enabled !== false || field[operation]?.enabled === true);
+}
+function matchesClause(row, clause, schema, options2 = {}) {
   const field = resolveFieldName(schema, clause.field) ?? clause.field;
   const byName = indexFields(schema);
   const prepared = prepareWhereClause(
     { ...clause, field },
-    evaluationTime(options)
+    evaluationTime(options2)
   );
   prepareDatetimePredicates([{ kind: "lit", predicate: prepared }], byName);
   return matchesWith(byName, row, prepared);
 }
-function applyAggregations(rows, q, schema, options = {}) {
-  if (options.signal?.aborted || q.where.some(
+function applyAggregations(rows, q, schema, options2 = {}) {
+  if (q.grouping) return evaluateMetrics(rows, q, schema, options2);
+  if (options2.signal?.aborted || q.where.some(
     (t) => predicatesOf(t).some(
       (p) => p.op === "matches_regex" || p.op === "not_matches_regex"
     )
   ))
-    return evaluateMetrics(rows, q, schema, options);
+    return evaluateMetrics(rows, q, schema, options2);
   const advanced = (q.aggregations ?? []).filter(
-    (a) => a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.scope !== void 0 || a.distribution || a.sort || a.groupLimit !== void 0
+    (a) => a.dateGrouping || a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.scope !== void 0 || a.distribution || a.sort || a.groupLimit !== void 0
   );
   if (advanced.length) {
     if ((q.aggregations?.length ?? 0) > 20 || normalizeQueryState(q).aggregations?.length !== q.aggregations?.length)
-      return evaluateMetrics(rows, q, schema, options);
+      return evaluateMetrics(rows, q, schema, options2);
     const legacy = (q.aggregations ?? []).filter((a) => !advanced.includes(a));
     const results = [
       ...evaluateMetrics(
         rows,
         { ...q, aggregations: advanced },
         schema,
-        options
+        options2
       ).metrics,
       ...legacy.length ? applyAggregations(
         rows,
         { ...q, aggregations: legacy },
         schema,
-        options
+        options2
       ).metrics : []
     ];
     const byId = new Map(results.map((result) => [result.id, result]));
@@ -3202,7 +4810,7 @@ function applyAggregations(rows, q, schema, options = {}) {
       metrics: (q.aggregations ?? []).flatMap((a) => byId.get(a.id) ?? [])
     };
   }
-  const now = evaluationTime(options);
+  const now = evaluationTime(options2);
   const byName = indexFields(schema);
   const resolveField2 = (name) => resolveFieldName(schema, name) ?? name;
   const whereTerms = q.where.filter((term) => !predicatesOf(term).some((c) => isComputedField(c.field))).map((term) => prepareWhereTerm(term, resolveField2, now));
@@ -3491,7 +5099,13 @@ function normalizeSavedQuery(value) {
   if (typeof raw.id !== "string" || !raw.id || raw.id.length > 256 || typeof raw.name !== "string" || !raw.name || raw.name.length > MAX_SAVED_NAME_LENGTH || typeof raw.savedAt !== "number" || !Number.isFinite(raw.savedAt) || raw.query == null || typeof raw.query !== "object") {
     return null;
   }
-  return { id: raw.id, name: raw.name, savedAt: raw.savedAt, query: normalizeQueryState(raw.query) };
+  return {
+    id: raw.id,
+    name: raw.name,
+    savedAt: raw.savedAt,
+    query: normalizeQueryState(raw.query),
+    ...typeof raw.snapshotCode === "string" ? { snapshotCode: raw.snapshotCode } : {}
+  };
 }
 function normalizeSavedQueries(value) {
   if (!Array.isArray(value)) return [];
@@ -3524,7 +5138,7 @@ function memoryStorageAdapter() {
       if (!(saved.get(key) ?? []).some((item) => item.id === id)) throw new Error(`Saved query "${id}" does not exist.`);
       defaults.set(key, id);
     },
-    async saveNamed(key, name, query, savedAt) {
+    async saveNamed(key, name, query, savedAt, snapshotCode) {
       const normalizedName = name.trim();
       if (!normalizedName || normalizedName.length > MAX_SAVED_NAME_LENGTH) {
         throw new Error(`Saved query name must be between 1 and ${MAX_SAVED_NAME_LENGTH} characters.`);
@@ -3533,6 +5147,7 @@ function memoryStorageAdapter() {
       if (items.length >= MAX_SAVED_QUERIES) throw new Error(`At most ${MAX_SAVED_QUERIES} saved queries are allowed.`);
       if (items.some((item2) => item2.name === normalizedName)) throw new Error(`Saved query "${normalizedName}" already exists.`);
       const item = {
+        ...snapshotCode ? { snapshotCode } : {},
         id: `${savedAt}-${Math.round((savedAt * 9301 + 49297) % 233280)}`,
         name: normalizedName,
         savedAt,
@@ -3541,6 +5156,20 @@ function memoryStorageAdapter() {
       saved.set(key, [...items, item]);
       return item;
     },
+    async updateNamed(key, id, query, savedAt, snapshotCode) {
+      const items = saved.get(key) ?? [];
+      const original = items.find((item2) => item2.id === id);
+      if (!original) throw new Error(`Saved query "${id}" does not exist.`);
+      const item = {
+        id,
+        name: original.name,
+        savedAt,
+        query: normalizeQueryState(query),
+        ...snapshotCode ? { snapshotCode } : {}
+      };
+      saved.set(key, items.map((entry) => entry.id === id ? item : entry));
+      return item;
+    },
     async deleteSaved(key, id) {
       saved.set(key, (saved.get(key) ?? []).filter((item) => item.id !== id));
       if (defaults.get(key) === id) defaults.delete(key);
@@ -3605,7 +5234,7 @@ function localStorageAdapter() {
       }
       writeDefaultId(key, id);
     },
-    async saveNamed(key, name, query, savedAt) {
+    async saveNamed(key, name, query, savedAt, snapshotCode) {
       const normalizedName = name.trim();
       if (!normalizedName || normalizedName.length > MAX_SAVED_NAME_LENGTH) {
         throw new Error(`Saved query name must be between 1 and ${MAX_SAVED_NAME_LENGTH} characters.`);
@@ -3616,6 +5245,7 @@ function localStorageAdapter() {
         throw new Error(`Saved query "${normalizedName}" already exists.`);
       }
       const item = {
+        ...snapshotCode ? { snapshotCode } : {},
         id: `${savedAt}-${Math.round((savedAt * 9301 + 49297) % 233280)}`,
         name: normalizedName,
         savedAt,
@@ -3625,6 +5255,20 @@ function localStorageAdapter() {
       writeSaved(key, items);
       return item;
     },
+    async updateNamed(key, id, query, savedAt, snapshotCode) {
+      const items = readSaved(key);
+      const original = items.find((item2) => item2.id === id);
+      if (!original) throw new Error(`Saved query "${id}" does not exist.`);
+      const item = {
+        id,
+        name: original.name,
+        savedAt,
+        query: normalizeQueryState(query),
+        ...snapshotCode ? { snapshotCode } : {}
+      };
+      writeSaved(key, items.map((entry) => entry.id === id ? item : entry));
+      return item;
+    },
     async deleteSaved(key, id) {
       writeSaved(
         key,
@@ -3634,6 +5278,248 @@ function localStorageAdapter() {
     }
   };
 }
+
+// src/propertyStorage.ts
+var empty = () => ({ last: null, saved: [], defaultId: null });
+var clone = (saved) => ({
+  ...saved,
+  view: normalizePropertyView(saved.view)
+});
+function jsonPropertyViewStorage(read, write) {
+  const keyFor = (type) => `query-table:properties:${type}`;
+  function load(type) {
+    const value = read(keyFor(type));
+    if (value === null) return empty();
+    const raw = JSON.parse(value);
+    if (!raw || !Array.isArray(raw.saved) || raw.saved.length > 100 || !(raw.defaultId === null || typeof raw.defaultId === "string"))
+      throw new Error("Invalid saved property views.");
+    const saved = raw.saved.map((item) => {
+      if (!item || typeof item.id !== "string" || !item.id || typeof item.name !== "string" || !item.name.trim() || item.name.length > 200 || !Number.isFinite(item.savedAt))
+        throw new Error("Invalid saved property view.");
+      return clone(item);
+    });
+    return {
+      last: raw.last === null ? null : normalizePropertyView(raw.last),
+      saved,
+      defaultId: raw.defaultId
+    };
+  }
+  const store = (type, value) => write(keyFor(type), JSON.stringify(value));
+  return {
+    async loadLast(type) {
+      return load(type).last;
+    },
+    async saveLast(type, view) {
+      const data = load(type);
+      data.last = normalizePropertyView(view);
+      store(type, data);
+    },
+    async listSaved(type) {
+      return load(type).saved;
+    },
+    async saveNamed(type, name, view, savedAt) {
+      name = name.trim();
+      if (!name || name.length > 200 || !Number.isFinite(savedAt))
+        throw new Error(
+          "A view name (1\u2013200 characters) and valid save time are required."
+        );
+      const data = load(type);
+      if (data.saved.some((v) => v.name === name))
+        throw new Error(`A property view named \u201C${name}\u201D already exists.`);
+      if (data.saved.length >= 100)
+        throw new Error("At most 100 saved property views are allowed.");
+      let suffix = 0;
+      while (data.saved.some((v) => v.id === `${savedAt}-${suffix}`)) suffix++;
+      const saved = {
+        id: `${savedAt}-${suffix}`,
+        name,
+        savedAt,
+        view: normalizePropertyView(view)
+      };
+      data.saved.push(saved);
+      store(type, data);
+      return clone(saved);
+    },
+    async deleteSaved(type, id) {
+      const data = load(type);
+      data.saved = data.saved.filter((v) => v.id !== id);
+      if (data.defaultId === id) data.defaultId = null;
+      store(type, data);
+    },
+    async loadDefaultSaved(type) {
+      const data = load(type);
+      return data.saved.find((v) => v.id === data.defaultId) ?? null;
+    },
+    async setDefaultSaved(type, id) {
+      const data = load(type);
+      if (id !== null && !data.saved.some((v) => v.id === id))
+        throw new Error("Unknown property view.");
+      data.defaultId = id;
+      store(type, data);
+    }
+  };
+}
+function memoryPropertyViewStorage() {
+  const values = /* @__PURE__ */ new Map();
+  return jsonPropertyViewStorage(
+    (key) => values.get(key) ?? null,
+    (key, value) => {
+      values.set(key, value);
+    }
+  );
+}
+function localPropertyViewStorage() {
+  return jsonPropertyViewStorage(
+    (key) => localStorage.getItem(key),
+    (key, value) => localStorage.setItem(key, value)
+  );
+}
+
+// src/source.ts
+function sourceDependencies(query, schema, resolveComputed) {
+  const fields = /* @__PURE__ */ new Set([schema.idField]);
+  const addSort = (name) => {
+    fields.add(name);
+    const sortField = schema.fields.find((field) => field.name === name)?.sort?.field;
+    if (sortField) fields.add(sortField);
+  };
+  const source = query.grouping?.source ?? query;
+  for (const term of source.where) for (const predicate of predicatesOf(term)) fields.add(predicate.field);
+  if (query.grouping) {
+    const model = createGroupingModel(schema);
+    model.validate(query.grouping);
+    for (const key of query.grouping.keys) fields.add(key);
+    for (const summary of query.grouping.summaries) {
+      if (summary.op === "row") fields.add(summary.field);
+      else for (const dependency of compileMetric(model.summaryExpression(summary), schema, resolveComputed).dependencies) fields.add(dependency);
+    }
+    for (const term of query.grouping.representative?.orderBy ?? []) addSort(term.field);
+  } else {
+    for (const column of source.select) if (column.field !== ITEM_DETAILS_COLUMN) fields.add(column.field);
+    for (const term of source.orderBy) addSort(term.field);
+    for (const metric of source.aggregations ?? []) for (const dependency of metricDependencies(metric, schema, resolveComputed)) fields.add(dependency);
+  }
+  const base = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const visit = (name) => {
+    if (visiting.has(name)) throw Error("Source dependency cycle.");
+    const field = schema.fields.find((field2) => field2.name === name);
+    if (!field && name === schema.idField) {
+      base.add(name);
+      return;
+    }
+    const dependencies = field?.source.kind === "derived" ? field.source.dependencies : resolveComputed?.(name)?.dependencies;
+    if (!field && !dependencies) throw Error(`Unavailable source dependency: ${name}.`);
+    if (dependencies?.length) {
+      visiting.add(name);
+      for (const dependency of dependencies) visit(dependency);
+      visiting.delete(name);
+    } else base.add(name);
+  };
+  for (const name of fields) visit(name);
+  const paths = Object.fromEntries([...base].map((name) => {
+    const field = schema.fields.find((field2) => field2.name === name);
+    return [name, field?.source.kind === "backend" ? field.source.path ?? name : name];
+  }));
+  return { fields: [...fields].sort(), baseFields: [...base].sort(), identity: schema.idField, paths };
+}
+
+// src/queryV3.ts
+function sourceExecutionSchema(schema, execution, catalogue = []) {
+  const fields = new Map(schema.fields.map((field) => [field.name, field]));
+  for (const [name, capability] of Object.entries(execution?.fields ?? {})) {
+    const definition = catalogue.find((definition2) => name === `@computed/${definition2.id}`);
+    const revision = execution?.resolvedRevisions[name] ?? execution?.resolvedRevisions[name.slice(10)];
+    const current = !!revision && (!definition || definition.revision === revision);
+    fields.set(name, {
+      ...fields.get(name),
+      name,
+      label: definition?.label ?? fields.get(name)?.label ?? name,
+      type: capability.type,
+      source: { kind: "backend" },
+      select: { enabled: current && capability.select },
+      filter: { enabled: current && capability.filter === true },
+      sort: { enabled: current && capability.sort },
+      aggregate: { measure: current && capability.measure, groupable: current && capability.group }
+    });
+  }
+  return { ...schema, fields: [...fields.values()] };
+}
+function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 = {}) {
+  const now = evaluationTime(options2), q = normalizeQueryState(query);
+  const sourceSchema = sourceExecutionSchema(baseSchema, execution);
+  const source = q.grouping?.source ?? withoutGrouping(q);
+  const diagnostics = [];
+  if ((query.aggregations?.length ?? 0) !== (q.aggregations?.length ?? 0)) diagnostics.push("The query exceeds its metric budget or contains malformed metric state.");
+  if (capabilities.version !== 3 || execution && execution.profile !== capabilities.profile) diagnostics.push("The negotiated query profile is unavailable.");
+  let resultSchema = sourceSchema;
+  if (q.grouping) {
+    if (!capabilities.groupedRows) diagnostics.push("This server does not support grouped rows.");
+    try {
+      const model = createGroupingModel(sourceSchema);
+      model.validate(q.grouping);
+      resultSchema = model.resultSchema(q.grouping.keys, q.grouping.summaries);
+    } catch (error) {
+      diagnostics.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const sourceRequest = toServerQuery(withoutGrouping(source), sourceSchema);
+  for (const term of source.where) for (const predicate of predicatesOf(term)) if (["matches_regex", "not_matches_regex"].includes(predicate.op) && !capabilities.regexSourceFilters)
+    diagnostics.push("This server profile does not support isolated regex source filtering.");
+  const result = toServerQuery(withoutGrouping(q), resultSchema);
+  if (sourceRequest.where.length !== source.where.length || result.where.length !== q.where.length) diagnostics.push("The query contains unsupported source or result predicates.");
+  if (result.orderBy.length !== q.orderBy.length) diagnostics.push("The query contains unsupported result ordering.");
+  if (q.grouping) {
+    for (const term of q.grouping.source.where) for (const predicate of predicatesOf(term))
+      if (predicate.field.startsWith("@computed/") && !capabilities.computedSourceFilters) diagnostics.push("This server does not support computed source predicates.");
+  }
+  const metrics = toMetricQuery(withoutGrouping(q), resultSchema, execution).metrics.map((metric) => {
+    const dateGrouping = q.aggregations?.find((clause) => clause.id === metric.id)?.dateGrouping;
+    return dateGrouping ? { ...metric, dateGrouping } : metric;
+  });
+  for (const metric of metrics) {
+    diagnostics.push(...validateMetric(metric, resultSchema).map((issue) => issue.message));
+    if (metric.dateGrouping && !capabilities.calendarGrouping) diagnostics.push("This server does not support calendar grouping.");
+  }
+  const revisions = /* @__PURE__ */ Object.create(null);
+  for (const [id, revision] of Object.entries(execution?.resolvedRevisions ?? {})) {
+    if (!revision || id.length > 256 || revision.length > 256) diagnostics.push("Invalid computed revision envelope.");
+    else revisions[id.startsWith("@computed/") ? id.slice(10) : id] = revision;
+  }
+  return {
+    version: 3,
+    profile: capabilities.profile,
+    now,
+    expectedRevisions: revisions,
+    ...execution?.planToken ? { planToken: execution.planToken } : {},
+    ...execution?.snapshot !== void 0 ? { snapshot: execution.snapshot } : {},
+    source: sourceRequest,
+    result,
+    ...q.grouping ? { grouping: {
+      keys: q.grouping.keys,
+      summaries: q.grouping.summaries,
+      representative: q.grouping.representative,
+      ...q.grouping.diagnostics ? { diagnostics: q.grouping.diagnostics } : {}
+    } } : {},
+    rows: options2.rows !== false,
+    metrics,
+    diagnostics: [...new Set(diagnostics)]
+  };
+}
+function validateQueryResultV3(result, request, schema) {
+  if (!result || result.version !== 3 || result.now !== request.now || !Number.isSafeInteger(result.total) || result.total < 0 || !Number.isSafeInteger(result.sourceTotal) || result.sourceTotal < 0 || !Array.isArray(result.rows) || !Array.isArray(result.metrics) || result.execution?.profile !== request.profile || (result.execution.planToken ?? "") !== (request.planToken ?? "") || (result.execution.snapshot ?? "") !== (request.snapshot ?? "") || result.schema?.idField !== schema.idField)
+    throw Error("Invalid or mismatched query execution response.");
+  const expected = new Map(schema.fields.map((field) => [field.name, field.type]));
+  if (!Array.isArray(result.schema.fields) || result.schema.fields.some((field) => expected.get(field.name) !== field.type) || request.rows && request.result.select.some((name) => !result.schema.fields.some((field) => field.name === name))) throw Error("The server returned a different projected schema.");
+  for (const [id, revision] of Object.entries(request.expectedRevisions)) if (result.execution.resolvedRevisions[id] !== revision)
+    throw Error("Computed definitions changed. Refresh the server execution handshake.");
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of result.rows) {
+    const id = row[schema.idField];
+    if (typeof id !== "string" && typeof id !== "number" || seen.has(id)) throw Error("The server returned invalid or duplicate group identities.");
+    seen.add(id);
+  }
+}
 export {
   AGG_OPS_BY_TYPE,
   AGG_OPS_NEEDING_FIELD,
@@ -3641,17 +5527,29 @@ export {
   EMPTY_QUERY,
   FORMULA_FUNCTIONS,
   FormulaError,
+  GROUP_ID_FIELD,
+  ITEM_DETAILS_COLUMN,
   MAX_AGGREGATIONS,
   MAX_GROUP_BY_FIELDS,
   MAX_ORDER_BY_TERMS,
+  MAX_PROPERTIES,
   MAX_QUERY_LIMIT,
   MAX_QUERY_OFFSET,
+  MAX_QUERY_STATE_BYTES,
   MAX_QUERY_TOKEN_LENGTH,
   MAX_RELATIVE_TIME_MS,
+  MAX_REPRESENTATIVE_SORTS,
+  MAX_RESULT_GROUPS,
   MAX_SELECT_COLUMNS,
+  MAX_SUMMARY_COLUMNS,
   MAX_WHERE_CLAUSES,
+  METRIC_DATE_INTERVALS,
+  METRIC_FUNCTIONS,
   NULLARY_OPS,
   OPS_BY_TYPE,
+  OP_LABEL,
+  QueryDecodeError,
+  QuerySnapshotHttpError,
   aggOpAllowedForType,
   aggOpNeedsField,
   aggOpsForField,
@@ -3663,8 +5561,13 @@ export {
   compileFormula,
   compileMetric,
   computedFieldName,
+  createGroupingModel,
+  createPropertyView,
+  createQueryLinkService,
   createSetFilter,
   decodeQuery,
+  decodeQueryStrict,
+  discoverFieldRelationships,
   encodeQuery,
   evaluateMetricReductions,
   evaluateMetrics,
@@ -3675,6 +5578,7 @@ export {
   histogramCounts,
   histogramEdges,
   httpComputedColumnStore,
+  httpQuerySnapshotStore,
   indexFields,
   isComputedCellError,
   isComputedField,
@@ -3686,38 +5590,62 @@ export {
   isPushdownFilter,
   isSelectable,
   isSortable,
+  itemPageFields,
+  jsonPropertyViewStorage,
   loadSchema,
+  localPropertyViewStorage,
+  localQuerySnapshotCache,
   localStorageAdapter,
   mapSetFilterValues,
   matchesClause,
   memoryComputedColumnStore,
+  memoryPropertyViewStorage,
+  memoryQuerySnapshotCache,
   memoryStorageAdapter,
   metricAggregatePlans,
   metricComputationKey,
+  metricDateFloor,
+  metricDateNext,
+  metricDateRange,
+  metricDateTime,
   metricDependencies,
   metricExpression,
   metricPlans,
   negateClause,
+  normalizePropertyFormat,
+  normalizePropertyView,
   normalizeQueryState,
+  objectReferenceKey,
   opAllowedForType,
   opPairsForField,
   opsForField,
   parseRelativeDuration,
   percentile,
   predicatesOf,
+  prepareGrouping,
   queriesEqual,
   readFieldValue,
+  readObjectReference,
   readSetFilter,
   reduceMetricValues,
+  renderItemPageTemplate,
   resolveFieldName,
   selectMetricShownRows,
   selectedFields,
+  sourceDependencies,
+  sourceExecutionSchema,
   stripSetFilter,
   toAggregationQuery,
   toMetricQuery,
+  toQueryRequestV3,
   toServerQuery,
   toServerQueryV2,
   validateComputedColumn,
-  validateMetric
+  validateDateGrouping,
+  validateItemPageTemplate,
+  validateMetric,
+  validateQueryResultV3,
+  validateQuerySnapshot,
+  withoutGrouping
 };
 //# sourceMappingURL=index.js.map