@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/src/upgrade.ts

@@ -0,0 +1,338 @@
+// `pr-review upgrade`: brings pr-review, acpx, and the project's copy of the skill up to date. It
+// says what it will change and asks first. Once pr-review itself moves, the new version checks the
+// skill, so the skill it ships is stamped by the code that ships it.
+import { realpath } from 'node:fs/promises'
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import { z } from 'zod'
+import { type CliIo, EXIT, printJson, UsageError } from './commands.js'
+import { findSkillCopies, type ReadSkill, type SkillCopy } from './review/doctor.js'
+import { installSkill, SkillDirExistsError } from './review/install-skill.js'
+
+export const ACPX_PACKAGE = 'acpx'
+
+export interface CommandResult {
+  ok: boolean
+  stdout: string
+  stderr: string
+}
+
+export interface UpgradeDeps {
+  /** The running pr-review: its package name, version, and where it is installed. */
+  packageName: string
+  version: string
+  packageRoot: string
+  /** The repository whose skill copies are refreshed, or null outside one. */
+  repoRoot: string | null
+  acpxVersion: () => Promise<string | null>
+  /** The acpx that PATH runs, which chat uses. */
+  acpxPath: string | null
+  /** Runs one command without a shell. Only `npm` is run. */
+  run: (file: string, args: string[]) => Promise<CommandResult>
+  /** Runs `pr-review <args>` from the package on disk, which is the new one after its upgrade. */
+  runInstalled: (args: string[]) => Promise<CommandResult>
+  /** Asks a yes/no question, or returns null when there is no one to ask. */
+  confirm: (question: string) => Promise<boolean | null>
+  readSkill?: ReadSkill
+}
+
+/** What one step upgrades, in the order a plan runs them. */
+const StepKindSchema = z.enum(['package', 'acpx', 'skill'])
+type StepKind = z.infer<typeof StepKindSchema>
+
+const NpmStepSchema = z.object({
+  kind: z.enum(['package', 'acpx']),
+  name: z.string(),
+  from: z.string(),
+  to: z.string(),
+})
+const SkillStepSchema = z.object({ kind: z.literal('skill'), paths: z.array(z.string()) })
+const OutcomeFields = {
+  status: z.enum(['done', 'failed']),
+  detail: z.string().optional(),
+}
+const StepOutcomeSchema = z.discriminatedUnion('kind', [
+  NpmStepSchema.extend(OutcomeFields),
+  SkillStepSchema.extend(OutcomeFields),
+])
+/** What an applied upgrade prints, and so what the parent reads back from the new version. */
+const AppliedReportSchema = z.object({ steps: z.array(StepOutcomeSchema) })
+
+export type UpgradeStep = z.infer<typeof NpmStepSchema> | z.infer<typeof SkillStepSchema>
+export type StepOutcome = z.infer<typeof StepOutcomeSchema>
+
+export interface UpgradePlan {
+  steps: UpgradeStep[]
+  /** What was looked at and left alone, and why. */
+  notes: string[]
+}
+
+/** `1.2.10` against `1.2.9`, numerically. A prerelease tag is ignored. */
+export function isNewer(candidate: string, current: string): boolean {
+  const parts = (v: string): number[] => v.trim().replace(/^v/, '').split(/[-+]/)[0]!.split('.').map(Number)
+  const a = parts(candidate)
+  const b = parts(current)
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0)
+    if (Number.isNaN(diff)) return false
+    if (diff !== 0) return diff > 0
+  }
+  return false
+}
+
+async function latestVersion(deps: UpgradeDeps, name: string): Promise<string | null> {
+  const result = await deps.run('npm', ['view', name, 'version'])
+  const version = result.stdout.trim()
+  return result.ok && version !== '' ? version : null
+}
+
+/**
+ * Whether `installed` lies in the copy of `name` that `npm install -g` replaces. Installing over
+ * any other copy (pnpm, brew, another node) would leave the one in use as it was.
+ */
+async function ownedByGlobalNpm(
+  globalRoot: string | null,
+  name: string,
+  installed: string
+): Promise<boolean> {
+  if (globalRoot === null) return false
+  try {
+    const globalCopy = await realpath(path.join(globalRoot, name))
+    const real = await realpath(installed)
+    return real === globalCopy || real.startsWith(`${globalCopy}${path.sep}`)
+  } catch {
+    return false
+  }
+}
+
+function notGlobalNote(name: string, latest: string, installed: string): string {
+  return `${name} ${latest} is out, but the copy in use (${installed}) is not the global npm install; update it the way you installed it`
+}
+
+async function skillCopies(deps: UpgradeDeps): Promise<SkillCopy[]> {
+  return deps.repoRoot === null ? [] : findSkillCopies(deps.repoRoot, deps.readSkill)
+}
+
+export async function planUpgrade(deps: UpgradeDeps): Promise<UpgradePlan> {
+  const steps: UpgradeStep[] = []
+  const notes: string[] = []
+
+  const root = await deps.run('npm', ['root', '-g'])
+  const globalRoot = root.ok ? root.stdout.trim() : null
+  const latest = await latestVersion(deps, deps.packageName)
+  if (latest === null) {
+    notes.push(`${deps.packageName}: could not read the latest version from npm`)
+  } else if (!isNewer(latest, deps.version)) {
+    notes.push(`${deps.packageName} ${deps.version} is up to date`)
+  } else if (await ownedByGlobalNpm(globalRoot, deps.packageName, deps.packageRoot)) {
+    steps.push({ kind: 'package', name: deps.packageName, from: deps.version, to: latest })
+  } else {
+    notes.push(notGlobalNote(deps.packageName, latest, deps.packageRoot))
+  }
+
+  const acpx = deps.acpxPath === null ? null : await deps.acpxVersion()
+  const acpxLatest = acpx === null ? null : await latestVersion(deps, ACPX_PACKAGE)
+  if (acpx === null || deps.acpxPath === null) {
+    notes.push('acpx is not installed; AI Chat needs it: npm install -g acpx@latest')
+  } else if (acpxLatest === null) {
+    notes.push('acpx: could not read the latest version from npm')
+  } else if (!isNewer(acpxLatest, acpx)) {
+    notes.push(`acpx ${acpx} is up to date`)
+  } else if (await ownedByGlobalNpm(globalRoot, ACPX_PACKAGE, deps.acpxPath)) {
+    steps.push({ kind: 'acpx', name: ACPX_PACKAGE, from: acpx, to: acpxLatest })
+  } else {
+    notes.push(notGlobalNote(ACPX_PACKAGE, acpxLatest, deps.acpxPath))
+  }
+
+  if (deps.repoRoot === null) {
+    notes.push('not in a repository, so no project skill to refresh')
+  } else {
+    const copies = await skillCopies(deps)
+    // A new pr-review can ship a new skill, so every copy is in question once the package moves.
+    const packageMoves = steps.some(step => step.kind === 'package')
+    const toCheck = copies.filter(copy => packageMoves || copy.stale)
+    if (copies.length === 0) {
+      notes.push('the project has no copy of the skill; run `pr-review install-skill` to add one')
+    } else if (toCheck.length > 0) {
+      steps.push({ kind: 'skill', paths: toCheck.map(copy => copy.path) })
+    } else {
+      notes.push(`the project skill matches pr-review ${deps.version}`)
+    }
+  }
+  return { steps, notes }
+}
+
+export function describeStep(step: UpgradeStep): string {
+  if (step.kind === 'skill') {
+    return `refresh the project skill where it differs from pr-review's: ${step.paths.join(', ')}`
+  }
+  return `upgrade ${step.name} ${step.from} -> ${step.to} (npm install -g ${step.name}@${step.to})`
+}
+
+async function applySkill(deps: UpgradeDeps): Promise<{ written: string[]; skipped: string[] }> {
+  const written: string[] = []
+  const skipped: string[] = []
+  for (const copy of await skillCopies(deps)) {
+    if (!copy.stale) continue
+    try {
+      await installSkill({ targets: [{ kind: copy.kind, dir: copy.dir }] })
+      written.push(copy.path)
+    } catch (err) {
+      if (!(err instanceof SkillDirExistsError)) throw err
+      skipped.push(copy.path)
+    }
+  }
+  return { written, skipped }
+}
+
+async function applySkillStep(
+  step: z.infer<typeof SkillStepSchema>,
+  deps: UpgradeDeps
+): Promise<StepOutcome> {
+  const { written, skipped } = await applySkill(deps)
+  if (skipped.length > 0) {
+    return {
+      ...step,
+      paths: written,
+      status: 'failed',
+      detail: `not a managed copy, left alone: ${skipped.join(', ')}; run \`pr-review install-skill --force\` to replace it`,
+    }
+  }
+  return { ...step, paths: written, status: 'done' }
+}
+
+/**
+ * The new pr-review's own `upgrade --yes --only <kinds>`: it plans again with its own code, and runs
+ * only the kinds of step the user confirmed. Its report's steps join this one's, so this process
+ * stays the one that prints them.
+ */
+async function handOff(deps: UpgradeDeps, kinds: StepKind[]): Promise<StepOutcome[]> {
+  const result = await deps.runInstalled([
+    'upgrade',
+    '--yes',
+    '--only',
+    kinds.join(','),
+    ...(deps.repoRoot === null ? [] : ['--repo', deps.repoRoot]),
+  ])
+  let report: unknown
+  try {
+    // The report is the last line; String() turns a missing one into text JSON.parse rejects.
+    report = JSON.parse(String(result.stdout.trim().split('\n').at(-1)))
+  } catch {
+    report = null
+  }
+  const parsed = AppliedReportSchema.safeParse(report)
+  if (parsed.success) return parsed.data.steps
+  return [
+    {
+      kind: 'skill',
+      paths: [],
+      status: 'failed',
+      detail:
+        `the new pr-review did not report a result; run \`pr-review upgrade\` again\n` +
+        result.stderr.trim().split('\n').slice(-3).join('\n'),
+    },
+  ]
+}
+
+/**
+ * Runs every step in order. A failed npm install does not stop the rest. Once pr-review itself is
+ * upgraded, the new version plans and runs whatever is left, so the skill it ships is checked and
+ * copied by its own code.
+ */
+export async function applyUpgrade(plan: UpgradePlan, deps: UpgradeDeps): Promise<StepOutcome[]> {
+  const outcomes: StepOutcome[] = []
+  for (const [index, step] of plan.steps.entries()) {
+    if (step.kind === 'skill') {
+      outcomes.push(await applySkillStep(step, deps))
+      continue
+    }
+    const result = await deps.run('npm', ['install', '-g', `${step.name}@${step.to}`])
+    if (!result.ok) {
+      const detail = result.stderr.trim().split('\n').slice(-3).join('\n') || 'npm install failed'
+      outcomes.push({ ...step, status: 'failed', detail })
+      continue
+    }
+    outcomes.push({ ...step, status: 'done' })
+    const rest = plan.steps.slice(index + 1)
+    if (step.kind === 'package' && rest.length > 0) {
+      return [
+        ...outcomes,
+        ...(await handOff(
+          deps,
+          rest.map(later => later.kind)
+        )),
+      ]
+    }
+  }
+  return outcomes
+}
+
+/** `--only package,acpx,skill`: the kinds of step this run may take. */
+function parseOnly(raw: string | undefined): ReadonlySet<StepKind> | null {
+  if (raw === undefined) return null
+  const kinds = z.array(StepKindSchema).safeParse(raw.split(','))
+  if (!kinds.success) {
+    throw new UsageError(`--only takes a comma list of ${StepKindSchema.options.join(', ')}; got "${raw}"`)
+  }
+  return new Set(kinds.data)
+}
+
+/**
+ * `upgrade [--yes] [--only <kinds>]`: the plan on stderr, a confirmation, then one JSON line with
+ * what happened.
+ */
+export async function runUpgrade(deps: UpgradeDeps, argv: string[], io: CliIo): Promise<number> {
+  const { values } = parseArgs({
+    args: argv,
+    options: { yes: { type: 'boolean', short: 'y' }, only: { type: 'string' } },
+    strict: true,
+  })
+  const only = parseOnly(values.only)
+  const full = await planUpgrade(deps)
+  const plan: UpgradePlan =
+    only === null
+      ? full
+      : {
+          steps: full.steps.filter(step => only.has(step.kind)),
+          notes: [
+            ...full.notes,
+            ...full.steps
+              .filter(step => !only.has(step.kind))
+              .map(step => `left out by --only: ${describeStep(step)}`),
+          ],
+        }
+  for (const note of plan.notes) io.stderr(`  ${note}`)
+  if (plan.steps.length === 0) {
+    io.stderr('Everything is up to date.')
+    printJson(io, { applied: false, steps: [], notes: plan.notes })
+    return EXIT.ok
+  }
+  io.stderr('pr-review upgrade will:')
+  for (const step of plan.steps) io.stderr(`  - ${describeStep(step)}`)
+  if (plan.steps.some(step => step.kind === 'package')) {
+    io.stderr('  Once pr-review is upgraded, the new version checks and runs the steps after it.')
+  }
+
+  const confirmed = values.yes === true ? true : await deps.confirm('Proceed? [y/N] ')
+  if (confirmed !== true) {
+    io.stderr(confirmed === null ? 'Nothing changed. Re-run with --yes to apply.' : 'Nothing changed.')
+    printJson(io, { applied: false, steps: plan.steps, notes: plan.notes })
+    return EXIT.ok
+  }
+
+  const outcomes = await applyUpgrade(plan, deps)
+  for (const outcome of outcomes) {
+    io.stderr(
+      `  ${outcome.status}: ${describeStep(outcome)}${outcome.detail ? `\n    ${outcome.detail}` : ''}`
+    )
+  }
+  // A skill step lists only the copies it wrote, failed or not.
+  const refreshed = outcomes.flatMap(o => (o.kind === 'skill' ? o.paths : []))
+  if (refreshed.length > 0) {
+    io.stderr(`The project skill changed. Commit and push ${refreshed.join(' and ')} so your team gets it.`)
+  }
+  const ok = outcomes.every(o => o.status !== 'failed')
+  printJson(io, { applied: true, ok, steps: outcomes, notes: plan.notes })
+  return ok ? EXIT.ok : EXIT.error
+}

