@vintasoftware/pr-review-canvas 0.1.0

package/static/js/points.js

@@ -0,0 +1,247 @@
+// @ts-check
+/** @typedef {import('./contract-types.js').Layer} Layer */
+/** @typedef {import('./contract-types.js').Point} Point */
+/** @typedef {import('./contract-types.js').PrState} PrState */
+import { askButtonHtml } from './ask.js'
+import { viewCommentHtml } from './comment-link.js'
+import { esc } from './dom.js'
+import { layerAnchorId, pointAnchorId } from './keys.js'
+import { renderMarkdown } from './markdown.js'
+
+export const LEVELS = /** @type {const} */ (['decide', 'check', 'fyi'])
+
+/**
+ * @param {ReadonlyArray<Point>} points
+ * @returns {Record<'decide' | 'check' | 'fyi', Point[]>}
+ */
+export function pointsByLevel(points) {
+  /** @type {Record<'decide' | 'check' | 'fyi', Point[]>} */
+  const out = { decide: [], check: [], fyi: [] }
+  for (const p of points) {
+    out[p.level].push(p)
+  }
+  return out
+}
+
+/**
+ * The `#line:` link for a point's anchor.
+ * @param {Point} p
+ */
+export function pointLink(p) {
+  const range = p.endLine !== undefined && p.endLine !== p.line ? `${p.line}-${p.endLine}` : `${p.line}`
+  return `#line:${p.path}:${range}${p.side === 'old' ? ':old' : ''}`
+}
+
+/** @param {Point} p */
+export function pointLocation(p) {
+  const range = p.endLine !== undefined && p.endLine !== p.line ? `${p.line}-${p.endLine}` : `${p.line}`
+  return `${p.path}:${range}`
+}
+
+/**
+ * @param {Point} p
+ */
+export function squareHtml(p) {
+  return `<span class="sq ${p.level}" role="img" aria-label="${p.level}" title="${p.level}"></span>`
+}
+
+/**
+ * The point as a GitHub comment: the title, the body, and where it is anchored.
+ * @param {Point} p
+ */
+export function pointToMarkdown(p) {
+  return `**${p.title}**\n\n${p.body}\n\n_${pointLocation(p)} · ${p.kind} · ${p.level} · from the pr-review canvas_`
+}
+
+/**
+ * What the chat is asked about when a point's `[ ask ]` is used: the point itself. The server
+ * resolves the fingerprint against the canvas and sends the agent the point's text along with
+ * the lines it sits on, so the agent sees what the reader is reacting to.
+ * @param {Point} p
+ * @returns {import('./chat-context.js').ChatContext}
+ */
+export function pointContext(p) {
+  return { kind: 'point', fingerprint: p.fingerprint }
+}
+
+/**
+ * The commands every point carries. `copy` puts the markdown on the clipboard, `post to github`
+ * opens nothing and posts it at the anchor, `dismiss` takes the point off the page.
+ * @param {Point} p
+ * @param {{ dismissed?: boolean, postedUrl?: string | undefined }} [opts]
+ * @returns {string}
+ */
+export function pointCommandsHtml(p, opts = {}) {
+  const fp = esc(p.fingerprint)
+  const toggle = opts.dismissed
+    ? `<button class="cmd" type="button" data-act="point-restore" data-fingerprint="${fp}">restore</button>`
+    : `<button class="cmd" type="button" data-act="point-dismiss" data-fingerprint="${fp}">dismiss</button>`
+  return (
+    '<span class="tbtns">' +
+    `<button class="cmd" type="button" data-copy="${esc(pointToMarkdown(p))}">copy</button>` +
+    (opts.postedUrl === undefined
+      ? `<button class="cmd" type="button" data-act="point-post" data-point="${esc(p.id)}" data-needs-post>post to github</button>`
+      : viewCommentHtml(opts.postedUrl)) +
+    askButtonHtml(pointContext(p)) +
+    toggle +
+    '</span>'
+  )
+}
+
+/**
+ * The comment this point was posted as, when it was.
+ * @param {Point} p
+ * @param {{ posted?: ReadonlyMap<string, string> }} ctx
+ */
+export function postedFor(p, ctx) {
+  return ctx.posted?.get(p.fingerprint)
+}
+
+/**
+ * Where each point's posted comment lives, read from the state and the comments the page holds.
+ * @param {import('./contract-types.js').PrState} state
+ * @param {ReadonlyArray<{ id: number, url: string }>} comments
+ * @returns {Map<string, string>} point fingerprint → comment url
+ */
+export function postedUrls(state, comments) {
+  const urls = new Map(comments.map(c => [c.id, c.url]))
+  /** @type {Map<string, string>} */
+  const out = new Map()
+  for (const entry of state.posted) {
+    const url = urls.get(entry.commentId)
+    if (entry.pointFingerprint !== undefined && url !== undefined) {
+      out.set(entry.pointFingerprint, url)
+    }
+  }
+  return out
+}
+
+/**
+ * One attention point card, shown in the layer that owns the point.
+ * @param {Point} p
+ * @param {{ paths: ReadonlySet<string>, state?: PrState, posted?: ReadonlyMap<string, string> }} ctx
+ */
+export function pointCardHtml(p, ctx) {
+  const dismissed = ctx.state?.dismissed[p.fingerprint] !== undefined
+  const posted = postedFor(p, ctx)
+  return (
+    `<li class="finding" id="${esc(pointAnchorId(p.id))}" data-point="${esc(p.id)}" data-fingerprint="${esc(p.fingerprint)}"${dismissed ? ' hidden' : ''}>${squareHtml(p)}<div>` +
+    `<div class="f-title"><span>${esc(p.title)}</span><span class="pill kind">${esc(p.kind)}</span>` +
+    `<a class="loc" href="${esc(pointLink(p))}">${esc(pointLocation(p))}</a></div>` +
+    `<div class="prose">${renderMarkdown(p.body, { paths: ctx.paths })}</div>` +
+    `${pointCommandsHtml(p, { postedUrl: posted })}</div></li>`
+  )
+}
+
+/**
+ * The muted line under the overview that holds the points the reader set aside.
+ * @param {ReadonlyArray<Point>} points
+ * @param {PrState} state
+ * @param {{ paths: ReadonlySet<string>, posted?: ReadonlyMap<string, string> }} ctx
+ * @param {boolean} [expanded]
+ */
+export function dismissedListHtml(points, state, ctx, expanded = false) {
+  const dismissed = points.filter(p => state.dismissed[p.fingerprint] !== undefined)
+  if (dismissed.length === 0) {
+    return '<div class="dismissed-list" hidden></div>'
+  }
+  const rows = dismissed
+    .map(p => {
+      const posted = postedFor(p, ctx)
+      return (
+        `<li class="finding" data-point="${esc(p.id)}" data-fingerprint="${esc(p.fingerprint)}">${squareHtml(p)}<div>` +
+        `<div class="f-title"><span>${esc(p.title)}</span><span class="pill kind">${esc(p.kind)}</span>` +
+        `<a class="loc" href="${esc(pointLink(p))}">${esc(pointLocation(p))}</a></div>` +
+        `<div class="prose">${renderMarkdown(p.body, { paths: ctx.paths })}</div>` +
+        `${pointCommandsHtml(p, { dismissed: true, postedUrl: posted })}</div></li>`
+      )
+    })
+    .join('')
+  return (
+    '<div class="dismissed-list">' +
+    `<p class="muted dismissed-line">${dismissed.length} dismissed <button class="cmd" type="button" data-act="show-dismissed" aria-expanded="${expanded}">${expanded ? 'hide' : 'show'}</button></p>` +
+    `<ol class="findings dismissed"${expanded ? '' : ' hidden'}>${rows}</ol></div>`
+  )
+}
+
+/**
+ * Shows the points that are active and hides the ones the reader dismissed, wherever they are
+ * on the page, and rebuilds the dismissed list. Calling it again with the same state changes
+ * nothing.
+ * @param {ParentNode} root
+ * @param {ReadonlyArray<Point>} points
+ * @param {PrState} state
+ * @param {{ paths: ReadonlySet<string>, layers?: ReadonlyArray<Layer>, posted?: ReadonlyMap<string, string> }} ctx
+ */
+export function applyDismissed(root, points, state, ctx) {
+  const byId = new Map(points.map(p => [p.id, p]))
+  for (const el of Array.from(root.querySelectorAll('[data-point]'))) {
+    const point = byId.get(el.getAttribute('data-point') ?? '')
+    if (point === undefined || el.closest('.dismissed-list') !== null) {
+      continue
+    }
+    const dismissed = state.dismissed[point.fingerprint] !== undefined
+    el.toggleAttribute('hidden', dismissed)
+  }
+  for (const counter of Array.from(root.querySelectorAll('.point-count'))) {
+    const layerId = counter.closest('[data-layer]')?.getAttribute('data-layer')
+    const own = points.filter(p => p.layerId === layerId && state.dismissed[p.fingerprint] === undefined)
+    counter.textContent = String(own.length)
+  }
+  const host = root.querySelector('.dismissed-list')
+  if (host !== null) {
+    const expanded = host.querySelector('[data-act="show-dismissed"]')?.getAttribute('aria-expanded') === 'true'
+    const template = document.createElement('template')
+    template.innerHTML = dismissedListHtml(points, state, ctx, expanded)
+    const next = template.content.firstElementChild
+    if (next !== null) {
+      host.replaceWith(next)
+    }
+  }
+  const sevsum = root.querySelector('.sevsum')
+  if (sevsum !== null) {
+    const active = points.filter(p => state.dismissed[p.fingerprint] === undefined)
+    const template = document.createElement('template')
+    template.innerHTML = sevsumHtml(active, ctx.layers ?? [])
+    const next = template.content.firstElementChild
+    if (next !== null) {
+      sevsum.replaceWith(next)
+    }
+  }
+}
+
+/**
+ * The inline row under a diff line.
+ * @param {Point} p
+ * @param {{ paths: ReadonlySet<string>, state?: PrState, posted?: ReadonlyMap<string, string> }} ctx
+ */
+export function pointRowHtml(p, ctx) {
+  const dismissed = ctx.state?.dismissed[p.fingerprint] !== undefined
+  const posted = postedFor(p, ctx)
+  return (
+    `<tr class="ifind ${p.level}" data-point="${esc(p.id)}" data-fingerprint="${esc(p.fingerprint)}"${dismissed ? ' hidden' : ''}><td class="ln" colspan="3"></td><td class="code x">` +
+    `<div class="f-title">${squareHtml(p)}<span>${esc(p.title)}</span><span class="pill kind">${esc(p.kind)}</span></div>` +
+    `<div class="prose">${renderMarkdown(p.body, { paths: ctx.paths })}</div>` +
+    `${pointCommandsHtml(p, { postedUrl: posted })}</td></tr>`
+  )
+}
+
+/**
+ * The three squares with counts in the overview header. Each count links to the first layer that
+ * has a point of that level, so the overview only counts and the layers hold the cards.
+ * @param {ReadonlyArray<Point>} points
+ * @param {ReadonlyArray<Layer>} [layers] artifact order; omitted when there is nothing to link to
+ */
+export function sevsumHtml(points, layers = []) {
+  const by = pointsByLevel(points)
+  const cell = /** @param {'decide' | 'check' | 'fyi'} level */ level => {
+    const n = by[level].length
+    const square = `<span class="sq ${level}" role="img" aria-label="${n} ${level}" title="${n} ${level}"></span>${n}`
+    const target = layers.find(l => by[level].some(p => p.layerId === l.id))
+    return target ? `<a href="#${esc(layerAnchorId(target.key))}">${square}</a>` : `<span>${square}</span>`
+  }
+  return (
+    `<span class="sevsum" tabindex="0" role="group" aria-label="Attention points by level">${cell('decide')}${cell('check')}${cell('fyi')}` +
+    '<span class="legend" aria-hidden="true"><span><span class="sq decide"></span>decide</span><span><span class="sq check"></span>check</span><span><span class="sq fyi"></span>fyi</span></span></span>'
+  )
+}

