@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/src/review/test-paths.ts

@@ -2,11 +2,51 @@ import path from 'node:path'
 import { matchesGlob } from './glob.js'
 
 /**
- * What counts as a test file when the project config says nothing: the JavaScript and TypeScript
- * conventions this repository uses. `tests.patterns` in `pr-review.config.yml` replaces the list,
- * so a Python or Go project can name `test_*.py` or `*_test.go` instead.
+ * The languages whose test classes are named `XTest` or `XTests`. Only these extensions, so a
+ * component such as `ABTest.tsx` is not taken for a test.
  */
-export const DEFAULT_TEST_PATTERNS: readonly string[] = ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
+const CLASS_TEST_EXTENSIONS = ['java', 'kt', 'scala', 'groovy', 'cs', 'fs', 'vb', 'swift', 'php'] as const
+
+/**
+ * The test conventions found across stacks, by directory and by file-name shape rather than by
+ * language, so a repository without a `pr-review.config.yml` still gets its tests labelled,
+ * ordered after the code they cover, and kept open at the light reading level. Directories:
+ * `__tests__`, `tests`, `test`. Names: `x.test.*` and `x.spec.*` (JS/TS), `x_test.*` (Go,
+ * Python, Elixir, Dart, Rust), `test_x.py` and `conftest.py` (pytest), `x_spec.*` (Ruby),
+ * `XTest` and `XTests` in the class-test languages above. A `spec/` directory is left out: it
+ * often holds API specs rather than tests. `tests.patterns` replaces the list.
+ */
+export const DEFAULT_TEST_PATTERNS: readonly string[] = [
+  '**/__tests__/**',
+  '**/tests/**',
+  '**/test/**',
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/*_test.*',
+  '**/*_spec.*',
+  '**/test_*.py',
+  '**/conftest.py',
+  ...CLASS_TEST_EXTENSIONS.flatMap(ext => [`**/*Test.${ext}`, `**/*Tests.${ext}`]),
+]
+
+/**
+ * Generated content that lives beside tests: snapshots and fixtures. They are test paths, but
+ * nobody reads them line by line, so they may hide at the light level like any generated file.
+ */
+export const GENERATED_TEST_PATTERNS: readonly string[] = [
+  '**/__snapshots__/**',
+  '**/*.snap',
+  '**/fixtures/**',
+  '**/__fixtures__/**',
+]
+
+/** True for a test path a reviewer reads as written: a test path that is not a snapshot or fixture. */
+export function isHandWrittenTest(
+  filePath: string,
+  patterns: readonly string[] = DEFAULT_TEST_PATTERNS
+): boolean {
+  return isTestPath(filePath, patterns) && !isTestPath(filePath, GENERATED_TEST_PATTERNS)
+}
 
 /** True when one of the patterns matches the repo-relative path. */
 export function isTestPath(filePath: string, patterns: readonly string[] = DEFAULT_TEST_PATTERNS): boolean {

package/src/review/validate-folds.ts

@@ -1,11 +1,82 @@
-import type { CodeFold, FileEntry, Hunk, ModelLayer, ModelOutput } from '../contract/review-artifact.js'
+import type {
+  CodeFold,
+  FileEntry,
+  FoldLevel,
+  Hunk,
+  ModelLayer,
+  ModelOutput,
+} from '../contract/review-artifact.js'
+import {
+  contains,
+  coveredRows,
+  fileRows,
+  foldLevelRank,
+  hiddenLines,
+  UNDISCUSSED,
+} from '../contract/review-artifact.js'
 import type { ValidationError } from '../contract/validation.js'
 import { hunkForLine } from '../git/patch-lines.js'
+import { DEFAULT_TEST_PATTERNS, isHandWrittenTest } from './test-paths.js'
+
+/**
+ * Rows a reviewer reads without help. Above this many diff rows outside its annotations, a file
+ * with no attention point must hide something at some level: the reading-level control exists to
+ * take routine code off the screen, and a routine file left fully open at every level defeats it.
+ * An annotation marks the lines to read; it does not make the rows around it any less routine.
+ * The same count decides when a layer has enough left open at `moderate` for `aggressive` to owe
+ * a difference.
+ */
+export const ROUTINE_ROWS = 20
+
+/**
+ * At or below this many diff rows, a layer reads whole and the levels have little to add, so the
+ * layer rule about `aggressive` hiding more than `moderate` does not apply. The file rules still
+ * do: a routine file hides something, and a core file folds half, whatever the layer's size.
+ */
+export const SMALL_LAYER_ROWS = 100
+
+/**
+ * The most a `light` fold may cover. Light is the diff as it always looked, plus wholly generated
+ * blocks; a wider range is hand-written code dressed as generated, and hiding it by default is
+ * what the higher levels are for.
+ */
+export const LIGHT_FOLD_MAX_ROWS = 40
+
+/**
+ * Above this many rows, a file that stays open is a core file the reviewer reads, and by
+ * `aggressive` it must fold at least `AGGRESSIVE_MIN_HIDDEN` of the rows outside its attention
+ * points. Annotated rows count: an aggressive fold may hide them, and leaving them out would let a
+ * generator lower the bar by annotating more. Otherwise aggressive shows the same core as moderate.
+ */
+export const CORE_FILE_ROWS = 60
+export const AGGRESSIVE_MIN_HIDDEN = 0.5
 
 type SourceRange = Pick<CodeFold, 'side' | 'startLine' | 'endLine'>
+type LeveledRange = SourceRange & { level: FoldLevel }
 type ModelFile = ModelLayer['files'][number]
 
-function assignedHunk(fold: CodeFold, file: ModelFile, hunks: readonly Hunk[]): Hunk | null {
+/** One file's folds as the rules read them, with the ranges a fold may not cover. */
+interface FileFolds {
+  file: ModelFile
+  hunks: readonly Hunk[]
+  where: string
+  /** Attention points and the marker a missing test adds: no fold ever hides these. */
+  pinned: SourceRange[]
+  /** Only an aggressive fold may hide these, and the file they are in never collapses. */
+  annotations: SourceRange[]
+  folds: LeveledRange[]
+  collapsed: FoldLevel | null
+  /** Diff rows the file draws, the longer side of each of its hunks. */
+  rows: number
+  /**
+   * Rows outside the attention points: what a fold may be asked to hide. Annotated rows are among
+   * them, because an aggressive fold may hide them, and leaving them out would let a generator
+   * lower the bar by annotating more.
+   */
+  judged: number
+}
+
+function assignedHunk(fold: SourceRange, file: ModelFile, hunks: readonly Hunk[]): Hunk | null {
   if (fold.endLine < fold.startLine) {
     return null
   }
@@ -20,6 +91,11 @@ function assignedHunk(fold: CodeFold, file: ModelFile, hunks: readonly Hunk[]):
   return start
 }
 
+/** Whether `outer` holds every line of `inner`, on the same side. */
+function covers(outer: SourceRange, inner: SourceRange): boolean {
+  return outer.side === inner.side && outer.startLine <= inner.startLine && inner.endLine <= outer.endLine
+}
+
 /** Different coordinate sides in one hunk need the full patch to prove they are separate. */
 function rangesOverlap(left: SourceRange, right: SourceRange, hunks: readonly Hunk[]): boolean {
   const leftHunk = hunkForLine(hunks, left.side, left.startLine)
@@ -32,13 +108,47 @@ function rangesOverlap(left: SourceRange, right: SourceRange, hunks: readonly Hu
   return left.side !== right.side || (left.startLine <= right.endLine && right.startLine <= left.endLine)
 }
 
-function protectedRanges(
+/**
+ * How two folds of one file sit together. Levels nest, so a fold may sit inside a fold of a higher
+ * level: at the lower level the reader opens the outer one and still finds the inner one folded.
+ * Anything else leaves the page unable to say which summary owns a row.
+ */
+function foldRelation(
+  left: LeveledRange,
+  right: LeveledRange,
+  hunks: readonly Hunk[]
+): 'separate' | 'nested' | 'partial' | 'same-range' {
+  if (!rangesOverlap(left, right, hunks)) {
+    return 'separate'
+  }
+
+  if (left.side !== right.side) {
+    return 'partial'
+  }
+
+  if (left.startLine === right.startLine && left.endLine === right.endLine) {
+    return 'same-range'
+  }
+
+  if (contains(left, right)) {
+    return foldLevelRank(right.level) < foldLevelRank(left.level) ? 'nested' : 'partial'
+  }
+
+  if (contains(right, left)) {
+    return foldLevelRank(left.level) < foldLevelRank(right.level) ? 'nested' : 'partial'
+  }
+
+  return 'partial'
+}
+
+/** Ranges no fold may ever hide: attention points, and the marker a missing test adds. */
+function pinnedRanges(
   file: ModelFile,
   layer: ModelLayer,
   output: ModelOutput,
   hunks: readonly Hunk[]
 ): SourceRange[] {
-  const ranges: SourceRange[] = [...file.annotations]
+  const ranges: SourceRange[] = []
   const points = output.points.filter(point => point.path === file.path)
 
   for (const point of points) {
@@ -62,23 +172,59 @@ function protectedRanges(
   return ranges
 }
 
-function validateFileFolds(
+function fileFolds(
   file: ModelFile,
   layer: ModelLayer,
   output: ModelOutput,
   hunks: readonly Hunk[]
-): ValidationError[] {
-  const errors: ValidationError[] = []
-  const where = `layer:${layer.key}/file:${file.path}`
-  const protectedCode = protectedRanges(file, layer, output, hunks)
-  const folds = file.folds ?? []
+): FileFolds {
+  const pinned = pinnedRanges(file, layer, output, hunks)
+  const rows = fileRows(file, hunks)
+  return {
+    file,
+    hunks,
+    where: `layer:${layer.key}/file:${file.path}`,
+    pinned,
+    annotations: [...file.annotations],
+    folds: file.folds ?? [],
+    collapsed: file.collapsed ?? null,
+    rows,
+    judged: Math.max(rows - coveredRows(pinned), 0),
+  }
+}
+
+function error(code: ValidationError['code'], where: string, message: string): ValidationError {
+  return { code, where, message: `${where}: ${message}` }
+}
 
+/**
+ * The rules every canvas meets, whenever it was written: fold coordinates fit the assigned hunks,
+ * folds nest or stay apart, attention points stay visible at every level, and an annotation is
+ * hidden only by an aggressive fold and never by a collapse of its file.
+ */
+function correctnessErrors({
+  file,
+  hunks,
+  where,
+  pinned,
+  annotations,
+  folds,
+  collapsed,
+}: FileFolds): ValidationError[] {
+  const errors: ValidationError[] = []
   const fail = (message: string): void => {
-    errors.push({ code: 'FOLD_INVALID', where, message: `${where}: ${message}` })
+    errors.push(error('FOLD_INVALID', where, message))
   }
 
-  if (file.collapsed && protectedCode.length > 0) {
-    fail('a file with annotations or attention points must start expanded')
+  // A fold that covers an annotation shows the annotation's text as its title; a collapsed file
+  // shows nothing but its path. So an annotated file never collapses, at any level, and hides
+  // its routine parts with folds instead.
+  if (collapsed !== null) {
+    if (pinned.length > 0) {
+      fail('a file with attention points must start expanded')
+    } else if (annotations.length > 0) {
+      fail('a file with annotations never collapses; fold the ranges around them instead')
+    }
   }
 
   for (const [index, fold] of folds.entries()) {
@@ -87,24 +233,203 @@ function validateFileFolds(
       continue
     }
 
-    const earlierFolds = folds.slice(0, index)
-    if (earlierFolds.some(earlier => rangesOverlap(fold, earlier, hunks))) {
-      fail(`fold ${index + 1} overlaps an earlier fold or uses another coordinate side in the same chunk`)
+    for (const earlier of folds.slice(0, index)) {
+      const relation = foldRelation(fold, earlier, hunks)
+      if (relation === 'same-range') {
+        fail(`fold ${index + 1} repeats the range of an earlier fold`)
+      } else if (relation === 'partial') {
+        fail(
+          `fold ${index + 1} partly overlaps an earlier fold, uses another coordinate side in the same chunk, ` +
+            'or nests inside a fold of the same or a lower level'
+        )
+      }
+    }
+
+    if (pinned.some(range => rangesOverlap(fold, range, hunks))) {
+      fail(`fold ${index + 1} would hide an attention point`)
     }
 
-    if (protectedCode.some(range => rangesOverlap(fold, range, hunks))) {
-      fail(`fold ${index + 1} would hide an annotation or attention point`)
+    // An aggressive fold shows the text of the annotation it hides as its title, so it hides one
+    // whole annotation at most: a second one, or a part of one, would vanish without its text.
+    const hidden = annotations.filter(range => rangesOverlap(fold, range, hunks))
+    if (hidden.length > 0 && fold.level !== 'aggressive') {
+      fail(`fold ${index + 1} would hide an annotation, which only an aggressive fold may do`)
+    } else if (hidden.length > 1) {
+      fail(
+        `fold ${index + 1} hides ${hidden.length} annotations; an aggressive fold may hide one, and shows its text`
+      )
+    } else if (hidden.some(range => !covers(fold, range))) {
+      fail(
+        `fold ${index + 1} hides part of an annotation; an aggressive fold covers a whole annotation or none of it`
+      )
     }
   }
 
   return errors
 }
 
-/** Checks fold coordinates and keeps attention points and annotations visible. */
-export function validateFolds(output: ModelOutput, files: readonly FileEntry[]): ValidationError[] {
+/**
+ * The rules a fresh generation meets for one file, about what the reading levels must be given to
+ * hide: a hand-written test file keeps its titles at light, a light fold is one generated block, a file with
+ * over `ROUTINE_ROWS` unannotated rows and no attention point hides something somewhere, and an
+ * open core file folds half of what the reviewer need not judge by aggressive. A stored canvas
+ * may predate them.
+ */
+function generationErrors(
+  { file, hunks, where, pinned, annotations, folds, collapsed, rows, judged }: FileFolds,
+  isTest: boolean
+): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  // Light leaves tests exactly as the diff shows them; the bodies fold from moderate. Snapshots
+  // and fixtures are generated, so they are not held to this.
+  if (isTest && collapsed === 'light') {
+    errors.push(
+      error(
+        'FOLD_INVALID',
+        where,
+        'a test file never collapses at light; fold each test body under its title, or collapse the file at moderate'
+      )
+    )
+  }
+
+  for (const [index, fold] of folds.entries()) {
+    if (isTest && fold.level === 'light') {
+      errors.push(
+        error(
+          'FOLD_INVALID',
+          where,
+          `fold ${index + 1} is light in a test file; light leaves tests as the diff shows them — ` +
+            'fold each test body under its title at moderate'
+        )
+      )
+    }
+
+    const span = fold.endLine - fold.startLine + 1
+    if (fold.level === 'light' && span > LIGHT_FOLD_MAX_ROWS) {
+      errors.push(
+        error(
+          'FOLD_INVALID',
+          where,
+          `fold ${index + 1} at light covers ${span} rows; a light fold is one test body or one generated ` +
+            'block — fold each test under its own title, or give the range moderate'
+        )
+      )
+    }
+  }
+
+  if (collapsed !== null) {
+    return errors
+  }
+
+  // An attention point is budgeted and always visible, so a file that carries one may stay open
+  // for it. An annotation is not a licence: it marks the lines to read, and the rows around it are
+  // as routine as in any other file.
+  const unannotated = Math.max(rows - coveredRows(annotations), 0)
+  if (pinned.length === 0 && unannotated > ROUTINE_ROWS && folds.length === 0) {
+    errors.push(
+      error(
+        'FOLD_MISSING',
+        where,
+        annotations.length === 0
+          ? `${rows} changed lines with no attention point or annotation, and nothing hidden at ` +
+              'any level; collapse the file or fold its routine ranges'
+          : `${rows} changed lines, ${unannotated} of them outside its annotations, and nothing hidden ` +
+              'at any level; an annotation marks what to read — fold the routine ranges around it'
+      )
+    )
+  } else if (rows > CORE_FILE_ROWS) {
+    // Every fold hides at aggressive, whatever its own level, so what the reader is left with
+    // there is the page's own count.
+    const { hidden } = hiddenLines(file, hunks, 'aggressive', UNDISCUSSED)
+    if (hidden < Math.ceil(judged * AGGRESSIVE_MIN_HIDDEN)) {
+      errors.push(
+        error(
+          'FOLD_MISSING',
+          where,
+          `${hidden} of ${rows} changed lines hide at aggressive; a core file keeps its defining ` +
+            `lines and folds the rest, at least half of the ${judged} lines outside its attention points`
+        )
+      )
+    }
+  }
+
+  return errors
+}
+
+/**
+ * The rule a fresh generation meets for a layer as a whole, once the layer is bigger than
+ * `SMALL_LAYER_ROWS`: where `moderate` leaves more than `ROUTINE_ROWS` rows open outside the
+ * attention points, `aggressive` hides some of them. The prompt asks the generator to check this
+ * itself, and a layer with the same count at both levels is the one that has not. A file that
+ * fails its own rule may fail this one too; both name a fix, and the file's is the smaller one.
+ */
+function layerErrors(layer: ModelLayer, files: readonly FileFolds[]): ValidationError[] {
+  let rows = 0
+  let judged = 0
+  let hiddenAtModerate = 0
+  let hiddenAtAggressive = 0
+
+  for (const folds of files) {
+    rows += folds.rows
+    judged += folds.judged
+    hiddenAtModerate += hiddenLines(folds.file, folds.hunks, 'moderate', UNDISCUSSED).hidden
+    hiddenAtAggressive += hiddenLines(folds.file, folds.hunks, 'aggressive', UNDISCUSSED).hidden
+  }
+
+  const open = Math.max(judged - hiddenAtModerate, 0)
+  if (rows <= SMALL_LAYER_ROWS || open <= ROUTINE_ROWS || hiddenAtAggressive > hiddenAtModerate) {
+    return []
+  }
+
+  return [
+    error(
+      'FOLD_MISSING',
+      `layer:${layer.key}`,
+      `${open} changed lines stay open at moderate outside the attention points, and aggressive hides ` +
+        'none of them; aggressive leaves only the core on screen — collapse the files outside it, ' +
+        'fold the routine ranges inside it'
+    ),
+  ]
+}
+
+/**
+ * Checks fold coordinates and keeps attention points visible at every level. An annotation stays
+ * visible below aggressive, and its file never collapses. A fresh generation is also held to what
+ * the reading levels must be given to hide; a stored artifact is not, because its generator may
+ * predate those rules.
+ */
+export function validateFolds(
+  output: ModelOutput,
+  files: readonly FileEntry[],
+  options: FoldValidationOptions = {}
+): ValidationError[] {
   const byPath = new Map(files.map(file => [file.path, file]))
+  const testPatterns = options.testPatterns ?? DEFAULT_TEST_PATTERNS
+
+  return output.layers.flatMap(layer => {
+    const layerFiles = layer.files.map(file =>
+      fileFolds(file, layer, output, byPath.get(file.path)?.hunks ?? [])
+    )
+    if (options.storedArtifact === true) {
+      return layerFiles.flatMap(correctnessErrors)
+    }
+    return [
+      ...layerFiles.flatMap(folds => [
+        ...correctnessErrors(folds),
+        ...generationErrors(folds, isHandWrittenTest(folds.file.path, testPatterns)),
+      ]),
+      ...layerErrors(layer, layerFiles),
+    ]
+  })
+}
 
-  return output.layers.flatMap(layer =>
-    layer.files.flatMap(file => validateFileFolds(file, layer, output, byPath.get(file.path)?.hunks ?? []))
-  )
+export interface FoldValidationOptions {
+  /** The globs that make a file a test; the built-in list when omitted. */
+  testPatterns?: readonly string[] | undefined
+  /**
+   * The output was read back from a stored `review.json`, whose generator may predate the rules
+   * about what a canvas must hide. Only the correctness rules apply then.
+   */
+  storedArtifact?: boolean | undefined
 }

package/src/review/validate.ts

@@ -32,6 +32,12 @@ export interface ValidationInput {
   headPaths?: ReadonlySet<string>
   /** The globs that make a file a test; the project config's list, or the built-in one. */
   testPatterns?: readonly string[] | undefined
+  /**
+   * The output was read back from a stored `review.json`, whose generator may predate the rules
+   * about what a canvas must hide. Only the correctness rules apply then: coordinates, and the
+   * ranges no fold may cover. A fresh `model.json` is held to the full shape.
+   */
+  storedArtifact?: boolean | undefined
 }
 
 export type ValidationResult = ValidationReport & { output: ModelOutput | null }
@@ -560,7 +566,10 @@ export function validateModelOutput(raw: unknown, input: ValidationInput): Valid
   checkTests(output, index, input.headPaths ?? new Set(), input.testPatterns ?? DEFAULT_TEST_PATTERNS, report)
   checkRisk(output, input.highRisk, report)
   checkAnnotations(output, index, report)
-  for (const error of validateFolds(output, input.files)) {
+  for (const error of validateFolds(output, input.files, {
+    testPatterns: input.testPatterns ?? DEFAULT_TEST_PATTERNS,
+    storedArtifact: input.storedArtifact === true,
+  })) {
     report.add(error.code, error.where ?? 'folds', error.message)
   }
   checkPoints(output, index, input.limits, report)

package/src/server/bundle.ts

@@ -15,6 +15,7 @@ import { describeLocalWork, resolveLocalBase } from '../git/local-target.js'
 import { fetchPrRefs } from '../git/pr-refs.js'
 import { toPr } from '../host/pr.js'
 import { lookupCanvas } from '../review/carry-over.js'
+import { marksForCanvas } from '../review/carry-marks.js'
 import { reviewedCommit, stateForCanvas } from '../review/review-body.js'
 import { discoverSharedCanvas, discoveryFingerprint } from '../host/attachments.js'
 import { buildSkillCommand } from '../review/skill-command.js'
@@ -320,6 +321,8 @@ async function bundleBase(
     diff: ShownDiff
     /** The commit of the canvas on screen: the marks the page shows are the ones made on it. */
     canvasSha: string
+    /** The canvas on screen, when there is one: marks may follow the line of descent onto it. */
+    artifact: ReviewArtifact | null
     warnings: string[]
   }
 ): Promise<Omit<PrBundle, 'status' | 'skillCommand'>> {
@@ -333,13 +336,19 @@ async function bundleBase(
   if (chatEnabled && !acpx.installed) {
     input.warnings.push('acpx is not on PATH, so the AI Chat pane is off; install acpx to turn it on')
   }
+  // With no canvas to read, a mark counts only when it was made on this very commit. With one,
+  // marks made on a canvas it descends from follow it wherever the diff is untouched.
+  const marks =
+    input.artifact === null
+      ? { state: stateForCanvas(stored, input.canvasSha), carriedFrom: undefined }
+      : await marksForCanvas(ctx, input.artifact, input.canvasSha, stored)
   return {
     pr: input.pr,
     files: input.diff.files,
     derivable: input.diff.derivable,
     comments: input.comments,
-    // Marks made on another canvas describe other code, so the page never shows them as reviewed.
-    state: stateForCanvas(stored, input.canvasSha),
+    state: marks.state,
+    ...(marks.carriedFrom === undefined ? {} : { marksCarriedFrom: marks.carriedFrom }),
     capabilities,
     chat: {
       enabled: chatEnabled && acpx.installed,
@@ -400,6 +409,7 @@ export async function resolveLocalBundle(
     capabilities: Promise.resolve(LOCAL_CAPABILITIES),
     diff,
     canvasSha: reviewedCommit(found, pr),
+    artifact: loaded?.artifact ?? null,
     warnings,
   })
   const { warning: _screenWarning, ...screenFields } = screen
@@ -430,6 +440,7 @@ export async function resolveBundle(
       capabilities,
       diff,
       canvasSha: pr.headSha,
+      artifact: null,
       warnings,
     })
     const canvas: CanvasInfo = { headSha: pr.headSha, source: 'fixture', manifest: null }
@@ -472,6 +483,7 @@ export async function resolveBundle(
     capabilities,
     diff,
     canvasSha: reviewedCommit(found, pr),
+    artifact: loaded?.artifact ?? null,
     warnings,
   })
   const shared = sharedCanvas === null ? {} : { sharedCanvas }

package/src/server/html.ts

@@ -1,7 +1,7 @@
 import { html, raw } from 'hono/html'
 import type { HtmlEscapedString } from 'hono/utils/html'
-import type { ErrorEnvelope, HomeData } from '../contract/api.js'
-import { keyLabel, keyToString, type LocalKey, type ReviewKey } from '../contract/review-key.js'
+import type { ErrorEnvelope, HomeData, ReviewBootstrap } from '../contract/api.js'
+import { keyLabel, keyToString, type LocalKey } from '../contract/review-key.js'
 import type { Appearance } from '../contract/settings.js'
 import { type Host, publicHost } from '../host/host.js'
 
@@ -70,11 +70,11 @@ ${opts.app ? html`<script type="module" src="/static/js/app.js"></script>` : ''}
 }
 
 export function reviewPage(
-  page: { prNumber: ReviewKey; owner: string; repo: string; version: string; host: Host },
+  page: Omit<ReviewBootstrap, 'host'> & { host: Host },
   nonce: string,
   appearance: Appearance
 ): Html {
-  const bootstrap = { ...page, host: publicHost(page.host) }
+  const bootstrap: ReviewBootstrap = { ...page, host: publicHost(page.host) }
   const key = keyToString(bootstrap.prNumber)
   const what =
     typeof bootstrap.prNumber === 'number' ? `${page.host.nounShort} #${key}` : keyLabel(bootstrap.prNumber)

package/src/server/routes/chat-routes.ts

@@ -1,6 +1,6 @@
-// The AI Chat pane's routes and the personal settings behind it. Every route here answers 404
-// when the project config turns chat off, so a repository that does not want an agent in the
-// loop has no agent surface at all.
+// The AI Chat pane's routes and the personal settings behind it. Every chat and agent route here
+// answers 404 when the project config turns chat off, so a repository that does not want an agent
+// in the loop has no agent surface at all; the settings file stays reachable for the reading level.
 import { Hono, type MiddlewareHandler } from 'hono'
 import { ChatBusyError } from '../../chat/chat-manager.js'
 import { ChatContextError } from '../../chat/context.js'
@@ -124,13 +124,22 @@ function withDiff(artifact: ReviewArtifact, headSha: string, derived: Derived |
   return { artifact, headSha, files: derived.files, patches: derived.patches }
 }
 
-/** Every path this file serves, so the chat-disabled check covers all of them and nothing else. */
-export const CHAT_ROUTE_PATTERNS = ['/settings', '/settings/*', '/prs/:n/chat', '/prs/:n/chat/*'] as const
+/**
+ * Every chat path this file serves, so the chat-disabled check covers all of them and nothing
+ * else. `/settings` itself stays open: the settings file also holds the reading level a review
+ * opens at, which the page reads whether or not chat is on.
+ */
+export const CHAT_ROUTE_PATTERNS = [
+  '/settings/agents',
+  '/settings/agents/*',
+  '/prs/:n/chat',
+  '/prs/:n/chat/*',
+] as const
 
 export function chatRoutes(ctx: AppContext, loader: PrLoader): Hono {
   const api = new Hono()
 
-  // With chat off, none of these routes exist. The patterns are listed rather than `*`: this
+  // With chat off, none of the chat routes exist. The patterns are listed rather than `*`: this
   // app is mounted at the API root, so a blanket middleware would answer for every route.
   const requireChat: MiddlewareHandler = async (_c, next) => {
     if (!ctx.projectConfig.config.chat.enabled) {

package/src/server/routes/pages.ts

@@ -61,6 +61,8 @@ export function pageRoutes(ctx: AppContext): Hono<AppEnv> {
         'use /review/<number>, /review/branch, or /review/uncommitted'
       )
     }
+    // One read serves both the appearance and the reading level the canvas opens at.
+    const settings = await ctx.settings.read()
     return c.html(
       reviewPage(
         {
@@ -69,9 +71,10 @@ export function pageRoutes(ctx: AppContext): Hono<AppEnv> {
           repo: ctx.config.repo.name,
           version: ctx.version,
           host: ctx.config.host,
+          foldLevel: settings.foldLevel,
         },
         c.get('cspNonce'),
-        await appearanceFor(ctx, appearanceQuery(c))
+        appearanceForRequest(settings, appearanceQuery(c))
       )
     )
   })