package/static/js/api.js

@@ -176,6 +176,60 @@ export function postComment(prNumber, input, opts = {}) {
   })
 }
 
+/**
+ * Adds one comment to the pending review. Nothing reaches the forge: it is kept in the local
+ * state until the review is submitted.
+ * @param {ReviewKey} prNumber
+ * @param {import('./contract-types.js').AddPendingInput} input
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<import('./contract-types.js').StateResponse>}
+ */
+export function addPending(prNumber, input, opts = {}) {
+  return fetchJson(`/api/prs/${prNumber}/pending`, {
+    method: 'POST',
+    body: input,
+    fetchImpl: opts.fetchImpl,
+  })
+}
+
+/**
+ * @param {ReviewKey} prNumber
+ * @param {string} id
+ * @param {string} body
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<import('./contract-types.js').StateResponse>}
+ */
+export function editPending(prNumber, id, body, opts = {}) {
+  return fetchJson(`/api/prs/${prNumber}/pending/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    body: { body },
+    fetchImpl: opts.fetchImpl,
+  })
+}
+
+/**
+ * @param {ReviewKey} prNumber
+ * @param {string} id
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<import('./contract-types.js').StateResponse>}
+ */
+export function deletePending(prNumber, id, opts = {}) {
+  return fetchJson(`/api/prs/${prNumber}/pending/${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+    fetchImpl: opts.fetchImpl,
+  })
+}
+
+/**
+ * Throws the whole pending review away.
+ * @param {ReviewKey} prNumber
+ * @param {{ fetchImpl?: typeof fetch }} [opts]
+ * @returns {Promise<import('./contract-types.js').StateResponse>}
+ */
+export function discardPending(prNumber, opts = {}) {
+  return fetchJson(`/api/prs/${prNumber}/pending`, { method: 'DELETE', fetchImpl: opts.fetchImpl })
+}
+
 /**
  * @param {ReviewKey} prNumber
  * @param {{ fetchImpl?: typeof fetch }} [opts]
@@ -187,7 +241,7 @@ export function fetchReviewBody(prNumber, opts = {}) {
 
 /**
  * @param {ReviewKey} prNumber
- * @param {{ event: 'APPROVE' | 'REQUEST_CHANGES', body?: string, headSha?: string }} input
+ * @param {{ event: import('./contract-types.js').ReviewEvent, body?: string, headSha?: string, includePending?: boolean }} input
  * @param {{ fetchImpl?: typeof fetch }} [opts]
  * @returns {Promise<import('./contract-types.js').PostReviewResponse>}
  */

