@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/src/store/state-store.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import type { ReviewKey } from '../contract/review-key.js'
 import { emptyState, type PrState, PrStateSchema } from '../contract/state.js'
 import { readJsonOrDefault, writeJsonAtomic } from './atomic-json.js'
 import type { PrStore } from './pr-store.js'
@@ -9,23 +10,24 @@ export interface PostedEntry {
   pointFingerprint?: string
 }
 
-/** Per-PR local state: reviewed cards, dismissed points, hidden threads, posted comments. */
+/** Per-target local state: reviewed cards, dismissed points, hidden threads, posted comments. */
 export interface StateStore {
   /** Defaults when the file is missing or does not match the schema (an older tool version wrote it). */
-  read(number: number): Promise<PrState>
+  read(key: ReviewKey): Promise<PrState>
   /**
-   * Read, change, write. Calls for the same PR run one after another, so two requests that
+   * Read, change, write. Calls for the same target run one after another, so two requests that
    * arrive together both land instead of one overwriting the other.
    */
-  update(number: number, mutate: (state: PrState) => PrState): Promise<PrState>
+  update(key: ReviewKey, mutate: (state: PrState) => PrState): Promise<PrState>
   /**
-   * Marks one layer or file. `headSha` is the commit the page was showing: when it differs from
-   * the one the marks describe, the old marks are dropped, because they were about other code.
+   * Marks one layer or file. `canvasSha` is the commit of the canvas the page was showing: when it
+   * differs from the one the marks describe, the old marks are dropped, because they were about
+   * other code.
    */
-  setReviewed(number: number, id: string, reviewed: boolean, headSha?: string): Promise<PrState>
-  setDismissed(number: number, fingerprint: string, dismissed: boolean, reason?: string): Promise<PrState>
-  setThreadHidden(number: number, rootCommentId: number, hidden: boolean): Promise<PrState>
-  addPosted(number: number, entry: PostedEntry): Promise<PrState>
+  setReviewed(key: ReviewKey, id: string, reviewed: boolean, canvasSha?: string): Promise<PrState>
+  setDismissed(key: ReviewKey, fingerprint: string, dismissed: boolean, reason?: string): Promise<PrState>
+  setThreadHidden(key: ReviewKey, rootCommentId: number, hidden: boolean): Promise<PrState>
+  addPosted(key: ReviewKey, entry: PostedEntry): Promise<PrState>
 }
 
 /** `layer:<id>` or `layer:<id>/file:<key>`, with the ids and keys the artifact uses. */
