@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/static/js/pending.js

@@ -0,0 +1,161 @@
+// @ts-check
+// The pending review: the comments the reviewer has written and not submitted yet. They live in
+// the local state, are drawn on the diff with a "pending" badge, and are counted in a bar that
+// stays on screen for as long as any of them is waiting.
+/** @typedef {import('./contract-types.js').PendingComment} PendingComment */
+/** @typedef {import('./contract-types.js').PrState} PrState */
+/** @typedef {import('./contract-types.js').Side} Side */
+import { esc, timeAgo } from './dom.js'
+import { hostLabel } from './host.js'
+import { renderMarkdown } from './markdown.js'
+
+export const PENDING_BAR_ID = 'pending-bar'
+
+/**
+ * The drafts of one target, oldest first. A state written by an older tool version has no list
+ * at all, which reads as none waiting.
+ * @param {PrState | null | undefined} state
+ * @returns {ReadonlyArray<PendingComment>}
+ */
+export function pendingComments(state) {
+  return state?.pending ?? []
+}
+
+/**
+ * @param {PrState | null | undefined} state
+ * @returns {number}
+ */
+export function pendingCount(state) {
+  return pendingComments(state).length
+}
+
+/**
+ * The drafts anchored to one file, by the diff key the rows carry.
+ * @param {PrState | null | undefined} state
+ * @param {string} path
+ * @returns {ReadonlyArray<PendingComment>}
+ */
+export function pendingForPath(state, path) {
+  return pendingComments(state).filter(p => p.path === path)
+}
+
+/**
+ * The draft an attention point was added to the review as, when it was. A point is queued at most
+ * once: its fingerprint is what ties the two together.
+ * @param {PrState | null | undefined} state
+ * @param {string} fingerprint
+ * @returns {PendingComment | undefined}
+ */
+export function pendingForPoint(state, fingerprint) {
+  return pendingComments(state).find(p => p.pointFingerprint === fingerprint)
+}
+
+/** @param {number} count */
+export function pendingLabel(count) {
+  return count === 1 ? '1 pending comment' : `${count} pending comments`
+}
+
+/**
+ * Where a draft sits, said the way the selection toolbar says it.
+ * @param {PendingComment} p
+ */
+export function pendingRange(p) {
+  const range = p.startLine !== undefined && p.startLine !== p.line ? `${p.startLine}–${p.line}` : `${p.line}`
+  return `${p.path}:${range}${p.side === 'old' ? ' (old)' : ''}`
+}
+
+/**
+ * One draft as it is drawn under the line it comments on: the body, when it was written, and the
+ * commands that edit or drop it. The badge is what tells the reviewer it is not on the forge yet.
+ * @param {PendingComment} p
+ * @param {Date} now
+ */
+export function pendingCommentHtml(p, now) {
+  // The same two-column shape a posted comment has, so drafts and comments line up on the diff:
+  // the marker takes the avatar's place, and the commands span both columns under them.
+  return (
+    `<div class="cmt pending-cmt" data-pending-id="${esc(p.id)}">` +
+    '<span class="av pending-av" aria-hidden="true">&hellip;</span>' +
+    `<span class="who"><span class="pill pending">pending</span> ` +
+    `<span class="muted">${esc(timeAgo(p.createdAt, now))} · not posted to ${esc(hostLabel())} yet</span></span>` +
+    `<div class="prose">${renderMarkdown(p.body, { github: true })}</div>` +
+    '<span class="tbtns">' +
+    `<button class="cmd" type="button" data-act="pending-edit" data-pending-id="${esc(p.id)}">edit</button>` +
+    `<button class="cmd" type="button" data-act="pending-delete" data-pending-id="${esc(p.id)}">delete</button>` +
+    '</span></div>'
+  )
+}
+
+/**
+ * The row the draft is drawn in, so it can sit under its line in the diff table.
+ * @param {ReadonlyArray<PendingComment>} drafts the drafts anchored to one line
+ * @param {Date} now
+ */
+export function pendingRowHtml(drafts, now) {
+  return (
+    '<tr class="pending-row"><td class="code x" colspan="4">' +
+    drafts.map(p => pendingCommentHtml(p, now)).join('') +
+    '</td></tr>'
+  )
+}
+
+/**
+ * The bar that says a review is being written. It is drawn only while something is waiting, and
+ * carries the two ways out: submit the review, or throw the drafts away.
+ * @param {number} count
+ * @param {ReadonlyArray<PendingComment>} [earlier]
+ */
+export function pendingBarHtml(count, earlier = []) {
+  if (count === 0) {
+    return ''
+  }
+  return (
+    `<div class="pending-bar" id="${PENDING_BAR_ID}" role="status">` +
+    `<span class="pending-mark" aria-hidden="true"></span>` +
+    `<span class="pending-text"><b>${esc(pendingLabel(count))}</b> waiting in your review. ` +
+    `Nothing is on ${esc(hostLabel())} until you submit it.</span>` +
+    '<span class="pending-actions">' +
+    '<button class="cmd fill" type="button" data-act="pending-finish" data-needs-post>finish your review</button>' +
+    '<button class="cmd" type="button" data-act="pending-discard">discard</button>' +
+    '</span></div>' +
+    (earlier.length === 0
+      ? ''
+      : '<details class="earlier-pending"><summary>Comments written on earlier commits</summary>' +
+        '<p>These drafts are kept at their original locations. They can be submitted only if the diff is unchanged. Otherwise copy the text, delete the draft, and comment on the current code.</p>' +
+        earlier
+          .map(
+            p =>
+              `<div class="earlier-draft"><p>${esc(pendingRange(p))} · commit ${esc(p.headSha.slice(0, 7))}</p>` +
+              `<div class="prose">${renderMarkdown(p.body, { github: true })}</div>` +
+              `<button class="cmd" type="button" data-copy="${esc(p.body)}">copy</button>` +
+              `<button class="cmd" type="button" data-act="pending-delete" data-pending-id="${esc(p.id)}">delete</button></div>`
+          )
+          .join('') +
+        '</details>')
+  )
+}
+
+/**
+ * Draws the bar from the current state, adding it when the first draft appears and taking it away
+ * with the last one. The host element is where the bar lives; it is emptied when nothing waits.
+ * @param {ParentNode} root
+ * @param {PrState} state
+ * @param {string} [headSha]
+ * @returns {number} how many drafts are waiting
+ */
+export function refreshPendingBar(root, state, headSha) {
+  const count = pendingCount(state)
+  const host = root.querySelector('.pending-bar-host')
+  if (host !== null) {
+    const earlier = headSha === undefined ? [] : state.pending.filter(p => p.headSha !== headSha)
+    const signature = JSON.stringify([count, earlier])
+    if (host.getAttribute('data-pending-state') !== signature) {
+      const open = host.querySelector('details')?.open ?? false
+      host.innerHTML = pendingBarHtml(count, earlier)
+      host.setAttribute('data-pending-state', signature)
+      if (open) host.querySelector('details')?.setAttribute('open', '')
+    }
+    host.classList.toggle('has-pending', count > 0)
+  }
+  return count
+}