package/static/js/app.js

@@ -13,30 +13,43 @@ import {
   saveAppearance,
 } from './api.js'
 import { setChatEnabled } from './ask.js'
-import { readChatWidth, renderChatShell, wireChat } from './chat.js'
+import { readChatMinimized, readChatWidth, renderChatShell, wireChat } from './chat.js'
 import { runCommand, wireCopyCommands } from './commands.js'
 import { initDeepLinks } from './deep-link.js'
 import { initDiagrams } from './diagram.js'
 import { esc, qs } from './dom.js'
 import { exportCanvasZip } from './download.js'
-import { carriedOverBarHtml, renderEmptyState, renderStaleState, staleBarHtml } from './empty-state.js'
+import {
+  carriedOverBarHtml,
+  marksCarriedBarHtml,
+  renderEmptyState,
+  renderStaleState,
+  staleBarHtml,
+} from './empty-state.js'
 import { errorCardHtml } from './errors.js'
 import { renderHeader } from './header.js'
 import { wireDropZone } from './import-zone.js'
 import { toast, wireReview } from './interactions.js'
-import { defineLayerElements, pathSet, renderLayers, renderRail, setRenderContext } from './layers.js'
+import {
+  defineLayerElements,
+  pathSet,
+  renderLayers,
+  renderRail,
+  setFoldLevel,
+  setRenderContext,
+} from './layers.js'
 import { renderOverview } from './overview.js'
 import { wireQuickQuestions } from './quick-questions.js'
 import { canvasChanged, openRegenerateDialog } from './regenerate.js'
 import { createReviewSession } from './review-session.js'
 import { initScrollSpy } from './scroll-spy.js'
 import { openSettingsDialog } from './settings.js'
