ochre-sdk 1.0.69 → 1.0.71

package/dist/parsers/website/index.mjs

@@ -60,7 +60,8 @@ function collectWebsitePageSlugs(resources, options, slugPrefix, pageSlugsByUuid
 			collectWebsitePageSlugs(resource.resource, options, slugPrefix, pageSlugsByUuid, segmentSlugPrefix);
 			continue;
 		}
-		if (websitePresentationReader(resource.properties != null ? parseSimplifiedProperties(resource.properties, options) : []).value("presentation") === "page") {
+		const resourceProperties = resource.properties != null ? parseSimplifiedProperties(resource.properties, options) : [];
+		if (websitePresentationReader(resourceProperties).value("presentation") === "page") {
 			const slug = cleanWebsitePageSlug(resource.slug);
 			if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(resource)})`, { cause: resource });
 			const pageSlug = prefixSlug(slug, slugPrefix);
@@ -812,7 +813,8 @@ function parseWebTitle(properties, identification, overrides) {
 function parseWebElement(elementResource, options, context) {
 	const identification = parseIdentification(elementResource.identification, options);
 	const elementProperties = elementResource.properties?.property ? parseSimplifiedProperties(elementResource.properties, options) : [];
-	const properties = parseWebElementProperties(websitePresentationReader(websitePresentationReader(elementProperties).requiredProperty("presentation", `Presentation property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`).properties).requiredProperty("component", `Component property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`), elementResource, options, context);
+	const presentationProperty = websitePresentationReader(elementProperties).requiredProperty("presentation", `Presentation property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`);
+	const properties = parseWebElementProperties(websitePresentationReader(presentationProperty.properties).requiredProperty("component", `Component property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`), elementResource, options, context);
 	const cssStyles = parseResponsiveCssStyles(elementProperties);
 	const title = parseWebTitle(elementProperties, identification, {
 		isNameDisplayed: [
@@ -980,7 +982,8 @@ function parseSidebar(resources, options, context) {
 		mobile: []
 	};
 	const sidebarResource = resources.find((resource) => {
-		const resourceReader = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []);
+		const resourceProperties = resource.properties ? parseSimplifiedProperties(resource.properties, options) : [];
+		const resourceReader = websitePresentationReader(resourceProperties);
 		return resourceReader.value("presentation") === "element" && resourceReader.nestedByValue("presentation", "element").value("component") === "sidebar";
 	});
 	if (sidebarResource != null) {
@@ -995,7 +998,8 @@ function parseSidebar(resources, options, context) {
 		cssStyles.mobile = parsedCssStyles.mobile;
 		const sidebarResources = sidebarResource.resource ? normalizeWebsiteResources(sidebarResource.resource) : [];
 		for (const resource of sidebarResources) {
-			const resourceType = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []).value("presentation");
+			const resourceProperties = resource.properties ? parseSimplifiedProperties(resource.properties, options) : [];
+			const resourceType = websitePresentationReader(resourceProperties).value("presentation");
 			if (resourceType === null) continue;
 			switch (resourceType) {
 				case "element": {
@@ -1025,7 +1029,8 @@ function parseWebAccordionItem(elementResource, childResources, options, context
 	const trigger = parseWebElement(elementResource, options, context);
 	const items = [];
 	for (const resource of childResources) {
-		const resourceType = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []).value("presentation");
+		const resourceProperties = resource.properties ? parseSimplifiedProperties(resource.properties, options) : [];
+		const resourceType = websitePresentationReader(resourceProperties).value("presentation");
 		if (resourceType === null) continue;
 		switch (resourceType) {
 			case "element": {
@@ -1131,7 +1136,8 @@ function parseWebBlock(blockResource, options, context) {
 	const isSupportingAccordionItems = returnBlock.properties.default.layout === "accordion" || returnBlock.properties.tablet?.layout === "accordion" || returnBlock.properties.mobile?.layout === "accordion";
 	const blockItems = [];
 	for (const resource of blockResources) {
-		const resourceReader = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []);
+		const resourceProperties = resource.properties ? parseSimplifiedProperties(resource.properties, options) : [];
+		const resourceReader = websitePresentationReader(resourceProperties);
 		const resourceType = resourceReader.value("presentation");
 		if (resourceType === null) continue;
 		switch (resourceType) {
@@ -1165,7 +1171,8 @@ function parseWebBlock(blockResource, options, context) {
 * @returns Parsed WebsiteProperties object
 */
 function parseWebsiteProperties(properties, websiteTree, sidebar, options, parent) {
-	const websiteReader = websitePresentationReader(parseSimplifiedProperties({ property: properties }, options)).nested("presentation");
+	const mainProperties = parseSimplifiedProperties({ property: properties }, options);
+	const websiteReader = websitePresentationReader(mainProperties).nested("presentation");
 	const returnProperties = {
 		type: websiteReader.valueOr("webUI", parent?.type ?? "traditional"),
 		status: websiteReader.valueOr("status", parent?.status ?? "development"),

package/dist/query.d.mts

@@ -1,12 +1,40 @@
 import { Query } from "./types/index.mjs";
 //#region src/query.d.ts
+/**
+ * Error message for OCR queries nested inside an OR group
+ * @internal
+ */
+declare 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";
+type OcrUuidBinding = {
+  name: string;
+  expression: string;
+};
 declare function buildAndCtsQueryExpression(queryExpressions: Array<string>): string | null;
+/**
+ * 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
+ */
+declare function buildOcrTermQueryExpressions(parameters: {
+  value: string;
+  matchMode: "includes" | "exact";
+  isCaseSensitive: boolean;
+}): Array<string>;
+/**
+ * Whether a query tree nests an OCR leaf inside an OR group
+ * @internal
+ */
+declare function hasOcrQueryInDisjunction(query: Query, isInDisjunction?: boolean): boolean;
 declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: Array<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 declare function buildQueryPlan(parameters: {
   queries: Query | null;
 }): {
   prolog: string;
   queryExpression: string | null;
+  ocrBindings: Array<OcrUuidBinding>;
+  itemPredicates: string;
 };
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { OCR_DISJUNCTION_ERROR_MESSAGE, buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildOcrTermQueryExpressions, buildQueryPlan, hasOcrQueryInDisjunction };

package/dist/query.mjs

@@ -12,6 +12,11 @@ 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 CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -199,6 +204,9 @@ 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()";
@@ -472,6 +480,63 @@ 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({
+		value,
+		matchMode,
+		isCaseSensitive
+	});
+	const isWholeWordEquality = matchMode === "exact" && terms.length === 1;
+	return Array.from(terms, (term) => isWholeWordEquality ? buildCtsElementValueQueryExpression({
+		elementName: "string",
+		value: term,
+		isCaseSensitive
+	}) : 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()");
+}
+function registerOcrItemPredicate(context, query) {
+	const bindingKey = [
+		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)`
+		});
+	}
+	const itemPredicate = query.isNegated === true ? `[not(@uuid = ${variableName})]` : `[@uuid = ${variableName}]`;
+	if (!context.itemPredicates.includes(itemPredicate)) context.itemPredicates.push(itemPredicate);
+}
 function getLeafSearchValue(query) {
 	switch (query.target) {
 		case "string":
@@ -552,7 +617,11 @@ function createQueryCompilerContext() {
 	return {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
-		helperDeclarations: []
+		helperDeclarations: [],
+		nextOcrSerial: 1,
+		ocrVariableNamesByKey: /* @__PURE__ */ new Map(),
+		ocrBindings: [],
+		itemPredicates: []
 	};
 }
 function registerConstantHelper(parameters) {
@@ -749,11 +818,24 @@ 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)) return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr") return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -814,14 +896,20 @@ function buildIncludesGroupQueryExpression(context, queries) {
 		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
 	}).callExpression, tokenizedQueryExpression]);
 }