@@ -42,25 +44,25 @@ function layerOf(id: string): string {
 }
 
 export function createStateStore(prs: PrStore, now: () => Date): StateStore {
-  const file = (number: number): string => path.join(prs.prDir(number), 'state.json')
-  const read = (number: number): Promise<PrState> =>
-    readJsonOrDefault(file(number), PrStateSchema, () => emptyState(now().toISOString()))
+  const file = (key: ReviewKey): string => path.join(prs.prDir(key), 'state.json')
+  const read = (key: ReviewKey): Promise<PrState> =>
+    readJsonOrDefault(file(key), PrStateSchema, () => emptyState(now().toISOString()))
 
-  /** One chain per PR number; each update waits for the one before it. */
-  const chains = new Map<number, Promise<unknown>>()
+  /** One chain per target; each update waits for the one before it. */
+  const chains = new Map<ReviewKey, Promise<unknown>>()
 
-  const update = (number: number, mutate: (state: PrState) => PrState): Promise<PrState> => {
+  const update = (key: ReviewKey, mutate: (state: PrState) => PrState): Promise<PrState> => {
     const run = async (): Promise<PrState> => {
-      const current = await read(number)
+      const current = await read(key)
       // Every write counts up, so the page can tell which of two answers was written later.
       const next = { ...mutate(current), rev: (current.rev ?? 0) + 1, updatedAt: now().toISOString() }
-      await writeJsonAtomic(file(number), next)
+      await writeJsonAtomic(file(key), next)
       return next
     }
-    const chained = (chains.get(number) ?? Promise.resolve()).then(run, run)
+    const chained = (chains.get(key) ?? Promise.resolve()).then(run, run)
     // The chain only orders the calls, so a failed update never blocks the next one.
     chains.set(
-      number,
+      key,
       chained.catch(() => undefined)
     )
     return chained
@@ -69,28 +71,30 @@ export function createStateStore(prs: PrStore, now: () => Date): StateStore {
   return {
     read,
     update,
-    setReviewed: (number, id, reviewed, headSha) =>
-      update(number, state => {
-        const sameHead =
-          headSha === undefined || state.reviewedHeadSha === undefined || state.reviewedHeadSha === headSha
-        const next = sameHead ? { ...state.reviewed } : {}
+    setReviewed: (key, id, reviewed, canvasSha) =>
+      update(key, state => {
+        const sameCanvas =
+          canvasSha === undefined ||
+          state.reviewedCanvasSha === undefined ||
+          state.reviewedCanvasSha === canvasSha
+        const next = sameCanvas ? { ...state.reviewed } : {}
         if (reviewed) {
           next[id] = true
         } else {
-          for (const key of Object.keys(next)) {
+          for (const marked of Object.keys(next)) {
             // Reopening a layer reopens its files, and reopening a file reopens its layer:
             // both readings of "reviewed" have to agree.
-            if (key === id || key.startsWith(`${id}/`) || key === layerOf(id)) {
-              delete next[key]
+            if (marked === id || marked.startsWith(`${id}/`) || marked === layerOf(id)) {
+              delete next[marked]
             }
           }
         }
-        return headSha === undefined
+        return canvasSha === undefined
           ? { ...state, reviewed: next }
-          : { ...state, reviewed: next, reviewedHeadSha: headSha }
+          : { ...state, reviewed: next, reviewedCanvasSha: canvasSha }
       }),
-    setDismissed: (number, fingerprint, dismissed, reason) =>
-      update(number, state => {
+    setDismissed: (key, fingerprint, dismissed, reason) =>
+      update(key, state => {
         const next = { ...state.dismissed }
         if (dismissed) {
           next[fingerprint] =
@@ -100,8 +104,8 @@ export function createStateStore(prs: PrStore, now: () => Date): StateStore {
         }
         return { ...state, dismissed: next }
       }),
-    setThreadHidden: (number, rootCommentId, hidden) =>
-      update(number, state => {
+    setThreadHidden: (key, rootCommentId, hidden) =>
+      update(key, state => {
         const next = { ...state.hiddenThreads }
         if (hidden) {
           next[String(rootCommentId)] = { at: now().toISOString() }
@@ -110,8 +114,8 @@ export function createStateStore(prs: PrStore, now: () => Date): StateStore {
         }
         return { ...state, hiddenThreads: next }
       }),
-    addPosted: (number, entry) =>
-      update(number, state => {
+    addPosted: (key, entry) =>
+      update(key, state => {
         if (state.posted.some(p => p.commentId === entry.commentId)) {
           return state
         }

package/static/js/api.js

@@ -1,5 +1,6 @@
 // @ts-check
 /** @typedef {import('./contract-types.js').ErrorEnvelope} ErrorEnvelope */
+/** @typedef {import('./contract-types.js').ReviewKey} ReviewKey */
 /** @typedef {import('./contract-types.js').PrBundle} PrBundle */
 /** @typedef {import('./contract-types.js').PatchesResponse} PatchesResponse */
 
@@ -69,17 +70,20 @@ export async function fetchJson(url, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
- * @param {{ refresh?: boolean, fetchImpl?: typeof fetch | undefined }} [opts]
+ * The bundle for one target. `refresh` asks the server to read the forge, or the working tree,
+ * again; `poll` says this is the background poller, which is answered from the head the page was
+ * opened with rather than by snapshotting the working tree every few seconds.
+ * @param {ReviewKey} prNumber
+ * @param {{ refresh?: boolean, poll?: boolean, fetchImpl?: typeof fetch | undefined }} [opts]
  * @returns {Promise<PrBundle>}
  */
 export function fetchBundle(prNumber, opts = {}) {
-  const q = opts.refresh ? '?refresh=1' : ''
+  const q = opts.refresh ? '?refresh=1' : opts.poll ? '?poll=1' : ''
   return fetchJson(`/api/prs/${prNumber}${q}`, { fetchImpl: opts.fetchImpl })
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ headSha?: string, fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<PatchesResponse>}
  */
@@ -89,7 +93,7 @@ export function fetchPatches(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').StateResponse>}
  */
@@ -98,14 +102,18 @@ export function fetchState(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {string} id `layer:<id>` or `layer:<id>/file:<key>`
  * @param {boolean} reviewed
- * @param {{ headSha?: string, fetchImpl?: typeof fetch }} [opts]
+ * @param {{ headSha?: string, canvasSha?: string, fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').StateResponse>}
  */
 export function putReviewed(prNumber, id, reviewed, opts = {}) {
-  const body = opts.headSha === undefined ? { reviewed } : { reviewed, headSha: opts.headSha }
+  const body = {
+    reviewed,
+    ...(opts.headSha === undefined ? {} : { headSha: opts.headSha }),
+    ...(opts.canvasSha === undefined ? {} : { canvasSha: opts.canvasSha }),
+  }
   return fetchJson(`/api/prs/${prNumber}/reviewed/${id}`, {
     method: 'PUT',
     body,
@@ -114,7 +122,7 @@ export function putReviewed(prNumber, id, reviewed, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {string} fingerprint
  * @param {boolean} dismissed
  * @param {{ reason?: string, fetchImpl?: typeof fetch }} [opts]
@@ -130,7 +138,7 @@ export function putDismissed(prNumber, fingerprint, dismissed, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {number} rootCommentId
  * @param {boolean} hidden
  * @param {{ fetchImpl?: typeof fetch }} [opts]
@@ -145,7 +153,7 @@ export function putThreadHidden(prNumber, rootCommentId, hidden, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ refresh?: boolean, fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').Capabilities>}
  */
@@ -155,7 +163,7 @@ export function fetchCapabilities(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {import('./contract-types.js').PostCommentInput} input
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').PostCommentResponse>}
@@ -169,7 +177,7 @@ export function postComment(prNumber, input, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').ReviewBodyResponse>}
  */
@@ -178,7 +186,7 @@ export function fetchReviewBody(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ event: 'APPROVE' | 'REQUEST_CHANGES', body?: string, headSha?: string }} input
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').PostReviewResponse>}
@@ -210,7 +218,7 @@ export const POLL_SLOW_INTERVAL_MS = 15_000
  * After five minutes of waiting the gap grows to 15 s, because a generation that has not finished
  * by then takes minutes more. A failed poll is reported and polling goes on; the page never
  * blocks on it.
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {PollOptions} [opts]
  * @returns {{ stop: () => void }}
  */
@@ -230,7 +238,7 @@ export function pollBundle(prNumber, opts = {}) {
     /** @type {PrBundle} */
     let bundle
     try {
-      bundle = await fetchBundle(prNumber, { fetchImpl: opts.fetchImpl })
+      bundle = await fetchBundle(prNumber, { poll: true, fetchImpl: opts.fetchImpl })
     } catch (err) {
       if (!stopped) {
         opts.onError?.(err)
@@ -306,7 +314,7 @@ export function uploadForm(url, form, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {File} file
  * @param {{ force?: boolean, onProgress?: (fraction: number) => void, xhrImpl?: () => XMLHttpRequest }} [opts]
  * @returns {Promise<import('./contract-types.js').ImportResult>}
@@ -321,7 +329,7 @@ export function importCanvas(prNumber, file, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').SharedCanvasFetchResponse>}
  */
@@ -331,7 +339,7 @@ export function fetchSharedCanvas(prNumber, opts = {}) {
 
 /**
  * The zip as a blob plus the name the server chose, ready to hand to the browser.
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ headSha?: string, fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<{ blob: Blob, filename: string }>}
  */
@@ -378,7 +386,7 @@ export function saveAppearance(input, opts = {}) {
 /* ---- AI Chat and its settings ---- */
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').ChatThreadsResponse>}
  */
@@ -387,7 +395,7 @@ export function fetchThreads(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').ChatThreadsResponse>}
  */
@@ -400,7 +408,7 @@ export function createThread(prNumber, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {string} name
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').ChatHistoryResponse>}
@@ -412,7 +420,7 @@ export function fetchThreadHistory(prNumber, name, opts = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<{ cancelled: boolean }>}
  */
@@ -501,7 +509,7 @@ export function readSseFrames(buffer, chunk) {
 /**
  * Sends one chat message and calls `onEvent` for every frame until the turn ends. Rejects with
  * an ApiError when the server refuses the message (a busy chat, a context it cannot resolve).
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {{ message: string, context: import('./chat-context.js').ChatContext, thread?: string }} input
  * @param {{
  *   onEvent: (event: { event: string, data: unknown }) => void,

package/static/js/app.js

@@ -19,7 +19,7 @@ import { initDeepLinks } from './deep-link.js'
 import { initDiagrams } from './diagram.js'
 import { esc, qs } from './dom.js'
 import { exportCanvasZip } from './download.js'
-import { renderEmptyState, renderStaleState, staleBarHtml } from './empty-state.js'
+import { carriedOverBarHtml, renderEmptyState, renderStaleState, staleBarHtml } from './empty-state.js'
 import { errorCardHtml } from './errors.js'
 import { renderHeader } from './header.js'
 import { wireDropZone } from './import-zone.js'
@@ -33,8 +33,10 @@ import { initScrollSpy } from './scroll-spy.js'
 import { openSettingsDialog } from './settings.js'
 import { applySkin, nextSkin, readSkin, skinLabel } from './skin.js'
 import { applyTheme, nextTheme, readTheme, themeLabel } from './theme.js'
+import { hostLabel, setHost } from './host.js'
 
-/** @typedef {{ prNumber: number, owner: string, repo: string, version: string }} Bootstrap */
+/** @typedef {import('./contract-types.js').ReviewKey} ReviewKey */
+/** @typedef {{ prNumber: ReviewKey, owner: string, repo: string, version: string, host: import('./contract-types.js').PublicHost }} Bootstrap */
 
 /** @returns {Bootstrap | null} */
 function readBootstrap() {
@@ -57,7 +59,7 @@ function footerHtml(version, bundle) {
   const canvas = bundle?.canvas
     ? `<span>canvas <span class="mono">${esc(bundle.canvas.headSha.slice(0, 7))}</span> · ${esc(bundle.canvas.source)}</span>`
     : ''
-  return `<footer><span>pr-review ${esc(version)}</span>${canvas}<span>localhost only · nothing leaves this machine except GitHub posts you confirm</span></footer>`
+  return `<footer><span>pr-review ${esc(version)}</span>${canvas}<span>localhost only · nothing leaves this machine except ${esc(hostLabel())} posts you confirm</span></footer>`
 }
 
 /** @param {ReadonlyArray<string>} warnings */
@@ -83,7 +85,7 @@ function toEnvelopeError(err) {
 /**
  * The patches for the bundle. The first visit builds derived/ while the bundle resolves, so the
  * parallel fetch can land before the patches exist; one more try after the bundle is enough.
- * @param {number} prNumber
+ * @param {ReviewKey} prNumber
  * @param {Promise<Record<string, string> | null>} started
  * @param {string} [headSha] the canvas commit, when it is not the PR head
  */
@@ -155,6 +157,7 @@ export class PrAppElement extends HTMLElement {
       this.innerHTML = errorCardHtml({ code: 'INTERNAL', message: 'missing bootstrap data' })
       return
     }
+    setHost(this.bootstrap.host)
     this.theme = readTheme(document.documentElement)
     this.skin = readSkin(document.documentElement)
     const patchesPromise = fetchPatches(this.bootstrap.prNumber).then(
@@ -224,7 +227,12 @@ export class PrAppElement extends HTMLElement {
         now,
       })
       defineLayerElements()
-      const staleBar = bundle.status === 'stale' && bundle.stale ? staleBarHtml(bundle.stale) : ''
+      const staleBar =
+        bundle.status === 'stale' && bundle.stale
+          ? staleBarHtml(bundle.stale, bundle.local)
+          : bundle.carriedOver
+            ? carriedOverBarHtml(bundle.carriedOver)
+            : ''
       this.innerHTML =
         header +
         bannerHtml(bundle.warnings) +
@@ -249,6 +257,8 @@ export class PrAppElement extends HTMLElement {
         state: bundle.state,
         capabilities,
         headSha: bundle.pr.headSha,
+        // The marks are keyed to the canvas on the page, so every mark names it.
+        ...(bundle.canvas === undefined ? {} : { canvasSha: bundle.canvas.headSha }),
       })
       const interactions = wireReview(this, session, {
         chat: () => this.chat,
@@ -371,11 +381,15 @@ export class PrAppElement extends HTMLElement {
       this.viewStale = true
       void this.render(bundle)
     })
-    wireDropZone(this, {
-      prNumber: boot.prNumber,
-      importImpl: importCanvas,
-      onImported: () => void this.reload(),
-    })
+    // Importing a canvas a teammate attached is a pull request thing; local work has no thread
+    // to attach one to, and the local screens draw no drop zone.
+    if (typeof boot.prNumber === 'number') {
+      wireDropZone(this, {
+        prNumber: boot.prNumber,
+        importImpl: importCanvas,
+        onImported: () => void this.reload(),
+      })
+    }
   }
 
   /**

package/static/js/chat.js

@@ -23,6 +23,7 @@ import { postedCommentUrl, viewCommentHtml } from './comment-link.js'
 import { esc, qs } from './dom.js'
 import { getRenderContext } from './layers.js'
 import { renderMarkdown } from './markdown.js'
+import { postToLabel } from './host.js'
 import { splitChatAnswer, targetsFromFiles } from './proposed-comment.js'
 
 export const CHAT_WIDTH_KEY = 'pr-review.chat-width'
@@ -113,7 +114,7 @@ export const QUICK_QUESTIONS = [
 /**
  * @typedef {{
  *   root: HTMLElement,
- *   prNumber: number,
+ *   prNumber: import('./contract-types.js').ReviewKey,
  *   session: ReviewSession,
  *   storage?: Storage | null,
  *   api?: Partial<ChatApi>,
@@ -179,7 +180,7 @@ export function proposedCommentHtml(comment, id, postedUrl) {
     `<div class="prose">${renderMarkdown(comment.body)}</div>` +
     '<span class="tbtns">' +
     (postedUrl === undefined
-      ? `<button class="cmd fill" type="button" data-act="proposed-post" data-proposed="${esc(id)}" data-needs-post>post to github</button>`
+      ? `<button class="cmd fill" type="button" data-act="proposed-post" data-proposed="${esc(id)}" data-needs-post>${postToLabel()}</button>`
       : viewCommentHtml(postedUrl, true)) +
     `<button class="cmd" type="button" data-act="proposed-edit" data-proposed="${esc(id)}" data-needs-post>edit</button>` +
     `<button class="cmd" type="button" data-copy="${esc(comment.body)}">copy</button>` +

package/static/js/composer.js

@@ -6,6 +6,7 @@
 import { cssEscape } from './anchors.js'
 import { renderMarkdown } from './markdown.js'
 import { esc } from './dom.js'
+import { noPostingTitle, postToLabel } from './host.js'
 
 /**
  * @typedef {{
@@ -50,7 +51,7 @@ export function composerHtml(opts) {
     `<label class="sr" for="${esc(opts.id)}-t">${esc(opts.label)}</label>` +
     previewControlsHtml() +
     `<textarea id="${esc(opts.id)}-t" rows="3" placeholder="${esc(opts.label)}">${esc(opts.body ?? '')}</textarea>` +
-    '<div class="composer-actions"><button class="cmd fill" type="button" data-act="composer-post" data-needs-post>post to github</button>' +
+    `<div class="composer-actions"><button class="cmd fill" type="button" data-act="composer-post" data-needs-post>${postToLabel()}</button>` +
     '<button class="cmd" type="button" data-act="composer-cancel">cancel</button></div></div>'
   )
 }
@@ -144,12 +145,9 @@ export function closeComposers(root) {
   return closed
 }
 
-/** What a command says when this GitHub login may not post. */
-export const NO_POSTING_TITLE = 'this GitHub login cannot post on this repository'
-
 /**
  * Disables everything that posts when the probe said no, and enables it otherwise. A token
- * whose rights cannot be read ('unknown') stays enabled: GitHub answers for itself.
+ * whose rights cannot be read ('unknown') stays enabled: the host answers for itself.
  *
  * A command can be disabled for a reason of its own (the approve command before every layer is
  * read, a command whose request is still running). Those keep their state: this only adds and
@@ -159,7 +157,7 @@ export const NO_POSTING_TITLE = 'this GitHub login cannot post on this repositor
  */
 export function applyCapabilityGating(root, capabilities) {
   const blocked = capabilities.canComment === false
-  const reason = capabilities.reason ?? NO_POSTING_TITLE
+  const reason = capabilities.reason ?? noPostingTitle()
   for (const el of Array.from(root.querySelectorAll('[data-needs-post]'))) {
     if (!(el instanceof HTMLButtonElement) || el.getAttribute('aria-busy') === 'true') {
       continue
@@ -222,15 +220,19 @@ export function setDisabledReason(el, reason) {
   }
 }
 
+/** One command that swaps the box between writing and previewing; its label is the mode it goes to. */
 export function previewControlsHtml() {
-  return '<div class="preview-controls" role="group" aria-label="Markdown editor"><button class="cmd" type="button" data-act="markdown-write" aria-pressed="true">Write</button><button class="cmd" type="button" data-act="markdown-preview" aria-pressed="false">Preview</button></div><div class="markdown-preview prose" hidden></div>'
+  return '<div class="preview-controls"><button class="cmd" type="button" data-act="markdown-toggle">preview</button></div><div class="markdown-preview prose" hidden></div>'
 }
 
-/** @param {HTMLElement} button @param {boolean} preview */
-export function toggleMarkdownPreview(button, preview) {
-  const host = button.closest('.composer-box, .signoff-dialog')
-  const textarea = host?.querySelector('textarea')
-  const output = host?.querySelector('.markdown-preview')
+/**
+ * Puts one editor into write or preview mode.
+ * @param {Element} host the `.composer-box` or `.signoff-dialog` that holds the editor
+ * @param {boolean} preview
+ */
+export function setMarkdownPreview(host, preview) {
+  const textarea = host.querySelector('textarea')
+  const output = host.querySelector('.markdown-preview')
   if (!(textarea instanceof HTMLTextAreaElement) || !(output instanceof HTMLElement)) return
   if (preview)
     output.innerHTML = textarea.value.trim()
@@ -238,7 +240,15 @@ export function toggleMarkdownPreview(button, preview) {
       : '<p class="muted">Nothing to preview.</p>'
   textarea.hidden = preview
   output.hidden = !preview
-  host?.querySelector('[data-act="markdown-write"]')?.setAttribute('aria-pressed', String(!preview))
-  host?.querySelector('[data-act="markdown-preview"]')?.setAttribute('aria-pressed', String(preview))
+  const toggle = host.querySelector('[data-act="markdown-toggle"]')
+  if (toggle !== null) toggle.textContent = preview ? 'write' : 'preview'
   if (!preview) textarea.focus()
 }
+
+/** @param {HTMLElement} button */
+export function toggleMarkdownPreview(button) {
+  const host = button.closest('.composer-box, .signoff-dialog')
+  if (host === null) return
+  const output = host.querySelector('.markdown-preview')
+  setMarkdownPreview(host, output instanceof HTMLElement && output.hidden)
+}

package/static/js/contract-types.d.ts

@@ -1,6 +1,7 @@
 // Type-only bridge so the browser modules (JSDoc) see the same contract as the server.
 
 export type {
+  CarriedOverInfo,
   CanvasRelation,
   Capabilities,
   ChatStatus,
@@ -10,6 +11,7 @@ export type {
   PostCommentResponse,
   PostReviewResponse,
   PrBundle,
+  PublicHost,
   ReviewBodyResponse,
   ReviewSummary,
   SharedCanvasFetchResponse,
@@ -23,6 +25,7 @@ export type {
   ChatThreadsResponse,
   ChatTurn,
 } from '../../src/contract/chat.js'
+export type { ReviewKey } from '../../src/contract/review-key.js'
 export type {
   CommentsPayload,
   IssueComment,

package/static/js/diff-renderer.js

@@ -855,7 +855,7 @@ export function renderDiff(file, patch, opts = {}) {
     highlightHunk(h, file.lang)
     tables.push(
       `<table class="diff" id="${esc(hunkAnchorId(file.key, n))}" data-hunk="${esc(id)}" data-key="${esc(file.key)}">` +
-        `<caption class="sr">Hunk ${n} of ${esc(file.path)}</caption>${THEAD}<tbody>${buildRows(h, file.key)}</tbody></table>`
+        `<caption class="sr">Chunk ${n} of ${esc(file.path)}</caption>${THEAD}<tbody>${buildRows(h, file.key)}</tbody></table>`
     )
   })
   if (tables.length === 0) {

package/static/js/download.js

@@ -26,7 +26,7 @@ export function saveBlob(blob, filename, deps = {}) {
 }
 
 /**
- * @param {number} prNumber
+ * @param {import('./contract-types.js').ReviewKey} prNumber
  * @param {{ headSha?: string, fetchImpl?: typeof fetch } & SaveDeps} [opts]
  * @returns {Promise<string>} the file name the browser saved
  */