-import { applySkin, nextSkin, readSkin, skinLabel } from './skin.js'
+import { applySkin, DEFAULT_SKIN, nextSkin, readSkin, skinLabel } from './skin.js'
 import { applyTheme, nextTheme, readTheme, themeLabel } from './theme.js'
 import { hostLabel, setHost } from './host.js'
 
 /** @typedef {import('./contract-types.js').ReviewKey} ReviewKey */
-/** @typedef {{ prNumber: ReviewKey, owner: string, repo: string, version: string, host: import('./contract-types.js').PublicHost }} Bootstrap */
+/** @typedef {import('./contract-types.js').ReviewBootstrap} Bootstrap */
 
 /** @returns {Bootstrap | null} */
 function readBootstrap() {
@@ -109,7 +122,7 @@ export class PrAppElement extends HTMLElement {
   /** @type {import('./theme.js').Theme} */
   theme = 'auto'
   /** @type {import('./skin.js').Skin} */
-  skin = 'terminal'
+  skin = DEFAULT_SKIN
   /** @type {{ stop: () => void } | null} */
   diagrams = null
   /** @type {{ stop: () => void } | null} */
@@ -160,6 +173,9 @@ export class PrAppElement extends HTMLElement {
     setHost(this.bootstrap.host)
     this.theme = readTheme(document.documentElement)
     this.skin = readSkin(document.documentElement)
+    // The reading level the canvas opens at comes from the settings file with the page, so the
+    // first draw hides what the reader asked for.
+    setFoldLevel(this, this.bootstrap.foldLevel)
     const patchesPromise = fetchPatches(this.bootstrap.prNumber).then(
       r => r.patches,
       () => null
@@ -199,6 +215,7 @@ export class PrAppElement extends HTMLElement {
     const header = renderHeader(bundle, { host: location.host, theme: this.theme, skin: this.skin, now })
     const chatEnabled = bundle.chat.enabled
     const storage = typeof localStorage === 'undefined' ? null : localStorage
+    const chatMinimized = chatEnabled && readChatMinimized(storage)
     // The renderers read this while they build the cards, so it is set before the first one.
     setChatEnabled(chatEnabled)
     const showsCanvas = bundle.artifact !== undefined && (bundle.status === 'ready' || this.viewStale)
@@ -218,10 +235,12 @@ export class PrAppElement extends HTMLElement {
         staleSha
       )
       // The context is set before any <pr-file> connects, so each card renders once, when visible.
+      const headSha = staleSha ?? bundle.pr.headSha
       setRenderContext({
         artifact,
         files,
         patches,
+        headSha,
         comments: bundle.comments.reviewComments,
         state: bundle.state,
         now,
@@ -233,10 +252,12 @@ export class PrAppElement extends HTMLElement {
           : bundle.carriedOver
             ? carriedOverBarHtml(bundle.carriedOver)
             : ''
+      const marksBar =
+        bundle.marksCarriedFrom === undefined ? '' : marksCarriedBarHtml(bundle.marksCarriedFrom)
       this.innerHTML =
         header +
         bannerHtml(bundle.warnings) +
-        `<div class="layout${chatEnabled ? '' : ' no-chat'}">${renderRail(artifact, bundle.state)}<main id="main">${staleBar}${renderOverview(bundle, { paths, now })}${renderLayers(artifact, files, bundle.state, bundle.comments.reviewComments)}</main>${renderChatShell({ enabled: chatEnabled, width: readChatWidth(storage) })}</div>` +
+        `<div class="layout${chatEnabled && !chatMinimized ? '' : ' no-chat'}">${renderRail(artifact, bundle.state)}<main id="main">${staleBar}${marksBar}${renderOverview(bundle, { paths, now })}${renderLayers(artifact, files, bundle.state, bundle.comments.reviewComments, headSha)}</main>${renderChatShell({ enabled: chatEnabled, width: readChatWidth(storage), minimized: chatMinimized })}</div>` +
         footerHtml(boot.version, bundle)
       // The screen is interactive from here: reviewed state, dismissals, threads, and posting.
       // A stale canvas shows the diff of an older commit, so nothing is posted from it: a line

package/static/js/chat-panel.js

@@ -1,42 +1,65 @@
 // @ts-check
 
 /** Keeps the same chat mounted while switching between the sidebar and floating panel.
+ *
+ * The chat minimizes at every width. Narrow screens float it over the canvas, so minimizing
+ * closes the dialog; wide screens dock it in the layout grid, so minimizing drops the column.
+ * Either way the launcher brings back the same pane with its draft and transcript intact.
+ *
  * @param {HTMLElement} root
  * @param {HTMLElement} pane
+ * @param {{ minimized?: boolean, onMinimizedChange?: (minimized: boolean) => void }} [opts]
  */
-export function wireChatPanel(root, pane) {
+export function wireChatPanel(root, pane, opts = {}) {
   const dialog = /** @type {HTMLDialogElement} */ (root.querySelector('#chat-dialog'))
   const launcher = /** @type {HTMLButtonElement} */ (root.querySelector('#chat-launcher'))
   const minimize = /** @type {HTMLButtonElement} */ (root.querySelector('#chat-minimize'))
+  const layout = root.querySelector('.layout')
   const narrow = window.matchMedia('(max-width: 1360px)')
   const mobile = window.matchMedia('(max-width: 600px)')
-  let expanded = false
+  /** Floating panels start minimized; a docked one starts the way the reader last left it. */
+  let floating = false
+  let docked = !opts.minimized
+
+  const shown = () => (narrow.matches ? floating : docked)
 
   function sync() {
     if (dialog.open) dialog.close()
     if (narrow.matches) {
       dialog.append(pane)
-      if (expanded) {
+      pane.hidden = false
+      if (floating) {
         if (mobile.matches) dialog.showModal()
         else dialog.show()
       }
     } else {
       dialog.before(pane)
+      pane.hidden = !docked
     }
-    launcher.setAttribute('aria-expanded', String(narrow.matches && expanded))
-    launcher.hidden = narrow.matches && expanded
+    layout?.classList.toggle('no-chat', !narrow.matches && !docked)
+    launcher.setAttribute('aria-expanded', String(shown()))
+    launcher.hidden = shown()
   }
 
   function open() {
-    if (narrow.matches && !expanded) {
-      expanded = true
+    if (!shown()) {
+      if (narrow.matches) floating = true
+      else {
+        docked = true
+        opts.onMinimizedChange?.(false)
+      }
       sync()
     }
-    pane.querySelector('textarea')?.focus()
+    // The composer sits low in a tall sticky pane, so plain focus() would scroll the canvas to it.
+    pane.querySelector('textarea')?.focus({ preventScroll: true })
   }
 
   function close() {
-    expanded = false
+    if (narrow.matches) floating = false
+    else {
+      docked = false
+      opts.onMinimizedChange?.(true)
+    }
     sync()
     launcher.focus()
   }

package/static/js/chat.js

@@ -27,12 +27,13 @@ import { postToLabel } from './host.js'
 import { splitChatAnswer, targetsFromFiles } from './proposed-comment.js'
 
 export const CHAT_WIDTH_KEY = 'pr-review.chat-width'
+export const CHAT_MINIMIZED_KEY = 'pr-review.chat-minimized'
 export const CHAT_WIDTH_MIN = 280
 export const CHAT_WIDTH_MAX = 560
 export const CHAT_WIDTH_DEFAULT = 340
 
 /**
- * @param {{ enabled: boolean, width?: number }} opts
+ * @param {{ enabled: boolean, width?: number, minimized?: boolean }} opts
  * @returns {string} '' when AI Chat is disabled
  */
 export function renderChatShell(opts) {
@@ -40,8 +41,10 @@ export function renderChatShell(opts) {
     return ''
   }
   const width = clampWidth(opts.width ?? CHAT_WIDTH_DEFAULT)
+  // The launcher starts hidden and `wireChatPanel` reveals it where it belongs, so a docked
+  // chat never paints a launcher over itself on the first frame.
   return (
-    '<aside class="chat" aria-labelledby="chat-h">' +
+    `<aside class="chat" aria-labelledby="chat-h"${opts.minimized ? ' hidden' : ''}>` +
     `<button class="handle" type="button" id="chat-handle" role="separator" aria-orientation="vertical" aria-label="Resize AI Chat" aria-valuenow="${width}" aria-valuemin="${CHAT_WIDTH_MIN}" aria-valuemax="${CHAT_WIDTH_MAX}"></button>` +
     '<div class="chat-h"><h2 id="chat-h">AI Chat</h2><label class="sr" for="thread">Thread</label>' +
     '<select id="thread"></select>' +
@@ -60,7 +63,7 @@ export function renderChatShell(opts) {
     '<span class="muted small">enter to send</span></div></form>' +
     '</aside>' +
     '<dialog class="chat-dialog" id="chat-dialog" aria-labelledby="chat-h"></dialog>' +
-    '<button class="chat-launcher" id="chat-launcher" type="button" aria-controls="chat-dialog" aria-expanded="false">AI Chat</button>'
+    '<button class="chat-launcher" id="chat-launcher" type="button" hidden aria-controls="chat-dialog" aria-expanded="false">AI Chat</button>'
   )
 }
 
@@ -102,6 +105,23 @@ export function writeChatWidth(storage, width) {
   storage?.setItem(CHAT_WIDTH_KEY, String(clampWidth(width)))
 }
 
+/**
+ * Only a wide screen stores this: a floating chat always starts minimized.
+ * @param {Storage | null} storage
+ * @returns {boolean}
+ */
+export function readChatMinimized(storage) {
+  return (storage === null ? null : storage.getItem(CHAT_MINIMIZED_KEY)) === '1'
+}
+
+/**
+ * @param {Storage | null} storage
+ * @param {boolean} minimized
+ */
+export function writeChatMinimized(storage, minimized) {
+  storage?.setItem(CHAT_MINIMIZED_KEY, minimized ? '1' : '0')
+}
+
 /** The questions the quick menu offers, and the one that just focuses the box. */
 export const QUICK_QUESTIONS = [
   'Suggestion to solve this?',
@@ -749,7 +769,10 @@ export function wireChat(options) {
   }
 
   const stopResize = wireResize(pane, root, storage, applyWidth)
-  const panel = wireChatPanel(root, pane)
+  const panel = wireChatPanel(root, pane, {
+    minimized: readChatMinimized(storage),
+    onMinimizedChange: minimized => writeChatMinimized(storage, minimized),
+  })
 
   form.addEventListener('submit', onSubmit)
   root.addEventListener('click', onClick)