Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

8.0 KB
Raw Blame
/**
 * 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;
}