samagotchi 0.56.0 → 0.58.0

data/lib/samagotchi/web/public/ref_scan.js

@@ -0,0 +1,216 @@
+// `path:line` refs in an answer's or a step's text (traceable refs P3).
+// A name becomes a file ref (refs.js: span.ref with data-ref-kind="file")
+// only when it names a file the session's rows touched (their refs): the
+// answer's text is unchanged, it resolves on the page, and nothing the
+// session didn't touch gets linked. The scan is github-pr's LineLinker
+// (bundles/github-pr/plugin.rb) on the DOM: pre, links and fenced blocks
+// are left alone, inline code only when it is the ref alone, a bare URL's
+// text too.
+
+import { refAttrs } from "./refs.js";
+
+// A path (no spaces), a line, an optional end line and an optional column
+// (kept in the text, not used). LineLinker::REF.
+export const REF = /(?<![\w./@+~-])(?<path>[\w./@+~-]*[\w@+~-]):(?<from>\d+)(?:-(?<to>\d+))?(?::\d+)?(?![\w/])/;
+export const REF_ALONE = new RegExp(`^${REF.source}$`);
+// A ref, or a bare path (no `:line`): a bare one counts only when it is a
+// touched file exactly (resolveRef's +bare+). Not after a `\` or a `:`
+// either: the tail of `C:\x\foo.rb:3` or `host:lib/foo.rb:3` is another
+// machine's file.
+const REF_OR_PATH = /(?<![\w./@+~\\:-])(?<path>[\w./@+~-]*[\w@+~-])(?::(?<from>\d+)(?:-(?<to>\d+))?(?::\d+)?(?![\w/])|(?![\w/]|:\d))/g;
+const PATH_ALONE = /^(?<path>[\w./@+~-]*[\w@+~-])$/;
+const URL_SPAN = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
+const MARKDOWN_LINK = /\[[^\]]*\]\([^)]*\)/g;
+// A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+// Elements whose text is never scanned: code blocks, links (a github-pr
+// PR link stays the PR's), a ref already made.
+const SKIP = "pre, a, [data-ref-kind]";
+
+// The ref a match names: { path, line, endLine } or null. A path has a `/`
+// or an extension (`10:30` is a time, `host:8080` a port); line 0 is never
+// a ref; an end line not after the line is dropped.
+export function refOf(groups) {
+  const path = groups?.path || "";
+  if (!path.includes("/") && !/\.[A-Za-z0-9]+$/.test(path)) return null;
+  if (groups.from === undefined) return { path, line: null, endLine: null };
+  const line = Number(groups.from);
+  if (!line) return null;
+  const to = groups.to === undefined ? null : Number(groups.to);
+  return { path, line, endLine: to && to > line ? to : null };
+}
+
+// The absolute touched file +path+ names, or null: the path itself when
+// absolute, else the path under +cwd+ (`.` and `..` folded either way); else (not for a +bare+ path: no
+// `:line`) the ONE touched file ending in `/<path>`. Ambiguous: none.
+export function resolveRef(path, touched, cwd, { bare = false } = {}) {
+  const rel = String(path).replace(/^(?:\.\/)+/, "");
+  const exact = rel.startsWith("/") ? joinPath("", rel) : cwd ? joinPath(cwd, rel) : null;
+  if (exact && touched.has(exact)) return exact;
+  if (bare || rel.startsWith("/")) return null;
+  const tail = `/${rel.replace(/^(?:\.\.\/)+/, "")}`;
+  const found = [...touched].filter((file) => file.endsWith(tail));
+  return found.length === 1 ? found[0] : null;
+}
+
+// +rel+ under +dir+, `.` and `..` segments folded.
+function joinPath(dir, rel) {
+  const out = [];
+  for (const part of `${dir}/${rel}`.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") out.pop();
+    else out.push(part);
+  }
+  return `/${out.join("/")}`;
+}
+
+// [start, end, ref] for each ref in a plain +text+ that names a touched
+// file: fenced blocks, markdown links and URLs skipped, inline code only
+// as the ref alone (the span with its backticks). +touched+: a Set of
+// absolute paths; +cwd+: the session's working directory.
+export function textRefs(text, touched, cwd) {
+  if (!touched?.size || !text) return [];
+  const fences = fencedBlocks(text);
+  const skipped = [...fences, ...spans(text, URL_SPAN), ...spans(text, MARKDOWN_LINK)];
+  const code = inlineCode(text, fences);
+  const found = [];
+  for (const [start, end, inner] of code) {
+    if (insideAny(skipped, start, end)) continue;
+    const ref = aloneRef(inner, touched, cwd);
+    if (ref) found.push([start, end, ref]);
+  }
+  for (const match of text.matchAll(REF_OR_PATH)) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (insideAny(skipped, start, end) || insideAny(code, start, end)) continue;
+    const ref = resolved(refOf(match.groups), touched, cwd);
+    if (ref) found.push([start, end, ref]);
+  }
+  return found.sort((a, b) => a[0] - b[0]);
+}
+
+// The ref an inline code's text is when it is a ref (or a touched path)
+// alone, else null.
+function aloneRef(text, touched, cwd) {
+  const inner = String(text).trim();
+  const match = inner.match(REF_ALONE) || inner.match(PATH_ALONE);
+  return match ? resolved(refOf(match.groups), touched, cwd) : null;
+}
+
+function resolved(ref, touched, cwd) {
+  if (!ref) return null;
+  const path = resolveRef(ref.path, touched, cwd, { bare: ref.line === null });
+  return path ? { kind: "file", path, line: ref.line, end_line: ref.endLine } : null;
+}
+
+// The absolute paths of the file refs under +roots+ (the session's rows,
+// approval cards): what a text ref may name.
+export function touchedFiles(roots) {
+  const touched = new Set();
+  for (const root of roots) {
+    for (const el of root.querySelectorAll('[data-ref-kind="file"][data-ref-path]')) {
+      touched.add(el.dataset.refPath);
+    }
+  }
+  return touched;
+}
+
+// Wraps the refs in +el+'s text in span.ref (refs.js clicks and
+// hover them as it does a row title). Text inside pre, a link or a ref is
+// left alone; an inline code element is wrapped whole when it is a ref
+// alone. A link whose text is a ref alone (github-pr's PR diff link) is
+// that ref itself: its href stays the plain click's, the ref's other
+// targets join it in the menu (refs.js). Runs again over the same element
+// without wrapping twice.
+export function linkRefs(el, touched, cwd) {
+  if (!el || !touched?.size) return;
+  const doc = el.ownerDocument;
+  for (const link of [...el.querySelectorAll("a[href]:not([data-ref-kind])")]) {
+    if (link.parentElement?.closest("pre, a, [data-ref-kind]")) continue;
+    const ref = aloneRef(link.textContent, touched, cwd);
+    if (!ref) continue;
+    link.classList.add("ref");
+    for (const [name, value] of Object.entries(refSpan(doc, ref).dataset)) link.dataset[name] = value;
+  }
+  for (const code of [...el.querySelectorAll("code")]) {
+    if (code.closest(SKIP)) continue;
+    const ref = aloneRef(code.textContent, touched, cwd);
+    if (!ref) continue;
+    const span = refSpan(doc, ref);
+    code.replaceWith(span);
+    span.append(code);
+  }
+  const walker = doc.createTreeWalker(el, 4 /* NodeFilter.SHOW_TEXT */);
+  const nodes = [];
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const skip = node.parentElement?.closest(`${SKIP}, code`);
+    if (!skip || !el.contains(skip)) nodes.push(node);
+  }
+  for (const node of nodes) wrapRefs(node, textRefs(node.data, touched, cwd));
+}
+
+function wrapRefs(node, hits) {
+  if (!hits.length) return;
+  const doc = node.ownerDocument;
+  const frag = doc.createDocumentFragment();
+  let pos = 0;
+  for (const [start, end, ref] of hits) {
+    if (start < pos) continue;
+    if (start > pos) frag.append(node.data.slice(pos, start));
+    const span = refSpan(doc, ref);
+    span.textContent = node.data.slice(start, end);
+    frag.append(span);
+    pos = end;
+  }
+  if (pos < node.data.length) frag.append(node.data.slice(pos));
+  node.replaceWith(frag);
+}
+
+function refSpan(doc, ref) {
+  const holder = doc.createElement("div");
+  holder.innerHTML = `<span class="ref"${refAttrs(ref)}></span>`;
+  return holder.firstChild;
+}
+
+// [start, end] of each fenced block (an unclosed one runs to the end).
+function fencedBlocks(text) {
+  const blocks = [];
+  let open = null;
+  let offset = 0;
+  for (const line of text.split(/(?<=\n)/)) {
+    const marker = line.match(FENCE_OPEN)?.[1];
+    if (!open && marker) {
+      open = [offset, marker];
+    } else if (open && marker && marker[0] === open[1][0] && marker.length >= open[1].length && line.trim() === marker) {
+      blocks.push([open[0], offset + line.length]);
+      open = null;
+    }
+    offset += line.length;
+  }
+  if (open) blocks.push([open[0], text.length]);
+  return blocks;
+}
+
+// [start, end, inner] of each inline code span outside +fences+: a run of
+// backticks to the next run of the same length.
+function inlineCode(text, fences) {
+  const runs = spans(text, /`+/g).filter(([start, end]) => !insideAny(fences, start, end));
+  const found = [];
+  let index = 0;
+  while (index < runs.length) {
+    const [start, end] = runs[index];
+    const closing = runs.findIndex(([s, e], k) => k > index && e - s === end - start);
+    if (closing < 0) { index += 1; continue; }
+    found.push([start, runs[closing][1], text.slice(end, runs[closing][0])]);
+    index = closing + 1;
+  }
+  return found;
+}
+
+function spans(text, regex) {
+  return [...text.matchAll(regex)].map((m) => [m.index, m.index + m[0].length]);
+}
+
+function insideAny(list, start, end) {
+  return list.some(([s, e]) => start >= s && end <= e);
+}

data/lib/samagotchi/web/public/refs.js

@@ -1,16 +1,25 @@
 // Refs: quiet links from what a turn touched to the thing itself. A ref is
 // a kind and a target: today a file tool's row title (the server's FileRef,
-// {kind: "file", path, line?, end_line?}) and that row's diff lines (the
-// same file at a line). The DOM carries data-ref-kind and the target's
-// attributes, never what a click does: that is an action, kept per kind in
-// REF_ACTIONS, and a click runs the first one available to this viewer. A
-// ref with none (a phone: no editor) stays plain text; the page marks the
-// kinds that have one on its body (refs-<kind>), which the hover styling
-// keys on.
+// {kind: "file", path, line?, end_line?}), that row's diff lines and a
+// read row's numbered lines (the same file at a line), and an edit/write
+// approval card's paths and its dry run's diff lines, and a `path:line` in
+// an answer or a step's text (ref_scan.js; a link whose text is one too).
+// The DOM carries data-ref-kind and the target's attributes, never what a
+// click does: those are the ref's targets, kept per kind in REF_ACTIONS.
+// A plain click runs the first one available (the main target); a ref
+// with more shows a ▾ on hover that opens a menu of all of them
+// (ref_menu.js), and a tap opens it. A ref with a target is a tab stop
+// (syncRefTabs): Enter is its click, ↓ its menu. A ref with none (a phone's row title:
+// no editor, and the row is the ref's own) stays plain text; refs.js marks
+// a hovered or focused ref with its main target (data-ref-main), which the
+// hover styling keys on.
 
 import { escapeHtml } from "./format.js";
+import { copyText } from "./copy.js";
+import { createRefMenu } from "./ref_menu.js";
 
-// The data attributes a ref's element carries.
+// The data attributes a ref's element carries (its tab stop comes from
+// syncRefTabs, for the viewer).
 export function refAttrs(ref) {
   if (!ref?.kind) return "";
   const attr = (name, value) => (value ? ` data-ref-${name}="${escapeHtml(String(value))}"` : "");
@@ -26,47 +35,87 @@ export function editorUrl(template, path, line) {
   return template.replaceAll("{path}", encoded).replaceAll("{line}", String(line || 1));
 }
 
-// What a ref can do, per kind, in order: the first available one is a
-// click's. +viewer+ is what this page's viewer can do ({editor, editorUrl}:
-// the server's capabilities.editor and editor_url).
+// A ref's targets, per kind, in order: the first available one is a plain
+// click's (the main target), all of them are the menu's. Each says when
+// it's available for +viewer+ (what this page's viewer can do: {editor,
+// editorUrl}, the server's capabilities.editor and editor_url) and
+// +target+ (refTarget's). A secondary one (copy) joins a ref that has
+// another, never alone. A line (a diff or read line) has its click only.
 export const REF_ACTIONS = Object.freeze({
   file: Object.freeze([
+    // A link whose text is the ref (github-pr's PR diff): its href stays
+    // the plain click's, which the browser follows.
+    Object.freeze({
+      id: "link",
+      label: (target) => (/\/pull\/\d+\/files\b/.test(target.href) ? "PR diff" : "Open link"),
+      available: (_viewer, target) => !!target.href,
+      run: (target, _viewer, env) => env.openLink(target.href),
+    }),
     Object.freeze({
       id: "editor",
+      label: () => "Open in editor",
       available: (viewer) => viewer?.editor === true && !!viewer.editorUrl,
       url: (target, viewer) => editorUrl(viewer.editorUrl, target.path, target.line),
+      run(target, viewer, env) {
+        const url = this.url(target, viewer);
+        if (url) env.open(url);
+      },
       // The hover hint: it opens the file as it is now.
       hint: (target) => `Open the current file in your editor${target.line ? ` at line ${target.line}` : ""}`,
     }),
+    // The row that touched the file, in the turn: not for a row's own
+    // title or lines (they are in the turn already).
+    Object.freeze({
+      id: "show",
+      label: () => "Show in turn",
+      available: (_viewer, target) => !target.isLine && !target.owner?.matches?.(".activity-row") && !!turnRowFor(target),
+      run: (target, _viewer, env) => env.show(target),
+      hint: () => "Show the row that touched it in the turn",
+    }),
+    Object.freeze({
+      id: "copy",
+      label: () => "Copy path",
+      secondary: true,
+      available: (_viewer, target) => !target.isLine && !!target.path,
+      run: (target, _viewer, env) => env.copy(target.path),
+    }),
   ]),
 });
 
-// The first action +viewer+ has for a ref of +kind+, else null.
-export function refAction(kind, viewer, actions = REF_ACTIONS) {
-  return (actions[kind] || []).find((action) => action.available(viewer)) || null;
+// The targets +viewer+ has for +target+ (refTarget's), in order; none
+// when only a secondary one is.
+export function refActions(target, viewer, actions = REF_ACTIONS) {
+  if (!target) return [];
+  const found = (actions[target.kind] || []).filter((action) => action.available(viewer, target));
+  return found.some((action) => !action.secondary) ? found : [];
 }
 
-// The kinds that have an action for +viewer+ (the page's refs-<kind> classes).
-export function availableKinds(viewer, actions = REF_ACTIONS) {
-  return Object.keys(actions).filter((kind) => refAction(kind, viewer, actions));
-}
+// What owns a ref and its diff lines: a tool row, or an edit's approval
+// card (its paths and its dry run).
+const OWNERS = ".activity-row, .bubble.approval";
+
+// A line of the owner's file: a diff line, or a read row's numbered line.
+const LINES = ".diff-line[data-line], .read-line[data-line]";
 
-// What a click on +el+ points at: {kind, path, line, owner} or null. A row
-// title opens its file at the lines the call named (an edit without any at
-// its first changed line); a diff line (or a hunk header) in a row with a
-// ref opens the row's file at that line. A diff line outside a row (an
-// approval card's dry run) is none.
+// What a click on +el+ points at: {kind, path, line, owner, el, isLine,
+// href} or null. A row title (or an approval card's path) opens its file
+// at the lines the call named (an edit without any at its first changed
+// line); a diff line (or a hunk header) or a read row's numbered line, in
+// a row or a card with a ref, opens that file at that line. +el+ is the
+// ref's element (the line for a line), +href+ a link ref's.
+// A diff line elsewhere is none.
 export function refTarget(el) {
   const title = el?.closest?.("[data-ref-kind]");
   if (title) {
-    const owner = title.closest(".activity-row");
-    return { ...targetOf(title), line: Number(title.dataset.refLine) || firstChange(owner), owner: owner || title };
+    const owner = title.closest(OWNERS);
+    const href = title.matches("a[href]") ? title.getAttribute("href") : null;
+    return { ...targetOf(title), line: Number(title.dataset.refLine) || firstChange(owner), owner: owner || title, el: title, isLine: false, href };
   }
-  const diffLine = el?.closest?.(".diff-line[data-line]");
-  const owner = diffLine?.closest(".activity-row");
+  const diffLine = el?.closest?.(LINES);
+  const owner = diffLine?.closest(OWNERS);
   const ref = owner?.querySelector("[data-ref-kind]");
   if (!ref) return null;
-  return { ...targetOf(ref), line: Number(diffLine.dataset.line), owner };
+  return { ...targetOf(ref), line: Number(diffLine.dataset.line), owner, el: diffLine, isLine: true, href: null };
 }
 
 function targetOf(el) {
@@ -80,6 +129,99 @@ function firstChange(row) {
   return line ? Number(line.dataset.line) : null;
 }
 
+// The tool row that touched +target+'s file, for "show in turn", or null:
+// a row with a ref to the same file that isn't the ref's own. Looked for
+// in the ref's own step (a step's text comes before its rows), then its
+// own turn (turnBlockOf), then the rows before it, then the nearest after
+// it; in the first of those that has any, the last one showing the ref's
+// line, else the last one (after it: the nearest).
+export function turnRowFor(target) {
+  const el = target?.el;
+  if (!el?.ownerDocument || !target.path) return null;
+  const rows = [...el.ownerDocument.querySelectorAll(".activity-row")].filter((row) => {
+    if (row.contains(el)) return false;
+    const ref = row.querySelector("[data-ref-kind]");
+    return ref?.dataset.refKind === target.kind && ref.dataset.refPath === target.path;
+  });
+  const step = el.closest("details.gen");
+  const turn = turnBlockOf(el);
+  const before = rows.filter((row) => precedes(row, el));
+  const pools = [
+    step ? rows.filter((row) => step.contains(row)) : [],
+    turn ? rows.filter((row) => turn.contains(row)) : [],
+    before,
+    rows.filter((row) => !before.includes(row)).reverse(),
+  ];
+  const pool = pools.find((found) => found.length);
+  if (!pool) return null;
+  const showing = target.line ? pool.filter((row) => lineIn(row, target.line)) : [];
+  return showing.at(-1) || pool.at(-1);
+}
+
+// What holds +el+'s turn's rows: the steps block it is in, the stage (a
+// live turn: its answer comes before its cloud), else the nearest steps
+// block before it with no prompt between them (an answer, a card, in the
+// history). null when there is none.
+function turnBlockOf(el) {
+  const own = el.closest(".turn-work, .turn-stage");
+  if (own) return own;
+  const doc = el.ownerDocument;
+  const block = [...doc.querySelectorAll(".turn-work")].filter((b) => precedes(b, el)).at(-1);
+  if (!block) return null;
+  const prompt = [...doc.querySelectorAll(".bubble.user")].some((u) => precedes(block, u) && precedes(u, el));
+  return prompt ? null : block;
+}
+
+// +a+ comes before +b+ in the page (and doesn't hold it).
+function precedes(a, b) {
+  return !a.contains(b) && !!(a.compareDocumentPosition(b) & 4 /* Node.DOCUMENT_POSITION_FOLLOWING */);
+}
+
+// +row+'s line +line+: an added or context diff line first (a removed one
+// shares its number), then a read line; null when it doesn't show it.
+function lineIn(row, line) {
+  for (const selector of [".diff-line.diff-add", ".diff-line.diff-ctx", ".read-line", ".diff-line"]) {
+    const found = row.querySelector(`${selector}[data-line="${Number(line)}"]`);
+    if (found) return found;
+  }
+  return null;
+}
+
+// "Show in turn": opens what hides the row that touched +target+'s file
+// (the turn's steps, its step), its diff (or the read that shows the
+// line), scrolls to the line (else the row) and flashes both. A view that
+// hides its rows its own way (the stage's cloud) opens on the row's
+// ref:reveal event, which bubbles. The row, or null when there is none.
+export function showInTurn(target, { behavior = smoothScroll() } = {}) {
+  const row = turnRowFor(target);
+  if (!row) return null;
+  const view = row.ownerDocument.defaultView || globalThis;
+  row.dispatchEvent(new view.CustomEvent("ref:reveal", { bubbles: true }));
+  const line = target.line ? lineIn(row, target.line) : null;
+  const fold = line?.closest("details.activity-diff, details.activity-read") || row.querySelector("details.activity-diff");
+  for (let details = (line || fold || row).closest("details"); details; details = details.parentElement?.closest("details")) {
+    details.open = true;
+  }
+  if (fold) fold.open = true;
+  (line || row).scrollIntoView?.({ block: "center", behavior });
+  for (const el of [row, line].filter(Boolean)) flash(el);
+  return row;
+}
+
+const FLASH_MS = 1600;
+
+function flash(el) {
+  el.classList.remove("ref-flash");
+  void el.offsetWidth; // restarts the animation on a second show
+  el.classList.add("ref-flash");
+  clearTimeout(el._refFlash);
+  el._refFlash = setTimeout(() => el.classList.remove("ref-flash"), FLASH_MS);
+}
+
+function smoothScroll() {
+  return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth";
+}
+
 // A drag that selected text in the clicked ref's row isn't a click on the
 // ref. A selection elsewhere on the page (or a collapsed one) doesn't count.
 function selectingIn(owner, selection) {
@@ -93,42 +235,129 @@ function defaultOpen(url) {
   else window.location.href = url;
 }
 
-// One delegated listener on +root+ for every ref on the page. +viewer+()
-// is read per click and hover, so a capabilities change (another session,
-// a reload) is seen; +open+(url) opens an action's URL.
-export function installRefClicks(root, viewer, { open = defaultOpen, selection = () => window.getSelection?.() } = {}) {
+// A link ref's href from the menu: a new tab, as the answer's links open.
+function defaultOpenLink(href) {
+  window.open(href, "_blank", "noopener");
+}
+
+// One delegated listener set on +root+ for every ref on the page.
+// +viewer+() is read per click, key and hover, so a capabilities change
+// (another session, a reload) is seen. The targets run through: +open+(url)
+// (the editor's URL), +openLink+(href), +show+(target) and +copy+(text).
+// +menu+ is the ▾ and its menu (ref_menu.js).
+export function installRefClicks(root, viewer, {
+  open = defaultOpen, openLink = defaultOpenLink, show = (target) => showInTurn(target), copy = copyText,
+  selection = () => window.getSelection?.(), menu = createRefMenu(root.ownerDocument),
+} = {}) {
+  const env = { open, openLink, show, copy };
+  const run = (action, target) => action.run(target, viewer(), env);
+  const items = (actions, target) => actions.map((action) => ({ id: action.id, label: action.label(target), run: () => run(action, target) }));
+  const openMenu = (target, actions, options) => menu.open(target.el, items(actions, target), options);
+  // The last pointer's type: a tap opens the menu, a mouse click runs the
+  // main target.
+  let pointer = "mouse";
+  root.addEventListener("pointerdown", (e) => { pointer = e.pointerType || "mouse"; }, true);
+  // A key press: the keyboard leads now (Enter on a link after a tap is
+  // the link's own click); Tab works out the tab stops before it moves.
+  root.addEventListener("keydown", (e) => {
+    pointer = "keyboard";
+    if (e.key === "Tab") syncRefTabs(root, viewer());
+  }, true);
+
   root.addEventListener("click", (e) => {
     if (e.button !== 0 || e.defaultPrevented) return;
     const target = refTarget(e.target);
     if (!target) return;
-    const action = refAction(target.kind, viewer());
-    if (!action) return;
+    const actions = refActions(target, viewer());
+    if (!actions.length) return;
     if (selectingIn(target.owner, selection())) return;
-    const url = action.url(target, viewer());
-    if (!url) return;
+    if (pointer === "touch" && !target.isLine && actions.length > 1) {
+      e.preventDefault();
+      e.stopPropagation();
+      openMenu(target, actions, { focus: false });
+      return;
+    }
+    // A link's own click: the browser follows it.
+    if (actions[0].id === "link") return;
     e.preventDefault();
     e.stopPropagation();
-    open(url);
+    run(actions[0], target);
   });
-  // The hover hint, on the ref's own element, worked out on each hover
-  // (the viewer can change): its own title (a row title's hover) first,
-  // then the action's hint when there is one.
-  root.addEventListener("mouseover", (e) => {
+
+  // A focused ref: Enter is its main target (a link's Enter is its own
+  // click), ↓ opens the menu with the first target focused, Esc hides the ▾.
+  root.addEventListener("keydown", (e) => {
+    if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
+    const el = e.target;
+    if (!el?.matches?.("[data-ref-kind]")) return;
+    if (e.key === "Escape") menu.hideMore();
+    if (e.key !== "Enter" && e.key !== "ArrowDown") return;
+    const target = refTarget(el);
+    const actions = refActions(target, viewer());
+    if (!actions.length) return;
+    if (e.key === "Enter") {
+      if (actions[0].id === "link") return;
+      e.preventDefault();
+      run(actions[0], target);
+    } else if (actions.length > 1) {
+      e.preventDefault();
+      openMenu(target, actions, { focus: true });
+    }
+  });
+
+  // On hover or focus: the ref's main target on it (data-ref-main, for the
+  // styling), its hover hint, and the ▾ when it has more than one (not
+  // after a tap, which opens the menu itself).
+  const mark = (e) => {
     const target = refTarget(e.target);
     if (!target) return;
-    const el = e.target.closest("[data-ref-kind]") || e.target.closest(".diff-line[data-line]");
-    if (!el) return;
-    if (el.dataset.refTitle === undefined) el.dataset.refTitle = el.getAttribute("title") || "";
-    const own = el.dataset.refTitle;
-    const action = refAction(target.kind, viewer());
-    const title = [own, action ? action.hint(target) : ""].filter(Boolean).join("\n");
-    if (title) el.setAttribute("title", title);
-    else el.removeAttribute("title");
-  });
+    const actions = refActions(target, viewer());
+    const el = target.el;
+    if (actions.length) el.dataset.refMain = actions[0].id;
+    else delete el.dataset.refMain;
+    if (!target.isLine) setRefRole(el, actions);
+    hint(el, target, actions[0]);
+    if (!target.isLine && actions.length > 1 && pointer !== "touch") menu.showMore(el, () => openMenu(refTarget(el), refActions(refTarget(el), viewer()), { focus: true }));
+  };
+  root.addEventListener("mouseover", mark);
+  root.addEventListener("focusin", mark);
+  const leave = (e) => {
+    const el = e.target?.closest?.("[data-ref-kind]");
+    if (el && !el.contains(e.relatedTarget)) menu.hideMoreSoon(el);
+  };
+  root.addEventListener("mouseout", leave);
+  root.addEventListener("focusout", leave);
+}
+
+// The tab stops under +root+ for +viewer+: a ref is one (a button, with
+// aria-haspopup when it has a menu) only while it has a target, so a
+// phone's or an editorless viewer's row titles aren't. Worked out before a
+// Tab moves the focus and on a ref's hover or focus; a line never is one.
+export function syncRefTabs(root, viewer) {
+  for (const el of root.querySelectorAll("[data-ref-kind]")) setRefRole(el, refActions(refTarget(el), viewer));
+}
+
+function setRefRole(el, actions) {
+  if (actions.length > 1) el.setAttribute("aria-haspopup", "menu");
+  else el.removeAttribute("aria-haspopup");
+  // A link is focusable and a link already.
+  if (el.matches("a[href]")) return;
+  if (actions.length) {
+    el.tabIndex = 0;
+    el.setAttribute("role", "button");
+  } else {
+    el.removeAttribute("tabindex");
+    el.removeAttribute("role");
+  }
 }
 
-// The body's classes for +viewer+: refs-<kind> for each kind with an action.
-export function setRefKinds(body, viewer, actions = REF_ACTIONS) {
-  const kinds = availableKinds(viewer, actions);
-  for (const kind of Object.keys(actions)) body.classList.toggle(`refs-${kind}`, kinds.includes(kind));
+// The hover hint, on the ref's own element, worked out on each hover (the
+// viewer can change): its own title (a row title's hover) first, then the
+// main target's hint when it has one.
+function hint(el, target, action) {
+  if (el.dataset.refTitle === undefined) el.dataset.refTitle = el.getAttribute("title") || "";
+  const own = el.dataset.refTitle;
+  const title = [own, action?.hint ? action.hint(target) : ""].filter(Boolean).join("\n");
+  if (title) el.setAttribute("title", title);
+  else el.removeAttribute("title");
 }