ochre-sdk 1.0.71 → 1.0.73

package/dist/query.mjs

@@ -12,11 +12,7 @@ const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
 const CTS_INCLUDES_TOKEN_WORD_REGEX = /^\p{L}+$/u;
 const CTS_INCLUDES_TOKEN_REGEX = /[\p{L}\p{N}*?]+/gu;
 const CTS_EXACT_TEXT_TOKEN_REGEX = /[\p{L}\p{N}]+/gu;
-/**
-* Error message for OCR queries nested inside an OR group
-* @internal
-*/
-const OCR_DISJUNCTION_ERROR_MESSAGE = "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query";
+const MAX_OCR_TEXT_CONDITIONS = 4;
 const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -204,9 +200,6 @@ function buildNestedElementQuery(elementNames, queryExpression) {
 function buildNotCtsQueryExpression(queryExpression) {
 	return `cts:not-query(${queryExpression})`;
 }
-function buildCtsNearQueryExpression(queryExpressions) {
-	return `cts:near-query((${queryExpressions.join(", ")}), ${queryExpressions.length - 1}, ("ordered"))`;
-}
 function buildAndCtsQueryExpressionInternal(queryExpressions) {
 	if (queryExpressions.length === 0) return "cts:true-query()";
 	if (queryExpressions.length === 1) return queryExpressions[0] ?? "cts:true-query()";
@@ -246,8 +239,7 @@ function buildRichTextContentQueryExpression(parameters) {
 	const { value, matchMode, isCaseSensitive, language } = parameters;
 	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
 		value,
-		isCaseSensitive,
-		language
+		isCaseSensitive
 	}) : buildCtsWordQueryExpression({
 		value,
 		matchMode,
@@ -480,62 +472,83 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-function tokenizeOcrSearchValue(parameters) {
-	const { value, matchMode, isCaseSensitive } = parameters;
-	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).match(matchMode === "exact" ? CTS_EXACT_TEXT_TOKEN_REGEX : CTS_INCLUDES_TOKEN_REGEX) ?? [];
-	const terms = [];
-	for (const term of rawTerms) if (getWildcardStrippedValue(term) !== "") terms.push(term);
-	return terms;
-}
-/**
-* Compile one CTS query expression per OCR search term, in word order
-*
-* Highlighting matches each OCR word against these same per-term expressions,
-* so hit locations always agree with what the filter matched.
-* @internal
-*/
-function buildOcrTermQueryExpressions(parameters) {
-	const { value, matchMode, isCaseSensitive } = parameters;
-	const terms = tokenizeOcrSearchValue({
+function buildOcrTextQueryExpression(query) {
+	const { value, matchMode, isCaseSensitive } = query;
+	const phraseQueryExpression = buildRichTextPhraseQueryExpression({
 		value,
-		matchMode,
 		isCaseSensitive
 	});
-	const isWholeWordEquality = matchMode === "exact" && terms.length === 1;
-	return Array.from(terms, (term) => isWholeWordEquality ? buildCtsElementValueQueryExpression({
-		elementName: "string",
-		value: term,
+	if (matchMode === "exact") return buildNestedElementQuery(["ocrText"], phraseQueryExpression);
+	const terms = tokenizeIncludesSearchValue({
+		value,
 		isCaseSensitive
-	}) : buildCtsWordQueryExpression({
+	});
+	if (terms.length === 0) return "cts:false-query()";
+	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildCtsWordQueryExpression({
 		value: term,
 		matchMode,
 		isCaseSensitive,
 		queryFamily: "text"
-	}));
-}
-function buildOcrQueryExpression(query) {
-	const termQueryExpressions = buildOcrTermQueryExpressions(query);
-	if (termQueryExpressions.length === 0) return "cts:false-query()";
-	return buildNestedElementQuery(["ocr"], termQueryExpressions.length > 1 ? buildCtsNearQueryExpression(termQueryExpressions) : termQueryExpressions[0] ?? "cts:false-query()");
+	})));
+	return buildNestedElementQuery(["ocrText"], shouldUseFullValueFallbackForIncludes({
+		value,
+		isCaseSensitive,
+		terms
+	}) ? buildOrCtsQueryExpressionInternal([phraseQueryExpression, tokenizedQueryExpression]) : tokenizedQueryExpression);
 }
-function registerOcrItemPredicate(context, query) {
-	const bindingKey = [
+function getOcrTextConditionKey(query) {
+	return [
 		query.value,
 		query.matchMode,
 		query.isCaseSensitive ? "case-sensitive" : "case-insensitive"
 	].join("|");
-	let variableName = context.ocrVariableNamesByKey.get(bindingKey);
-	if (variableName == null) {
-		variableName = `$ocrUuids${context.nextOcrSerial}`;
-		context.nextOcrSerial += 1;
-		context.ocrVariableNamesByKey.set(bindingKey, variableName);
-		context.ocrBindings.push({
-			name: variableName,
-			expression: `for $ocrDocument in cts:search(doc(), ${buildOcrQueryExpression(query)})\n    return document-uri($ocrDocument)`
-		});
+}
+function registerOcrTextCondition(context, query) {
+	const key = getOcrTextConditionKey(query);
+	if (context.ocrTextConditionIndexesByKey.has(key)) return;
+	context.ocrTextConditionIndexesByKey.set(key, context.ocrTextConditions.length);
+	context.ocrTextConditions.push({
+		variableName: `$ocrTextUuids${context.ocrTextConditions.length + 1}`,
+		bindingExpression: `for $ocrTextDocument in cts:search(doc(), ${buildOcrTextQueryExpression(query)})\n    return document-uri($ocrTextDocument)`
+	});
+}
+function collectOcrTextConditions(context, query) {
+	if (isQueryLeaf(query)) {
+		if (query.target === "ocrText") registerOcrTextCondition(context, query);
+		return;
+	}
+	for (const childQuery of getQueryGroupChildren(query)) collectOcrTextConditions(context, childQuery);
+}
+function isOcrTextLeafMatched(context, query, ocrTextValues) {
+	const conditionIndex = context.ocrTextConditionIndexesByKey.get(getOcrTextConditionKey(query));
+	const isMatched = conditionIndex != null && ocrTextValues[conditionIndex] === true;
+	return query.isNegated === true ? !isMatched : isMatched;
+}
+/**
+* Enumerate every assignment of "this item is in the OCR text match set" across
+* the compiled conditions, least significant position first
+*/
+function getOcrTextValueCombinations(count) {
+	return Array.from({ length: 2 ** count }, (_, index) => Array.from({ length: count }, (_, position) => (index >> position & 1) === 1));
+}
+/**
+* Resolve a query tree against one OCR text assignment, treating every CTS leaf
+* as unknown. Only a definite `false` is actionable: it means the branch cannot
+* match anything and can be dropped before it costs a `cts:search`.
+*/
+function evaluateOcrTextBranch(context, query, ocrTextValues) {
+	if (isQueryLeaf(query)) return query.target === "ocrText" ? isOcrTextLeafMatched(context, query, ocrTextValues) : null;
+	const isAndGroup = "and" in query;
+	let result = isAndGroup;
+	for (const childQuery of getQueryGroupChildren(query)) {
+		const childResult = evaluateOcrTextBranch(context, childQuery, ocrTextValues);
+		if (childResult === !isAndGroup) return !isAndGroup;
+		if (childResult == null) result = null;
 	}
-	const itemPredicate = query.isNegated === true ? `[not(@uuid = ${variableName})]` : `[@uuid = ${variableName}]`;
-	if (!context.itemPredicates.includes(itemPredicate)) context.itemPredicates.push(itemPredicate);
+	return result;
+}
+function buildOcrTextItemPredicates(context, ocrTextValues) {
+	return Array.from(context.ocrTextConditions, (condition, index) => ocrTextValues[index] === true ? `[@uuid = ${condition.variableName}]` : `[not(@uuid = ${condition.variableName})]`).join("");
 }
 function getLeafSearchValue(query) {
 	switch (query.target) {
@@ -618,10 +631,8 @@ function createQueryCompilerContext() {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
 		helperDeclarations: [],
-		nextOcrSerial: 1,
-		ocrVariableNamesByKey: /* @__PURE__ */ new Map(),
-		ocrBindings: [],
-		itemPredicates: []
+		ocrTextConditions: [],
+		ocrTextConditionIndexesByKey: /* @__PURE__ */ new Map()
 	};
 }
 function registerConstantHelper(parameters) {
@@ -818,24 +829,11 @@ function getQueryGroupChildren(query) {
 function getQueryGroupOperator(query) {
 	return "and" in query ? "and" : "or";
 }
-function isDisjunctiveQueryGroup(query) {
-	return "or" in query && query.or.length > 1;
-}
-/**
-* Whether a query tree nests an OCR leaf inside an OR group
-* @internal
-*/
-function hasOcrQueryInDisjunction(query, isInDisjunction = false) {
-	if (isQueryLeaf(query)) return query.target === "ocr" && isInDisjunction;
-	const isChildInDisjunction = isInDisjunction || isDisjunctiveQueryGroup(query);
-	for (const childQuery of getQueryGroupChildren(query)) if (hasOcrQueryInDisjunction(childQuery, isChildInDisjunction)) return true;
-	return false;
-}
 function getCompatibleIncludesGroupLeaves(query) {
 	if (!("or" in query) || query.or.length <= 1) return null;
 	const leafQueries = [];
 	for (const childQuery of query.or) {
-		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr") return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocrText") return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -896,20 +894,15 @@ function buildIncludesGroupQueryExpression(context, queries) {
 		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
 	}).callExpression, tokenizedQueryExpression]);
 }
-function buildQueryNode(context, query, isInDisjunction) {
+function buildQueryNode(context, query, ocrTextValues) {
 	if (isQueryLeaf(query)) {
-		if (query.target === "ocr") {
-			if (isInDisjunction) throw new Error(OCR_DISJUNCTION_ERROR_MESSAGE, { cause: query });
-			registerOcrItemPredicate(context, query);
-			return "cts:true-query()";
-		}
+		if (query.target === "ocrText") return isOcrTextLeafMatched(context, query, ocrTextValues) ? "cts:true-query()" : "cts:false-query()";
 		const queryExpression = buildLeafQueryExpression(context, query);
 		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
 	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
-	const isChildInDisjunction = isInDisjunction || isDisjunctiveQueryGroup(query);
-	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, isChildInDisjunction));
+	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, ocrTextValues));
 	return (getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal : buildOrCtsQueryExpressionInternal)(childQueryExpressions);
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
@@ -923,22 +916,47 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 		}))))
 	});
 }