package/static/js/progress.js

@@ -0,0 +1,49 @@
+// @ts-check
+// Reviewed state per layer. Other changes never count.
+/** @typedef {import('./contract-types.js').Layer} Layer */
+/** @typedef {import('./contract-types.js').PrState} PrState */
+/** @typedef {import('./contract-types.js').ReviewArtifact} ReviewArtifact */
+import { sanitizeKey } from './keys.js'
+
+/**
+ * @param {Layer} layer
+ * @param {PrState} state
+ * @returns {'done' | 'partial' | 'none'}
+ */
+export function layerProgress(layer, state) {
+  if (state.reviewed[`layer:${layer.id}`] === true) {
+    return 'done'
+  }
+  const files = layer.files.length
+  let reviewedFiles = 0
+  for (const f of layer.files) {
+    if (state.reviewed[`layer:${layer.id}/file:${sanitizeKey(f.path)}`] === true) {
+      reviewedFiles++
+    }
+  }
+  if (files > 0 && reviewedFiles === files) {
+    return 'done'
+  }
+  return reviewedFiles > 0 ? 'partial' : 'none'
+}
+
+/**
+ * @param {ReviewArtifact} artifact
+ * @param {PrState} state
+ * @returns {{ done: number, total: number, percent: number }}
+ */
+export function progressSummary(artifact, state) {
+  const layers = artifact.layers.filter(l => l.kind !== 'other')
+  const done = layers.filter(l => layerProgress(l, state) === 'done').length
+  const total = layers.length
+  return { done, total, percent: total === 0 ? 0 : Math.round((done / total) * 100) }
+}
+
+/**
+ * Files reviewed in a layer, for the rail meta ("2 of 3 files").
+ * @param {Layer} layer
+ * @param {PrState} state
+ */
+export function filesReviewed(layer, state) {
+  return layer.files.filter(f => state.reviewed[`layer:${layer.id}/file:${sanitizeKey(f.path)}`] === true).length
+}