package/static/js/points.js

@@ -5,6 +5,8 @@
 import { askButtonHtml } from './ask.js'
 import { viewCommentHtml } from './comment-link.js'
 import { esc } from './dom.js'
+import { pendingForPoint } from './pending.js'
+import { postToLabel } from './host.js'
 import { layerAnchorId, pointAnchorId } from './keys.js'
 import { renderMarkdown } from './markdown.js'
 
@@ -64,11 +66,33 @@ export function pointContext(p) {
   return { kind: 'point', fingerprint: p.fingerprint }
 }
 
+/**
+ * What a point offers for getting its text onto the forge: the link to the comment it was posted
+ * as, the note that it is waiting in the review, or the two ways to send it. Unlike the box on a
+ * diff line, a point keeps both ways while a review is open: its text is written in advance, so
+ * firing one off on its own is a use of its own, not a comment jumping the queue.
+ * @param {Point} p
+ * @param {{ postedUrl?: string | undefined, queued?: boolean }} opts
+ */
+function pointSendHtml(p, opts) {
+  if (opts.postedUrl !== undefined) {
+    return viewCommentHtml(opts.postedUrl)
+  }
+  if (opts.queued === true) {
+    return '<span class="pill pending queued">in your review</span>'
+  }
+  return (
+    `<button class="cmd" type="button" data-act="point-post" data-point="${esc(p.id)}" data-needs-post>${postToLabel()}</button>` +
+    `<button class="cmd" type="button" data-act="point-queue" data-point="${esc(p.id)}">add to review</button>`
+  )
+}
+
 /**
  * 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.
+ * opens nothing and posts it at the anchor, `add to review` holds it as a draft instead, and
+ * `dismiss` takes the point off the page.
  * @param {Point} p
- * @param {{ dismissed?: boolean, postedUrl?: string | undefined }} [opts]
+ * @param {{ dismissed?: boolean, postedUrl?: string | undefined, queued?: boolean }} [opts]
  * @returns {string}
  */
 export function pointCommandsHtml(p, opts = {}) {
@@ -77,17 +101,24 @@ export function pointCommandsHtml(p, opts = {}) {
     ? `<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">' +
+    `<span class="tbtns" data-queued="${opts.queued === true ? '1' : '0'}">` +
     `<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)) +