-function buildQueryNode(context, query) {
+function buildQueryNode(context, query, isInDisjunction) {
 	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()";
+		}
 		const queryExpression = buildLeafQueryExpression(context, query);
 		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
 	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
-	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery));
+	const isChildInDisjunction = isInDisjunction || isDisjunctiveQueryGroup(query);
+	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, isChildInDisjunction));
 	return (getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal : buildOrCtsQueryExpressionInternal)(childQueryExpressions);
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
@@ -839,14 +927,18 @@ function buildQueryPlan(parameters) {
 	const { queries } = parameters;
 	if (queries == null) return {
 		prolog: "",
-		queryExpression: null
+		queryExpression: null,
+		ocrBindings: [],
+		itemPredicates: ""
 	};
 	const context = createQueryCompilerContext();
-	const queryExpression = buildQueryNode(context, queries);
+	const queryExpression = buildQueryNode(context, queries, false);
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		queryExpression
+		queryExpression,
+		ocrBindings: context.ocrBindings,
+		itemPredicates: context.itemPredicates.join("")
 	};
 }
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { OCR_DISJUNCTION_ERROR_MESSAGE, buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildOcrTermQueryExpressions, buildQueryPlan, hasOcrQueryInDisjunction };

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.GenericSchema<unknown, Query>, undefined>, null>;
+  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 attributes: v.OptionalSchema<v.ObjectSchema<{
     readonly bibliographies: v.GenericSchema<unknown, boolean>;
     readonly periods: v.GenericSchema<unknown, boolean>;
@@ -48,6 +48,17 @@ declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   }>;
   readonly isLimitedToLeafPropertyValues: v.GenericSchema<unknown, boolean>;
 }, undefined>;