+/**
+* Compile a query tree into the CTS searches that resolve it
+*
+* OCR text is not carried by Set item projections, so an `ocrText` leaf cannot
+* be a CTS term: it resolves to a document join whose UUID list can only be
+* applied as an item path predicate, and path predicates only ever AND. To keep
+* `ocrText` composable with `or` anyway, the tree is split on each distinct OCR
+* text condition, one branch per assignment of "this item is in that match
+* set". Every branch is a plain CTS search, and their union is the result.
+* Branches that the assignment already rules out are dropped, so a query whose
+* OCR text leaves are all conjunctive still compiles to a single search.
+*/
 function buildQueryPlan(parameters) {
 	const { queries } = parameters;
 	if (queries == null) return {
 		prolog: "",
-		queryExpression: null,
-		ocrBindings: [],
-		itemPredicates: ""
+		ocrTextBindings: [],
+		branches: [{
+			itemPredicates: "",
+			queryExpression: null
+		}]
 	};
 	const context = createQueryCompilerContext();
-	const queryExpression = buildQueryNode(context, queries, false);
+	collectOcrTextConditions(context, queries);
+	if (context.ocrTextConditions.length > MAX_OCR_TEXT_CONDITIONS) throw new Error(`A query cannot contain more than ${MAX_OCR_TEXT_CONDITIONS} distinct OCR text searches`, { cause: context.ocrTextConditions.length });
+	const branches = [];
+	for (const ocrTextValues of getOcrTextValueCombinations(context.ocrTextConditions.length)) {
+		if (evaluateOcrTextBranch(context, queries, ocrTextValues) === false) continue;
+		branches.push({
+			itemPredicates: buildOcrTextItemPredicates(context, ocrTextValues),
+			queryExpression: buildQueryNode(context, queries, ocrTextValues)
+		});
+	}
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		queryExpression,
-		ocrBindings: context.ocrBindings,
-		itemPredicates: context.itemPredicates.join("")
+		ocrTextBindings: Array.from(context.ocrTextConditions, (condition) => ({
+			name: condition.variableName,
+			expression: condition.bindingExpression
+		})),
+		branches
 	};
 }
 //#endregion