package/static/js/proposed-comment.js

@@ -0,0 +1,133 @@
+// @ts-check
+// A ```comment block in an assistant turn is a comment the agent thinks a human should post.
+// It is model output, so every field is checked against the pull request's own files before the
+// card offers to post it; a block that does not check out stays a code block.
+import { splitFences } from './fences.js'
+
+/**
+ * @typedef {{ path: string, line: number, side: 'new' | 'old', startLine?: number, body: string }} ProposedComment
+ */
+
+/**
+ * @typedef {{ type: 'markdown', text: string }
+ *   | { type: 'comment', comment: ProposedComment }
+ *   | { type: 'invalid', text: string, reason: string }} ChatSegment
+ */
+
+/** The comment body a card will show; longer than this is not a review comment. */
+export const PROPOSED_BODY_MAX = 4000
+
+/**
+ * What a target has to satisfy to be postable: the file is in this pull request, and the line is
+ * one the diff shows on that side.
+ * @typedef {{ hasPath: (path: string) => boolean, hasLine: (path: string, side: 'new' | 'old', line: number) => boolean }} CommentTargets
+ */
+
+/**
+ * Reads one block. Returns the comment, or the reason the block is not one.
+ * @param {string} source the text inside the fence
+ * @param {CommentTargets} [targets]
+ * @returns {{ comment: ProposedComment } | { reason: string }}
+ */
+export function parseProposedComment(source, targets) {
+  /** @type {unknown} */
+  let raw
+  try {
+    raw = JSON.parse(source)
+  } catch {
+    return { reason: 'the block is not JSON' }
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { reason: 'the block is not a JSON object' }
+  }
+  const record = /** @type {Record<string, unknown>} */ (raw)
+  const field = /** @param {string} key */ key => record[key]
+  const path = field('path')
+  const line = field('line')
+  const body = field('body')
+  const sideRaw = field('side')
+  const startRaw = field('startLine')
+  if (typeof path !== 'string' || path === '') {
+    return { reason: 'the block has no path' }
+  }
+  if (typeof line !== 'number' || !Number.isInteger(line) || line <= 0) {
+    return { reason: 'the block has no line number' }
+  }
+  if (typeof body !== 'string' || body.trim() === '') {
+    return { reason: 'the block has no body' }
+  }
+  if (body.length > PROPOSED_BODY_MAX) {
+    return { reason: 'the body is too long to post' }
+  }
+  if (sideRaw !== undefined && sideRaw !== 'new' && sideRaw !== 'old') {
+    return { reason: 'side must be "new" or "old"' }
+  }
+  const side = sideRaw === 'old' ? 'old' : 'new'
+  if (startRaw !== undefined && (typeof startRaw !== 'number' || !Number.isInteger(startRaw) || startRaw <= 0)) {
+    return { reason: 'startLine must be a line number' }
+  }
+  const startLine = typeof startRaw === 'number' ? startRaw : undefined
+  if (startLine !== undefined && startLine > line) {
+    return { reason: 'startLine comes after line' }
+  }
+  if (targets !== undefined) {
+    if (!targets.hasPath(path)) {
+      return { reason: `${path} is not a file of this pull request` }
+    }
+    // Both ends of a range have to be on screen, or the comment lands where nobody looked.
+    for (const at of startLine === undefined ? [line] : [startLine, line]) {
+      if (!targets.hasLine(path, side, at)) {
+        return { reason: `${path}:${at} is not a line the diff shows` }
+      }
+    }
+  }
+  /** @type {ProposedComment} */
+  const comment = { path, line, side, body }
+  if (startLine !== undefined) {
+    comment.startLine = startLine
+  }
+  return { comment }
+}
+
+/**
+ * One assistant turn split into what to render: prose, comment cards, and blocks that claimed to
+ * be comments but are not.
+ * @param {string} markdown
+ * @param {CommentTargets} [targets]
+ * @returns {ChatSegment[]}
+ */
+export function splitChatAnswer(markdown, targets) {
+  return splitFences(markdown, 'comment').map(segment => {
+    if (segment.type === 'markdown') {
+      return /** @type {ChatSegment} */ ({ type: 'markdown', text: segment.text })
+    }
+    const parsed = parseProposedComment(segment.text, targets)
+    return 'comment' in parsed
+      ? /** @type {ChatSegment} */ ({ type: 'comment', comment: parsed.comment })
+      : /** @type {ChatSegment} */ ({ type: 'invalid', text: segment.text, reason: parsed.reason })
+  })
+}
+
+/**
+ * The lines a diff shows, as the card's check needs them: every hunk's line numbers per side.
+ * @param {ReadonlyArray<import('./contract-types.js').FileEntry>} files
+ * @returns {CommentTargets}
+ */
+export function targetsFromFiles(files) {
+  const byPath = new Map(files.map(f => [f.path, f]))
+  return {
+    hasPath: path => byPath.has(path),
+    hasLine: (path, side, line) => {
+      const entry = byPath.get(path)
+      if (entry === undefined) {
+        return false
+      }
+      return entry.hunks.some(h => {
+        const start = side === 'new' ? h.newStart : h.oldStart
+        // A hunk that adds lines shows none on the old side, and the other way round.
+        const count = side === 'new' ? h.newLines : h.oldLines
+        return count > 0 && line >= start && line < start + count
+      })
+    },
+  }
+}

