@epam/ai-dial-quotations 1.1.0-dev.433 → 1.1.0-dev.435

package/index.d.ts

@@ -10,9 +10,10 @@ export { useAnnotations } from './utils/useAnnotations';
 export { useCitationCard } from './utils/useCitationCard';
 export { useCitationMarkdownComponents } from './hooks/useCitationMarkdownComponents/useCitationMarkdownComponents';
 export type { UseCitationMarkdownComponentsCallbacks } from './hooks/useCitationMarkdownComponents/useCitationMarkdownComponents';
-export { groupAnnotations, groupAnnotationsByCitId, groupAnnotationsBySource, } from './utils/group-annotations-by-source';
+export { gatherSameSourceAnnotations, groupAnnotations, groupAnnotationsByCitId, groupAnnotationsBySource, } from './utils/group-annotations-by-source';
 export type { AnnotationGroup } from './utils/group-annotations-by-source';
-export { annotationsToPdfHighlights, annotationHighlightId, getAnnotationPdfPage, normalizeRawAnnotations, resolveMessageAnnotations, } from './utils/annotation';
+export { annotationHighlightId, annotationsToPdfHighlights, annotationToOfficeHighlightLocations, getAnnotationPdfPage, isDocxRangeSelector, isExcelRcRangeSelector, isPptxRangeSelector, normalizeRawAnnotations, resolveMessageAnnotations, } from './utils/annotation';
+export type { DocxOfficeHighlightLocation, ExcelOfficeHighlightLocation, OfficeHighlightLocation, PptxOfficeHighlightLocation, } from './models/office-highlight';
 export { injectCitationSentinels, replaceSentinelsInChildren, stripCitTagsWhileStreaming, } from './utils/citation-injection';
 export { isReferenceOnlyAttachment, parsePdfPageReference, getReferenceAttachmentGroups, } from './utils/reference-attachment';
 export type { PdfPageReference } from './utils/reference-attachment';

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,YAAY,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAG5F,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,qEAAqE,CAAC;AACpH,YAAY,EAAE,sCAAsC,EAAE,MAAM,qEAAqE,CAAC;AAGlI,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,YAAY,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAG5F,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,qEAAqE,CAAC;AACpH,YAAY,EAAE,sCAAsC,EAAE,MAAM,qEAAqE,CAAC;AAGlI,OAAO,EACL,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,oCAAoC,EACpC,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

package/index.js

@@ -169,7 +169,7 @@ var j = {
 	if (t != null) return t;
 	let n = e.split(/[?#]/)[0], i = n.lastIndexOf(".");
 	if (i !== -1) return M[n.slice(i + 1).toLowerCase()];
-}, P = (e) => typeof e == "object" && !!e && !Array.isArray(e) && "type" in e && typeof e.type == "string", ee = (e) => Array.isArray(e) ? e.filter(P) : P(e) ? e : void 0, F = (e) => e.flatMap((e, t) => {
+}, P = (e) => typeof e == "object" && !!e && !Array.isArray(e) && "type" in e && typeof e.type == "string", ee = (e) => Array.isArray(e) ? e.filter(P) : P(e) ? e : void 0, te = (e) => e.flatMap((e, t) => {
 	let n = e.body?.selector;
 	if (n == null) return [];
 	let r = (Array.isArray(n) ? n : [n]).flatMap((e) => {
@@ -193,38 +193,38 @@ var j = {
 		bboxes: r,
 		style: j
 	}];
-}), te = (e, t) => String(e.index ?? t), ne = (e) => {
+}), ne = (e, t) => String(e.index ?? t), re = (e) => {
 	let t = e.body?.selector;
 	if (t != null) return (Array.isArray(t) ? t : [t]).find((e) => P(e) && e.type === "pdf_bbox" && typeof e.page == "number" && Number.isInteger(e.page) && e.page >= 1)?.page;
-}, I = (e) => typeof e == "number" ? e : null, re = (e) => {
+}, F = (e) => typeof e == "number" ? e : null, ie = (e) => {
 	if (typeof e != "object" || !e) return null;
 	let t = e;
 	if (t.type !== "pdf_region") return null;
 	let n = t.bbox;
 	if (typeof n != "object" || !n) return null;
-	let r = n, i = I(r.left), a = I(r.top), o = I(r.width), s = I(r.height);
+	let r = n, i = F(r.left), a = F(r.top), o = F(r.width), s = F(r.height);
 	return i === null || a === null || o === null || s === null ? null : {
 		type: "pdf_bbox",
-		page: I(t.page) ?? 1,
+		page: F(t.page) ?? 1,
 		x1: i,
 		y1: a,
 		x2: i + o,
 		y2: a + s
 	};
-}, ie = (t, n) => {
+}, ae = (t, n) => {
 	let r = t.target;
 	if (typeof r != "object" || !r) return null;
 	let i = r, a = i.source;
 	if (typeof a != "object" || !a) return null;
-	let o = I(a.attachment_index);
+	let o = F(a.attachment_index);
 	if (o === null) return null;
 	let s = n.find((e) => e.index === o);
 	if (s?.url == null) return null;
-	let c = re(i.selector);
+	let c = ie(i.selector);
 	if (c === null) return null;
 	let l = t.body, u = typeof l == "object" && l ? l : {}, d = typeof u.title == "string" ? u.title : void 0, f = typeof u.quote == "string" ? u.quote : void 0;
 	return {
-		index: I(t.index) ?? void 0,
+		index: F(t.index) ?? void 0,
 		body: {
 			title: d,
 			quote: f,
@@ -239,7 +239,7 @@ var j = {
 			selector: c
 		}
 	};
-}, ae = (t) => {
+}, oe = (t) => {
 	let n = t.target;
 	if (typeof n != "object" || !n) return null;
 	let r = n.selector;
@@ -260,7 +260,7 @@ var j = {
 	if (typeof u != "string") return null;
 	let d = typeof s.title == "string" ? s.title : void 0, f = typeof s.quote == "string" ? s.quote : void 0, p = ee(s.selector);
 	return {
-		index: I(t.index) ?? void 0,
+		index: F(t.index) ?? void 0,
 		target: { selector: a },
 		body: {
 			title: d,
@@ -276,7 +276,7 @@ var j = {
 			}
 		}
 	};
-}, L = (e) => {
+}, I = (e) => {
 	if (e.target?.selector?.type !== "html_tag") return e;
 	let t = e.body?.source?.attachment;
 	if (t?.url == null) return e;
@@ -295,24 +295,89 @@ var j = {
 			}
 		}
 	};
-}, R = (e, t) => e.flatMap((e) => {
+}, L = (e, t) => e.flatMap((e) => {
 	if (typeof e != "object" || !e) return [];
-	let n = e, r = ae(n);
+	let n = e, r = oe(n);
 	if (r) return [r];
-	let i = ie(n, t);
+	let i = ae(n, t);
 	return i ? [i] : [];
-}), z = (e) => {
+}), R = (e) => {
 	let t = e.custom_content?.annotations;
-	if (t?.length) return t.filter((e) => e != null && e.body?.source?.attachment?.url != null).map(L);
+	if (t?.length) return t.filter((e) => e != null && e.body?.source?.attachment?.url != null).map(I);
 	let n = e.custom_fields;
 	if (typeof n != "object" || !n) return [];
 	let r = n.annotations;
-	return !Array.isArray(r) || r.length === 0 ? [] : R(r, e.custom_content?.attachments ?? []).map(L);
-}, oe = (e, t) => v(() => t ? [] : z(e), [t, e]), se = {
+	return !Array.isArray(r) || r.length === 0 ? [] : L(r, e.custom_content?.attachments ?? []).map(I);
+}, z = (e) => {
+	if (e.type !== "docx_text_range") return !1;
+	let t = e;
+	return typeof t.story == "string" && Array.isArray(t.path) && t.path.every((e) => typeof e == "number") && typeof t.start == "number" && typeof t.end == "number" && typeof t.text == "string";
+}, B = (e) => {
+	if (e.type !== "pptx_text_range") return !1;
+	let t = e;
+	return typeof t.slide == "number" && typeof t.shape_id == "string" && typeof t.start == "number" && typeof t.end == "number" && typeof t.text == "string";
+}, V = (e) => typeof e == "object" && !!e && typeof e.row == "number" && typeof e.col == "number", H = (e) => {
+	if (e.type !== "excel_rc_range") return !1;
+	let t = e;
+	return typeof t.sheet == "string" && V(t.start) && (t.end === void 0 || t.end === null || V(t.end));
+}, se = (e) => {
+	let { story: t, path: n, start: r, end: i, text: a } = e;
+	if (!(!n.every((e) => Number.isInteger(e)) || !Number.isInteger(r) || !Number.isInteger(i) || r < 0 || i < r)) return {
+		type: "docx_text_range",
+		story: t,
+		path: n,
+		start: r,
+		endExclusive: i,
+		text: a
+	};
+}, ce = (e) => {
+	let { slide: t, shape_id: n, start: r, end: i, text: a } = e;
+	if (!(!Number.isInteger(t) || t < 1 || !Number.isInteger(r) || !Number.isInteger(i) || r < 0 || i < r)) return {
+		type: "pptx_text_range",
+		slide: t,
+		shapeId: n,
+		start: r,
+		endExclusive: i,
+		text: a
+	};
+}, le = (e) => {
+	let { sheet: t, start: n, end: r } = e;
+	if (!(t.length === 0 || !Number.isInteger(n.row) || !Number.isInteger(n.col) || n.row < 1 || n.col < 1)) {
+		if (r == null) return {
+			type: "excel_rc_range",
+			sheet: t,
+			start: n
+		};
+		if (!(!Number.isInteger(r.row) || !Number.isInteger(r.col) || r.row !== n.row || r.col < n.col)) return {
+			type: "excel_rc_range",
+			sheet: t,
+			start: n,
+			end: r
+		};
+	}
+}, ue = (e) => {
+	let t = e.body?.selector;
+	return t == null ? [] : (Array.isArray(t) ? t : [t]).flatMap((e) => {
+		if (!P(e)) return [];
+		if (z(e)) {
+			let t = se(e);
+			return t ? [t] : [];
+		}
+		if (B(e)) {
+			let t = ce(e);
+			return t ? [t] : [];
+		}
+		if (H(e)) {
+			let t = le(e);
+			return t ? [t] : [];
+		}
+		return [];
+	});
+}, de = (e, t) => v(() => t ? [] : R(e), [t, e]), fe = {
 	openGroupKey: null,
 	activeIndexByGroup: {}
-}, ce = () => {
-	let [e, t] = y(se), n = g((e) => {
+}, pe = () => {
+	let [e, t] = y(fe), n = g((e) => {
 		t((t) => ({
 			...t,
 			openGroupKey: e
@@ -343,7 +408,7 @@ var j = {
 		i,
 		e
 	]);
-}, le = /⟦C(\d+)⟧/g, B = (e, t) => {
+}, me = /⟦C(\d+)⟧/g, U = (e, t) => {
 	let n = t.map((e, t) => ({
 		g: e,
 		idx: t
@@ -356,9 +421,9 @@ var j = {
 	}).sort((e, t) => t.pos - e.pos), r = e;
 	for (let { idx: e, pos: t } of n) r = `${r.slice(0, t)}⟦C${e}⟧${r.slice(t)}`;
 	return r;
-}, V = /<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>/g, H = /^<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>$/, U = /<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>|<\/?cit\b[^>]*>|<\/?cit\b[^>]*$/gi, ue = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), W = (e) => e.replace(U, (e) => H.test(e) ? e : ue(e)), G = (e) => W(e).replace(V, ""), K = (e, t) => {
+}, he = /<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>/g, ge = /^<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>$/, _e = /<cit\s+data-id=(?:"[^"]+"|'[^']+')\s*>\s*<\/cit>|<\/?cit\b[^>]*>|<\/?cit\b[^>]*$/gi, ve = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), W = (e) => e.replace(_e, (e) => ge.test(e) ? e : ve(e)), G = (e) => W(e).replace(he, ""), K = (e, t) => {
 	if (typeof e == "string") {
-		let n = e.split(le);
+		let n = e.split(me);
 		if (n.length === 1) return e;
 		let r = [];
 		return n.forEach((e, n) => {
@@ -369,15 +434,15 @@ var j = {
 		let n = K(e, t);
 		return Array.isArray(n) ? n : [n];
 	}) : e;
-}, de = (e) => {
+}, ye = (e) => {
 	let t = e.primaryAnnotation.target?.selector;
 	return t?.type === "html_tag" ? t.id : void 0;
-}, fe = (e, t) => /* @__PURE__ */ S(b, { children: [
+}, be = (e, t) => /* @__PURE__ */ S(b, { children: [
 	e == null ? "<cit>" : `<cit data-id="${e}">`,
 	t,
 	"</cit>"
-] }), pe = (e, t, n, r = !1, a = !1) => {
-	let { onPreview: o, onOpenInBrowser: s, buildLabels: c } = n, l = v(() => r ? G(e) : W(t.length > 0 ? B(e, t) : e), [
+] }), xe = (e, t, n, r = !1, a = !1) => {
+	let { onPreview: o, onOpenInBrowser: s, buildLabels: c } = n, l = v(() => r ? G(e) : W(t.length > 0 ? U(e, t) : e), [
 		e,
 		t,
 		r
@@ -387,7 +452,7 @@ var j = {
 		markdownComponents: v(() => {
 			let e = /* @__PURE__ */ new Map();
 			for (let n of t) {
-				let t = de(n);
+				let t = ye(n);
 				t != null && e.set(t, n);
 			}
 			let n = (e) => {
@@ -404,7 +469,7 @@ var j = {
 				return r ? n(r) : null;
 			}, l = { cit: (t) => {
 				let r = t["data-id"] == null ? void 0 : e.get(t["data-id"]);
-				return r ? n(r) : fe(t["data-id"], t.children);
+				return r ? n(r) : be(t["data-id"], t.children);
 			} };
 			return t.length === 0 ? u ? l : {} : {
 				...l,
@@ -434,20 +499,20 @@ var j = {
 	} catch {
 		return e;
 	}
-}, me = (e) => {
+}, Se = (e) => {
 	try {
 		let t = new URL(e);
 		return t.pathname.split("/").map((e) => q(e)).filter(Boolean).at(-1) ?? t.hostname;
 	} catch {
 		return e.split("/").map((e) => q(e)).filter(Boolean).at(-1) ?? e;
 	}
-}, J = (e, t) => e.body?.source?.attachment?.title ?? me(t), Y = (e) => {
+}, J = (e, t) => e.body?.source?.attachment?.title ?? Se(t), Y = (e) => {
 	let t = e.target?.selector;
 	return t?.type === "html_tag" ? t : void 0;
-}, he = (e) => Y(e) != null, X = (e) => {
+}, Ce = (e) => Y(e) != null, X = (e) => {
 	let t = /* @__PURE__ */ new Map();
 	for (let n of e) {
-		if (he(n)) continue;
+		if (Ce(n)) continue;
 		let e = n.body?.source?.attachment?.url;
 		if (e == null) continue;
 		let r = t.get(e);
@@ -477,13 +542,16 @@ var j = {
 		});
 	}
 	return Array.from(t.values());
-}, ge = (e) => [...Z(e), ...X(e)], Q = (e) => e.url == null && e.reference_url != null, _e = /^(.*\.pdf)(?:#page=(\d+))?$/i, $ = (e) => {
-	let t = _e.exec(e);
+}, we = (e) => [...Z(e), ...X(e)], Te = (e, t) => {
+	let n = e.body?.source?.attachment?.url;
+	return n == null || !t.includes(e) ? [e] : t.filter((e) => e.body?.source?.attachment?.url === n);
+}, Q = (e) => e.url == null && e.reference_url != null, Ee = /^(.*\.pdf)(?:#page=(\d+))?$/i, $ = (e) => {
+	let t = Ee.exec(e);
 	return t ? {
 		baseUrl: t[1],
 		page: t[2] == null ? null : Number(t[2])
 	} : null;
-}, ve = (t) => X((t ?? []).filter(Q).map((t) => {
+}, De = (t) => X((t ?? []).filter(Q).map((t) => {
 	let n = t.reference_url, r = $(n) != null;
 	return { body: {
 		quote: t.data,
@@ -498,4 +566,4 @@ var j = {
 	} };
 }));
 //#endregion
-export { w as CitationCard, D as CitationCardProvider, A as CitationDropdown, T as CitationMarker, te as annotationHighlightId, F as annotationsToPdfHighlights, ne as getAnnotationPdfPage, ve as getReferenceAttachmentGroups, ge as groupAnnotations, Z as groupAnnotationsByCitId, X as groupAnnotationsBySource, B as injectCitationSentinels, Q as isReferenceOnlyAttachment, R as normalizeRawAnnotations, $ as parsePdfPageReference, K as replaceSentinelsInChildren, z as resolveMessageAnnotations, G as stripCitTagsWhileStreaming, oe as useAnnotations, ce as useCitationCard, O as useCitationCardContext, pe as useCitationMarkdownComponents };
+export { w as CitationCard, D as CitationCardProvider, A as CitationDropdown, T as CitationMarker, ne as annotationHighlightId, ue as annotationToOfficeHighlightLocations, te as annotationsToPdfHighlights, Te as gatherSameSourceAnnotations, re as getAnnotationPdfPage, De as getReferenceAttachmentGroups, we as groupAnnotations, Z as groupAnnotationsByCitId, X as groupAnnotationsBySource, U as injectCitationSentinels, z as isDocxRangeSelector, H as isExcelRcRangeSelector, B as isPptxRangeSelector, Q as isReferenceOnlyAttachment, L as normalizeRawAnnotations, $ as parsePdfPageReference, K as replaceSentinelsInChildren, R as resolveMessageAnnotations, G as stripCitTagsWhileStreaming, de as useAnnotations, pe as useCitationCard, O as useCitationCardContext, xe as useCitationMarkdownComponents };

package/models/office-highlight.d.ts

@@ -0,0 +1,62 @@
+import { ExcelCellAddress } from '@epam/ai-dial-chat-shared';
+/**
+ * A validated, normalised DOCX character-range location. `endExclusive` is
+ * the wire's `end` copied through unchanged — confirmed exclusive on the
+ * wire, unlike `TextCharacterRangeSelector`'s inclusive `end` (see the
+ * `annotation.ts` normaliser and `design.md` D3 for the evidence).
+ */
+export interface DocxOfficeHighlightLocation {
+    /** Discriminates this location within `OfficeHighlightLocation`. Mirrors the wire selector's `type`. */
+    type: 'docx_text_range';
+    /** Name of the DOCX story the range lives in, as an opaque string (only `'body'` is confirmed upstream). */
+    story: string;
+    /** Source-tree element indices identifying the paragraph, matched element-wise. */
+    path: number[];
+    /** Zero-based start character offset. */
+    start: number;
+    /** Zero-based exclusive end character offset. */
+    endExclusive: number;
+    /** The cited text, expected to equal the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+/**
+ * A validated, normalised PPTX character-range location. `endExclusive` is
+ * the wire's `end` copied through unchanged — confirmed exclusive on the
+ * wire (see `design.md` D3).
+ */
+export interface PptxOfficeHighlightLocation {
+    /** Discriminates this location within `OfficeHighlightLocation`. Mirrors the wire selector's `type`. */
+    type: 'pptx_text_range';
+    /** 1-based slide number. */
+    slide: number;
+    /** Shape identifier, compared as a string against the run's own shape id. */
+    shapeId: string;
+    /** Zero-based start character offset. */
+    start: number;
+    /** Zero-based exclusive end character offset. */
+    endExclusive: number;
+    /** The cited text, expected to equal the text resolved over `[start, endExclusive)`. */
+    text: string;
+}
+/** A validated, normalised XLSX cell or same-row cell-range location. */
+export interface ExcelOfficeHighlightLocation {
+    /** Discriminates this location within `OfficeHighlightLocation`. Mirrors the wire selector's `type`. */
+    type: 'excel_rc_range';
+    /** Sheet name, matched exactly against the workbook's own sheet names. */
+    sheet: string;
+    /** First cell of the range. */
+    start: ExcelCellAddress;
+    /** Last (inclusive) cell of the range, on the same row as `start`. Omitted for a single cell. */
+    end?: ExcelCellAddress;
+}
+/**
+ * A validated, normalised Office document highlight location, produced by
+ * `annotationToOfficeHighlightLocations`. Intentionally not the
+ * `@epam/ai-dial-attachment-canvas` `OoxmlHighlightLocation` shape — this lib
+ * must not depend on `attachment-canvas` (that lib's own test already
+ * depends on this one, via `annotationsToPdfHighlights`, and a lib-to-lib
+ * cycle is not permitted). `libs/chat-hooks`, which already depends on both,
+ * maps this into `OoxmlHighlight`/`OoxmlHighlightLocation`.
+ */
+export type OfficeHighlightLocation = DocxOfficeHighlightLocation | PptxOfficeHighlightLocation | ExcelOfficeHighlightLocation;
+//# sourceMappingURL=office-highlight.d.ts.map

package/models/office-highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-highlight.d.ts","sourceRoot":"","sources":["../../src/models/office-highlight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,wGAAwG;IACxG,IAAI,EAAE,iBAAiB,CAAC;IACxB,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,wGAAwG;IACxG,IAAI,EAAE,iBAAiB,CAAC;IACxB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,wGAAwG;IACxG,IAAI,EAAE,gBAAgB,CAAC;IACvB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,KAAK,EAAE,gBAAgB,CAAC;IACxB,iGAAiG;IACjG,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@epam/ai-dial-quotations",
   "description": "Citation and annotation components, hooks, and utilities for AI DIAL conversations",
-  "version": "1.1.0-dev.433",
+  "version": "1.1.0-dev.435",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./index.js",
@@ -19,7 +19,7 @@
     "react": "^19.0.0",
     "react-markdown": "^10.1.0",
     "@tabler/icons-react": "^3.0.0",
-    "@epam/ai-dial-chat-shared": "1.1.0-dev.433",
+    "@epam/ai-dial-chat-shared": "1.1.0-dev.435",
     "@epam/ai-dial-ui-kit": "*",
     "@epam/pdf-highlighter-kit": ">=0.0.14"
   },

package/utils/annotation.d.ts

@@ -1,5 +1,6 @@
-import { Annotation, Message, MessageAttachment } from '@epam/ai-dial-chat-shared';
+import { Annotation, AnnotationSelector, DocxRangeSelector, ExcelRcRangeSelector, Message, MessageAttachment, PptxRangeSelector } from '@epam/ai-dial-chat-shared';
 import { InputHighlightData } from '@epam/pdf-highlighter-kit';
+import { OfficeHighlightLocation } from '../models/office-highlight';
 /**
  * Maps a list of annotations to `InputHighlightData` entries for the PDF viewer.
  * Annotations whose `body.selector` contains no `pdf_bbox` selectors are skipped.
@@ -39,4 +40,26 @@ export declare const normalizeRawAnnotations: (rawAnnotations: unknown[], attach
  * normalises those entries using the message's `custom_content.attachments`.
  */
 export declare const resolveMessageAnnotations: (message: Message) => Annotation[];
+/**
+ * Returns whether `selector` is a `docx_text_range` selector carrying every
+ * field the shape requires — a `_range`-suffixed selector missing any field
+ * (or with a wrongly-typed one) does not match.
+ */
+export declare const isDocxRangeSelector: (selector: AnnotationSelector) => selector is DocxRangeSelector;
+/**
+ * Returns whether `selector` is a `pptx_text_range` selector carrying every
+ * field the shape requires.
+ */
+export declare const isPptxRangeSelector: (selector: AnnotationSelector) => selector is PptxRangeSelector;
+/**
+ * Returns whether `selector` is an `excel_rc_range` selector carrying every
+ * field the shape requires. `end` may be a cell address, `null`, or absent.
+ */
+export declare const isExcelRcRangeSelector: (selector: AnnotationSelector) => selector is ExcelRcRangeSelector;
+/**
+ * Converts an annotation's `body.selector` (scalar or array) to validated
+ * `OfficeHighlightLocation` entries, skipping any selector that is not a
+ * recognised Office range or that fails validation — never throwing.
+ */
+export declare const annotationToOfficeHighlightLocations: (annotation: Annotation) => OfficeHighlightLocation[];
 //# sourceMappingURL=annotation.d.ts.map

package/utils/annotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["../../src/utils/annotation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EAGV,OAAO,EACP,iBAAiB,EAElB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAyCnC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACrC,aAAa,UAAU,EAAE,KACxB,kBAAkB,EA0BjB,CAAC;AAEL,oHAAoH;AACpH,eAAO,MAAM,qBAAqB,GAChC,YAAY,UAAU,EACtB,eAAe,MAAM,KACpB,MAAmD,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,UAAU,KACrB,MAAM,GAAG,SAcX,CAAC;AA4KF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,GAClC,gBAAgB,OAAO,EAAE,EACzB,aAAa,iBAAiB,EAAE,KAC/B,UAAU,EAeT,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,KAAG,UAAU,EAoBtE,CAAC"}
+{"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["../../src/utils/annotation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EAEpB,OAAO,EACP,iBAAiB,EAEjB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAyC1E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACrC,aAAa,UAAU,EAAE,KACxB,kBAAkB,EA0BjB,CAAC;AAEL,oHAAoH;AACpH,eAAO,MAAM,qBAAqB,GAChC,YAAY,UAAU,EACtB,eAAe,MAAM,KACpB,MAAmD,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,UAAU,KACrB,MAAM,GAAG,SAcX,CAAC;AA4KF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,GAClC,gBAAgB,OAAO,EAAE,EACzB,aAAa,iBAAiB,EAAE,KAC/B,UAAU,EAeT,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,KAAG,UAAU,EAoBtE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,kBAAkB,KAC3B,QAAQ,IAAI,iBAWd,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,kBAAkB,KAC3B,QAAQ,IAAI,iBAUd,CAAC;AAUF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,kBAAkB,KAC3B,QAAQ,IAAI,oBAQd,CAAC;AA8FF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAC/C,YAAY,UAAU,KACrB,uBAAuB,EAsBzB,CAAC"}

package/utils/group-annotations-by-source.d.ts

@@ -41,4 +41,14 @@ export declare const groupAnnotationsByCitId: (annotations: Annotation[]) => Ann
  * citations without branching on selector type itself.
  */
 export declare const groupAnnotations: (annotations: Annotation[]) => AnnotationGroup[];
+/**
+ * Returns every annotation in `annotations` whose `body.source.attachment.url`
+ * equals `clicked`'s, in their original order — gathering across the whole
+ * list rather than one `cit`-id group, so annotations behind other markers
+ * citing the same file are included too. Keys on URL, never on the display
+ * title, since two different files can share a title. Returns `[clicked]`
+ * when `clicked` is not itself present in `annotations` (identified by
+ * reference identity) or has no source URL.
+ */
+export declare const gatherSameSourceAnnotations: (clicked: Annotation, annotations: Annotation[]) => Annotation[];
 //# sourceMappingURL=group-annotations-by-source.d.ts.map

package/utils/group-annotations-by-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-annotations-by-source.d.ts","sourceRoot":"","sources":["../../src/utils/group-annotations-by-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,2BAA2B,CAAC;AAE7E,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,wFAAwF;IACxF,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AAkDD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,UAAU,EAAE,KACxB,eAAe,EAuBjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,aAAa,UAAU,EAAE,KACxB,eAAe,EAwBjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,UAAU,EAAE,KACxB,eAAe,EAGjB,CAAC"}
+{"version":3,"file":"group-annotations-by-source.d.ts","sourceRoot":"","sources":["../../src/utils/group-annotations-by-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,2BAA2B,CAAC;AAE7E,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,wFAAwF;IACxF,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AAkDD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,UAAU,EAAE,KACxB,eAAe,EAuBjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,aAAa,UAAU,EAAE,KACxB,eAAe,EAwBjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,UAAU,EAAE,KACxB,eAAe,EAGjB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,UAAU,EACnB,aAAa,UAAU,EAAE,KACxB,UAAU,EAKZ,CAAC"}