@plannotator/ui 0.51.0 → 0.52.0

package/components/Viewer.tsx

@@ -6,7 +6,7 @@ import { AnnotationType, type Block, type Annotation, type EditorMode, type Inpu
 import { applyHighlight, codeBlockClassName, onCodeHighlightSwap } from '../utils/codeHighlight';
 import { paintCodeBlockMark } from '../utils/codeBlockMark';
 import { useFenceTheme } from '../hooks/useFenceTheme';
-import { computeListIndices, groupBlocks, type Frontmatter, type FrontmatterValue } from '../utils/parser';
+import { computeListIndices, groupBlocks, selectionSourceLines, type Frontmatter, type FrontmatterValue } from '../utils/parser';
 import { buildHeadingSlugMap } from '../utils/slugify';
 import { copyTextToClipboard } from '../utils/clipboard';
 import { BlockRenderer } from './BlockRenderer';
@@ -218,6 +218,21 @@ export interface ViewerProps {
    *  decision"), given the indexed question and its saved answer. Rendered in
    *  read-only cards too; return null for none. */
   renderQuestionFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
+  /** Whether answering a `Decision: when answered` question records a
+   *  decision, per question: return false to draw its "Records a decision"
+   *  tag dimmed with a dotted outline and hide the "Answering this records a
+   *  decision" row; true or undefined keeps today's card. Not consulted for a
+   *  question whose decision is already recorded. */
+  questionDecisionRecording?: (question: IndexedQuestion) => boolean | undefined;
+  /** Makes a `Decision: when answered` question's "Records a decision" tag a
+   *  toggle button (`aria-pressed`); a click calls this with the question's
+   *  key and the next state, which the host stores and returns from
+   *  `questionDecisionRecording`. Ignored when `readOnly`. */
+  onToggleQuestionDecisionRecording?: (key: string, next: boolean) => void;
+  /** `'none'` hides each question card's own status tag (Open / Answered /
+   *  Settled / Skipped) so the host can draw its own; the decision tags stay.
+   *  Default `'card'`. */
+  questionStatusTag?: 'card' | 'none';
   onAskAI?: CommentAskAIHandler;
   /** Whether comment popovers offer image attachments. Hosts without an
    *  uploadTransport pass false so the attach affordance never dead-ends.
@@ -590,6 +605,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   onSaveQuestionAnswer,
   saveQuestionAnswerLabel,
   renderQuestionFooter,
+  questionDecisionRecording,
+  onToggleQuestionDecisionRecording,
+  questionStatusTag,
   onAskAI,
   allowImages = true,
   readOnly = false,
@@ -1551,6 +1569,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                   onSaveQuestionAnswer={readOnly ? undefined : onSaveQuestionAnswer}
                   saveQuestionAnswerLabel={saveQuestionAnswerLabel}
                   renderQuestionFooter={renderQuestionFooter}
+                  questionDecisionRecording={question ? questionDecisionRecording?.(question) : undefined}
+                  onToggleQuestionDecisionRecording={readOnly ? undefined : onToggleQuestionDecisionRecording}
+                  questionStatusTag={questionStatusTag}
                 />
               );
             })()
@@ -1715,6 +1736,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 label: 'Selected text',
                 text: hookCommentPopover.selectedText ?? hookCommentPopover.contextText,
                 sourcePath: linkedDocInfo?.filepath ?? sourceInfo,
+                ...selectionSourceLines(blocks, hookCommentPopover.blockIds ?? []),
               }}
             />
           )}
@@ -1740,6 +1762,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               label: viewerCommentPopover.isGlobal ? 'Document' : 'Code block',
               text: viewerCommentPopover.selectedText,
               sourcePath: linkedDocInfo?.filepath ?? sourceInfo,
+              ...(!viewerCommentPopover.isGlobal && viewerCommentPopover.codeBlock
+                ? selectionSourceLines(blocks, [viewerCommentPopover.codeBlock.block.id])
+                : null),
             }}
           />
         )}

package/components/blocks/QuestionBlock.tsx

@@ -36,7 +36,10 @@ import { QuestionContext } from './QuestionContext';
  *
  * A host can add its own actions at the right of the footer
  * (`renderFooter`), and a question carrying `Decision: when answered` or a
- * `Decision: [statement](url)` link shows that beside the prompt.
+ * `Decision: [statement](url)` link shows that beside the prompt. A host can
+ * also let the reviewer switch a `Decision: when answered` question's
+ * recording off and on (`decisionRecording` + `onToggleDecisionRecording`),
+ * and hide the card's own status tag to draw its own (`statusTag: 'none'`).
  */
 
 /** Pointer travel (px) above which a press on a choice row is a drag. */
@@ -50,7 +53,7 @@ const now = (): number => (typeof performance !== 'undefined' ? performance.now(
 
 const cx = (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' ');
 
-const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.ReactNode; className?: string }> = ({ tone, children, className }) => (
+const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.ReactNode; className?: string; style?: React.CSSProperties }> = ({ tone, children, className, style }) => (
   <span
     className={cx(
       'annotation-exclude select-none inline-flex items-center gap-1 whitespace-nowrap rounded px-1.5 py-px align-[1px] text-[10.5px] font-semibold tracking-[0.03em]',
@@ -60,6 +63,7 @@ const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.Reac
       tone === 'open' && 'border border-dashed border-border text-muted-foreground',
       className,
     )}
+    style={style}
     data-pinpoint-ignore=""
   >
     {children}
@@ -78,6 +82,19 @@ const DiamondGlyph = () => (
   </svg>
 );
 
+/** Draws a decision tag in its "off" state: the same words, dimmed, with a
+ *  dotted outline instead of the tinted fill. Dimmed means the theme's
+ *  muted-foreground, not opacity: 60% opacity on primary text dropped the
+ *  default light theme under 3:1, while muted-foreground is the token every
+ *  theme already tunes for secondary text. Inline so it adds no utility
+ *  classes to the shared stylesheet and wins over the tag's `text-primary`. */
+const DECISION_OFF_STYLE: React.CSSProperties = {
+  background: 'transparent',
+  color: 'var(--muted-foreground)',
+  outline: '1px dotted currentColor',
+  outlineOffset: '-1px',
+};
+
 /** Two answers say the same thing (identity and line ignored). */
 const sameAnswer = (a: QuestionAnswer | null | undefined, b: QuestionAnswer | null | undefined): boolean => {
   const norm = (x: QuestionAnswer | null | undefined) =>
@@ -110,6 +127,21 @@ export interface QuestionBlockProps {
    *  saved answer (never the unsaved draft). Rendered in read-only cards too;
    *  return null for nothing. */
   renderFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
+  /** Whether answering a `Decision: when answered` question records a
+   *  decision (default true). False draws the "Records a decision" tag dimmed
+   *  with a dotted outline and hides the "Answering this records a decision"
+   *  row. Has no effect on a question whose decision is already recorded
+   *  (`Decision: [statement](url)`) or that carries no decision line. */
+  decisionRecording?: boolean;
+  /** Makes the "Records a decision" tag a toggle button (`aria-pressed`):
+   *  a click calls this with the question's key and the next state. The host
+   *  stores it and passes it back as `decisionRecording`. Not offered in a
+   *  read-only card (no answer handler), which draws the tag as it stands. */
+  onToggleDecisionRecording?: (key: string, next: boolean) => void;
+  /** `'none'` hides the card's own status tag (Open / Answered / Settled /
+   *  Skipped) so the host can draw its own; the decision tags stay. Default
+   *  `'card'`. */
+  statusTag?: 'card' | 'none';
   onOpenLinkedDoc?: (path: string) => void;
   onOpenCodeFile?: (path: string) => void;
   imageBaseDir?: string;
@@ -128,6 +160,9 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   onSaveAnswer,
   saveLabel,
   renderFooter,
+  decisionRecording,
+  onToggleDecisionRecording,
+  statusTag = 'card',
   onOpenLinkedDoc,
   onOpenCodeFile,
   imageBaseDir,
@@ -320,6 +355,17 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const other = answer?.other ?? '';
   const otherOn = other.trim() !== '';
 
+  // A `Decision: when answered` question the host may switch off. A recorded
+  // decision (`question.decision`) is never affected.
+  const decisionCapable = !question.decision && !!question.decisionOnAnswer;
+  const recordingOn = decisionRecording ?? true;
+  const decisionToggleable = decisionCapable && !readOnly && !!onToggleDecisionRecording;
+  // Present only when the host speaks to recording, so a card without these
+  // props carries exactly the attributes it always did.
+  const recordingAttr = decisionCapable && (decisionRecording !== undefined || !!onToggleDecisionRecording)
+    ? (recordingOn ? 'on' : 'off')
+    : undefined;
+
   const describedBy = [question.context ? contextId : null, question.kind === 'text' && question.suggestedText && !answered ? suggestId : null]
     .filter(Boolean)
     .join(' ') || undefined;
@@ -344,23 +390,44 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
       aria-describedby={describedBy}
       aria-disabled={readOnly || undefined}
       data-question-decision={question.decision ? 'recorded' : question.decisionOnAnswer ? 'on-answer' : undefined}
+      data-question-decision-recording={recordingAttr}
     >
       <div className="annotation-exclude select-none mb-1.5 flex items-center gap-2" data-pinpoint-ignore="">
         <span className="text-[10.5px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{eyebrow}</span>
         <span className="ml-auto">
           {question.decision && <><Tag tone="rec"><DiamondGlyph />Decision</Tag>{' '}</>}
-          {!question.decision && question.decisionOnAnswer && <><Tag tone="rec"><DiamondGlyph />Records a decision</Tag>{' '}</>}
-          {status === 'answered' && <Tag tone="ok"><CheckGlyph />Answered</Tag>}
-          {status === 'settled' && <Tag tone="ok"><CheckGlyph />Settled</Tag>}
-          {status === 'skipped' && <Tag tone="skip">Skipped</Tag>}
-          {status === 'open' && <Tag tone="open">Open</Tag>}
+          {decisionCapable && (decisionToggleable ? (
+            // Focus shows as a ring, not an outline: the dotted outline is
+            // what draws the off state.
+            <><button
+              type="button"
+              aria-pressed={recordingOn}
+              onClick={() => onToggleDecisionRecording!(question.key, !recordingOn)}
+              className="annotation-exclude select-none inline-flex cursor-pointer items-center gap-1 whitespace-nowrap rounded px-1.5 py-px align-[1px] text-[10.5px] font-semibold tracking-[0.03em] bg-primary/15 text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+              style={recordingOn ? undefined : DECISION_OFF_STYLE}
+              data-pinpoint-ignore=""
+              data-question-decision-toggle=""
+            ><DiamondGlyph />Records a decision</button>{' '}</>
+          ) : recordingOn ? (
+            <><Tag tone="rec"><DiamondGlyph />Records a decision</Tag>{' '}</>
+          ) : (
+            <><Tag tone="rec" style={DECISION_OFF_STYLE}><DiamondGlyph />Records a decision</Tag>{' '}</>
+          ))}
+          {statusTag !== 'none' && (
+            <>
+              {status === 'answered' && <Tag tone="ok"><CheckGlyph />Answered</Tag>}
+              {status === 'settled' && <Tag tone="ok"><CheckGlyph />Settled</Tag>}
+              {status === 'skipped' && <Tag tone="skip">Skipped</Tag>}
+              {status === 'open' && <Tag tone="open">Open</Tag>}
+            </>
+          )}
         </span>
       </div>
 
       <p id={promptId} className="m-0 text-[15px] font-semibold leading-[1.45] text-foreground" data-question-part="prompt">
         {inline(question.prompt)}
       </p>
-      {(question.decision || question.decisionOnAnswer) && (
+      {(question.decision || (question.decisionOnAnswer && recordingOn)) && (
         <div
           className="annotation-exclude mt-2 mb-0.5 flex items-center gap-2 rounded-lg bg-primary/8 px-[9px] py-1.5 text-[12.5px] leading-[18px] text-foreground [&>svg]:text-primary"
           data-pinpoint-ignore=""

package/components/html-viewer/bridge-script.asset.js

@@ -2457,9 +2457,88 @@
 
   function anchorTextSnapshot(el) {
     var text = (el.textContent || '').replace(/\s+/g, ' ').trim();
+    if (!text) return anchorSourceSnapshot(el);
     return text.length > 180 ? text.slice(0, 180) : text;
   }
 
+  // Media snapshots. An image, video or frame has no text to verify a weak
+  // selector against, but its source says what it shows the way text says
+  // what a paragraph says, and unlike the structure-derived signatures D1
+  // ruled out, two siblings showing different files never share it. The key
+  // is the author's reference to the resource: relative to the document's
+  // base when it lies under it (a host may re-root assets per session, through
+  // a <base> on its own asset route or by rewriting attributes to a session
+  // host), else its root-relative path on the document's own origin (a live
+  // app's proxy port changes per session), else origin and path. The query
+  // and the fragment are part of what a source shows (/_next/image?url=a.jpg,
+  // proto.html?step=2, icons.svg#close), so they count, but only as a digest:
+  // they can carry per-visit state (signed URLs, tokens) that must never be
+  // stored in plain text in an annotation. A source whose query changes per
+  // load therefore does not restore, which fails closed. Inline sources
+  // (data:, blob:) name no resource and get no key.
+  var ANCHOR_SOURCE_PREFIX = 'src:';
+  var ANCHOR_SOURCE_MAX = 176;
+
+  // FNV-1a, 32 bits, as 8 hex digits: an identity check, not a secret.
+  function anchorDigest(value) {
+    var hash = 0x811c9dc5;
+    for (var i = 0; i < value.length; i++) {
+      hash ^= value.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return ('0000000' + hash.toString(16)).slice(-8);
+  }
+
+  function anchorSourceKey(el) {
+    var raw = descRawSource(el);
+    if (!raw || /^(data|blob):/i.test(raw)) return '';
+    var path = raw;
+    var variant = '';
+    var url = null;
+    try { url = new URL(raw, document.baseURI); } catch (ex) {}
+    if (!url || !/^https?:$/i.test(url.protocol)) {
+      var mark = raw.search(/[?#]/);
+      if (mark >= 0) {
+        path = raw.slice(0, mark);
+        variant = raw.slice(mark);
+      }
+    } else {
+      variant = url.search + url.hash;
+      var base = null;
+      try { base = new URL('.', document.baseURI); } catch (ex2) {}
+      if (base && url.origin === base.origin && url.pathname.indexOf(base.pathname) === 0) {
+        path = url.pathname.slice(base.pathname.length);
+      } else if (base && url.origin === base.origin) {
+        path = url.pathname;
+      } else {
+        path = url.origin + url.pathname;
+      }
+    }
+    if (!path) return '';
+    return variant ? path + '?' + anchorDigest(variant) : path;
+  }
+
+  function sourceSnapshotOf(el) {
+    var key = anchorSourceKey(el);
+    if (!key) return '';
+    // A long key keeps its head for readability and a digest of the whole,
+    // so two sources that differ only past the cut never compare equal.
+    if (key.length > ANCHOR_SOURCE_MAX) key = key.slice(0, ANCHOR_SOURCE_MAX - 9) + '~' + anchorDigest(key);
+    return ANCHOR_SOURCE_PREFIX + key;
+  }
+
+  // A source that another element of the same kind shares cannot tell the two
+  // apart, which is the D1 failure again: no snapshot, so no anchor.
+  function anchorSourceSnapshot(el) {
+    var snapshot = sourceSnapshotOf(el);
+    if (!snapshot) return '';
+    var sameKind = document.getElementsByTagName(el.tagName);
+    for (var i = 0; i < sameKind.length; i++) {
+      if (sameKind[i] !== el && sourceSnapshotOf(sameKind[i]) === snapshot) return '';
+    }
+    return snapshot;
+  }
+
   function uniquelySelects(selector, el) {
     try {
       var matches = document.querySelectorAll(selector);
@@ -2558,12 +2637,13 @@
     if (!selector) return null;
     var snapshot = anchorTextSnapshot(el);
     // Text-less elements anchor ONLY through a stable-identity rung (#id or
-    // an author-controlled data-* identity attribute). A weak (positional /
-    // class) selector has nothing to verify against — identical siblings
-    // share every structural trait, so any derived signature would validate
-    // the WRONG element after a sibling is inserted or removed. A
-    // wrong-binding anchor is worse than no anchor: ship none and fail
-    // closed (the pin simply doesn't restore).
+    // an author-controlled data-* identity attribute), or, for media, through
+    // a source no other element of its kind shows (anchorSourceSnapshot).
+    // Otherwise a weak (positional / class) selector has nothing to verify
+    // against — identical siblings share every structural trait, so any
+    // derived signature would validate the WRONG element after a sibling is
+    // inserted or removed. A wrong-binding anchor is worse than no anchor:
+    // ship none and fail closed (the pin simply doesn't restore).
     if (!snapshot && !anchorHasStableIdentity(selector, el)) return null;
     return {
       selector: selector,
@@ -2596,6 +2676,26 @@
 
   function resolveAnchorElement(anchor) {
     if (!anchor || typeof anchor.selector !== 'string' || !anchor.selector || typeof anchor.tagName !== 'string') return null;
+    return resolveAnchorSelector(anchor) || relocateBySource(anchor);
+  }
+
+  // A media anchor whose selector no longer lands on its element (a sibling
+  // was inserted or removed, a refresh reordered the page) finds it again by
+  // its source, the way a text annotation falls back to searching for its
+  // text. Exactly one element may match: two resolve nothing.
+  function relocateBySource(anchor) {
+    if (typeof anchor.text !== 'string' || anchor.text.indexOf(ANCHOR_SOURCE_PREFIX) !== 0) return null;
+    var found = null;
+    var candidates = document.getElementsByTagName(anchor.tagName);
+    for (var i = 0; i < candidates.length; i++) {
+      if (sourceSnapshotOf(candidates[i]) !== anchor.text) continue;
+      if (found) return null;
+      found = candidates[i];
+    }
+    return found;
+  }
+
+  function resolveAnchorSelector(anchor) {
     var matches;
     try {
       matches = document.querySelectorAll(anchor.selector);

package/components/html-viewer/bridge-script.ts

@@ -2693,9 +2693,88 @@ export const BRIDGE_SCRIPT = `(function() {
 
   function anchorTextSnapshot(el) {
     var text = (el.textContent || '').replace(/\\s+/g, ' ').trim();
+    if (!text) return anchorSourceSnapshot(el);
     return text.length > 180 ? text.slice(0, 180) : text;
   }
 
+  // Media snapshots. An image, video or frame has no text to verify a weak
+  // selector against, but its source says what it shows the way text says
+  // what a paragraph says, and unlike the structure-derived signatures D1
+  // ruled out, two siblings showing different files never share it. The key
+  // is the author's reference to the resource: relative to the document's
+  // base when it lies under it (a host may re-root assets per session, through
+  // a <base> on its own asset route or by rewriting attributes to a session
+  // host), else its root-relative path on the document's own origin (a live
+  // app's proxy port changes per session), else origin and path. The query
+  // and the fragment are part of what a source shows (/_next/image?url=a.jpg,
+  // proto.html?step=2, icons.svg#close), so they count, but only as a digest:
+  // they can carry per-visit state (signed URLs, tokens) that must never be
+  // stored in plain text in an annotation. A source whose query changes per
+  // load therefore does not restore, which fails closed. Inline sources
+  // (data:, blob:) name no resource and get no key.
+  var ANCHOR_SOURCE_PREFIX = 'src:';
+  var ANCHOR_SOURCE_MAX = 176;
+
+  // FNV-1a, 32 bits, as 8 hex digits: an identity check, not a secret.
+  function anchorDigest(value) {
+    var hash = 0x811c9dc5;
+    for (var i = 0; i < value.length; i++) {
+      hash ^= value.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return ('0000000' + hash.toString(16)).slice(-8);
+  }
+
+  function anchorSourceKey(el) {
+    var raw = descRawSource(el);
+    if (!raw || /^(data|blob):/i.test(raw)) return '';
+    var path = raw;
+    var variant = '';
+    var url = null;
+    try { url = new URL(raw, document.baseURI); } catch (ex) {}
+    if (!url || !/^https?:$/i.test(url.protocol)) {
+      var mark = raw.search(/[?#]/);
+      if (mark >= 0) {
+        path = raw.slice(0, mark);
+        variant = raw.slice(mark);
+      }
+    } else {
+      variant = url.search + url.hash;
+      var base = null;
+      try { base = new URL('.', document.baseURI); } catch (ex2) {}
+      if (base && url.origin === base.origin && url.pathname.indexOf(base.pathname) === 0) {
+        path = url.pathname.slice(base.pathname.length);
+      } else if (base && url.origin === base.origin) {
+        path = url.pathname;
+      } else {
+        path = url.origin + url.pathname;
+      }
+    }
+    if (!path) return '';
+    return variant ? path + '?' + anchorDigest(variant) : path;
+  }
+
+  function sourceSnapshotOf(el) {
+    var key = anchorSourceKey(el);
+    if (!key) return '';
+    // A long key keeps its head for readability and a digest of the whole,
+    // so two sources that differ only past the cut never compare equal.
+    if (key.length > ANCHOR_SOURCE_MAX) key = key.slice(0, ANCHOR_SOURCE_MAX - 9) + '~' + anchorDigest(key);
+    return ANCHOR_SOURCE_PREFIX + key;
+  }
+
+  // A source that another element of the same kind shares cannot tell the two
+  // apart, which is the D1 failure again: no snapshot, so no anchor.
+  function anchorSourceSnapshot(el) {
+    var snapshot = sourceSnapshotOf(el);
+    if (!snapshot) return '';
+    var sameKind = document.getElementsByTagName(el.tagName);
+    for (var i = 0; i < sameKind.length; i++) {
+      if (sameKind[i] !== el && sourceSnapshotOf(sameKind[i]) === snapshot) return '';
+    }
+    return snapshot;
+  }
+
   function uniquelySelects(selector, el) {
     try {
       var matches = document.querySelectorAll(selector);
@@ -2794,12 +2873,13 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!selector) return null;
     var snapshot = anchorTextSnapshot(el);
     // Text-less elements anchor ONLY through a stable-identity rung (#id or
-    // an author-controlled data-* identity attribute). A weak (positional /
-    // class) selector has nothing to verify against — identical siblings
-    // share every structural trait, so any derived signature would validate
-    // the WRONG element after a sibling is inserted or removed. A
-    // wrong-binding anchor is worse than no anchor: ship none and fail
-    // closed (the pin simply doesn't restore).
+    // an author-controlled data-* identity attribute), or, for media, through
+    // a source no other element of its kind shows (anchorSourceSnapshot).
+    // Otherwise a weak (positional / class) selector has nothing to verify
+    // against — identical siblings share every structural trait, so any
+    // derived signature would validate the WRONG element after a sibling is
+    // inserted or removed. A wrong-binding anchor is worse than no anchor:
+    // ship none and fail closed (the pin simply doesn't restore).
     if (!snapshot && !anchorHasStableIdentity(selector, el)) return null;
     return {
       selector: selector,
@@ -2832,6 +2912,26 @@ export const BRIDGE_SCRIPT = `(function() {
 
   function resolveAnchorElement(anchor) {
     if (!anchor || typeof anchor.selector !== 'string' || !anchor.selector || typeof anchor.tagName !== 'string') return null;
+    return resolveAnchorSelector(anchor) || relocateBySource(anchor);
+  }
+
+  // A media anchor whose selector no longer lands on its element (a sibling
+  // was inserted or removed, a refresh reordered the page) finds it again by
+  // its source, the way a text annotation falls back to searching for its
+  // text. Exactly one element may match: two resolve nothing.
+  function relocateBySource(anchor) {
+    if (typeof anchor.text !== 'string' || anchor.text.indexOf(ANCHOR_SOURCE_PREFIX) !== 0) return null;
+    var found = null;
+    var candidates = document.getElementsByTagName(anchor.tagName);
+    for (var i = 0; i < candidates.length; i++) {
+      if (sourceSnapshotOf(candidates[i]) !== anchor.text) continue;
+      if (found) return null;
+      found = candidates[i];
+    }
+    return found;
+  }
+
+  function resolveAnchorSelector(anchor) {
     var matches;
     try {
       matches = document.querySelectorAll(anchor.selector);