-export { OCR_DISJUNCTION_ERROR_MESSAGE, buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildOcrTermQueryExpressions, buildQueryPlan, hasOcrQueryInDisjunction };
+export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/schemas.d.mts

@@ -38,7 +38,7 @@ declare const renderOptionsSchema: v.SchemaWithPipe<readonly [v.StringSchema<und
 declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
-  readonly queries: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly attributes: v.OptionalSchema<v.ObjectSchema<{
     readonly bibliographies: v.GenericSchema<unknown, boolean>;
     readonly periods: v.GenericSchema<unknown, boolean>;
@@ -49,15 +49,14 @@ declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   readonly isLimitedToLeafPropertyValues: v.GenericSchema<unknown, boolean>;
 }, undefined>;
 /**
- * Schema for validating OCR matches parameters
+ * Schema for validating the parameters for the item OCR data fetching function
  * @internal
  */
-declare const ocrMatchesParametersSchema: v.ObjectSchema<{
-  readonly uuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one UUID is required">]>;
-  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "A search value is required">]>;
+declare const itemOcrDataParametersSchema: v.ObjectSchema<{
+  readonly uuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
+  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "A search value is required">]>;
   readonly matchMode: v.OptionalSchema<v.PicklistSchema<["includes", "exact"], undefined>, "includes">;
   readonly isCaseSensitive: v.GenericSchema<unknown, boolean>;
-  readonly maxMatchesPerItem: v.OptionalSchema<v.GenericSchema<unknown, number>, 50>;
 }, undefined>;
 /**
  * Schema for validating Set items parameters
@@ -66,7 +65,7 @@ declare const ocrMatchesParametersSchema: v.ObjectSchema<{
 declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
-  readonly queries: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
     readonly target: v.LiteralSchema<"none", undefined>;
   }, undefined>, v.StrictObjectSchema<{
@@ -86,4 +85,4 @@ declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
 }, undefined>;
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/schemas.mjs

@@ -1,6 +1,5 @@
 import { isPseudoUuid } from "./utilities.mjs";
 import "./helpers.mjs";
-import { OCR_DISJUNCTION_ERROR_MESSAGE, hasOcrQueryInDisjunction } from "./query.mjs";
 import * as v from "valibot";
 //#region src/schemas.ts
 const positiveNumber = (message) => v.pipe(v.number(), v.minValue(1, message));
@@ -143,7 +142,7 @@ const setQueryLeafSchema = v.union([
 		...standardQueryFields
 	}),
 	v.strictObject({
-		target: v.literal("ocr"),
+		target: v.literal("ocrText"),
 		value: v.string(),
 		matchMode: standardQueryFields.matchMode,
 		isCaseSensitive: standardQueryFields.isCaseSensitive,
@@ -175,7 +174,7 @@ const setQuerySchema = v.lazy(() => v.union([
 * Schema for validating Set queries
 * @internal
 */
