~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
/**
* Annotation Surface (shared component)
*
* Word-review-style inline comments over a container of IMMUTABLE
* rendered text (research reports, library-document extracted text —
* immutability is what makes quote anchors safe). Provides:
* - a selection toolbar (Comment + host-supplied extra actions),
* - the comment-entry popover (each comment is saved as a NOTE by the
* host's endpoint; this component only ships quote/prefix/suffix +
* comment),
* - the anchor engine: whitespace-normalized quote matching with
* virtual spaces at <br>/block boundaries, per-text-node <mark>
* wrapping, prefix/suffix disambiguation for repeated phrases,
* - highlight popovers with Open note / Delete.
*
* Hosts (components/research_notes.js, components/document_notes.js)
* call LDRAnnotationSurface.init(config) with their endpoints. The ONE
* deliberate global is the namespaced window.LDRAnnotationSurface —
* unique enough not to collide with the deferred shared scripts.
*
* URL security: all URLs used here come from the host config and are
* same-origin relative paths; no external URLs are handled. External URL
* validation is available via URLValidator.isSafeUrl if that changes.
*/
(function() {
'use strict';
// ------------------------------------------------------------------
// Anchor engine (pure — exposed on the test hook below)
// ------------------------------------------------------------------
// Elements whose boundary reads as a break in the rendered text even
// though they contribute NO character to textContent: <br> most of
// all (markdown renderers turn intra-paragraph newlines into <br>, so
// textContent says "butshared" where the user sees — and selects —
// "but\nshared"), plus block-level containers.
const BLOCK_BOUNDARY_RE = /^(?:P|DIV|LI|UL|OL|H[1-6]|BLOCKQUOTE|PRE|TABLE|THEAD|TBODY|TR|TD|TH|SECTION|ARTICLE|BR|HR)$/;
/**
* Build a whitespace-normalized string over the container's rendered
* text plus a per-character map back to (node, offset). Whitespace
* runs collapse to one space, and <br>/block boundaries emit a
* VIRTUAL space (map entry null — no DOM position), so a quote
* captured from selection.toString() (which inserts newlines at those
* boundaries) matches the same passage in the haystack.
*/
function buildNormalizedText(root) {
const map = [];
let text = '';
let lastWasSpace = true; // drop leading whitespace
const pushVirtualSpace = () => {
if (!lastWasSpace) {
text += ' ';
map.push(null);
lastWasSpace = true;
}
};
// Recursive DFS (document order, same as a TreeWalker) so a block/<br>
// boundary can emit a virtual space on BOTH sides. Emitting only on
// ENTER left bare text that immediately follows a closed block (e.g. a
// caption right after </blockquote>) glued to the block's text
// ("insightas noted"), so a quote spanning that boundary — where a
// selection inserts a newline — never anchored.
const walk = (parent) => {
for (let node = parent.firstChild; node; node = node.nextSibling) {
if (node.nodeType === Node.ELEMENT_NODE) {
const isBoundary = BLOCK_BOUNDARY_RE.test(node.tagName);
if (isBoundary) pushVirtualSpace();
walk(node);
if (isBoundary) pushVirtualSpace();
} else if (node.nodeType === Node.TEXT_NODE) {
const s = node.textContent;
for (let i = 0; i < s.length; i++) {
if (/\s/.test(s[i])) {
if (!lastWasSpace) {
text += ' ';
map.push({ node, offset: i });
lastWasSpace = true;
}
} else {
text += s[i];
map.push({ node, offset: i });
lastWasSpace = false;
}
}
}
}
};
walk(root);
// Drop trailing boundary/whitespace: the outermost element's exit adds
// a trailing virtual space, but a quote is always trimmed, so the
// haystack should end at its last real character (keeps the text stable
// and matchable).
while (text.endsWith(' ')) {
text = text.slice(0, -1);
map.pop();
}
return { text, map };
}
function normalizeWhitespace(s) {
return String(s || '').replace(/\s+/g, ' ').trim();
}
/**
* Locate `quote` in the normalized haystack; when the phrase repeats,
* prefer the occurrence whose surroundings best match prefix/suffix.
*/
function findQuoteIndex(haystack, quote, prefix, suffix) {
// Empty quote: indexOf('', n) never returns -1, so the hit-collection
// loop below would spin forever. Callers already guard, but this is
// the exposed pure engine — fail closed.
if (!quote) return -1;
const hits = [];
let i = haystack.indexOf(quote);
while (i !== -1) {
hits.push(i);
i = haystack.indexOf(quote, i + 1);
}
if (!hits.length) return -1;
if (hits.length === 1 || (!prefix && !suffix)) return hits[0];
const sharedEndLen = (a, b) => {
let n = 0;
while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) n++;
return n;
};
const sharedStartLen = (a, b) => {
let n = 0;
while (n < a.length && n < b.length && a[n] === b[n]) n++;
return n;
};
let best = hits[0];
let bestScore = -1;
for (const h of hits) {
let score = 0;
if (prefix) score += sharedEndLen(haystack.slice(Math.max(0, h - prefix.length), h), prefix);
if (suffix) score += sharedStartLen(haystack.slice(h + quote.length, h + quote.length + suffix.length), suffix);
if (score > bestScore) {
bestScore = score;
best = h;
}
}
return best;
}
/**
* Wrap the normalized-index range [start, end) in <mark> elements —
* one per text-node segment (a Range spanning element boundaries
* can't be surrounded in one piece). Null map entries are virtual
* boundary spaces with no DOM position.
*/
function wrapNormalizedRange(map, start, end, noteId) {
const segments = [];
let current = null;
for (let i = start; i < end; i++) {
const m = map[i];
if (!m) {
if (current) {
segments.push(current);
current = null;
}
continue;
}
if (current && current.node === m.node && m.offset === current.endOffset) {
current.endOffset = m.offset + 1;
} else {
if (current) segments.push(current);
current = { node: m.node, startOffset: m.offset, endOffset: m.offset + 1 };
}
}
if (current) segments.push(current);
// Wrap segments HIGHEST-offset-first. A quote spanning a collapsed
// whitespace run (e.g. a double space) maps to two non-contiguous
// segments on the SAME text node; wrapping the earlier one first calls
// surroundContents, which splits that node and shortens it, so the
// later segment's offsets become out of bounds -> IndexSizeError.
// Going back-to-front keeps every not-yet-wrapped segment's offsets
// valid. The whole range op is guarded so one bad segment (e.g. an
// overlap with a prior mark) is skipped, not fatal to the other marks.
for (const seg of segments.slice().reverse()) {
const mark = document.createElement('mark');
mark.className = 'ldr-research-annotation';
mark.dataset.noteId = noteId;
try {
const range = document.createRange();
range.setStart(seg.node, seg.startOffset);
range.setEnd(seg.node, seg.endOffset);
range.surroundContents(mark);
} catch (e) {
SafeLogger.error('Annotation wrap failed:', e);
}
}
}
/** Apply one annotation's highlight; returns whether it anchored. */
function applyAnnotation(container, annotation) {
const quote = normalizeWhitespace(annotation.quote);
if (!quote) return false;
// Rebuilt per annotation: wrapping mutates/splits text nodes, so
// earlier maps go stale. Targets are a few hundred KB at most and
// annotations number in the dozens — fine.
const { text, map } = buildNormalizedText(container);
const idx = findQuoteIndex(
text,
quote,
normalizeWhitespace(annotation.prefix),
normalizeWhitespace(annotation.suffix)
);
if (idx === -1) return false;
wrapNormalizedRange(map, idx, idx + quote.length, annotation.note_id);
return true;
}
// ------------------------------------------------------------------
// Surface factory
// ------------------------------------------------------------------
// Component-local wrappers over the shared trio (window.NotesShared) —
// local names kept for shadowing-safety; the bodies live in one place.
const csrfToken = () => window.NotesShared.csrfToken();
const toast = (message, type) => window.NotesShared.toast(message, type);
/**
* Wire an annotation surface over a container.
*
* @param {Object} config
* @param {string} config.containerId Element holding the immutable
* rendered text.
* @param {Object} config.endpoints { list, create, deleteFor(noteId) }
* — list GETs {annotations}, create POSTs {quote, prefix, suffix,
* comment}, deleteFor(noteId) returns the DELETE url. All
* same-origin relative paths.
* @param {Array} [config.extraActions] Additional selection-toolbar
* actions: {icon, label, onActivate(selectionHit)} where
* selectionHit = {text, range}.
* @param {Function} [config.onChanged] Called after a comment is
* created or deleted (hosts refresh their notes panels).
* @returns {{reload: Function}}
*/
function init(config) {
const containerId = config.containerId;
const endpoints = config.endpoints;
const onChanged = config.onChanged || (() => {});
let toolbar = null;
let popover = null;
let clickBound = false;
let annotationsByNoteId = {};
// Re-apply-across-render machinery (see applyWhenReady).
let readyObserver = null;
let applyingHighlights = false;
// Monotonic token so an out-of-order reload() response can't
// overwrite a newer annotation list (see reload).
let reloadToken = 0;
const container = () => document.getElementById(containerId);
const postJson = (url, body) => window.NotesShared.postJson(url, body);
// ---- selection toolbar ----
function makeToolbarButton(iconClass, label, onActivate) {
const btn = document.createElement('button');
btn.type = 'button';
btn.className = 'btn btn-primary btn-sm';
const icon = document.createElement('i');
icon.className = iconClass;
icon.setAttribute('aria-hidden', 'true');
btn.append(icon, document.createTextNode(` ${label}`));
// mousedown, not click: a click first collapses the selection
// (mousedown clears it), hiding the toolbar before its click
// handler ever ran.
btn.addEventListener('mousedown', (e) => {
e.preventDefault();
onActivate(selectionWithinContainer());
});
return btn;
}
function setupToolbar() {
toolbar = document.createElement('div');
toolbar.className = 'ldr-selection-toolbar';
toolbar.style.display = 'none';
toolbar.appendChild(
makeToolbarButton('fas fa-comment', 'Comment', openCommentPopover)
);
for (const action of config.extraActions || []) {
toolbar.appendChild(
makeToolbarButton(action.icon, action.label, (hit) => {
hideToolbar();
action.onActivate(hit);
})
);
}
document.body.appendChild(toolbar);
document.addEventListener('mouseup', () => {
// Defer: the selection object updates after mouseup.
setTimeout(maybeShowToolbar, 0);
});
document.addEventListener('scroll', hideToolbar, { passive: true });
}
function selectionWithinContainer() {
const root = container();
const sel = window.getSelection();
if (!root || !sel || sel.isCollapsed || sel.rangeCount === 0) return null;
const range = sel.getRangeAt(0);
if (!root.contains(range.commonAncestorContainer)) return null;
const text = sel.toString().trim();
return text.length >= 10 ? { text, range } : null;
}
function maybeShowToolbar() {
const hit = selectionWithinContainer();
if (!hit) {
hideToolbar();
return;
}
const rect = hit.range.getBoundingClientRect();
toolbar.style.position = 'fixed';
toolbar.style.top = `${Math.max(8, rect.top - 36)}px`;
toolbar.style.left = `${Math.min(window.innerWidth - 220, Math.max(8, rect.left + rect.width / 2 - 80))}px`;
toolbar.style.zIndex = '10001';
toolbar.style.display = 'inline-flex';
}
function hideToolbar() {
if (toolbar) toolbar.style.display = 'none';
}
// ---- popovers ----
// The current popover's outside-click listener, so EVERY close path
// (Cancel, save, delete, Escape, opening the next popover) can remove
// it. Previously it was only removed from inside its own handler on a
// genuine outside click, so closing any other way orphaned the
// document-level 'mousedown' listener permanently — unbounded
// accumulation over a session of opening/closing comments.
let popoverOutsideClick = null;
function closePopover() {
if (popoverOutsideClick) {
document.removeEventListener('mousedown', popoverOutsideClick);
popoverOutsideClick = null;
}
if (popover) {
popover.remove();
popover = null;
}
}
function positionPopover(pop, anchorRect) {
pop.style.position = 'fixed';
pop.style.top = `${Math.min(window.innerHeight - 60, anchorRect.bottom + 6)}px`;
pop.style.left = `${Math.min(window.innerWidth - 340, Math.max(8, anchorRect.left))}px`;
pop.style.zIndex = '10002';
}
function basePopover() {
closePopover();
const pop = document.createElement('div');
pop.className = 'ldr-annotation-popover';
popover = pop;
document.body.appendChild(pop);
setTimeout(() => {
if (popover !== pop) return; // already closed before we armed
popoverOutsideClick = (e) => {
if (popover === pop && !pop.contains(e.target)) {
closePopover();
}
};
document.addEventListener('mousedown', popoverOutsideClick);
}, 0);
pop.addEventListener('keydown', (e) => {
if (e.key === 'Escape') closePopover();
});
return pop;
}
/**
* Capture short normalized prefix/suffix context around the
* selection to disambiguate repeated phrases. Range.comparePoint
* against the normalized index map finds the exact occurrence the
* user selected rather than guessing among duplicates.
*/
function captureContext(range, quote) {
const root = container();
const empty = { prefix: '', suffix: '' };
if (!root) return empty;
try {
const { text, map } = buildNormalizedText(root);
let start = -1;
for (let i = 0; i < map.length; i++) {
if (!map[i]) continue; // virtual boundary space
if (range.comparePoint(map[i].node, map[i].offset) >= 0) {
start = i;
break;
}
}
if (start === -1) return empty;
const end = Math.min(start + quote.length, text.length);
return {
prefix: text.slice(Math.max(0, start - 30), start),
suffix: text.slice(end, end + 30)
};
} catch (e) {
SafeLogger.error('Annotation context capture failed:', e);
return empty;
}
}
/** Selection → comment entry popover. */
function openCommentPopover(hit) {
hideToolbar();
if (!hit) return;
let quote = normalizeWhitespace(hit.text);
if (quote.length > 1000) quote = quote.slice(0, 1000);
const context = captureContext(hit.range, quote);
const rect = hit.range.getBoundingClientRect();
const pop = basePopover();
const label = document.createElement('div');
label.className = 'ldr-annotation-popover-quote';
label.textContent = quote.length > 120 ? `${quote.slice(0, 120)}…` : quote;
const textarea = document.createElement('textarea');
textarea.className = 'ldr-annotation-popover-input';
textarea.rows = 3;
textarea.placeholder = 'Your comment… (saved as a note linked to this page)';
const actions = document.createElement('div');
actions.className = 'ldr-annotation-popover-actions';
const save = document.createElement('button');
save.type = 'button';
save.className = 'btn btn-primary btn-sm';
save.textContent = 'Comment';
const cancel = document.createElement('button');
cancel.type = 'button';
cancel.className = 'btn ldr-btn-outline btn-sm';
cancel.textContent = 'Cancel';
actions.append(save, cancel);
pop.append(label, textarea, actions);
positionPopover(pop, rect);
textarea.focus();
cancel.addEventListener('click', closePopover);
save.addEventListener('click', async () => {
const comment = textarea.value.trim();
if (!comment) {
textarea.focus();
return;
}
save.disabled = true;
try {
await postJson(endpoints.create, {
quote,
prefix: context.prefix,
suffix: context.suffix,
comment
});
closePopover();
toast('Comment saved as a note', 'success');
onChanged();
reload();
} catch (error) {
SafeLogger.error('Error saving annotation:', error);
toast(error.message || 'Failed to save comment', 'error');
save.disabled = false;
}
});
}
/** Existing-highlight popover: comment preview + open/delete. */
function showAnnotationPopover(mark, annotation) {
const pop = basePopover();
const body = document.createElement('div');
body.className = 'ldr-annotation-popover-comment';
// Note content is comment-first, then the quoted passage as a
// "> " blockquote; the reader is already looking at the
// passage, so show only the comment part.
const preview = annotation.comment_preview || annotation.note_title || '';
body.textContent = preview.split(/\n\s*>/)[0].trim();
const actions = document.createElement('div');
actions.className = 'ldr-annotation-popover-actions';
const open = document.createElement('a');
open.className = 'btn btn-primary btn-sm';
open.href = `/notes/${encodeURIComponent(annotation.note_id)}`;
open.textContent = 'Open note';
const del = document.createElement('button');
del.type = 'button';
del.className = 'btn ldr-btn-outline btn-sm';
del.textContent = 'Delete note';
actions.append(open, del);
pop.append(body, actions);
positionPopover(pop, mark.getBoundingClientRect());
del.addEventListener('click', async () => {
// The comment IS a note that the user may have opened and
// expanded with unrelated content — deleting the annotation
// deletes that whole note. Confirm so it's never silent.
if (!window.confirm(
'Delete this comment? The linked note (and anything you '
+ 'added to it) will be permanently removed.'
)) {
return;
}
del.disabled = true;
try {
const response = await safeFetchWithAuth(endpoints.deleteFor(annotation.note_id), {
method: 'DELETE',
headers: { 'X-CSRFToken': csrfToken() },
credentials: 'same-origin'
});
const data = await response.json().catch(() => ({}));
if (!response.ok || !data.success) {
throw new Error(
data.error || data.detail ||
`Server returned ${response.status}`
);
}
closePopover();
toast('Comment deleted', 'success');
onChanged();
// Unwrap ALL segments of this annotation, not just the
// clicked one: a quote spanning a <br>/whitespace run
// renders as several <mark data-note-id=X> siblings (see
// wrapNormalizedRange / anchoredCount), so unwrapping only
// the clicked mark leaves the others as clickable ghosts
// bound to a now-deleted note. Also drop the map entry
// synchronously so a ghost click before the fire-and-forget
// reload() completes (or if reload() fails) can't reopen a
// popover for the deleted note. reload() re-applies the rest.
const root = container();
if (root) {
root.querySelectorAll('mark.ldr-research-annotation').forEach((m) => {
if (m.dataset.noteId === String(annotation.note_id)) {
// audited 2026-07-22: replaceWith() spreads the mark's own child Nodes (never a string) — no HTML parsing
// bearer:disable javascript_lang_dangerous_insert_html
m.replaceWith(...m.childNodes);
}
});
} else {
// audited 2026-07-22: same Node-spread unwrap as above — no HTML parsing
// bearer:disable javascript_lang_dangerous_insert_html
mark.replaceWith(...mark.childNodes);
}
delete annotationsByNoteId[annotation.note_id];
reload();
} catch (error) {
SafeLogger.error('Error deleting annotation:', error);
toast(error.message || 'Failed to delete comment', 'error');
del.disabled = false;
}
});
}
// ---- highlight application ----
function applyAllAnnotations(annotations) {
const root = container();
if (!root) return;
for (const mark of [...root.querySelectorAll('mark.ldr-research-annotation')]) {
// audited 2026-07-22: unwrap pass spreads each mark's existing child Nodes (never a string) — no HTML parsing
// bearer:disable javascript_lang_dangerous_insert_html
mark.replaceWith(...mark.childNodes);
}
root.normalize();
let missed = 0;
for (const a of annotations) {
if (!applyAnnotation(root, a)) missed++;
}
if (missed) {
SafeLogger.error(`${missed} annotation(s) could not be anchored to the rendered text`);
}
annotationsByNoteId = {};
for (const a of annotations) annotationsByNoteId[a.note_id] = a;
if (!clickBound) {
clickBound = true;
root.addEventListener('click', (e) => {
const mark = e.target.closest('mark.ldr-research-annotation');
if (!mark) return;
const annotation = annotationsByNoteId[mark.dataset.noteId];
if (annotation) showAnnotationPopover(mark, annotation);
});
}
}
// A loading placeholder is present. Must be robust to more than the
// original page markup: the results page (results.js) first replaces
// results.html's `.ldr-loading-spinner` with its OWN placeholder
// (`<i class="fas fa-spinner fa-pulse"> Loading research results…`)
// and only THEN, after the report fetch, swaps in the real content —
// so a heuristic that only knew `.ldr-loading-spinner` would treat
// the placeholder as ready, anchor nothing, and never re-run.
function looksLikeLoading(root) {
if (root.querySelector('.ldr-loading-spinner, .ldr-spinner, .fa-spinner, .fa-pulse, .spinner-border')) {
return true;
}
const text = root.textContent.trim();
if (!text) return true;
// Only a SHORT body that opens with a loading word is a
// placeholder ("Loading research results…"). A real report that
// merely begins with the word "Loading"/"Searching" is long, and
// treating it as a placeholder would suppress every highlight on
// that page permanently.
return text.length < 120 && /^(?:loading|searching)\b/i.test(text);
}
/**
* The host's text often renders asynchronously (the research report
* is fetched + rendered by results.js, possibly through more than
* one placeholder). Apply once real content is present, and RE-APPLY
* whenever the container's content is replaced — results.js swaps the
* whole report in via innerHTML, which would blow away marks applied
* to an earlier placeholder. Stop once every annotation has anchored
* (or after a timeout / on the surface being reloaded).
*/
function applyWhenReady(annotations) {
const root = container();
if (!root) return;
if (readyObserver) {
readyObserver.disconnect();
readyObserver = null;
}
const total = annotations.length;
// Count DISTINCT anchored annotations, not <mark> elements: a
// multi-segment quote yields several marks for ONE annotation,
// so an element count would over-report and stop the observer
// while other annotations are still unanchored.
const anchoredCount = () => {
const ids = new Set();
root.querySelectorAll('mark.ldr-research-annotation').forEach((m) => {
if (m.dataset.noteId) ids.add(m.dataset.noteId);
});
return ids.size;
};
const tryApply = () => {
if (looksLikeLoading(root)) return false;
// applyAllAnnotations mutates the DOM (wraps marks). Those
// mutations fire the observer on a LATER microtask — after a
// synchronous `applyingHighlights=false` reset would already
// have cleared — so a partially-anchored set would re-trigger
// this callback forever (a browser-hanging microtask loop).
// Disconnect around the mutation and discard our own records
// before reconnecting, so only genuine host changes re-run us.
applyingHighlights = true;
if (readyObserver) readyObserver.disconnect();
try {
applyAllAnnotations(annotations);
} finally {
if (readyObserver) {
readyObserver.takeRecords();
readyObserver.observe(root, { childList: true, subtree: true });
}
applyingHighlights = false;
}
return anchoredCount() >= total;
};
if (tryApply()) return;
const thisObserver = new MutationObserver(() => {
if (applyingHighlights) return;
if (tryApply() && readyObserver === thisObserver) {
readyObserver.disconnect();
readyObserver = null;
}
});
readyObserver = thisObserver;
readyObserver.observe(root, { childList: true, subtree: true });
// Content that never fully anchors (a quote genuinely not present
// in the final render) must not observe forever. Guard on identity:
// a newer applyWhenReady() may have replaced readyObserver with its
// own observer (and its own fresh 60s window); this stale timeout
// must only tear down ITS OWN observer, never the newer one.
setTimeout(() => {
if (readyObserver === thisObserver) {
readyObserver.disconnect();
readyObserver = null;
}
}, 60000);
}
async function reload() {
// Sequence concurrent reloads: create-comment and delete both
// fire their own reload(), so responses can arrive out of order.
// Only the newest reload is allowed to apply — otherwise a stale
// earlier list can overwrite a newer one (a just-added highlight
// vanishing, or a just-deleted mark reappearing).
const myToken = ++reloadToken;
try {
const response = await safeFetchWithAuth(endpoints.list, {
credentials: 'same-origin'
});
const data = await response.json();
if (!data.success) throw new Error(data.error || 'load failed');
if (myToken !== reloadToken) return; // superseded
const annotations = data.annotations || [];
if (!annotations.length && !Object.keys(annotationsByNoteId).length) return;
applyWhenReady(annotations);
} catch (error) {
SafeLogger.error('Error loading annotations:', error);
}
}
setupToolbar();
reload();
return { reload };
}
window.LDRAnnotationSurface = { init };
// Test hook (production-inert): the pure anchor engine.
if (window.__VITEST_TEST__) {
window.__annotationSurfaceTest = {
buildNormalizedText,
normalizeWhitespace,
findQuoteIndex,
applyAnnotation
};
}
})();