DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
/**
* Selection geometry: browser client rects → normalised annotation rects.
*
* Everything here is pure so it can be tested without a DOM: callers pass the
* rectangles they already measured. The output space is the one the store and
* the PDF export both speak — 0..1 of the unit box, origin top-left.
*
* Two behaviours are worth stating, because both were failure modes in the
* hand-rolled version:
*
* * **Line merging.** A selection spanning a wrapped phrase yields one client
* rect per line, plus slivers where the range clips a character box. Slivers
* render as visual noise, so rects are merged per text line and the
* degenerate ones dropped.
* * **Clamping.** A drag that leaves the page produces rects outside the box.
* They are clipped rather than discarded, so the highlight still covers the
* part of the text that *is* on the page.
*/
export interface Box {
left: number;
top: number;
width: number;
height: number;
}
export type NormalisedRect = [number, number, number, number];
/** Rects thinner or shorter than this (in px) are selection artefacts. */
const MIN_RECT_PX = 2;
/** Vertical overlap ratio above which two rects count as the same line. */
const SAME_LINE_OVERLAP = 0.5;
function clamp01(value: number): number {
if (!Number.isFinite(value)) return 0;
return Math.min(1, Math.max(0, value));
}
/**
* Group rects into text lines by vertical overlap, then union each group.
*
* Overlap rather than equal tops: sub/superscripts and mixed font sizes on one
* line have different tops but clearly belong together.
*/
export function mergeRectsByLine(rects: Box[]): Box[] {
const usable = rects.filter(
(rect) => rect.width >= MIN_RECT_PX && rect.height >= MIN_RECT_PX,
);
if (!usable.length) return [];
const sorted = [...usable].sort((a, b) => a.top - b.top || a.left - b.left);
const lines: Box[][] = [];
for (const rect of sorted) {
const line = lines.find((candidate) => {
const probe = candidate[0];
const overlap =
Math.min(probe.top + probe.height, rect.top + rect.height) -
Math.max(probe.top, rect.top);
const shorter = Math.min(probe.height, rect.height);
return shorter > 0 && overlap / shorter >= SAME_LINE_OVERLAP;
});
if (line) line.push(rect);
else lines.push([rect]);
}
return lines.map((line) => {
const left = Math.min(...line.map((r) => r.left));
const top = Math.min(...line.map((r) => r.top));
const right = Math.max(...line.map((r) => r.left + r.width));
const bottom = Math.max(...line.map((r) => r.top + r.height));
return { left, top, width: right - left, height: bottom - top };
});
}
/**
* Convert client rects to normalised rects relative to *container*.
*
* Both inputs are viewport-space rects (what `getBoundingClientRect` returns),
* so scroll position cancels out and no scroll offset is needed.
*/
export function normaliseRects(rects: Box[], container: Box): NormalisedRect[] {
if (container.width <= 0 || container.height <= 0) return [];
return mergeRectsByLine(rects)
.map((rect): NormalisedRect => {
const x0 = clamp01((rect.left - container.left) / container.width);
const y0 = clamp01((rect.top - container.top) / container.height);
const x1 = clamp01(
(rect.left + rect.width - container.left) / container.width,
);
const y1 = clamp01(
(rect.top + rect.height - container.top) / container.height,
);
return [
Math.min(x0, x1),
Math.min(y0, y1),
Math.max(x0, x1),
Math.max(y0, y1),
];
})
.filter(([x0, y0, x1, y1]) => x1 - x0 > 0.001 && y1 - y0 > 0.001);
}
/** Union of normalised rects, for positioning a popover over a selection. */
export function unionRect(rects: NormalisedRect[]): NormalisedRect | null {
if (!rects.length) return null;
return [
Math.min(...rects.map((r) => r[0])),
Math.min(...rects.map((r) => r[1])),
Math.max(...rects.map((r) => r[2])),
Math.max(...rects.map((r) => r[3])),
];
}
/**
* Tidy a selected string for storage as a quote.
*
* pdf.js text layers introduce line breaks wherever the PDF did, so the raw
* selection is full of hard wraps. Collapsing them is what makes the quote
* match the stored unit text server-side — the verification step that gates
* `reader_goto` depends on it.
*/
export function cleanQuote(raw: string, limit = 2000): string {
const flat = (raw || "").replace(/\s+/g, " ").trim();
return flat.length <= limit ? flat : flat.slice(0, limit);
}
const MARGIN_NUMBER = /^\d{1,4}$/;
/**
* The selected words without the page's margin line numbers, or `null` when
* there were none to drop.
*
* Review copies, legal texts and some textbooks number their lines in the
* margin, and pdf.js lays those digits out as text-layer spans like any other.
* A selection over several lines therefore comes back with them glued to the
* neighbouring words ("fall short in3 delivering", "DeepTu-4 tor"). A span
* that is nothing but a short number and sits wholly outside the column the
* selected words are set in is furniture, not text; a number inside that
* column ("Figure 3", "1 Introduction") is kept.
*
* Only for what a question carries. A mark keeps the raw selection: that is
* the string that matches the text layer when it is re-anchored.
*/
export function selectionTextWithoutLineNumbers(range: Range): string | null {
const container = range.commonAncestorContainer;
const root =
container.nodeType === Node.ELEMENT_NODE ? container : container.parentNode;
if (!root) return null;
const walker = document.createTreeWalker(
root,
NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT,
);
const nodes: Node[] = [];
// A selection inside a single text node has that node as its root, which
// the walker never yields; start from it rather than from its children.
for (
let node: Node | null =
root.nodeType === Node.TEXT_NODE ? root : walker.nextNode();
node;
node = walker.nextNode()
) {
if (range.intersectsNode(node)) nodes.push(node);
}
const isNumber = (node: Node) =>
node.nodeType === Node.TEXT_NODE &&
MARGIN_NUMBER.test((node.textContent ?? "").trim());
let columnLeft = Infinity;
let columnRight = -Infinity;
for (const node of nodes) {
if (node.nodeType !== Node.TEXT_NODE || isNumber(node)) continue;
if (!(node.textContent ?? "").trim() || !node.parentElement) continue;
const rect = node.parentElement.getBoundingClientRect();
columnLeft = Math.min(columnLeft, rect.left);
columnRight = Math.max(columnRight, rect.right);
}
if (!Number.isFinite(columnLeft)) return null;
const parts: string[] = [];
let dropped = false;
for (const node of nodes) {
if (node.nodeType === Node.ELEMENT_NODE) {
if ((node as Element).tagName === "BR") parts.push("\n");
continue;
}
const raw = node.textContent ?? "";
if (isNumber(node) && node.parentElement) {
const rect = node.parentElement.getBoundingClientRect();
if (rect.right <= columnLeft + 1 || rect.left >= columnRight - 1) {
dropped = true;
parts.push(" ");
continue;
}
}
const start = node === range.startContainer ? range.startOffset : 0;
const end = node === range.endContainer ? range.endOffset : raw.length;
parts.push(raw.slice(start, end));
}
if (!dropped) return null;
// A word the line broke with a hyphen keeps the hyphen but loses the gap
// the dropped number left: "DeepTu-tor" reads, "DeepTu- tor" does not.
const joined = parts.join("").replace(/(\p{L})-\s+(?=\p{L})/gu, "$1-");
return cleanQuote(joined) || null;
}
/**
* Which locator a selection belongs to, given the elements it spans.
*
* A selection dragged across a page boundary is attributed to where it
* *started*, matching how the user thinks about it, instead of being rejected.
*/
export function locatorOfSelection(
locators: Array<number | null>,
): number | null {
for (const locator of locators) {
if (typeof locator === "number" && locator >= 1) return locator;
}
return null;
}