-const setQueriesSchema = v.optional(v.nullable(v.pipe(setQuerySchema, v.check((query) => !hasOcrQueryInDisjunction(query), OCR_DISJUNCTION_ERROR_MESSAGE))), null);
+const setQueriesSchema = v.optional(v.nullable(setQuerySchema), null);
 /**
 * Schema for validating Set items sort
 * @internal
@@ -222,15 +221,14 @@ const setPropertyValuesParametersSchema = v.object({
 	isLimitedToLeafPropertyValues: defaultBoolean(false)
 });
 /**
-* Schema for validating OCR matches parameters
+* Schema for validating the parameters for the item OCR data fetching function
 * @internal
 */
-const ocrMatchesParametersSchema = v.object({
-	uuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one UUID is required")),
-	value: v.pipe(v.string(), v.minLength(1, "A search value is required")),
+const itemOcrDataParametersSchema = v.object({
+	uuid: uuidSchema,
+	value: v.pipe(v.string(), v.check((value) => value.trim() !== "", "A search value is required")),
 	matchMode: v.optional(v.picklist(["includes", "exact"]), "includes"),
-	isCaseSensitive: defaultBoolean(false),
-	maxMatchesPerItem: v.optional(positiveNumber("Max matches per item must be positive"), 50)
+	isCaseSensitive: defaultBoolean(false)
 });
 /**
 * Schema for validating Set items parameters
@@ -245,4 +243,4 @@ const setItemsParametersSchema = v.object({
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
 });
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/types/index.d.mts

@@ -263,58 +263,29 @@ type ImageMap = {
   height: number;
 };
 /**
- *  Vertex of an OCR word's bounding polygon in OCHRE
- */
-type OcrPoint = {
-  x: number;
-  y: number;
-};
-/**
- *  Word recognized within an OCR text line in OCHRE
- */
-type OcrWord = {
-  content: string;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  vertices: Array<OcrPoint>;
-};
-/**
- *  Text line of an OCR text block in OCHRE
- */
-type OcrTextLine = {
-  content: string;
-  words: Array<OcrWord>;
-};
-/**
- *  Text block of an OCR page in OCHRE
- */
-type OcrTextBlock = {
-  lines: Array<OcrTextLine>;
-};
-/**
- *  OCR page of a resource in OCHRE
- */
-type OcrPage = {
-  number: number | null;
-  fileName: string | null;
-  width: number | null;
-  height: number | null;
-  blocks: Array<OcrTextBlock>;
-};
-/**
- *  A run of adjacent OCR words matching a search value in OCHRE
+ *  Positioned OCR string in OCHRE
+ *
+ *  OCHRE gives no guarantee about the node hierarchy inside a Resource's
+ *  `<ocr>` layer, so only `<string>` nodes are parsed, at whatever depth they
+ *  occur. `x` and `y` come from `HPOS` and `VPOS` and locate the top-left
+ *  corner of the string's box, while `vertices` is its full bounding polygon,
+ *  which is not necessarily rectangular. Every geometry attribute is optional
+ *  in the source, so each one is null when absent or unparseable.
  *
- *  `uuid` is the requested resource, while `resourceUuid` is the resource that
- *  owns the OCR page — they differ when the OCR lives on a child page resource.
+ *  `resourceUuid` is the Resource that owns the OCR layer, which differs from
+ *  the requested item when the OCR lives on a child Resource.
  */
-type OcrMatch = {
-  uuid: string;
+type OcrString = {
   resourceUuid: string | null;
-  page: Omit<OcrPage, "blocks">;
   content: string;
-  words: Array<OcrWord>;
+  x: number | null;
+  y: number | null;
+  width: number | null;
+  height: number | null;
+  vertices: Array<{
+    x: number;
+    y: number;
+  }>;
 };
 /**
  *  Note in OCHRE
@@ -734,7 +705,6 @@ type Resource<T extends LanguageCodes = LanguageCodes, U extends ItemPayloadKind
   image: Image<T> | null;
   document: MultilingualString<T> | null;
   imageMap: ImageMap | null;
-  ocr: Array<OcrPage>;
   coordinates: Array<Coordinates<T>>;
   periods: Array<Period<T, "embedded">>;
   links: ItemLinks<T>;
@@ -845,12 +815,12 @@ type SetItemsSort = {
 /**
  * Represents a leaf query for Set items
  *
- * The `ocr` target matches the OCR text layer of resources. Because OCR is not
- * carried by Set item projections, it is resolved by a document join rather
- * than a CTS term, which means `ocr` leaves compose with `and` and `isNegated`
- * but cannot be nested inside an `or` group. Both match modes are adjacency
- * based: `includes` allows stemming and wildcards, `exact` requires whole OCR
- * words. OCR carries no language, so `ocr` leaves take no `language`.
+ * The `ocrText` target matches the OCR text layer of Resource items. Because
+ * Set item projections do not carry `<ocrText>`, it is resolved by a document
+ * join rather than a CTS term, so it composes with `and`, `or`, and `isNegated`
+ * at the cost of one extra search branch per distinct OCR text value in a
+ * disjunction. OCR text carries no language, so `ocrText` leaves take no
+ * `language`.
  */
 type QueryLeaf = {
   target: "property";
@@ -918,7 +888,7 @@ type QueryLeaf = {
   language: string;
   isNegated?: boolean;
 } | {
-  target: "ocr";
+  target: "ocrText";
   value: string;
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
@@ -944,4 +914,4 @@ type QueryGroup = {
  */
 type Query = QueryLeaf | QueryGroup;
 //#endregion
-export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, OcrMatch, OcrPage, OcrPoint, OcrTextBlock, OcrTextLine, OcrWord, Period, PeriodItemLink, Person, PersonItemLink, Prettify, Property, PropertyLike, PropertyRelation, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };
+export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, OcrString, Period, PeriodItemLink, Person, PersonItemLink, Prettify, Property, PropertyLike, PropertyRelation, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };

package/dist/utilities.d.mts

@@ -20,6 +20,30 @@ declare function isPseudoUuid(value: string): boolean;
  * @returns The escaped string literal
  */
 declare function stringLiteral(value: string): string;
+/**
+ * XQuery prolog declaring `local:omit-supplemental`, which drops every element
+ * carrying `supplemental="true"` from a node sequence, at any depth.
+ *
+ * Subtrees without a supplemental descendant are returned by reference, so
+ * nodes are only copied along the path leading to an omitted element. The
+ * lookahead walks the attribute axis (`//@supplemental`) rather than testing
+ * every element, which measures around three times faster on large documents.
+ *
+ * Must be declared before any query body that calls {@link omitSupplemental}.
+ */
+declare const SUPPLEMENTAL_XQUERY_PROLOG = "declare function local:omit-supplemental($nodes as node()*) as node()* {\n  for $node in $nodes\n  return\n    if ($node instance of element())\n    then\n      if ($node/@supplemental = \"true\")\n      then ()\n      else if (empty($node//@supplemental[. = \"true\"]))\n      then $node\n      else element { node-name($node) } {\n        $node/@*,\n        local:omit-supplemental($node/node())\n      }\n    else $node\n};";
+/**
+ * Wrap an XQuery node expression so supplemental nodes are omitted from it
+ * @param expression - The XQuery expression returning the nodes to filter
+ * @returns The wrapped XQuery expression
+ */
+declare function omitSupplemental(expression: string): string;
+/**
+ * XQuery predicate keeping only nodes that are neither supplemental themselves
+ * nor nested inside a supplemental node. Use it when aggregating over nodes
+ * instead of returning them.
+ */
+declare const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
 /**
  * Flatten a properties array
  * @param properties - The properties to flatten
@@ -28,4 +52,4 @@ declare function stringLiteral(value: string): string;
  */
 declare function flattenProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T> | SetItemProperty<T>>): Array<SetItemProperty<T>>;
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };

package/dist/utilities.mjs

@@ -151,6 +151,46 @@ function stringLiteral(value) {
 	return `"${value.replaceAll("\"", "\"\"")}"`;
 }
 /**
+* XQuery prolog declaring `local:omit-supplemental`, which drops every element
+* carrying `supplemental="true"` from a node sequence, at any depth.
+*
+* Subtrees without a supplemental descendant are returned by reference, so
+* nodes are only copied along the path leading to an omitted element. The
+* lookahead walks the attribute axis (`//@supplemental`) rather than testing
+* every element, which measures around three times faster on large documents.
+*
+* Must be declared before any query body that calls {@link omitSupplemental}.
+*/
+const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($nodes as node()*) as node()* {
+  for $node in $nodes
+  return
+    if ($node instance of element())
+    then
+      if ($node/@supplemental = "true")
+      then ()
+      else if (empty($node//@supplemental[. = "true"]))
+      then $node
+      else element { node-name($node) } {
+        $node/@*,
+        local:omit-supplemental($node/node())
+      }
+    else $node
+};`;
+/**
+* Wrap an XQuery node expression so supplemental nodes are omitted from it
+* @param expression - The XQuery expression returning the nodes to filter
+* @returns The wrapped XQuery expression
+*/
+function omitSupplemental(expression) {
+	return `local:omit-supplemental(${expression})`;
+}
+/**
+* XQuery predicate keeping only nodes that are neither supplemental themselves
+* nor nested inside a supplemental node. Use it when aggregating over nodes
+* instead of returning them.
+*/
+const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
+/**
 * Flatten a properties array
 * @param properties - The properties to flatten
 * @returns The flattened properties
@@ -169,4 +209,4 @@ function flattenProperties(properties) {
 	return result;
 }
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };

package/dist/xml/schemas.d.mts

@@ -1,11 +1,6 @@
-import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLOcrMatchesData as XMLOcrMatchesData$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
+import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
 import * as v from "valibot";
 //#region src/xml/schemas.d.ts
-/**
- * Schema for validating OCR matches fetched from the OCHRE API
- * @internal
- */
-declare const XMLOcrMatchesData: v.GenericSchema<unknown, XMLOcrMatchesData$1>;
 declare const XMLLink: v.GenericSchema<unknown, XMLLink$1>;
 declare const XMLDataItem: v.GenericSchema<unknown, XMLDataItem$1>;
 declare const XMLItemLinksData: v.GenericSchema<unknown, XMLItemLinksData$1>;
@@ -14,4 +9,4 @@ declare const XMLSetItemsData: v.GenericSchema<unknown, XMLSetItemsData$1>;
 declare const XMLData: v.GenericSchema<unknown, XMLData$1>;
 declare const XMLWebsiteData: v.GenericSchema<unknown, XMLWebsiteData$1>;
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };