@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/store/canvas-store.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { CanvasRelation } from '../contract/api.js'
+import type { CarriedOverInfo } from '../contract/api.js'
 import {
   type CanvasIndex,
   CanvasIndexSchema,
@@ -7,13 +7,43 @@ import {
   CanvasManifestSchema,
 } from '../contract/canvas-manifest.js'
 import { type ReviewArtifact, ReviewArtifactSchema } from '../contract/review-artifact.js'
+import { isLocalKey, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import type { Git } from '../git/git.js'
 import { readJson, readText, writeJsonAtomic } from './atomic-json.js'
 
+/** A canvas of a commit the head was built on, and how many commits the head gained since. */
+export interface AncestorCanvas {
+  status: 'stale'
+  headSha: string
+  relation: 'ancestor'
+  commitsBehind: number
+}
+
 export type CanvasLookup =
-  | { status: 'ready'; headSha: string }
-  | { status: 'stale'; headSha: string; relation: CanvasRelation; commitsBehind?: number }
-  | { status: 'missing' }
+  /** `headSha` is the canvas's own commit: the head, or another commit with an identical diff. */
+  { status: 'ready'; headSha: string; carriedOver?: CarriedOverInfo } | StaleCanvas | { status: 'missing' }
+
+/** A canvas of another commit: one the head was built on, or one from a line the head no longer contains. */
+export type StaleCanvas = AncestorCanvas | { status: 'stale'; headSha: string; relation: 'unrelated' }
+
+/** One canvas as `index.json` lists it. */
+export type CanvasEntry = CanvasIndex['canvases'][string]
+
+/**
+ * Whether a canvas is one of this target's. A canvas belongs to a pull request when it was
+ * generated for it or before it existed; to a local review when it belongs to no pull request. A
+ * snapshot of uncommitted work sits on no branch, so only the `uncommitted` review claims it.
+ *
+ * Every consumer asks through here: the lookups that pick the canvas to show, and the routes that
+ * accept a canvas a mark was made on. Two answers to this question is how marks end up keyed to a
+ * canvas their review will never show.
+ */
+export function canvasBelongsTo(entry: CanvasEntry, key: ReviewKey): boolean {
+  if (isLocalKey(key)) {
+    return entry.prNumber === undefined && (key === 'uncommitted' || entry.worktree !== true)
+  }
+  return entry.worktree !== true && (entry.prNumber === undefined || entry.prNumber === key)
+}
 
 export interface CanvasStore {
   readonly root: string
@@ -24,12 +54,23 @@ export interface CanvasStore {
   readArtifact(headSha: string): Promise<ReviewArtifact | null>
   readManifest(headSha: string): Promise<CanvasManifest | null>
   /** Writes review.json + manifest.json atomically and records the canvas in index.json. */
-  write(headSha: string, artifact: ReviewArtifact, manifest: CanvasManifest, prNumber?: number): Promise<void>
+  write(
+    headSha: string,
+    artifact: ReviewArtifact,
+    manifest: CanvasManifest,
+    prNumber?: number,
+    flags?: { worktree?: boolean }
+  ): Promise<void>
   /**
    * The best canvas for this PR: the one written for its current head, else the newest one the
    * head was built on top of, else one from a branch the head no longer contains.
    */
   findForPr(prNumber: number, currentHeadSha: string): Promise<CanvasLookup>
+  /**
+   * The best canvas for a local review: the one for this head, else the newest canvas that belongs
+   * to no pull request. A snapshot of uncommitted work counts only for the `uncommitted` review.
+   */
+  findForLocal(key: LocalKey, currentHeadSha: string): Promise<CanvasLookup>
   /** Records the PR number on a canvas that was exported before the pull request existed. */
   attachPrNumber(headSha: string, prNumber: number): Promise<void>
 }
@@ -47,6 +88,43 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
   const readIndex = async (): Promise<CanvasIndex> =>
     (await readJson(indexFile, CanvasIndexSchema)) ?? { canvases: {} }
 
+  /**
+   * The canvas for this head, or the closest one `accept` allows. Commits the head was built on
+   * come first, newest wins inside a relation, and a canvas off a discarded branch is the last
+   * resort.
+   */
+  const rank = async (
+    currentHeadSha: string,
+    accept: (entry: CanvasEntry) => boolean
+  ): Promise<CanvasLookup> => {
+    const index = await readIndex()
+    if (index.canvases[currentHeadSha] !== undefined) {
+      return { status: 'ready', headSha: currentHeadSha }
+    }
+    const candidates = Object.entries(index.canvases).filter(
+      ([sha, entry]) => sha !== currentHeadSha && accept(entry)
+    )
+    const ranked: Array<{ generatedAt: string; found: StaleCanvas }> = []
+    for (const [sha, entry] of candidates) {
+      const found: StaleCanvas = (await git.isAncestor(sha, currentHeadSha))
+        ? {
+            status: 'stale',
+            headSha: sha,
+            relation: 'ancestor',
+            commitsBehind: await git.countCommitsBetween(sha, currentHeadSha),
+          }
+        : { status: 'stale', headSha: sha, relation: 'unrelated' }
+      ranked.push({ generatedAt: entry.generatedAt, found })
+    }
+    ranked.sort((a, b) => {
+      if (a.found.relation !== b.found.relation) {
+        return a.found.relation === 'ancestor' ? -1 : 1
+      }
+      return a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0
+    })
+    return ranked[0]?.found ?? { status: 'missing' }
+  }
+
   return {
     root: repoRoot,
     canvasDir,
@@ -54,12 +132,12 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
     exists: async headSha => (await readText(path.join(canvasDir(headSha), 'review.json'))) !== null,
     readArtifact: headSha => readJson(path.join(canvasDir(headSha), 'review.json'), ReviewArtifactSchema),
     readManifest: headSha => readJson(path.join(canvasDir(headSha), 'manifest.json'), CanvasManifestSchema),
-    write: async (headSha, artifact, manifest, prNumber) => {
+    write: async (headSha, artifact, manifest, prNumber, flags) => {
       const dir = canvasDir(headSha)
       await writeJsonAtomic(path.join(dir, 'review.json'), artifact)
       await writeJsonAtomic(path.join(dir, 'manifest.json'), manifest)
       const index = await readIndex()
-      const entry: CanvasIndex['canvases'][string] = {
+      const entry: CanvasEntry = {
         generatedAt: artifact.generatedAt,
         source: artifact.source,
       }
@@ -70,57 +148,17 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
       if (artifact.importedAt !== undefined) {
         entry.importedAt = artifact.importedAt
       }
-      index.canvases[headSha] = entry
-      await writeJsonAtomic(indexFile, index)
-    },
-    findForPr: async (prNumber, currentHeadSha) => {
-      const index = await readIndex()
-      if (index.canvases[currentHeadSha] !== undefined) {
-        return { status: 'ready', headSha: currentHeadSha }
-      }
-      // A canvas belongs to this PR when it was exported for it, or before the PR existed.
-      const candidates = Object.entries(index.canvases).filter(
-        ([sha, entry]) =>
-          sha !== currentHeadSha && (entry.prNumber === undefined || entry.prNumber === prNumber)
-      )
-      const ranked: Array<{
-        headSha: string
-        generatedAt: string
-        relation: CanvasRelation
-        commitsBehind?: number
-      }> = []
-      for (const [sha, entry] of candidates) {
-        if (await git.isAncestor(sha, currentHeadSha)) {
-          ranked.push({
-            headSha: sha,
-            generatedAt: entry.generatedAt,
-            relation: 'ancestor',
-            commitsBehind: await git.countCommitsBetween(sha, currentHeadSha),
-          })
-        } else {
-          ranked.push({ headSha: sha, generatedAt: entry.generatedAt, relation: 'unrelated' })
-        }
+      if (artifact.basisCanvasSha !== undefined) {
+        entry.basisCanvasSha = artifact.basisCanvasSha
       }
-      // Commits the head was built on come first; a force-pushed-away canvas is the last resort.
-      ranked.sort((a, b) => {
-        if (a.relation !== b.relation) {
-          return a.relation === 'ancestor' ? -1 : 1
-        }
-        return a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0
-      })
-      const best = ranked[0]
-      if (best === undefined) {
-        return { status: 'missing' }
+      if (flags?.worktree === true) {
+        entry.worktree = true
       }
-      return best.commitsBehind === undefined
-        ? { status: 'stale', headSha: best.headSha, relation: best.relation }
-        : {
-            status: 'stale',
-            headSha: best.headSha,
-            relation: best.relation,
-            commitsBehind: best.commitsBehind,
-          }
+      index.canvases[headSha] = entry
+      await writeJsonAtomic(indexFile, index)
     },
+    findForPr: (prNumber, currentHeadSha) => rank(currentHeadSha, entry => canvasBelongsTo(entry, prNumber)),
+    findForLocal: (key, currentHeadSha) => rank(currentHeadSha, entry => canvasBelongsTo(entry, key)),
     attachPrNumber: async (headSha, prNumber) => {
       const index = await readIndex()
       const entry = index.canvases[headSha]

package/src/store/data-dir.ts

@@ -25,5 +25,6 @@ export async function ensureDataDir(dataDir: string): Promise<void> {
 }
 
 export function repoDir(dataDir: string, repo: Repo): string {
-  return path.join(dataDir, 'repos', `${repo.owner}__${repo.name}`)
+  const owner = repo.owner.replaceAll('/', '__')
+  return path.join(dataDir, 'repos', `${owner}__${repo.name}`)
 }

package/src/store/derived-store.ts

@@ -24,6 +24,12 @@ export interface DerivedStore {
   /** Reads `derived/` when it matches the commits, otherwise rebuilds it from local git. */
   ensure(headSha: string, mergeBaseSha: string): Promise<Derived>
   read(headSha: string): Promise<Derived | null>
+  /**
+   * The diffs built from the clone when the merge base is known and both commits are local, so a
+   * base that advanced under the head is seen; else the stored copy, which is all an imported
+   * canvas has.
+   */
+  readOrBuild(headSha: string, mergeBaseSha: string | undefined): Promise<Derived | null>
   /** Lines `from..to` (1-based, inclusive) of a materialized file, or null when not materialized. */
   readLines(
     headSha: string,
@@ -47,36 +53,44 @@ export function createDerivedStore(canvases: CanvasStore, git: Git, now: () => D
     return { files, patches }
   }
 
+  const derivable = async (headSha: string, mergeBaseSha: string): Promise<boolean> =>
+    (await git.commitExists(headSha)) && (await git.commitExists(mergeBaseSha))
+
+  const ensure = async (headSha: string, mergeBaseSha: string): Promise<Derived> => {
+    const dir = derivedDir(headSha)
+    const meta = await readJson(path.join(dir, 'meta.json'), DerivedMetaSchema)
+    if (meta !== null && meta.mergeBaseSha === mergeBaseSha) {
+      const cached = await read(headSha)
+      if (cached !== null) {
+        return cached
+      }
+    }
+    const collected = await collectDiffs(git, mergeBaseSha, headSha)
+    const files = collected.map(toFileEntry)
+    const patches = toPatchMap(collected)
+    await writeJsonAtomic(path.join(dir, 'files.json'), files)
+    await writeJsonAtomic(path.join(dir, 'patches.json'), patches)
+    for (const f of collected) {
+      await writeTextAtomic(path.join(dir, 'patches', `${f.key}.diff`), `${labelPatch(f.key, f.patch)}\n`)
+    }
+    await materialize(git, { headSha, mergeBaseSha, files: collected, outDir: dir })
+    await writeJsonAtomic(path.join(dir, 'meta.json'), {
+      headSha,
+      mergeBaseSha,
+      builtAt: now().toISOString(),
+    })
+    return { files, patches }
+  }
+
   return {
     derivedDir,
-    derivable: async (headSha, mergeBaseSha) =>
-      (await git.commitExists(headSha)) && (await git.commitExists(mergeBaseSha)),
-    ensure: async (headSha, mergeBaseSha) => {
-      const dir = derivedDir(headSha)
-      const meta = await readJson(path.join(dir, 'meta.json'), DerivedMetaSchema)
-      if (meta !== null && meta.mergeBaseSha === mergeBaseSha) {
-        const cached = await read(headSha)
-        if (cached !== null) {
-          return cached
-        }
-      }
-      const collected = await collectDiffs(git, mergeBaseSha, headSha)
-      const files = collected.map(toFileEntry)
-      const patches = toPatchMap(collected)
-      await writeJsonAtomic(path.join(dir, 'files.json'), files)
-      await writeJsonAtomic(path.join(dir, 'patches.json'), patches)
-      for (const f of collected) {
-        await writeTextAtomic(path.join(dir, 'patches', `${f.key}.diff`), `${labelPatch(f.key, f.patch)}\n`)
-      }
-      await materialize(git, { headSha, mergeBaseSha, files: collected, outDir: dir })
-      await writeJsonAtomic(path.join(dir, 'meta.json'), {
-        headSha,
-        mergeBaseSha,
-        builtAt: now().toISOString(),
-      })
-      return { files, patches }
-    },
+    derivable,
+    ensure,
     read,
+    readOrBuild: async (headSha, mergeBaseSha) =>
+      mergeBaseSha !== undefined && (await derivable(headSha, mergeBaseSha))
+        ? ensure(headSha, mergeBaseSha)
+        : read(headSha),
     readLines: async (headSha, side, filePath, from, to) => {
       const root = path.join(derivedDir(headSha), side)
       const full = path.resolve(root, filePath)

package/src/store/pr-store.ts

@@ -2,39 +2,48 @@ import { readdir, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { type CommentsPayload, CommentsPayloadSchema } from '../contract/comments.js'
 import { type DiscoveryCache, DiscoveryCacheSchema } from '../contract/discovery.js'
+import { type LocalPrepareTarget, LocalPrepareTargetSchema } from '../contract/generation-context.js'
+import { isLocalKey, keyToString, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import { type Pr, PrSchema } from '../contract/review-artifact.js'
 import { readJson, readJsonOrDefault, writeJsonAtomic } from './atomic-json.js'
 
-/** PR-keyed files: the cached PR meta and the last comments payload. */
+/** Target-keyed files: the cached PR meta and the last comments payload. */
 export interface PrStore {
-  prDir(number: number): string
-  readPr(number: number): Promise<Pr | null>
-  writePr(pr: Pr): Promise<void>
+  prDir(key: ReviewKey): string
+  readPr(key: ReviewKey): Promise<Pr | null>
+  /** The key is passed in, because the local review's meta carries no number of its own. */
+  writePr(key: ReviewKey, pr: Pr): Promise<void>
   readComments(number: number): Promise<CommentsPayload | null>
   writeComments(number: number, comments: CommentsPayload): Promise<void>
   /** The last attachment scan, so an unchanged PR is not scanned again. */
   readDiscovery(number: number): Promise<DiscoveryCache | null>
   writeDiscovery(number: number, discovery: DiscoveryCache): Promise<void>
-  /** PR numbers with a cached pr.json, newest first by file mtime. */
+  /** PR numbers with a cached pr.json, newest first by file mtime. Local reviews are not ones. */
   listRecent(limit: number): Promise<Array<{ number: number; title: string; updatedAt: string }>>
+  /** What this local review was last prepared for, so the page can resolve the same head again. */
+  readLocalTarget(key: LocalKey): Promise<LocalPrepareTarget | null>
+  writeLocalTarget(key: LocalKey, target: LocalPrepareTarget): Promise<void>
 }
 
 export function createPrStore(repoRoot: string): PrStore {
-  const prDir = (number: number): string => {
-    if (!Number.isInteger(number) || number <= 0) {
-      throw new Error(`not a pull request number: ${number}`)
+  const prDir = (key: ReviewKey): string => {
+    if (!isLocalKey(key) && (!Number.isInteger(key) || key <= 0)) {
+      throw new Error(`not a pull request number: ${String(key)}`)
     }
-    return path.join(repoRoot, 'prs', String(number))
+    return path.join(repoRoot, 'prs', keyToString(key))
   }
   return {
     prDir,
-    readPr: number => readJson(path.join(prDir(number), 'pr.json'), PrSchema),
-    writePr: async pr => {
-      if (pr.number === null) {
-        throw new Error('cannot cache a pre-PR change set under prs/')
+    readPr: key => readJson(path.join(prDir(key), 'pr.json'), PrSchema),
+    writePr: async (key, pr) => {
+      if (!isLocalKey(key) && pr.number !== key) {
+        throw new Error(`pull request ${String(key)} cannot hold the meta of ${String(pr.number)}`)
       }
-      await writeJsonAtomic(path.join(prDir(pr.number), 'pr.json'), pr)
+      await writeJsonAtomic(path.join(prDir(key), 'pr.json'), pr)
     },
+    readLocalTarget: key =>
+      readJsonOrDefault(path.join(prDir(key), 'target.json'), LocalPrepareTargetSchema, () => null),
+    writeLocalTarget: (key, target) => writeJsonAtomic(path.join(prDir(key), 'target.json'), target),
     readComments: number => readJson(path.join(prDir(number), 'comments.json'), CommentsPayloadSchema),
     writeComments: (number, comments) => writeJsonAtomic(path.join(prDir(number), 'comments.json'), comments),
     readDiscovery: number =>

package/src/store/settings-store.ts

@@ -11,11 +11,15 @@ export const SETTINGS_TEMPLATE = `# Personal pr-review settings. Gitignored: thi
 version: 1
 
 # The look of the page: terminal or github.
-skin: terminal
+skin: ${DEFAULT_SETTINGS.skin}
 
 # Light or dark: auto follows the operating system, light and dark pin one.
 theme: auto
 
+# How much code a review hides when it opens: light, moderate, or aggressive. The Hide code
+# control on the page changes it for that page only.
+foldLevel: light
+
 # Which agent answers in the AI Chat pane: claude or codex.
 agent: claude
 
@@ -121,6 +125,7 @@ export function applySettings(text: string, input: SettingsInput): { text: strin
   doc.set('version', 1)
   doc.set('skin', settings.skin)
   doc.set('theme', settings.theme)
+  doc.set('foldLevel', settings.foldLevel)
   doc.set('agent', settings.agent)
   doc.set('model', settings.model)
   doc.set('chatTimeoutSec', settings.chatTimeoutSec)
@@ -136,6 +141,9 @@ function stripUndefined(input: SettingsInput): Partial<Settings> {
   if (input.theme !== undefined) {
     out.theme = input.theme
   }
+  if (input.foldLevel !== undefined) {
+    out.foldLevel = input.foldLevel
+  }
   if (input.agent !== undefined) {
     out.agent = input.agent
   }

package/src/store/state-store.ts

@@ -1,5 +1,7 @@
 import path from 'node:path'
+import type { ReviewKey } from '../contract/review-key.js'
 import { emptyState, type PrState, PrStateSchema } from '../contract/state.js'
+import type { AddPendingInput, PendingComment } from '../contract/pending.js'
 import { readJsonOrDefault, writeJsonAtomic } from './atomic-json.js'
 import type { PrStore } from './pr-store.js'
 
@@ -9,23 +11,45 @@ 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, and `carried` takes their place — the marks the caller worked out may follow that
+   * canvas from the one it was generated from.
    */
-  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, opts?: SetReviewedOptions): 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>
+  /** Adds one comment to the pending review and returns the state that holds it. */
+  addPending(key: ReviewKey, input: AddPendingInput, headSha: string): Promise<PrState>
+  /** Rewrites one draft's body. A draft that is no longer there leaves the state alone. */
+  editPending(key: ReviewKey, id: string, body: string): Promise<PrState>
+  removePending(key: ReviewKey, id: string): Promise<PrState>
+  /** Discards every draft at the reviewer's request. */
+  clearPending(key: ReviewKey): Promise<PrState>
+  /** Acknowledge submitted versions, preserving drafts added or edited while posting. */
+  completePending(
+    key: ReviewKey,
+    submitted: ReadonlyArray<PendingComment>,
+    posted: PostedEntry[]
+  ): Promise<PrState>
+}
+
+export interface SetReviewedOptions {
+  /** The commit of the canvas the page was showing. */
+  canvasSha?: string | undefined
+  /** Marks that follow `canvasSha` from the canvas it was generated from; used on the first write. */
+  carried?: Readonly<Record<string, true>> | undefined
 }
 
 /** `layer:<id>` or `layer:<id>/file:<key>`, with the ids and keys the artifact uses. */
@@ -41,26 +65,32 @@ function layerOf(id: string): string {
   return at === -1 ? id : id.slice(0, at)
 }
 
+/** Ids only have to be unique inside one state file; the clock and the counter make them so. */
+function pendingId(now: () => Date, seq: number): string {
+  return `p${now().getTime().toString(36)}-${seq.toString(36)}`
+}
+
 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()))
+  let pendingSeq = 0
+  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 +99,31 @@ 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, opts) =>
+      update(key, state => {
+        const canvasSha = opts?.canvasSha
+        const sameCanvas =
+          canvasSha === undefined ||
+          state.reviewedCanvasSha === undefined ||
+          state.reviewedCanvasSha === canvasSha
+        const next = sameCanvas ? { ...state.reviewed } : { ...opts?.carried }
         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 +133,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,13 +143,49 @@ 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
         }
         const posted = { ...entry, at: now().toISOString() }
         return { ...state, posted: [...state.posted, posted] }
       }),
+    addPending: (key, input, headSha) => {
+      pendingSeq += 1
+      const at = now().toISOString()
+      const draft: PendingComment = {
+        id: pendingId(now, pendingSeq),
+        path: input.path,
+        line: input.line,
+        side: input.side,
+        ...(input.startLine === undefined ? {} : { startLine: input.startLine }),
+        body: input.body,
+        ...(input.pointFingerprint === undefined ? {} : { pointFingerprint: input.pointFingerprint }),
+        headSha,
+        createdAt: at,
+        updatedAt: at,
+      }
+      return update(key, state => ({ ...state, pending: [...state.pending, draft] }))
+    },
+    editPending: (key, id, body) =>
+      update(key, state => ({
+        ...state,
+        pending: state.pending.map(p => (p.id === id ? { ...p, body, updatedAt: now().toISOString() } : p)),
+      })),
+    removePending: (key, id) =>
+      update(key, state => ({ ...state, pending: state.pending.filter(p => p.id !== id) })),
+    clearPending: key => update(key, state => ({ ...state, pending: [] })),
+    completePending: (key, submitted, posted) =>
+      update(key, state => ({
+        ...state,
+        pending: state.pending.filter(p => !submitted.some(s => s.id === p.id && s.body === p.body)),
+        posted: [
+          ...state.posted,
+          ...posted
+            .filter(p => !state.posted.some(s => s.commentId === p.commentId))
+            .map(p => ({ ...p, at: now().toISOString() })),
+        ],
+      })),
   }
 }