+    pointSendHtml(p, opts) +
     askButtonHtml(pointContext(p)) +
     toggle +
     '</span>'
   )
 }
 
+/**
+ * Whether this point is waiting in the review, read from the state the renderer was given.
+ * @param {Point} p
+ * @param {{ state?: PrState }} ctx
+ */
+export function queuedFor(p, ctx) {
+  return pendingForPoint(ctx.state, p.fingerprint) !== undefined
+}
+
 /**
  * The comment this point was posted as, when it was.
  * @param {Point} p
@@ -129,7 +160,7 @@ export function pointCardHtml(p, ctx) {
     `<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>`
+    `${pointCommandsHtml(p, { postedUrl: posted, queued: queuedFor(p, ctx) })}</div></li>`
   )
 }
 
@@ -153,7 +184,7 @@ export function dismissedListHtml(points, state, ctx, expanded = false) {
         `<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>`
+        `${pointCommandsHtml(p, { dismissed: true, postedUrl: posted, queued: queuedFor(p, { state }) })}</div></li>`
       )
     })
     .join('')
@@ -182,6 +213,7 @@ export function applyDismissed(root, points, state, ctx) {
     }
     const dismissed = state.dismissed[point.fingerprint] !== undefined
     el.toggleAttribute('hidden', dismissed)
+    refreshPointCommands(el, point, { dismissed, state, ...ctx })
   }
   for (const counter of Array.from(root.querySelectorAll('.point-count'))) {
     const layerId = counter.closest('[data-layer]')?.getAttribute('data-layer')
@@ -211,6 +243,35 @@ export function applyDismissed(root, points, state, ctx) {
   }
 }
 
+/**
+ * Draws a point's commands again when it has just joined the review or just left it, wherever the
+ * point is on the page. Nothing else is touched: a command that is mid-request keeps its state,
+ * because neither posting nor dismissing changes whether the point is waiting in the review.
+ * @param {Element} el the element that carries `data-point`
+ * @param {Point} p
+ * @param {{ dismissed: boolean, state: PrState, posted?: ReadonlyMap<string, string> }} ctx
+ * @returns {boolean} true when the commands were drawn again
+ */
+export function refreshPointCommands(el, p, ctx) {
+  const tbtns = el.querySelector('.tbtns')
+  const queued = queuedFor(p, ctx)
+  if (tbtns === null || (tbtns.getAttribute('data-queued') === '1') === queued) {
+    return false
+  }
+  const template = document.createElement('template')
+  template.innerHTML = pointCommandsHtml(p, {
+    dismissed: ctx.dismissed,
+    queued,
+    ...(postedFor(p, ctx) === undefined ? {} : { postedUrl: postedFor(p, ctx) }),
+  })
+  const next = template.content.firstElementChild
+  if (next === null) {
+    return false
+  }
+  tbtns.replaceWith(next)
+  return true
+}
+
 /**
  * The inline row under a diff line.
  * @param {Point} p
@@ -223,7 +284,7 @@ export function pointRowHtml(p, ctx) {
     `<tr class="ifind ${p.level}" data-point="${esc(p.id)}" data-fingerprint="${esc(p.fingerprint)}"${dismissed ? ' hidden' : ''}><td class="code x" colspan="4">` +
     `<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>`
+    `${pointCommandsHtml(p, { postedUrl: posted, queued: queuedFor(p, ctx) })}</td></tr>`
   )
 }
 

package/static/js/progress.js

@@ -3,7 +3,7 @@
 /** @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'
+import { reviewedId } from './keys.js'
 
 /**
  * @param {Layer} layer
@@ -11,13 +11,13 @@ import { sanitizeKey } from './keys.js'
  * @returns {'done' | 'partial' | 'none'}
  */
 export function layerProgress(layer, state) {
-  if (state.reviewed[`layer:${layer.id}`] === true) {
+  if (state.reviewed[reviewedId(layer.key)] === 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) {
+    if (state.reviewed[reviewedId(layer.key, f.path)] === true) {
       reviewedFiles++
     }
   }
@@ -45,6 +45,5 @@ export function progressSummary(artifact, state) {
  * @param {PrState} state
  */
 export function filesReviewed(layer, state) {
-  return layer.files.filter(f => state.reviewed[`layer:${layer.id}/file:${sanitizeKey(f.path)}`] === true)
-    .length
+  return layer.files.filter(f => state.reviewed[reviewedId(layer.key, f.path)] === true).length
 }

package/static/js/quick-questions.js

@@ -12,6 +12,9 @@ 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'
+/** The gap between a command and its menu, and the room the menu keeps from the window edge. */
+export const MENU_GAP_PX = 4
+export const MENU_EDGE_PX = 8
 export const ASK_SOMETHING_ELSE = 'ask something else…'
 
 /** @returns {string} */
@@ -77,8 +80,18 @@ export function wireQuickQuestions(root, options) {
     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`
+    // The menu is positioned against the window, so a command near an edge would push it off
+    // screen: keep it inside, and hang it above a command with no room below.
+    const view = doc.defaultView ?? window
+    // `clientWidth` leaves out the scrollbar; a document that does not report it falls back.
+    const roomAcross = doc.documentElement.clientWidth || view.innerWidth
+    const roomDown = doc.documentElement.clientHeight || view.innerHeight
+    const below = rect.bottom + MENU_GAP_PX
+    const top =
+      below + menu.offsetHeight > roomDown - MENU_EDGE_PX ? rect.top - MENU_GAP_PX - menu.offsetHeight : below
+    const left = Math.min(rect.left, roomAcross - menu.offsetWidth - MENU_EDGE_PX)
+    menu.style.left = `${Math.round(Math.max(MENU_EDGE_PX, left))}px`
+    menu.style.top = `${Math.round(Math.max(MENU_EDGE_PX, top))}px`
   }
 
   const clearTimer = () => {

package/static/js/reading-level.js

@@ -0,0 +1,97 @@
+// @ts-check
+// The reader's control over how much code the canvas hides: the copy that says what each level
+// takes off the screen, the control under the header, and the labels that say how much of the
+// diff that is. The level itself, and the counts, belong to layers.js, which owns the file cards
+// and the rule for what a card keeps open.
+import { esc } from './dom.js'
+import { FOLD_LEVELS } from './fold-levels.js'
+
+/** @typedef {import('./contract-types.js').FoldLevel} FoldLevel */
+/** @typedef {{ total: number, hidden: number }} HiddenCounts */
+
+export const FOLD_LEVEL_SELECT_ID = 'fold-level'
+
+/** What each level adds to the one below it, said in the reader's terms. */
+const FOLD_LEVEL_WHAT = {
+  light: 'the diff as always: imports, whitespace, moved blocks, and generated files',
+  moderate: 'also test bodies, helpers, wiring, templates, and boilerplate',
+  aggressive: 'only the code you have to judge stays open',
+}
+
+/**
+ * What the counter says, or '' when this level hides nothing.
+ * @param {HiddenCounts} counts
+ * @returns {string}
+ */
+export function hiddenLabel(counts) {
+  return counts.hidden === 0 ? '' : `${counts.hidden} of ${counts.total} lines hidden`
+}
+
+/**
+ * The same with the separator the Files heading needs, so an empty counter adds nothing.
+ * @param {HiddenCounts} counts
+ * @returns {string}
+ */
+export function foldCountText(counts) {
+  const label = hiddenLabel(counts)
+  return label === '' ? '' : ` · ${label}`
+}
+
+/**
+ * The line under the control: what this level hides, and how much of the diff that is. The reader
+ * changes one setting, so the page says what it did rather than leaving them to scroll and find out.
+ * @param {FoldLevel} level
+ * @param {HiddenCounts} counts what the level hides across the canvas
+ * @returns {string}
+ */
+export function foldLevelHint(level, counts) {
+  const amount = counts.hidden === 0 ? 'nothing hidden yet' : `${hiddenLabel(counts)} of the diff`
+  return `${FOLD_LEVEL_WHAT[level]} · ${amount}`
+}
+
+/**
+ * The levels as options, with one selected. The control on the page and the default field of the
+ * settings dialog are the same list.
+ * @param {FoldLevel} level
+ * @returns {string}
+ */
+export function foldLevelOptionsHtml(level) {
+  return FOLD_LEVELS.map(
+    l => `<option value="${esc(l)}"${l === level ? ' selected' : ''}>${esc(l)}</option>`
+  ).join('')
+}
+
+/**
+ * How much of the diff the page hides. One control for the whole canvas, next to the review
+ * progress rather than among the commands, because it changes what the reader sees and does not
+ * act on the pull request. The page opens at the level saved in the settings dialog; a change
+ * here holds for this page only.
+ * @param {FoldLevel} level
+ * @param {HiddenCounts} counts what the level hides across the canvas
+ * @returns {string}
+ */
+export function foldLevelControlHtml(level, counts) {
+  const options = foldLevelOptionsHtml(level)
+  return (
+    `<div class="reading"><label for="${FOLD_LEVEL_SELECT_ID}">Hide code</label>` +
+    `<select id="${FOLD_LEVEL_SELECT_ID}" title="How much of the diff this page hides. Press f to step through the levels; the settings dialog sets the default.">${options}</select>` +
+    `<span class="fold-hint" role="status">${esc(foldLevelHint(level, counts))}</span></div>`
+  )
+}
+
+/**
+ * Points the control and its hint at a level the reader chose elsewhere, such as with the `f` key.
+ * @param {ParentNode} root
+ * @param {FoldLevel} level
+ * @param {HiddenCounts} counts what the level hides across the canvas
+ */
+export function refreshFoldLevel(root, level, counts) {
+  const select = root.querySelector(`#${FOLD_LEVEL_SELECT_ID}`)
+  if (select instanceof HTMLSelectElement) {
+    select.value = level
+  }
+  const hint = root.querySelector('.reading .fold-hint')
+  if (hint !== null) {
+    hint.textContent = foldLevelHint(level, counts)
+  }
+}

package/static/js/review-session.js

@@ -9,8 +9,18 @@
 /** @typedef {import('./contract-types.js').PrState} PrState */
 /** @typedef {import('./contract-types.js').ReviewArtifact} ReviewArtifact */
 /** @typedef {import('./contract-types.js').ReviewSummary} ReviewSummary */
-import { postComment, postReview, putDismissed, putReviewed, putThreadHidden } from './api.js'
-import { sanitizeKey } from './keys.js'
+/** @typedef {import('./contract-types.js').ReviewComment} ReviewComment */
+import {
+  addPending,
+  deletePending,
+  discardPending,
+  editPending,
+  postComment,
+  postReview,
+  putDismissed,
+  putReviewed,
+  putThreadHidden,
+} from './api.js'
 
 /**
  * @typedef {{
@@ -19,17 +29,22 @@ import { sanitizeKey } from './keys.js'
  *   putThreadHidden: typeof putThreadHidden,
  *   postComment: typeof postComment,
  *   postReview: typeof postReview,
+ *   addPending: typeof addPending,
+ *   editPending: typeof editPending,
+ *   deletePending: typeof deletePending,
+ *   discardPending: typeof discardPending,
  * }} SessionApi
  */
 
 /**
  * @typedef {{
- *   prNumber: number,
+ *   prNumber: import('./contract-types.js').ReviewKey,
  *   artifact: ReviewArtifact,
  *   files: ReadonlyArray<FileEntry>,
  *   state: PrState,
  *   capabilities: Capabilities,
  *   headSha: string,
+ *   canvasSha?: string,
  *   api?: Partial<SessionApi>,
  *   onState?: (state: PrState) => void,
  * }} SessionOptions
@@ -37,22 +52,29 @@ import { sanitizeKey } from './keys.js'
 
 /** @param {Partial<SessionApi> | undefined} overrides */
 function withDefaults(overrides) {
-  return { putReviewed, putDismissed, putThreadHidden, postComment, postReview, ...overrides }
+  return {
+    putReviewed,
+    putDismissed,
+    putThreadHidden,
+    postComment,
+    postReview,
+    addPending,
+    editPending,
+    deletePending,
+    discardPending,
+    ...overrides,
+  }
 }
 
-/**
- * @param {string} layerId
- * @param {string} [path]
- */
-export function reviewedId(layerId, path) {
-  return path === undefined ? `layer:${layerId}` : `layer:${layerId}/file:${sanitizeKey(path)}`
-}
+export { reviewedId } from './keys.js'
 
 /** @param {SessionOptions} options */
 export function createReviewSession(options) {
   const api = withDefaults(options.api)
   /** @type {PrState} */
   let state = options.state
+  /** @type {ReviewComment[]} */
+  let submittedComments = []
   /** @type {Capabilities} */
   let capabilities = options.capabilities
   const keyToPath = new Map(options.files.map(f => [f.key, f.path]))
@@ -130,6 +152,28 @@ export function createReviewSession(options) {
     }
   }
 
+  /**
+   * A change the server owns outright: the answer it sends is the new state. Unlike `change`
+   * there is nothing to show first and nothing to take back, because the page never guessed.
+   * @template {{ state: PrState }} T
+   * @param {() => Promise<T>} request
+   * @returns {Promise<T>}
+   */
+  const run = async request => {
+    inFlight += 1
+    try {
+      const answer = await request()
+      inFlight -= 1
+      takeAnswer(answer.state)
+      settle()
+      return answer
+    } catch (err) {
+      inFlight -= 1
+      settle()
+      throw err
+    }
+  }
+
   /**
    * @param {PrState} current
    * @param {'reviewed' | 'dismissed' | 'hiddenThreads'} field
@@ -193,7 +237,11 @@ export function createReviewSession(options) {
       return change(
         current => withEntry(current, 'reviewed', id, reviewed ? true : undefined),
         current => withEntry(current, 'reviewed', id, before),
-        () => api.putReviewed(options.prNumber, id, reviewed, { headSha: options.headSha })
+        () =>
+          api.putReviewed(options.prNumber, id, reviewed, {
+            headSha: options.headSha,
+            ...(options.canvasSha === undefined ? {} : { canvasSha: options.canvasSha }),
+          })
       )
     },
     /**
@@ -229,27 +277,63 @@ export function createReviewSession(options) {
      * @returns {Promise<PostCommentResponse>}
      */
     async postComment(input) {
-      inFlight += 1
-      try {
-        const answer = await api.postComment(options.prNumber, { ...input, headSha: options.headSha })
-        inFlight -= 1
-        takeAnswer(answer.state)
-        settle()
-        return answer
-      } catch (err) {
-        inFlight -= 1
-        settle()
-        throw err
-      }
+      return run(() => api.postComment(options.prNumber, { ...input, headSha: options.headSha }))
+    },
+    /** Comments returned by reviews submitted during this session. */
+    get submittedComments() {
+      return submittedComments
+    },
+    /** The comments waiting in the pending review, oldest first. */
+    get pending() {
+      return state.pending ?? []
     },
     /**
-     * @param {'APPROVE' | 'REQUEST_CHANGES'} event
+     * Writes one comment into the pending review. The answer carries the state that holds it, so
+     * the page draws the draft from the same place a reload would read it from.
+     * @param {Omit<import('./contract-types.js').AddPendingInput, 'headSha'>} input
+     * @returns {Promise<PrState>}
+     */
+    async addPending(input) {
+      return (await run(() => api.addPending(options.prNumber, { ...input, headSha: options.headSha }))).state
+    },
+    /**
+     * @param {string} id
+     * @param {string} body
+     * @returns {Promise<PrState>}
+     */
+    async editPending(id, body) {
+      return (await run(() => api.editPending(options.prNumber, id, body))).state
+    },
+    /**
+     * @param {string} id
+     * @returns {Promise<PrState>}
+     */
+    async deletePending(id) {
+      return (await run(() => api.deletePending(options.prNumber, id))).state
+    },
+    /** @returns {Promise<PrState>} */
+    async discardPending() {
+      return (await run(() => api.discardPending(options.prNumber))).state
+    },
+    /**
+     * Submits the review. The pending comments go out with it unless the caller says otherwise,
+     * and the answer's state is the one with them cleared.
+     * @param {import('./contract-types.js').ReviewEvent} event
      * @param {string} [body]
-     * @returns {Promise<ReviewSummary>}
+     * @param {{ includePending?: boolean }} [opts]
+     * @returns {Promise<import('./contract-types.js').PostReviewResponse>}
      */
-    async postReview(event, body) {
-      const input = body === undefined ? { event } : { event, body }
-      return (await api.postReview(options.prNumber, { ...input, headSha: options.headSha })).review
+    async postReview(event, body, opts = {}) {
+      const input = {
+        event,
+        ...(body === undefined ? {} : { body }),
+        ...(opts.includePending === undefined ? {} : { includePending: opts.includePending }),
+      }
+      return run(async () => {
+        const answer = await api.postReview(options.prNumber, { ...input, headSha: options.headSha })
+        submittedComments = [...submittedComments, ...answer.comments]
+        return answer
+      })
     },
   }
 }