@sheetxl/query 0.8.0-beta.12 → 0.8.0-beta.14

package/node/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/query - SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface - v0.8.0-beta.12
+* @license @sheetxl/query - SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface - v0.8.0-beta.14
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.
@@ -88,7 +88,7 @@ function j(e) {
 		display: t
 	};
 }
-var M = (e) => "object" == typeof e && null !== e && !n.isError(e) && e.getKind().getName() === t.Type, I = (e) => {
+var M = (e) => "object" == typeof e && null !== e && !n.isError(e) && "function" == typeof e.getKind && e.getKind().getName() === t.Type, I = (e) => {
 	const t = e.getAltText();
 	return t ? `[image: ${e.getSource()} "${t}"]` : `[image: ${e.getSource()}]`;
 }, F = {
@@ -147,9 +147,9 @@ function D(e, t) {
 	const n = t.getCoords(), o = e.evidence, r = (s = e.check, P.get(s) ?? s);
 	var s;
 	switch (e.check) {
-		case O.InconsistentFormula: return `${r} · the cells ${H(o)} have ${J(String(o.expected ?? ""), n)}${B(o)}`;
-		case O.HardcodeInRun: return `${r} · the cells ${H(o)} are formulas${B(o)}`;
-		case O.StyleBreak: return `${o.layer} ${r} · ${o.actual} here, ${o.expected} ${H(o)}${B(o)}`;
+		case O.InconsistentFormula: return `${r} · the cells ${V(o)} have ${J(String(o.expected ?? ""), n)}${B(o)}`;
+		case O.HardcodeInRun: return `${r} · the cells ${V(o)} are formulas${B(o)}`;
+		case O.StyleBreak: return `${o.layer} ${r} · ${o.actual} here, ${o.expected} ${V(o)}${B(o)}`;
 		case O.StyleRole: return `${o.part} ${r} · ${o.actual} on a ${o.role}, ${o.majority} of the sheet's ${o.of} are ${o.expected}`;
 		case O.OmittedCells: return `${r} · ${J(String(o.reference ?? ""), n)} stops before the number in ${J(String(o.omitted ?? ""), n)}`;
 		case O.EmptyCellReference: return `${r} · reads ${J(String(o.reference ?? ""), n)}`;
@@ -164,7 +164,7 @@ function D(e, t) {
 		}
 		case O.MisalignedReference: {
 			const e = void 0 !== o.landsAt && o.landsAt !== o.term ? ` in ${J(String(o.landsAt), n)}` : "";
-			return `${r} · ${J(String(o.term ?? ""), n)}, ${V[String(o.targetRole)] ?? o.targetRole}${e}, beside the block ${J(String(o.block ?? ""), n)}`;
+			return `${r} · ${J(String(o.term ?? ""), n)}, ${H[String(o.targetRole)] ?? o.targetRole}${e}, beside the block ${J(String(o.block ?? ""), n)}`;
 		}
 		case O.ApproximateMatch: return `${r} · ${o.function} match type ${o.matchType}`;
 		case O.LookupShape: return `${r} · reads ${J(String(o.array ?? ""), n)} at a position found in ${J(String(o.vector ?? ""), n)}`;
@@ -203,12 +203,12 @@ function D(e, t) {
 		default: return r;
 	}
 }
-var V = {
+var H = {
 	lineItem: "a line of another block",
 	closingRow: "another block's total",
 	outsideBlocks: "a cell in no block",
 	absolute: "an absolute reference"
-}, H = (e) => "row" === e.axis ? "left and right" : "above and below";
+}, V = (e) => "row" === e.axis ? "left and right" : "above and below";
 function B(e) {
 	const t = [], n = Number(e.thickness ?? 1);
 	n > 1 && t.push(`${n} ${"row" === e.axis ? "columns" : "rows"} wide`), 1 === Number(e.flanks) && t.push("one cell each side");
@@ -679,10 +679,10 @@ var Le = [
 }, Pe = {
 	name: "format",
 	project: (e) => ne(e)
-}, De = [Oe, Pe], Ve = [{
+}, De = [Oe, Pe], He = [{
 	name: "color",
 	project: (e) => Y(e)
-}], He = [{
+}], Ve = [{
 	name: "edges",
 	project: (e) => Q(e)
 }], Be = [
@@ -722,8 +722,8 @@ function _e(e) {
 var Ue = {
 	[Re.Font]: Le,
 	[Re.NumberFormat]: De,
-	[Re.Fill]: Ve,
-	[Re.Borders]: He,
+	[Re.Fill]: He,
+	[Re.Borders]: Ve,
 	[Re.Alignment]: Be
 }, Je = (e) => e in Ue;
 function qe(e, t, n, o) {
@@ -1059,7 +1059,10 @@ function ft(e, t) {
 			const n = t.replace(/\s+/g, " ").trim();
 			return n ? n.length > 60 ? `${n.slice(0, 59)}…` : n : null;
 		};
-		case gt.Spills: return (e) => e.getCell().getSpill()?.getValuesRange().toString() ?? null;
+		case gt.Spills: return (e) => {
+			const t = e.getCell();
+			return "error" === t.getSpillKind() ? null : t.getSpill()?.getValuesRange().toString() ?? null;
+		};
 		case gt.Hyperlink: return (e) => e.getCell().getHyperlink()?.getAddress() ?? null;
 		case gt.Table: return (e) => e.getCell().getTable()?.getName() ?? null;
 		case gt.Fill: return (e) => Y(dt(e));
@@ -1318,7 +1321,7 @@ var Dt = [
 	s.Role.Computed,
 	s.Role.Output
 ];
-function Vt(e, t) {
+function Ht(e, t) {
 	const n = [...t.getRegions([Rt.Role, Rt.Font])];
 	if (0 === n.length) return;
 	const o = t.getWorksheet().getWorkbook()?.getStyles() ?? null, r = (e) => {
@@ -1348,7 +1351,7 @@ function Vt(e, t) {
 		e.blank();
 	}
 }
-function Ht(e, t, n) {
+function Vt(e, t, n) {
 	const o = t.getWorksheet().getWorkbook()?.getStyles().getNormal() ?? null, r = void 0 === n?.features ? null : new Set("string" == typeof n.features ? [n.features] : n.features), s = Nt.filter((e) => !r || r.has(e));
 	if (0 === s.length) return;
 	const l = t.getCounts(s);
@@ -1936,12 +1939,12 @@ function Pn(e, t) {
 var Dn = (e) => {
 	const t = e.getContent();
 	return !0 === t?.isIGroup ? t : null;
-}, Vn = (e) => {
-	const t = Hn(e);
+}, Hn = (e) => {
+	const t = Vn(e);
 	return !0 === t?.isIShape ? In(t.toJSON() ?? {}) : e.getContent().getType();
-}, Hn = (e) => e.getContent(), Bn = (e, t, n) => {
+}, Vn = (e) => e.getContent(), Bn = (e, t, n) => {
 	for (const o of t.getItems()) {
-		const t = Hn(o), r = [Vn(o), t.getName?.() || "(unnamed)"];
+		const t = Vn(o), r = [Hn(o), t.getName?.() || "(unnamed)"];
 		!0 === t.isIPicture && r.push(t.getResource()?.getName?.() || "(no image)");
 		const s = t.getTextFrame?.()?.getText();
 		s && r.push(Mn(s, 120, "")), o.isHidden() && r.push("(hidden)"), e.text(`${"  ".repeat(n + 2)}${r.join(" · ")}`);
@@ -2156,7 +2159,7 @@ var io = (e) => "visible" === e.getVisibility(), co = (e, t, n) => {
 		}
 		default: return null;
 	}
-}, go = ["hyperlink", "numberFormat"], ho = (e, t) => t && "" !== t.trim() ? [{
+}, go = /* @__PURE__ */ new Map([["hyperlink", l.Feature.Hyperlink], ["numberFormat", l.Feature.NumberFormat]]), ho = (e, t) => t && "" !== t.trim() ? [{
 	field: e,
 	text: {
 		match: t,
@@ -2242,14 +2245,14 @@ async function So(t, n) {
 				throw new Error(`Invalid regex ${JSON.stringify(e.pattern)}: ${t instanceof Error ? t.message : String(t)}. Use fixedStrings (-F) to search for the literal text.`);
 			}
 		}
-	})(n), u = co(t, n.scope, a), g = !o.some((e) => go.includes(e)), d = o.includes("display") && o.includes("value"), h = "content" === r || "addresses" === r, f = [], m = [];
-	let p = 0, $ = 0, w = 0, y = !1;
-	const b = (e) => {
+	})(n), u = co(t, n.scope, a), g = o.filter((e) => !go.has(e)), d = o.filter((e) => go.has(e)), h = o.includes("display") && o.includes("value"), f = "content" === r || "addresses" === r, m = [], p = [];
+	let $ = 0, w = 0, y = 0, b = 0, S = !1;
+	const x = (e) => {
 		const t = e.filter((t, n) => c.test(t.text.match) && e.findIndex((e) => e.field === t.field && e.text.display === t.text.display && c.test(e.text.match)) === n);
 		return l ? 0 === t.length && e.length > 0 ? [e[0]] : null : 0 === t.length ? null : "addresses" === r ? t.slice(0, 1) : t;
-	}, S = (e, t, n, o, r) => {
-		if (s > 0 && p + $ >= s) return y = !0, !1;
-		if ("cell" === e ? p++ : $++, h) for (const e of o) f.push({
+	}, k = (e, t, n, o, r, l = 1) => {
+		if (s > 0 && y >= s) return S = !0, !1;
+		if (y++, "cell" === e ? $ += l : w++, f) for (const e of o) m.push({
 			sheet: t,
 			address: n,
 			field: e.field,
@@ -2259,93 +2262,113 @@ async function So(t, n) {
 		return !0;
 	};
 	for (const { sheet: t, address: n } of u) {
-		if (y) continue;
+		if (S) continue;
 		const s = t.getName();
-		w++, await t.getCalculation().ready();
+		b++, await t.getCalculation().ready();
 		const l = null !== n ? t.getRange(n) : t.getUsedRange(), c = l && i && "content" === r ? bo(i, s, l) : null, u = {
 			...null !== n ? { address: n } : {},
 			...a ? {} : { ignoreHidden: !0 }
-		}, h = /* @__PURE__ */ new Map();
+		}, f = /* @__PURE__ */ new Map();
 		if (o.includes("comment")) for (const e of t.getComments().getItems(u)) {
 			const t = e.getRange().getCoords();
-			h.set(`${t.rowStart}:${t.colStart}`, e);
+			f.set(`${t.rowStart}:${t.colStart}`, e);
 		}
-		let f = 0;
-		l?.forEach((e, t) => {
-			if (g && null == e) return;
-			const n = t.getCell(), r = t.getCoords(), l = [];
-			let a;
-			for (const e of o) {
+		let m = 0;
+		g.length > 0 && l?.forEach((e, t) => {
+			if (null == e) return;
+			const n = t.getCell(), o = t.getCoords(), r = [];
+			let l;
+			for (const e of g) {
 				if ("comment" === e) {
-					const e = `${r.rowIndex}:${r.colIndex}`, t = h.get(e);
-					t && (l.push(...fo(t)), h.delete(e));
+					const e = `${o.rowIndex}:${o.colIndex}`, t = f.get(e);
+					t && (r.push(...fo(t)), f.delete(e));
 					continue;
 				}
 				const t = uo(n, e);
-				"display" === e && (a = t?.match ?? null), null !== t && ("value" === e && d && (void 0 === a && (a = uo(n, "display")?.match ?? null), t.match === a) || l.push({
+				"display" === e && (l = t?.match ?? null), null !== t && ("value" === e && h && (void 0 === l && (l = uo(n, "display")?.match ?? null), t.match === l) || r.push({
 					field: e,
 					text: t
 				}));
 			}
-			const i = b(l);
-			if (!i) return;
-			const u = c?.resolve(n, r);
-			if (!S("cell", s, t.getAddress(), i, u)) return { break: !0 };
-			f++;
-		}, a ? void 0 : { ignoreHidden: !0 });
-		const p = [...h.values()].map((e) => ({
+			const a = x(r);
+			if (!a) return;
+			const i = c?.resolve(n, o);
+			if (!k("cell", s, t.getAddress(), a, i)) return { break: !0 };
+			m++;
+		}, { ignoreHidden: !a });
+		const $ = [...f.values()].map((e) => ({
 			comment: e,
 			at: e.getRange().getCoords()
 		})).sort((e, t) => yo(e.at, t.at));
-		for (const { comment: t, at: n } of p) {
-			if (y) break;
-			const o = b(fo(t));
+		for (const { comment: t, at: n } of $) {
+			if (S) break;
+			const o = x(fo(t));
 			if (!o) continue;
 			const r = c?.resolve(t.getRange().getCell(), {
 				rowIndex: n.rowStart,
 				colIndex: n.colStart
 			});
-			S("cell", s, e.rangeToString(n) ?? t.getRange().toString(), o, r) && f++;
+			k("cell", s, e.rangeToString(n) ?? t.getRange().toString(), o, r) && m++;
+		}
+		for (const e of d) {
+			if (S || !l) break;
+			const t = [...l.getRegions(go.get(e), { ignoreHidden: !a })].map((e) => ({
+				region: e,
+				at: e.getCoords()
+			})).sort((e, t) => yo(e.at, t.at));
+			for (const { region: n, at: o } of t) {
+				const t = n.getCell(), r = uo(t, e), l = x(r ? [{
+					field: e,
+					text: r
+				}] : []);
+				if (!l) continue;
+				const a = c?.resolve(t, {
+					rowIndex: o.rowStart,
+					colIndex: o.colStart
+				}), i = (o.rowEnd - o.rowStart + 1) * (o.colEnd - o.colStart + 1);
+				if (!k("cell", s, n.toString(), l, a, i)) break;
+				m += i;
+			}
 		}
-		let $ = 0;
-		if (!y && (o.includes("shape") || o.includes("chart"))) {
+		let w = 0;
+		if (!S && (o.includes("shape") || o.includes("chart"))) {
 			const n = t.getMovables().getItems(u).filter((e) => "note" !== e.getContent().getType()).filter((e) => a || !e.isHidden()).map((e) => ({
 				movable: e,
 				at: e.getRange().getCoords()
 			})).sort((e, t) => yo(e.at, t.at));
 			for (const { movable: t, at: r } of n) {
-				const n = b(mo(t, o));
+				const n = x(mo(t, o));
 				if (n) {
-					if (!S("object", s, e.rangeToString(r) ?? t.getRange().toString(), n)) break;
-					$++;
+					if (!k("object", s, e.rangeToString(r) ?? t.getRange().toString(), n)) break;
+					w++;
 				}
 			}
 		}
-		(f > 0 || $ > 0) && m.push({
+		(m > 0 || w > 0) && p.push({
 			sheet: s,
-			cells: f,
-			objects: $
+			cells: m,
+			objects: w
 		});
 	}
-	if (!y && o.includes("name")) {
+	if (!S && o.includes("name")) {
 		const e = Boolean(n.scope?.trim()), o = t.getNames().getItems(a ? { includeHidden: !0 } : void 0) ?? [];
 		for (const t of o) {
 			if (e && !wo(t, u)) continue;
-			const n = b(po(t));
-			if (n && !S("object", t.getScope() ?? "", t.getName(), n)) break;
+			const n = x(po(t));
+			if (n && !k("object", t.getScope() ?? "", t.getName(), n)) break;
 		}
 	}
 	return {
 		pattern: n.pattern,
 		fields: o,
 		scope: n.scope?.trim() || "workbook",
-		matches: f,
-		cellCount: p,
-		objectCount: $,
-		sheets: m,
-		sheetsSearched: w,
-		sheetsMatched: m.length,
-		truncated: y,
+		matches: m,
+		cellCount: $,
+		objectCount: w,
+		sheets: p,
+		sheetsSearched: b,
+		sheetsMatched: p.length,
+		truncated: S,
 		output: r
 	};
 }
@@ -2612,19 +2635,19 @@ function Do(e, t) {
 					}).filter((e) => null !== e.score).map((t) => ({
 						...t,
 						hasMember: _o(e, t.key).some((e) => e.name.toLowerCase() === r)
-					})).sort((e, t) => Number(t.hasMember) - Number(e.hasMember) || e.score - t.score).slice(0, Vo).map(({ key: e, hasMember: t }) => ({
+					})).sort((e, t) => Number(t.hasMember) - Number(e.hasMember) || e.score - t.score).slice(0, Ho).map(({ key: e, hasMember: t }) => ({
 						key: e,
 						hasMember: t
 					}));
 				}(e, t, o), i = n ? function(e, t, n) {
-					const o = Ho(n)?.toLowerCase();
+					const o = Vo(n)?.toLowerCase();
 					return _o(e, t).map((e) => {
 						const t = Uo(n, e.name), r = o && o.length >= 3 && e.name.toLowerCase().includes(o);
 						return {
 							member: e,
 							score: t ?? (r ? 10 : null)
 						};
-					}).filter((e) => null !== e.score).sort((e, t) => e.score - t.score).slice(0, Vo).map((e) => e.member);
+					}).filter((e) => null !== e.score).sort((e, t) => e.score - t.score).slice(0, Ho).map((e) => e.member);
 				}(e, n, o) : [];
 				return a.length + i.length + l.length + s.length === 0 ? null : {
 					kind: "miss",
@@ -2636,8 +2659,8 @@ function Do(e, t) {
 					nearestTypes: a,
 					nearest: i,
 					hints: l,
-					elsewhere: s.slice(0, Vo),
-					elsewhereOmitted: Math.max(0, s.length - Vo)
+					elsewhere: s.slice(0, Ho),
+					elsewhereOmitted: Math.max(0, s.length - Ho)
 				};
 			}(e, t, o, s);
 			if (n) return n;
@@ -2662,7 +2685,7 @@ function Do(e, t) {
 		};
 	}(e, r > 0 ? n.slice(r + 1) : n);
 }
-var Vo = 5, Ho = (e) => /([A-Z][a-z0-9]+|^[a-z0-9]+)$/.exec(e)?.[1] ?? null;
+var Ho = 5, Vo = (e) => /([A-Z][a-z0-9]+|^[a-z0-9]+)$/.exec(e)?.[1] ?? null;
 function Bo(e, t) {
 	if (!t || "object" != typeof t && "function" != typeof t) return null;
 	const n = [], o = /* @__PURE__ */ new Set();
@@ -3308,13 +3331,13 @@ function Dr(e) {
 	}
 	return t.toLines().join("\n").trimEnd();
 }
-function Vr(e) {
+function Hr(e) {
 	const t = new pt(), n = e.getRanges();
 	t.h1(`Unlocked Range — ${e.getName()}`), t.blank(), t.fact(`Ranges: ${Wt(n)}`), t.fact(`Cells: ${n.size}`), t.fact("Password: " + (e.hasPassword() ? e.isUnlocked() ? "set · unlocked for this session" : "set · unlock(password) grants access" : "none"));
 	const o = n.getWorksheet().getProtection().isLocked();
 	return t.fact("In force: " + (o ? "true — the sheet is protected" : "false — the sheet is not protected, so every cell is editable")), e.getSecurityDescriptor() && t.fact("Security Descriptor: present · not evaluated"), t.toLines().join("\n").trimEnd();
 }
-var Hr = l.Feature;
+var Vr = l.Feature;
 async function Br(e, t) {
 	const n = e.getWorksheet().getRange(e.getCoords());
 	e = n.getCell();
@@ -3345,7 +3368,7 @@ async function Br(e, t) {
 			e.fact(`Merge: ${n} · ${a.height}×${a.width}`), i && e.fact("Merge Anchor: false — this cell is covered; the value lives at the top-left");
 		}
 		const c = t.getSpill();
-		c && e.fact(`Spill: ${c.toString()}`);
+		c && e.fact(`Spill: ${c.toString()}${"error" === t.getSpillKind() ? " (blocked)" : ""}`);
 		t.isSpillOverflow() && e.fact("Spill Overflow: true — the anchor formula is elsewhere");
 		const u = t.getTable();
 		u && e.fact(`Table: ${function(e, t) {
@@ -3478,7 +3501,7 @@ var zr = 8, _r = (e) => ({
 function Ur(e, t, n) {
 	if (e.isSingleCell()) return null;
 	const o = [];
-	for (const n of e.getRegions(Hr.Formula)) {
+	for (const n of e.getRegions(Vr.Formula)) {
 		const e = n.getCoords();
 		o.push({
 			start: "row" === t ? e.colStart : e.rowStart,
@@ -3556,7 +3579,7 @@ async function qr(e, t) {
 			const a = {
 				text: (s?.display ?? "").replace(/\|/g, "\\|").replace(/[\r\n]+/g, " "),
 				alignment: n.getRenderHorizontalAlignment()
-			}, i = n.getSpill();
+			}, i = "error" === n.getSpillKind() ? null : n.getSpill();
 			i && d.push({
 				address: n.getAddress(),
 				valuesRange: i.getValuesRange().toString()
@@ -4075,11 +4098,11 @@ function Os(e, t) {
 var Ps = (e, t) => {
 	if (null == e) return { text: "" };
 	if ("function" == typeof e) return { text: "[Function]" };
-	if ("bigint" == typeof e || "symbol" == typeof e) return { text: Hs(String(e)) };
+	if ("bigint" == typeof e || "symbol" == typeof e) return { text: Vs(String(e)) };
 	if ("object" == typeof e) {
 		if (e instanceof Date) return { text: e.toISOString() };
 		const n = e;
-		if (!0 === n.isFormulaError || !0 === n.isIRichData) return { text: Hs(Vs(e)) };
+		if (!0 === n.isFormulaError || !0 === n.isIRichData) return { text: Vs(Hs(e)) };
 		if (Ws(e) || Array.isArray(e)) {
 			let t;
 			try {
@@ -4087,11 +4110,11 @@ var Ps = (e, t) => {
 			} catch {
 				t = "[circular]";
 			}
-			return { text: Hs(t) };
+			return { text: Vs(t) };
 		}
-		return { text: Hs(t?.(e) ?? Ds(e)) };
+		return { text: Vs(t?.(e) ?? Ds(e)) };
 	}
-	const n = Hs(Vs(e).replace(/[\r\n]+/g, " "));
+	const n = Vs(Hs(e).replace(/[\r\n]+/g, " "));
 	return "number" == typeof e ? {
 		text: n,
 		alignment: "right"
@@ -4105,13 +4128,13 @@ var Ps = (e, t) => {
 	}
 	const n = /^\[object (.+)\]$/.exec(t)?.[1];
 	return n && "Object" !== n ? n : t;
-}, Vs = (e) => {
+}, Hs = (e) => {
 	try {
 		return j(e)?.match ?? String(e);
 	} catch {
 		return String(e);
 	}
-}, Hs = (e) => e.length > 80 ? `${e.slice(0, 79)}…` : e;
+}, Vs = (e) => e.length > 80 ? `${e.slice(0, 79)}…` : e;
 function Bs(e, t) {
 	const n = e.length, o = L(n, t?.maxRanges ?? 100), r = Math.min(n, o), s = [];
 	for (let t = 0; t < r; t++) {
@@ -4194,7 +4217,7 @@ async function Ks(e, t) {
 	const l = As(e);
 	l && n.text(`Print: ${l}`), n.blank();
 	const a = r ?? o;
-	Pt(n, a), Vt(n, a), Ht(n, a, {
+	Pt(n, a), Ht(n, a), Vt(n, a, {
 		profile: !0,
 		...t
 	});
@@ -4661,7 +4684,7 @@ var wl = (e, t) => !!e && "object" == typeof e && !0 === e[t], yl = {
 	is: (e) => wl(e, "isIProtectedRangeCollection"),
 	render: (e) => {
 		const t = e.getItems();
-		return 0 === t.length ? "# Unlocked Ranges (0)\nNone" : t.slice(0, xl).map(Vr).concat(t.length > xl ? [`…and ${t.length - xl} more · render one at a time to see them`] : []).join("\n\n");
+		return 0 === t.length ? "# Unlocked Ranges (0)\nNone" : t.slice(0, xl).map(Hr).concat(t.length > xl ? [`…and ${t.length - xl} more · render one at a time to see them`] : []).join("\n\n");
 	}
 }, bl = 2;
 function Sl(e) {
@@ -4749,7 +4772,7 @@ var xl = 20, kl = [
 	{
 		kind: "protectedRange",
 		is: (e) => wl(e, "isIProtectedRange"),
-		render: (e) => Vr(e)
+		render: (e) => Hr(e)
 	},
 	{
 		kind: "pageLayout",
@@ -5106,25 +5129,25 @@ function Pl(e, t) {
 		charts: Array.from(s.values(), jn)
 	};
 }
-var Dl = (e, t, n = `${t}s`) => `${e} ${1 === e ? t : n}`, Vl = (e, t) => `${`${e}:`.padEnd(14)}${t}`;
-function Hl(e) {
+var Dl = (e, t, n = `${t}s`) => `${e} ${1 === e ? t : n}`, Hl = (e, t) => `${`${e}:`.padEnd(14)}${t}`;
+function Vl(e) {
 	const t = [];
 	for (const n of e.sheets) {
 		if (n.written) {
-			t.push(Vl("Changed", `${n.written} — ${Bl(n)}`));
+			t.push(Hl("Changed", `${n.written} — ${Bl(n)}`));
 			for (const e of n.blocks) t.push(`  ${_l(e)}`);
 			n.blocksMore > 0 && t.push(`  +${Dl(n.blocksMore, "more formula block")}`);
 		}
-		n.shifts.length > 0 && t.push(Vl("Structure", n.shifts.map((e) => zl(n.sheet, e)).join(" · "))), n.styles && t.push(Vl("Formatting", n.styles));
+		n.shifts.length > 0 && t.push(Hl("Structure", n.shifts.map((e) => zl(n.sheet, e)).join(" · "))), n.styles && t.push(Hl("Formatting", n.styles));
 	}
 	const n = e.dependents;
 	if (n) {
 		const e = n.sheets.length > 1 ? ` on ${Dl(n.sheets.length, "sheet")}` : "";
-		t.push(Vl("Dependents", `${Dl(n.cells, "cell")}${e} — ${n.areas.join(", ")}${((e) => e > 0 ? ` · +${e} more` : "")(n.areasMore)}`));
+		t.push(Hl("Dependents", `${Dl(n.cells, "cell")}${e} — ${n.areas.join(", ")}${((e) => e > 0 ? ` · +${e} more` : "")(n.areasMore)}`));
 	}
 	if (e.errors.length > 0 || e.errorsCleared > 0) {
 		const n = e.errors.map((e) => `${e.address} ${e.error} (${e.cells})`);
-		e.errorsMore > 0 && n.push(`+${e.errorsMore} more`), e.errorsCleared > 0 && n.push(`${Dl(e.errorsCleared, "error")} cleared`), t.push(Vl("Errors", n.join(" · ")));
+		e.errorsMore > 0 && n.push(`+${e.errorsMore} more`), e.errorsCleared > 0 && n.push(`${Dl(e.errorsCleared, "error")} cleared`), t.push(Hl("Errors", n.join(" · ")));
 	}
 	const o = function(e) {
 		const t = [], n = (e, n, o) => {
@@ -5132,7 +5155,7 @@ function Hl(e) {
 		};
 		return n(e.names, "name"), n(e.conditionalFormats, "conditional format"), n(e.dataValidations, "data validation"), n(e.charts, "chart"), t.length > 0 ? t.join(" · ") : null;
 	}(e.touches);
-	return o && t.push(Vl("Also touches", o)), t.join("\n");
+	return o && t.push(Hl("Also touches", o)), t.join("\n");
 }
 function Bl(e) {
 	const t = [];
@@ -5158,11 +5181,11 @@ async function Ul(e, t, n) {
 		const o = await Il(e, t, n);
 		return o ? {
 			delta: o,
-			markdown: Hl(o)
+			markdown: Vl(o)
 		} : {};
 	} catch (e) {
 		return { markdown: `Changes could not be read: ${e?.message ?? String(e)}` };
 	}
 }
 var Jl = [No], ql = [Qo];
-export { Fo as API_ENTRY_POINTS, v as CellEncoding, T as GREP_FIELDS, A as GREP_FIELDS_DEFAULT, F as GrepField, pt as MarkdownBuilder, $t as MarkdownFrameSection, vl as NoRendererError, ql as REFERENCES, Cl as RENDERABLE_KINDS, kl as RENDERERS, pr as RENDER_OPTION_KEYS, Nt as REPORTED_FEATURES, Jl as TOOLS, xt as anomalyRegionKey, zo as apiPointerFor, Ko as apiSuggestionsFor, Qo as apiTool, Bo as apiTypeOf, tr as appendDependencies, zn as appendGroupFacts, Bn as appendGroupMembers, Pt as appendKinds, ps as appendModules, no as appendMovables, on as appendNames, yt as appendRegionList, Ht as appendRegions, Vt as appendRoles, ln as appendRules, Pn as appendShapeFacts, cn as appendSheetObjects, Lr as appendSheetProtection, vt as appendTables, ms as collectModules, Xn as collectShapeText, Ut as contentfulBlocks, xe as countDates, oe as describeAlignment, ct as describeAllowedValues, Jn as describeAnchor, Yo as describeApi, Q as describeBorder, te as describeBorderParts, Or as describeCellProtection, Z as describeColor, at as describeConditionalFormat, it as describeDataValidation, Il as describeDelta, Ft as describeExtent, Y as describeFill, re as describeFont, Er as describeLock, Zn as describeMovableSummary, fr as describeNode, hr as describeNodeLabel, gr as describeNodeLabels, ne as describeNumberFormat, sn as describeOutline, As as describePageLayout, Ot as describeQualifiedExtent, Xt as describeQualifiedName, Wt as describeQualifiedRanges, Wr as describeRangeProtection, Lt as describeRanges, ot as describeRuleStyle, ut as describeRules, st as describeScale, qn as describeShapeText, At as describeSheetCall, Tt as describeSheetName, me as describeSums, eo as describeTypeHeading, jr as describeWorkbookProtection, de as detectTotals, N as encodeCell, R as encodeFormattedNumber, E as encodeNumber, j as encodeScalar, an as findNames, So as grep, No as grepTool, to as groupMovables, Dn as groupOf, Ws as isPlainRecord, Do as lookupApi, It as parseFeatures, $r as parseRenderOptions, Se as profileKinds, ce as profileRegion, Pr as protectionPointerFor, Mn as quoteShapeText, Ul as readRunDelta, Kn as readShapeText, ft as regionPayload, mt as regionPayloads, Zo as renderApi, Br as renderCell, qr as renderCellRange, Zr as renderConditionalFormat, Yr as renderCounts, Qr as renderDataValidation, Hl as renderDelta, cs as renderFormula, Ro as renderGrep, Rl as renderMarkdown, ws as renderModule, ys as renderModules, ro as renderMovable, Ss as renderNames, Ls as renderPageLayout, Vr as renderProtectedRange, Dr as renderProtection, Bs as renderRanges, Os as renderRecords, kt as renderRegions, jl as renderResult, so as renderShape, Zs as renderStats, Qs as renderStyle, Et as renderTable, el as renderValues, sl as renderWorkbook, Ks as renderWorksheet, El as resolveRenderer, Ar as summarizeSheetProtection, Jo as withoutHiddenSuggestion };
+export { Fo as API_ENTRY_POINTS, v as CellEncoding, T as GREP_FIELDS, A as GREP_FIELDS_DEFAULT, F as GrepField, pt as MarkdownBuilder, $t as MarkdownFrameSection, vl as NoRendererError, ql as REFERENCES, Cl as RENDERABLE_KINDS, kl as RENDERERS, pr as RENDER_OPTION_KEYS, Nt as REPORTED_FEATURES, Jl as TOOLS, xt as anomalyRegionKey, zo as apiPointerFor, Ko as apiSuggestionsFor, Qo as apiTool, Bo as apiTypeOf, tr as appendDependencies, zn as appendGroupFacts, Bn as appendGroupMembers, Pt as appendKinds, ps as appendModules, no as appendMovables, on as appendNames, yt as appendRegionList, Vt as appendRegions, Ht as appendRoles, ln as appendRules, Pn as appendShapeFacts, cn as appendSheetObjects, Lr as appendSheetProtection, vt as appendTables, ms as collectModules, Xn as collectShapeText, Ut as contentfulBlocks, xe as countDates, oe as describeAlignment, ct as describeAllowedValues, Jn as describeAnchor, Yo as describeApi, Q as describeBorder, te as describeBorderParts, Or as describeCellProtection, Z as describeColor, at as describeConditionalFormat, it as describeDataValidation, Il as describeDelta, Ft as describeExtent, Y as describeFill, re as describeFont, Er as describeLock, Zn as describeMovableSummary, fr as describeNode, hr as describeNodeLabel, gr as describeNodeLabels, ne as describeNumberFormat, sn as describeOutline, As as describePageLayout, Ot as describeQualifiedExtent, Xt as describeQualifiedName, Wt as describeQualifiedRanges, Wr as describeRangeProtection, Lt as describeRanges, ot as describeRuleStyle, ut as describeRules, st as describeScale, qn as describeShapeText, At as describeSheetCall, Tt as describeSheetName, me as describeSums, eo as describeTypeHeading, jr as describeWorkbookProtection, de as detectTotals, N as encodeCell, R as encodeFormattedNumber, E as encodeNumber, j as encodeScalar, an as findNames, So as grep, No as grepTool, to as groupMovables, Dn as groupOf, Ws as isPlainRecord, Do as lookupApi, It as parseFeatures, $r as parseRenderOptions, Se as profileKinds, ce as profileRegion, Pr as protectionPointerFor, Mn as quoteShapeText, Ul as readRunDelta, Kn as readShapeText, ft as regionPayload, mt as regionPayloads, Zo as renderApi, Br as renderCell, qr as renderCellRange, Zr as renderConditionalFormat, Yr as renderCounts, Qr as renderDataValidation, Vl as renderDelta, cs as renderFormula, Ro as renderGrep, Rl as renderMarkdown, ws as renderModule, ys as renderModules, ro as renderMovable, Ss as renderNames, Ls as renderPageLayout, Hr as renderProtectedRange, Dr as renderProtection, Bs as renderRanges, Os as renderRecords, kt as renderRegions, jl as renderResult, so as renderShape, Zs as renderStats, Qs as renderStyle, Et as renderTable, el as renderValues, sl as renderWorkbook, Ks as renderWorksheet, El as resolveRenderer, Ar as summarizeSheetProtection, Jo as withoutHiddenSuggestion };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/query",
   "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
-  "version": "0.8.0-beta.12",
+  "version": "0.8.0-beta.14",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
     "query"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.12",
-    "@sheetxl/sdk": "^0.8.0-beta.12"
+    "@sheetxl/primitives": "^0.8.0-beta.14",
+    "@sheetxl/sdk": "^0.8.0-beta.14"
   },
   "devDependencies": {
     "@types/node": "^26.6.4"

package/types/src/grep/GrepTypes.d.ts

@@ -61,8 +61,9 @@ export type GrepField =
  *
  * Authored text (it is literally what was typed into Format Cells), canonical, and regex
  * is its native matcher. `--fields numberFormat "%"` is the well-posed form of "which
- * cells are percentages" — the rendered `40%` is not. Matches cells with a *direct*
- * format, including value-less ones (a formatted-but-empty column is a real finding).
+ * cells are percentages" — the rendered `40%` is not. Matches blocks given a format,
+ * directly or by a named style, including value-less ones (a formatted-but-empty column is
+ * a real finding).
  */
  | 'numberFormat'
 /**
@@ -238,7 +239,8 @@ export interface GrepArgs {
      *
      * @remarks
      * Counts **cells and objects**, not match rows — a cell matching in two fields is one unit of
-     * budget, and so is a chart matching in its title and an axis.
+     * budget, and so is a chart matching in its title and an axis, and a block matching in its
+     * hyperlink or number format.
      * The search looks one match past the cap, so a result that ends exactly at `maxCount` is
      * only reported truncated when a further match actually exists.
      */
@@ -290,8 +292,9 @@ export interface GrepMatch {
      */
     sheet: string;
     /**
-     * A1 cell address within the sheet; the anchor range (`F2:H6`) for a shape or chart; the name
-     * itself for a defined name. Qualified with `sheet`, each is something a follow-up call takes.
+     * A1 cell address within the sheet; the block (`A:J`) for a hyperlink or number format; the
+     * anchor range (`F2:H6`) for a shape or chart; the name itself for a defined name. Qualified
+     * with `sheet`, each is something a follow-up call takes.
      */
     address: string;
     /**
@@ -312,7 +315,7 @@ export interface GrepMatch {
 export interface GrepSheetMatches {
     /** Sheet name. */
     sheet: string;
-    /** Distinct cells that produced at least one match in this sheet. */
+    /** Cells that produced a match in this sheet, counted as {@link GrepResult.cellCount} is. */
     cells: number;
     /** Shapes and charts on this sheet that produced at least one match. */
     objects: number;
@@ -325,7 +328,10 @@ export interface GrepResult {
     /** Resolved human-readable scope, e.g. `Sheet1!A1:D847` or `workbook`. */
     scope: string;
     matches: readonly GrepMatch[];
-    /** Distinct cells that produced at least one match. */
+    /**
+     * Cells that produced a match. A hyperlink or number format block counts all of its cells, and
+     * a cell also matching in another field is counted again.
+     */
     cellCount: number;
     /** Shapes, charts and names that produced at least one match. */
     objectCount: number;

package/types/src/grep/grep.d.ts

@@ -4,8 +4,9 @@ import { GrepArgs, GrepResult } from './GrepTypes';
  * Searches a workbook's text by pattern — its cells, and what is written off the grid.
  *
  * @remarks
- * Per sheet: the cells in reading order (a comment rides its cell), then the shapes and charts
- * in reading order of their anchors. Defined names follow every sheet, since they belong to none.
+ * Per sheet: the cells in reading order (a comment rides its cell), then the blocks a hyperlink or
+ * number format is stated over, then the shapes and charts in reading order of their anchors.
+ * Defined names follow every sheet, since they belong to none.
  *
  * Deliberately shaped after ripgrep — args, defaults and vocabulary are pretrained, and every
  * novel idiom is paid for in error loops.