@plannotator/ui 0.49.0 → 0.51.0

package/utils/blockTargeting.ts

@@ -17,6 +17,10 @@ const SKIP_SELECTORS = [
 ].join(',');
 
 const INLINE_TARGET_SELECTOR = 'strong,em,a,code:not(.pn-code)';
+/** A `:::question` card (`QuestionBlock`): one block whose text is in parts. */
+const QUESTION_CARD_SELECTOR = 'fieldset.question-block';
+/** The card's text parts: the prompt, the context, and each choice's text. */
+const QUESTION_PART_SELECTOR = '[data-question-part]';
 const TABLE_EDGE_ZONE = 22;
 
 /** The semantic kind of a document target. */
@@ -133,10 +137,22 @@ function groupLabel(group: HTMLElement): string {
 }
 
 function listContentElement(block: HTMLElement): HTMLElement | null {
+  // A question card also starts with a `select-none` child (its eyebrow), so
+  // without this its second child, the prompt, stood in for the whole card:
+  // every pinpoint hover or click inside it resolved to the prompt.
+  if (block.matches(QUESTION_CARD_SELECTOR)) return null;
   if (!block.querySelector('.select-none')) return null;
   return block.children[1] instanceof HTMLElement ? block.children[1] : null;
 }
 
+function questionPartLabel(part: HTMLElement): string {
+  const text = truncate(part.textContent?.trim() ?? '', 30);
+  const kind = part.dataset.questionPart;
+  if (kind === 'choice') return `choice: "${text}"`;
+  if (kind === 'context') return `context: "${text}"`;
+  return `question: "${text}"`;
+}
+
 function addInlineTargets(
   targets: SemanticTarget[],
   byElement: Map<HTMLElement, SemanticTarget>,
@@ -199,6 +215,38 @@ export function buildSemanticTargetGraph(container: HTMLElement): SemanticTarget
 
     const group = block.closest<HTMLElement>('[data-pinpoint-group]');
     const parentKey = group ? groupTargets.get(group)?.key ?? null : null;
+
+    // First: a card's context can hold a table, a code fence or a formula,
+    // and the card is still one question block made of its parts.
+    if (block.matches(QUESTION_CARD_SELECTOR)) {
+      const prompt = block.querySelector<HTMLElement>('[data-question-part="prompt"]');
+      const cardTarget: SemanticTarget = {
+        key: `${blockId}:block`,
+        blockId,
+        element: block,
+        label: prompt ? questionPartLabel(prompt) : 'question',
+        kind: 'block',
+        parentKey,
+      };
+      targets.push(cardTarget);
+      byElement.set(block, cardTarget);
+      blockKeys.push(cardTarget.key);
+      block.querySelectorAll<HTMLElement>(QUESTION_PART_SELECTOR).forEach((part, index) => {
+        const partTarget: SemanticTarget = {
+          key: `${blockId}:part:${index}`,
+          blockId,
+          element: part,
+          label: questionPartLabel(part),
+          kind: 'inline',
+          parentKey: cardTarget.key,
+        };
+        targets.push(partTarget);
+        byElement.set(part, partTarget);
+        addInlineTargets(targets, byElement, blockId, partTarget, part, partTarget.key);
+      });
+      continue;
+    }
+
     const codeElement = block.querySelector<HTMLElement>('pre > code.pn-code');
     const mathElement = block.matches('.math-annotatable,[data-math-tex]')
       ? block
@@ -455,8 +503,11 @@ export function resolveSemanticTargetAtPoint(
   if (!block || !graph.container.contains(block) || block.tagName === 'HR') return null;
   const blockTarget = targetForBlock(graph, block);
   if (!blockTarget) return null;
+  // A question card's code fences and tables live in its context part; the
+  // part lookup below resolves them.
+  const card = block.matches(QUESTION_CARD_SELECTOR);
 
-  const code = block.querySelector<HTMLElement>('pre > code.pn-code');
+  const code = card ? null : block.querySelector<HTMLElement>('pre > code.pn-code');
   if (
     code
     && (pointerTarget === code || code.contains(pointerTarget) || pointerTarget.closest('pre'))
@@ -464,7 +515,7 @@ export function resolveSemanticTargetAtPoint(
     return blockTarget;
   }
 
-  const table = block.querySelector<HTMLTableElement>('table');
+  const table = card ? null : block.querySelector<HTMLTableElement>('table');
   if (table && pointer) {
     const rect = table.getBoundingClientRect();
     const nearHorizontalEdge = pointer.clientX - rect.left < TABLE_EDGE_ZONE
@@ -484,6 +535,14 @@ export function resolveSemanticTargetAtPoint(
     if (inlineTarget) return inlineTarget;
   }
 
+  // Inside a question card: the part under the pointer. A choice row's
+  // padding and marker belong to that choice's text.
+  const part = pointerTarget.closest<HTMLElement>(QUESTION_PART_SELECTOR)
+    ?? pointerTarget.closest<HTMLElement>('[data-question-option]')?.querySelector<HTMLElement>(QUESTION_PART_SELECTOR);
+  if (part && block.contains(part)) {
+    return graph.byElement.get(part) ?? blockTarget;
+  }
+
   const cell = pointerTarget.closest<HTMLTableCellElement>('td,th');
   if (cell && block.contains(cell)) {
     return graph.byElement.get(cell) ?? blockTarget;

package/utils/diagramAskAI.ts

@@ -0,0 +1,161 @@
+import {
+  diagramAnchorLocationLine,
+  diagramTargetName,
+  diagramTargetText,
+  type DiagramAnchor,
+  type DiagramKind,
+  type DiagramTarget,
+} from '@plannotator/core/diagram-anchor';
+import type { CommentAskAIContext } from '../components/CommentPopover';
+
+/**
+ * Ask AI from a diagram comment: the question rides the same
+ * `CommentAskAIContext` the markdown and html composers send, so the host's
+ * one Ask AI path (an SDK provider, "Ask this session", the agent terminal)
+ * carries it unchanged. `text` is the part's label (what the chat shows under
+ * the question); `detail` is the agent-facing identity, which
+ * `buildDefaultPrompt` puts on the USER message before the question, never in
+ * the system prompt:
+ *
+ *   Diagram node Approve? (D), line 7          <- the export's location line
+ *   Diagram type: Mermaid (flowchart)
+ *   Diagram source, document lines 6–9:
+ *   ````mermaid
+ *   …
+ *   ````
+ *
+ * The source is bounded (a window around the part when the diagram is long),
+ * so a huge whole-file diagram never floods a turn.
+ */
+
+const ENGINE_LABELS: Record<DiagramKind, string> = { mermaid: 'Mermaid', graphviz: 'Graphviz' };
+const FENCE_LANGUAGE: Record<DiagramKind, string> = { mermaid: 'mermaid', graphviz: 'dot' };
+
+/** Most diagram source lines a question carries. */
+export const MAX_ASK_AI_DIAGRAM_SOURCE_LINES = 40;
+/** Most diagram source characters a question carries. */
+export const MAX_ASK_AI_DIAGRAM_SOURCE_CHARS = 4000;
+
+export interface DiagramAskAIInput {
+  readonly kind: DiagramKind;
+  /** The part the question is about; `sourceLine` names DOCUMENT lines. */
+  readonly anchor: DiagramAnchor;
+  /** Shift-click targets the draft also covers (absent or empty for most). */
+  readonly additionalTargets?: readonly DiagramTarget[];
+  /** The diagram text (the fence body, or the whole file). */
+  readonly source: string;
+  /** Lines to add to a diagram line to name the document line: the fence's
+   * opening line for a fence, 0 when the document is the diagram. */
+  readonly sourceLineOffset: number;
+  /** The document the diagram lives in, as the other composers send it. */
+  readonly sourcePath?: string;
+}
+
+/** A fence that no backtick run in the source can close early. */
+function fenceFor(source: string): string {
+  let longest = 0;
+  for (const run of source.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  return '`'.repeat(Math.max(4, longest + 1));
+}
+
+/** A line longer than the whole budget is cut, with a visible marker. */
+const TRUNCATION_MARKER = '…';
+
+/**
+ * The bounded slice of the source a question carries, grown outward from the
+ * part's line (the top of the diagram when the part has no line), one line
+ * below then one above, until the line cap or the character cap stops a
+ * side. The part's own line is always in it; a part line longer than the
+ * whole character budget is cut with a visible marker, so the slice never
+ * exceeds MAX_ASK_AI_DIAGRAM_SOURCE_CHARS (newlines included). Returns
+ * 1-based DIAGRAM lines and the text to quote.
+ */
+function sourceWindow(
+  lines: readonly string[],
+  anchor: DiagramAnchor,
+  offset: number,
+): { first: number; last: number; body: string; excerpt: boolean } | null {
+  let wholeFirst = 1;
+  let wholeLast = lines.length;
+  while (wholeLast > 0 && (lines[wholeLast - 1] ?? '').trim() === '') wholeLast -= 1;
+  while (wholeFirst <= wholeLast && (lines[wholeFirst - 1] ?? '').trim() === '') wholeFirst += 1;
+  if (wholeLast === 0 || wholeFirst > wholeLast) return null;
+
+  const partLine = anchor.kind !== 'diagram' && anchor.sourceLine !== null ? anchor.sourceLine[0] - offset : null;
+  const center = partLine !== null && partLine >= wholeFirst && partLine <= wholeLast ? partLine : wholeFirst;
+
+  let centerText = lines[center - 1] ?? '';
+  let truncated = false;
+  if (centerText.length > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) {
+    centerText = centerText.slice(0, MAX_ASK_AI_DIAGRAM_SOURCE_CHARS - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+    truncated = true;
+  }
+  let chars = centerText.length;
+  let count = 1;
+  let first = center;
+  let last = center;
+  let growDown = true;
+  let growUp = true;
+  while ((growDown || growUp) && count < MAX_ASK_AI_DIAGRAM_SOURCE_LINES) {
+    if (growDown) {
+      const next = last + 1;
+      const cost = (lines[next - 1] ?? '').length + 1;
+      if (next > wholeLast || chars + cost > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) growDown = false;
+      else {
+        last = next;
+        chars += cost;
+        count += 1;
+      }
+    }
+    if (growUp && count < MAX_ASK_AI_DIAGRAM_SOURCE_LINES) {
+      const next = first - 1;
+      const cost = (lines[next - 1] ?? '').length + 1;
+      if (next < wholeFirst || chars + cost > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) growUp = false;
+      else {
+        first = next;
+        chars += cost;
+        count += 1;
+      }
+    }
+  }
+  const body = [...lines.slice(first - 1, center - 1), centerText, ...lines.slice(center, last)].join('\n');
+  return { first, last, body, excerpt: truncated || first > wholeFirst || last < wholeLast };
+}
+
+/** The agent-facing identity of a diagram part (the `detail` Ask AI sends). */
+export function diagramIdentityForAskAI(input: DiagramAskAIInput): string {
+  const { kind, anchor, source, sourceLineOffset } = input;
+  const out: string[] = [diagramAnchorLocationLine(anchor)];
+  for (const extra of input.additionalTargets ?? []) {
+    const text = diagramTargetText(extra);
+    out.push(`Also: ${diagramTargetName(extra)}${text !== '' && text !== extra.id ? ` "${text}"` : ''}`);
+  }
+  out.push(`Diagram type: ${ENGINE_LABELS[kind]} (${anchor.family})`);
+
+  const lines = source.split('\n');
+  const window = sourceWindow(lines, anchor, sourceLineOffset);
+  if (window !== null) {
+    const body = window.body;
+    const docFirst = window.first + sourceLineOffset;
+    const docLast = window.last + sourceLineOffset;
+    const range = docLast > docFirst ? `lines ${docFirst}–${docLast}` : `line ${docFirst}`;
+    const partial = window.excerpt ? ' (excerpt)' : '';
+    const fence = fenceFor(body);
+    out.push(`Diagram source${partial}, document ${range}:`);
+    out.push(`${fence}${FENCE_LANGUAGE[kind]}\n${body}\n${fence}`);
+  }
+  return out.join('\n');
+}
+
+/** The Ask AI context for a question asked from a diagram comment. */
+export function diagramAskAIContext(input: DiagramAskAIInput): CommentAskAIContext {
+  const { kind, anchor } = input;
+  const engine = ENGINE_LABELS[kind];
+  return {
+    kind: 'selection',
+    label: anchor.kind === 'diagram' ? `${engine} diagram` : `${engine} diagram ${diagramTargetName(anchor)}`,
+    text: diagramTargetText(anchor),
+    ...(input.sourcePath !== undefined ? { sourcePath: input.sourcePath } : {}),
+    detail: diagramIdentityForAskAI(input),
+  };
+}

package/utils/diffFileTree.ts

@@ -0,0 +1,203 @@
+/**
+ * Pure tree builder for a list of changed files (a diff), shared by
+ * Plannotator's code-review file tree (`packages/review-editor`) and the
+ * embeddable `DiffFileTree` component. Browser-safe, no React.
+ *
+ * Shape rules (the review's, unchanged when this moved here):
+ * - folders before files at every level, each group sorted by name
+ *   (`localeCompare`);
+ * - a folder whose only child is a folder is merged into it
+ *   (`packages/app/src`), recursively;
+ * - when the whole tree is one root folder holding only files, that folder is
+ *   unwrapped and the files sit at the root;
+ * - a folder's +/- counts are the sums of everything under it.
+ */
+
+/** Change status a tree row can show. 'binary' is a host-facing extra; the
+ * review's own parser never produces it. */
+export type DiffFileTreeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'binary';
+
+/** The minimum a file needs to sit in the tree. */
+export interface DiffFileTreeFile {
+  path: string;
+  oldPath?: string;
+  status: DiffFileTreeStatus;
+  additions: number;
+  deletions: number;
+}
+
+export interface DiffFileTreeNode<F extends DiffFileTreeFile = DiffFileTreeFile> {
+  type: 'file' | 'folder';
+  /** Display name: the file name, or the (possibly merged) folder segment(s). */
+  name: string;
+  /** File: the file's own path. Folder: the full folder path from the root. */
+  path: string;
+  depth: number;
+  /** Index of the file in the input array (file nodes only). */
+  fileIndex?: number;
+  file?: F;
+  children?: DiffFileTreeNode<F>[];
+  additions: number;
+  deletions: number;
+}
+
+interface TrieNode<F> {
+  children: Map<string, TrieNode<F>>;
+  file?: { index: number; data: F };
+}
+
+function buildTrie<F extends DiffFileTreeFile>(files: readonly F[]): TrieNode<F> {
+  const root: TrieNode<F> = { children: new Map() };
+
+  for (let i = 0; i < files.length; i++) {
+    const segments = files[i].path.split('/').filter(Boolean);
+    let current = root;
+
+    for (let j = 0; j < segments.length - 1; j++) {
+      if (!current.children.has(segments[j])) {
+        current.children.set(segments[j], { children: new Map() });
+      }
+      current = current.children.get(segments[j])!;
+    }
+
+    const fileName = segments[segments.length - 1];
+    const leaf: TrieNode<F> = { children: new Map(), file: { index: i, data: files[i] } };
+    current.children.set(fileName, leaf);
+  }
+
+  return root;
+}
+
+function trieToNodes<F extends DiffFileTreeFile>(
+  trie: TrieNode<F>,
+  parentPath: string,
+  depth: number,
+): DiffFileTreeNode<F>[] {
+  const folders: DiffFileTreeNode<F>[] = [];
+  const fileNodes: DiffFileTreeNode<F>[] = [];
+
+  for (const [name, child] of trie.children) {
+    const fullPath = parentPath ? `${parentPath}/${name}` : name;
+
+    if (child.file) {
+      fileNodes.push({
+        type: 'file',
+        name,
+        path: child.file.data.path,
+        depth,
+        fileIndex: child.file.index,
+        file: child.file.data,
+        additions: child.file.data.additions,
+        deletions: child.file.data.deletions,
+      });
+    } else {
+      const children = trieToNodes(child, fullPath, depth + 1);
+      const additions = children.reduce((s, c) => s + c.additions, 0);
+      const deletions = children.reduce((s, c) => s + c.deletions, 0);
+
+      folders.push({
+        type: 'folder',
+        name,
+        path: fullPath,
+        depth,
+        children,
+        additions,
+        deletions,
+      });
+    }
+  }
+
+  folders.sort((a, b) => a.name.localeCompare(b.name));
+  fileNodes.sort((a, b) => a.name.localeCompare(b.name));
+
+  return [...folders, ...fileNodes];
+}
+
+function collapseSingleChild<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): DiffFileTreeNode<F>[] {
+  return nodes.map(node => {
+    if (node.type !== 'folder' || !node.children) return node;
+
+    let current = node;
+    while (
+      current.children &&
+      current.children.length === 1 &&
+      current.children[0].type === 'folder'
+    ) {
+      const child = current.children[0];
+      current = {
+        ...child,
+        name: `${current.name}/${child.name}`,
+        depth: node.depth,
+      };
+    }
+
+    return {
+      ...current,
+      children: current.children ? collapseSingleChild(fixDepths(current.children, node.depth + 1)) : undefined,
+    };
+  });
+}
+
+function fixDepths<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[], depth: number): DiffFileTreeNode<F>[] {
+  return nodes.map(node => ({
+    ...node,
+    depth,
+    children: node.children ? fixDepths(node.children, depth + 1) : undefined,
+  }));
+}
+
+export function buildDiffFileTree<F extends DiffFileTreeFile>(files: readonly F[]): DiffFileTreeNode<F>[] {
+  if (files.length === 0) return [];
+
+  const trie = buildTrie(files);
+  let tree = trieToNodes(trie, '', 0);
+  tree = collapseSingleChild(tree);
+
+  // Flat fallback: if the tree is a single root folder with only file children, unwrap it
+  if (
+    tree.length === 1 &&
+    tree[0].type === 'folder' &&
+    tree[0].children?.every(c => c.type === 'file')
+  ) {
+    return fixDepths(tree[0].children!, 0);
+  }
+
+  return tree;
+}
+
+/** Every proper ancestor folder path of a file path (`a/b/c.ts` → `a`, `a/b`).
+ * A merged folder's path is one of these, so expanding them all reveals the file. */
+export function getAncestorPaths(filePath: string): string[] {
+  const segments = filePath.split('/').filter(Boolean);
+  const paths: string[] = [];
+  for (let i = 1; i < segments.length; i++) {
+    paths.push(segments.slice(0, i).join('/'));
+  }
+  return paths;
+}
+
+/** File indexes in the order the tree renders them (ignores collapse state). */
+export function getVisualFileOrder<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): number[] {
+  const order: number[] = [];
+  for (const node of nodes) {
+    if (node.type === 'file' && node.fileIndex != null) {
+      order.push(node.fileIndex);
+    } else if (node.children) {
+      order.push(...getVisualFileOrder(node.children));
+    }
+  }
+  return order;
+}
+
+export function getAllFolderPaths<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): string[] {
+  const paths: string[] = [];
+  for (const node of nodes) {
+    if (node.type === 'folder') {
+      paths.push(node.path);
+      if (node.children) {
+        paths.push(...getAllFolderPaths(node.children));
+      }
+    }
+  }
+  return paths;
+}

package/utils/htmlLinkNavigation.ts

@@ -12,8 +12,16 @@
  * server origin and the directories, so every branch is unit-testable.
  */
 
+import { isReviewImagePath } from "@plannotator/core/diff-paths";
 import { hasLinkedDocExtension } from "./markdownExtensions";
 
+/**
+ * Route the servers serve a raw-HTML page's support assets from. Spelled here
+ * rather than imported because `@plannotator/shared/html-assets` is node-side
+ * (parse5, `path`); `htmlLinkNavigation.test.ts` pins the two together.
+ */
+export const HTML_ASSET_ROUTE_PREFIX = "/api/html-assets";
+
 /** Longest href the parent will look at. Matches the bridge's own cap. */
 export const MAX_HTML_LINK_HREF_LENGTH = 2048;
 
@@ -27,11 +35,29 @@ export type HtmlLinkIntent =
 	| { kind: "document"; path: string; hash: string; rendersHtml: boolean }
 	/** Another origin. Opens in a new tab; the frame never navigates. */
 	| { kind: "external"; url: string }
-	/** A local file Plannotator cannot render as a document (`.pdf`, `.zip`, …). */
-	| { kind: "unsupported"; path: string; label: string }
+	/**
+	 * A local image inside the page's asset root, shown in the image lightbox.
+	 * `url` is the page's own `/api/html-assets/<token>/…` route, so the
+	 * lightbox reads exactly what the page itself can already load.
+	 */
+	| { kind: "image"; path: string; url: string; label: string }
+	/**
+	 * A local file Plannotator will not open. `type`: not a document or image
+	 * (`.pdf`, `.zip`, …). `outside-asset-root`: an image outside the page's
+	 * own folder, which the asset route refuses. `no-asset-root`: an image on
+	 * a page served without an asset route (share links, converted pages).
+	 */
+	| {
+			kind: "unsupported";
+			path: string;
+			label: string;
+			reason: HtmlLinkUnsupportedReason;
+	  }
 	/** Nothing to do: empty, fragment-only, or a scheme we do not follow. */
 	| { kind: "ignored"; reason: HtmlLinkIgnoreReason };
 
+export type HtmlLinkUnsupportedReason = "type" | "outside-asset-root" | "no-asset-root";
+
 export type HtmlLinkIgnoreReason =
 	| "empty"
 	| "too-long"
@@ -55,6 +81,12 @@ export interface HtmlLinkContext {
 	/** The session's `--markdown` preference: HTML is Turndowned by `/api/doc`,
 	 *  so an `.html` target renders as markdown rather than as an HTML surface. */
 	convertHtml?: boolean;
+	/**
+	 * The current page's asset root: the directory its `/api/html-assets`
+	 * token was minted for, and that token's route (`/api/html-assets/<t>/`).
+	 * Image links open in the lightbox only from inside `dir`.
+	 */
+	assetRoot?: { dir: string; url: string } | null;
 }
 
 /** Control characters never appear in a real href; they are how structure gets smuggled. */
@@ -119,11 +151,13 @@ function resolveRelative(
 	if (!baseDir) return { kind: "ignored", reason: "no-base" };
 	const resolved = joinPath(baseDir, decoded);
 	if (!resolved) return { kind: "ignored", reason: "invalid" };
+	const label = basename(resolved);
+	if (isReviewImagePath(resolved)) return resolveImage(resolved, label, context.assetRoot);
 	// Containment is the server's call (`/api/doc` answers 403 for an escaping
 	// path). The extension gate is ours: a `.pdf` would be a pointless fetch
 	// and a confusing server error, so it is reported as unsupported here.
 	if (!hasLinkedDocExtension(resolved)) {
-		return { kind: "unsupported", path: resolved, label: basename(resolved) };
+		return { kind: "unsupported", path: resolved, label, reason: "type" };
 	}
 	return {
 		kind: "document",
@@ -133,6 +167,56 @@ function resolveRelative(
 	};
 }
 
+/**
+ * An image link opens in the lightbox, read through the page's own asset
+ * route. That route serves only files below the token's directory (it refuses
+ * `..` and checks the realpath), so an image outside it is reported here
+ * instead of becoming a request the server would refuse. This check is
+ * lexical and only decides the UI; the server's check is the one that holds.
+ */
+function resolveImage(
+	path: string,
+	label: string,
+	assetRoot: HtmlLinkContext["assetRoot"],
+): HtmlLinkIntent {
+	if (!assetRoot?.dir || !assetRoot.url) {
+		return { kind: "unsupported", path, label, reason: "no-asset-root" };
+	}
+	const dir = assetRoot.dir.replace(/\\/g, "/").replace(/\/+$/, "");
+	if (!path.startsWith(`${dir}/`)) {
+		return { kind: "unsupported", path, label, reason: "outside-asset-root" };
+	}
+	const relative = path
+		.slice(dir.length + 1)
+		.split("/")
+		.map(encodeURIComponent)
+		.join("/");
+	const base = assetRoot.url.endsWith("/") ? assetRoot.url : `${assetRoot.url}/`;
+	return { kind: "image", path, url: `${base}${relative}`, label };
+}
+
+/**
+ * The asset route a served raw-HTML page is anchored at. Both servers install
+ * `<base href="/api/html-assets/<token>/">` first in `<head>` (re-anchoring a
+ * relative author base under the same token). Returns that token's route, or
+ * null when the page carries none (share links, an author's absolute base).
+ *
+ * Only the FIRST `<base>` element counts, as in the browser, and comments are
+ * skipped: a page cannot name a different token in a comment or a later base
+ * tag and have the lightbox read through it.
+ */
+const HTML_COMMENT_PATTERN = new RegExp("<!--[\\s\\S]*?(?:-->|$)", "g");
+
+export function htmlAssetRouteFromDocument(rawHtml: string | null | undefined): string | null {
+	if (!rawHtml) return null;
+	// RegExp constructor, not a literal: Semgrep's TS parser chokes on `<!--` in a regex literal.
+	const withoutComments = rawHtml.replace(HTML_COMMENT_PATTERN, "");
+	const baseTag = /<base\b[^>]*>/i.exec(withoutComments);
+	if (!baseTag) return null;
+	const match = /\bhref\s*=\s*["']?\/api\/html-assets\/([A-Za-z0-9_-]+)\//i.exec(baseTag[0]);
+	return match ? `${HTML_ASSET_ROUTE_PREFIX}/${match[1]}/` : null;
+}
+
 /**
  * Whether opening `path` lands on another raw-HTML surface rather than a
  * markdown one. `--markdown` sessions convert HTML on the way in, so nothing