+/**
+ * Schema for validating OCR matches parameters
+ * @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">]>;
+  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
  * @internal
@@ -55,7 +66,7 @@ declare const setPropertyValuesParametersSchema: 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.GenericSchema<unknown, Query>, undefined>, null>;
+  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 sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
     readonly target: v.LiteralSchema<"none", undefined>;
   }, undefined>, v.StrictObjectSchema<{
@@ -75,4 +86,4 @@ declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
 }, undefined>;
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/schemas.mjs

@@ -1,5 +1,6 @@
 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));
@@ -141,6 +142,13 @@ const setQueryLeafSchema = v.union([
 		value: v.string(),
 		...standardQueryFields
 	}),
+	v.strictObject({
+		target: v.literal("ocr"),
+		value: v.string(),
+		matchMode: standardQueryFields.matchMode,
+		isCaseSensitive: standardQueryFields.isCaseSensitive,
+		isNegated: standardQueryFields.isNegated
+	}),
 	v.strictObject({
 		target: v.picklist([
 			"title",
@@ -167,7 +175,7 @@ const setQuerySchema = v.lazy(() => v.union([
 * Schema for validating Set queries
 * @internal
 */
-const setQueriesSchema = v.optional(v.nullable(setQuerySchema), null);
+const setQueriesSchema = v.optional(v.nullable(v.pipe(setQuerySchema, v.check((query) => !hasOcrQueryInDisjunction(query), OCR_DISJUNCTION_ERROR_MESSAGE))), null);
 /**
 * Schema for validating Set items sort
 * @internal
@@ -214,6 +222,17 @@ const setPropertyValuesParametersSchema = v.object({
 	isLimitedToLeafPropertyValues: defaultBoolean(false)
 });
 /**
+* Schema for validating OCR matches parameters
+* @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")),
+	matchMode: v.optional(v.picklist(["includes", "exact"]), "includes"),
+	isCaseSensitive: defaultBoolean(false),
+	maxMatchesPerItem: v.optional(positiveNumber("Max matches per item must be positive"), 50)
+});
+/**
 * Schema for validating Set items parameters
 * @internal
 */