package/static/js/quick-questions.js

@@ -0,0 +1,216 @@
+// @ts-check
+// The small menu that opens on an `[ ask ]` command: four questions that are worth asking about
+// almost anything, plus a way to write your own. Picking one sets the context to that target and
+// sends, so the common questions cost one click.
+
+import { QUICK_QUESTIONS } from './chat.js'
+import { chatContextFromElement } from './chat-context.js'
+import { esc, qs } from './dom.js'
+
+/** A menu that opened on the way to a click would be in the way, so it waits. */
+export const HOVER_DELAY_MS = 150
+/** The pointer crosses a gap between the command and the menu, so closing waits out the crossing. */
+export const CLOSE_DELAY_MS = 200
+export const QQ_MENU_ID = 'qq-menu'
+export const ASK_SOMETHING_ELSE = 'ask something else…'
+
+/** @returns {string} */
+export function quickMenuHtml() {
+  const items = [...QUICK_QUESTIONS, ASK_SOMETHING_ELSE]
+    .map(
+      (q, i) => `<button class="qq-item" type="button" role="menuitem" tabindex="-1" data-qq="${i}">${esc(q)}</button>`
+    )
+    .join('')
+  return `<div class="qq-menu" id="${QQ_MENU_ID}" role="menu" aria-label="Quick questions" hidden>${items}</div>`
+}
+
+/**
+ * @typedef {{
+ *   onPick: (context: import('./chat-context.js').ChatContext, question: string | null) => void,
+ *   delayMs?: number,
+ *   doc?: Document,
+ * }} QuickQuestionOptions
+ */
+
+/**
+ * Wires one menu for every `[ ask ]` command under `root` and for the context chip. The menu is
+ * a single element that moves to whichever trigger is in play.
+ * @param {HTMLElement} root
+ * @param {QuickQuestionOptions} options
+ */
+export function wireQuickQuestions(root, options) {
+  const doc = options.doc ?? document
+  const delayMs = options.delayMs ?? HOVER_DELAY_MS
+  if (qs(`#${QQ_MENU_ID}`, root) === null) {
+    root.insertAdjacentHTML('beforeend', quickMenuHtml())
+  }
+  const menu = qs(`#${QQ_MENU_ID}`, root)
+  if (!(menu instanceof HTMLElement)) {
+    return { stop: () => undefined }
+  }
+  /** @type {HTMLElement | null} */
+  let trigger = null
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let closeTimer = null
+  /**
+   * The command Escape closed the menu on. Focus goes back to it, and that focus must not open
+   * the menu again.
+   */
+  /** @type {HTMLElement | null} */
+  let dismissed = null
+
+  const items = () => Array.from(menu.querySelectorAll('.qq-item')).filter(el => el instanceof HTMLElement)
+
+  const close = () => {
+    menu.hidden = true
+    trigger?.setAttribute('aria-expanded', 'false')
+    trigger = null
+  }
+
+  /** @param {HTMLElement} el */
+  const open = el => {
+    dismissed = null
+    trigger = el
+    el.setAttribute('aria-expanded', 'true')
+    menu.hidden = false
+    const rect = el.getBoundingClientRect()
+    menu.style.left = `${Math.round(rect.left)}px`
+    menu.style.top = `${Math.round(rect.bottom + 4)}px`
+  }
+
+  const clearTimer = () => {
+    if (timer !== null) {
+      clearTimeout(timer)
+      timer = null
+    }
+    if (closeTimer !== null) {
+      clearTimeout(closeTimer)
+      closeTimer = null
+    }
+  }
+
+  /** @param {EventTarget | null} target */
+  const triggerOf = target => {
+    const el = target instanceof Element ? target.closest('[data-ask], [data-ask-menu]') : null
+    return el instanceof HTMLElement ? el : null
+  }
+
+  /** @param {Event} event */
+  const onTriggerOver = event => {
+    const el = triggerOf(event.target)
+    if (el === null) {
+      return
+    }
+    // Being back on a command calls off the countdown its own pointer-out started.
+    cancelClose()
+    if (el === trigger) {
+      return
+    }
+    clearTimer()
+    timer = setTimeout(() => open(el), delayMs)
+  }
+
+  /**
+   * Leaving starts a short countdown rather than closing at once: the pointer has to cross the
+   * few pixels between the command and the menu to reach it.
+   * @param {Event} event
+   */
+  const onOut = event => {
+    const to = /** @type {MouseEvent} */ (event).relatedTarget
+    if (to instanceof Node && (menu.contains(to) || trigger?.contains(to) === true)) {
+      return
+    }
+    clearTimer()
+    if (trigger !== null) {
+      closeTimer = setTimeout(close, CLOSE_DELAY_MS)
+    }
+  }
+
+  const cancelClose = () => {
+    if (closeTimer !== null) {
+      clearTimeout(closeTimer)
+      closeTimer = null
+    }
+  }
+
+  /** Reaching the menu calls the countdown off. */
+  const onOver = cancelClose
+
+  /** @param {Event} event */
+  const onFocusIn = event => {
+    const el = triggerOf(event.target)
+    if (el !== null && el === dismissed) {
+      dismissed = null
+      return
+    }
+    if (el !== null && el !== trigger) {
+      clearTimer()
+      open(el)
+    }
+  }
+
+  /** @param {Event} event */
+  const onClick = event => {
+    const item = event.target instanceof Element ? event.target.closest('.qq-item') : null
+    if (!(item instanceof HTMLElement) || trigger === null) {
+      return
+    }
+    event.preventDefault()
+    const index = Number(item.getAttribute('data-qq'))
+    const question = QUICK_QUESTIONS[index] ?? null
+    const context = chatContextFromElement(trigger)
+    close()
+    options.onPick(context, question)
+  }
+
+  /** @param {KeyboardEvent} event */
+  const onKeyDown = event => {
+    if (menu.hidden) {
+      return
+    }
+    const list = items()
+    const at = list.indexOf(/** @type {HTMLElement} */ (doc.activeElement))
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      const back = trigger
+      close()
+      dismissed = back
+      back?.focus()
+      return
+    }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      const step = event.key === 'ArrowDown' ? 1 : -1
+      const next = list[(at + step + list.length) % list.length] ?? list[0]
+      next?.focus()
+    }
+  }
+
+  root.addEventListener('pointerover', onTriggerOver)
+  root.addEventListener('pointerout', onOut)
+  menu.addEventListener('pointerover', onOver)
+  root.addEventListener('focusin', onFocusIn)
+  menu.addEventListener('click', onClick)
+  doc.addEventListener('keydown', /** @type {EventListener} */ (onKeyDown))
+
+  return {
+    /** Opens the menu on a target without waiting, which is what a tap and the `a` key do. */
+    openFor(/** @type {HTMLElement} */ el) {
+      clearTimer()
+      open(el)
+      items()[0]?.focus()
+    },
+    isOpen: () => !menu.hidden,
+    stop() {
+      clearTimer()
+      root.removeEventListener('pointerover', onTriggerOver)
+      root.removeEventListener('pointerout', onOut)
+      menu.removeEventListener('pointerover', onOver)
+      root.removeEventListener('focusin', onFocusIn)
+      menu.removeEventListener('click', onClick)
+      doc.removeEventListener('keydown', /** @type {EventListener} */ (onKeyDown))
+    },
+  }
+}