@@ -226,4 +245,4 @@ const setItemsParametersSchema = v.object({
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
 });
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/types/index.d.mts

@@ -262,6 +262,60 @@ type ImageMap = {
   width: number;
   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
+ *
+ *  `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.
+ */
+type OcrMatch = {
+  uuid: string;
+  resourceUuid: string | null;
+  page: Omit<OcrPage, "blocks">;
+  content: string;
+  words: Array<OcrWord>;
+};
 /**
  *  Note in OCHRE
  */
@@ -680,6 +734,7 @@ 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>;
@@ -789,6 +844,13 @@ 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`.
  */
 type QueryLeaf = {
   target: "property";
@@ -855,6 +917,12 @@ type QueryLeaf = {
   isCaseSensitive: boolean;
   language: string;
   isNegated?: boolean;
+} | {
+  target: "ocr";
+  value: string;
+  matchMode: "includes" | "exact";
+  isCaseSensitive: boolean;
+  isNegated?: boolean;
 } | {
   target: "title" | "description" | "image" | "periods" | "bibliography" | "notes";
   value: string;
@@ -876,4 +944,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, 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, 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 };

package/dist/xml/schemas.d.mts

@@ -1,6 +1,11 @@
-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 { 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 * 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>;
@@ -9,4 +14,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, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/schemas.mjs

@@ -220,6 +220,42 @@ const XMLImageMap = v.object({
 	width: XMLNumber,
 	height: XMLNumber
 }, "XMLImageMap: Shape error");
+const XMLOcrString = v.object({
+	HPOS: XMLNumber,
+	VPOS: XMLNumber,
+	WIDTH: XMLNumber,
+	HEIGHT: XMLNumber,
+	CONTENT: v.string("XMLOcrString: CONTENT is string and required"),
+	VERTICES: v.optional(v.string("XMLOcrString: VERTICES is string and optional"))
+}, "XMLOcrString: Shape error");
+const XMLOcrTextLine = v.object({ string: v.optional(v.array(XMLOcrString, "XMLOcrTextLine: string is array of XMLOcrString")) }, "XMLOcrTextLine: Shape error");
+const XMLOcrTextBlock = v.object({ TextLine: v.optional(v.array(XMLOcrTextLine, "XMLOcrTextBlock: TextLine is array of XMLOcrTextLine")) }, "XMLOcrTextBlock: Shape error");
+const XMLOcrPage = v.object({
+	n: XMLOptionalNumber,
+	fileName: v.optional(v.string("XMLOcrPage: fileName is string and optional")),
+	WIDTH: XMLOptionalNumber,
+	HEIGHT: XMLOptionalNumber,
+	TextBlock: v.optional(v.array(XMLOcrTextBlock, "XMLOcrPage: TextBlock is array of XMLOcrTextBlock"))
+}, "XMLOcrPage: Shape error");
+const XMLOcr = v.object({ Page: v.optional(v.array(XMLOcrPage, "XMLOcr: Page is array of XMLOcrPage")) }, "XMLOcr: Shape error");
+const XMLOcrMatch = v.object({
+	resourceUuid: v.optional(v.string("XMLOcrMatch: resourceUuid is string and optional")),
+	n: XMLOptionalNumber,
+	fileName: v.optional(v.string("XMLOcrMatch: fileName is string and optional")),
+	WIDTH: XMLOptionalNumber,
+	HEIGHT: XMLOptionalNumber,
+	string: v.optional(v.array(XMLOcrString, "XMLOcrMatch: string is array of XMLOcrString"))
+}, "XMLOcrMatch: Shape error");
+const XMLOcrMatchItem = v.object({
+	uuid: v.pipe(v.string("XMLOcrMatchItem: uuid is string and required"), v.check(isPseudoUuid, "XMLOcrMatchItem: uuid is not a valid pseudo-UUID")),
+	matchCount: XMLNumber,
+	ocrMatch: v.optional(v.array(XMLOcrMatch, "XMLOcrMatchItem: ocrMatch is array of XMLOcrMatch"))
+}, "XMLOcrMatchItem: Shape error");
+/**
+* Schema for validating OCR matches fetched from the OCHRE API
+* @internal
+*/
+const XMLOcrMatchesData = v.object({ result: v.object({ ochre: v.object({ ocrMatches: v.optional(v.object({ ocrItem: v.optional(v.array(XMLOcrMatchItem, "XMLOcrMatchesData: ocrItem is array of XMLOcrMatchItem")) })) }) }) }, "XMLOcrMatchesData: Shape error");
 const XMLNote = v.object({
 	content: v.optional(XMLContent.entries.content),
 	payload: v.optional(v.string("XMLNote: payload is string and optional")),
@@ -640,6 +676,7 @@ const XMLResource = v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
+	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -791,6 +828,7 @@ const XMLWebsiteResource = v.lazy(() => v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
+	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -924,4 +962,4 @@ const XMLWebsiteData = v.object({ result: v.object({ ochre: v.object({
 	tree: v.array(XMLWebsiteTree)
 }, "XMLWebsiteData: ochre is object with website tree") }, "XMLWebsiteData: result is object with ochre") }, "XMLWebsiteData: Shape error");
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/types.d.mts

@@ -175,6 +175,48 @@ type XMLImageMap = {
   width: XMLNumber;
   height: XMLNumber;
 };
+type XMLOcrString = {
+  HPOS: XMLNumber;
+  VPOS: XMLNumber;
+  WIDTH: XMLNumber;
+  HEIGHT: XMLNumber;
+  CONTENT: string;
+  VERTICES?: string;
+};
+type XMLOcrTextLine = {
+  string?: Array<XMLOcrString>;
+};
+type XMLOcrTextBlock = {
+  TextLine?: Array<XMLOcrTextLine>;
+};
+type XMLOcrPage = {
+  n?: XMLNumber;
+  fileName?: string;
+  WIDTH?: XMLNumber;
+  HEIGHT?: XMLNumber;
+  TextBlock?: Array<XMLOcrTextBlock>;
+};
+type XMLOcr = {
+  Page?: Array<XMLOcrPage>;
+};
+type XMLOcrMatch = Omit<XMLOcrPage, "TextBlock"> & {
+  resourceUuid?: string;
+  string?: Array<XMLOcrString>;
+};
+type XMLOcrMatchItem = {
+  uuid: string;
+  matchCount: XMLNumber;
+  ocrMatch?: Array<XMLOcrMatch>;
+};
+type XMLOcrMatchesData = {
+  result: {
+    ochre: {
+      ocrMatches?: {
+        ocrItem?: Array<XMLOcrMatchItem>;
+      };
+    };
+  };
+};
 type XMLNote = Partial<XMLContent> & XMLString & {
   noteNo?: XMLNumber;
   title?: string;
@@ -556,6 +598,7 @@ type XMLResource = XMLBaseItem & {
   width?: XMLNumber;
   image?: XMLImage;
   imagemap?: XMLImageMap;
+  ocr?: XMLOcr;
   document?: XMLContent;
   coordinates?: XMLCoordinates;
   periods?: {
@@ -913,4 +956,4 @@ type XMLWebsiteData = {
   };
 };
 //#endregion
-export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };
+export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLOcr, XMLOcrMatch, XMLOcrMatchItem, XMLOcrMatchesData, XMLOcrPage, XMLOcrString, XMLOcrTextBlock, XMLOcrTextLine, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.69",
+  "version": "1.0.71",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -53,10 +53,10 @@
   "devDependencies": {
     "@antfu/eslint-config": "^9.2.0",
     "@types/node": "^24.13.3",
-    "bumpp": "^12.0.0",
+    "bumpp": "^12.1.1",
     "eslint": "^10.8.0",
-    "knip": "^6.29.0",
-    "oxfmt": "^0.60.0",
+    "knip": "^6.31.0",
+    "oxfmt": "^0.61.0",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"