@cat-factory/app 0.201.1 → 0.204.0

package/app/utils/binaryOutput.ts

@@ -0,0 +1,343 @@
+import { ASSET_STORAGE_CAPABILITY } from '@cat-factory/contracts'
+import type {
+  BinaryOutputArtifact,
+  BinaryOutputConfig,
+  BinaryOutputReport,
+  PipelineStep,
+} from '~/types/execution'
+import type { ResolvedFoundationalService } from '~/types/domain'
+
+// ---------------------------------------------------------------------------
+// The read model behind the binary-output surface
+// (docs/initiatives/binary-output-foundational-storage.md).
+//
+// A step whose kind carries the `binary-output` trait delivers BINARY artifacts through a
+// foundational service its step selected, and declares what it stored in a fenced block the
+// engine parses onto `step.binaryOutputs`. That parse deliberately keeps every failure mode
+// apart — `undeclared` ≠ `parseFailed` ≠ an empty `stored`, with `invalidEntries` / `omitted`
+// / `unknownServices` counted or named rather than absorbed — so the whole job of this module
+// is to NOT collapse them again on the way to a renderer.
+//
+// Pure: it reads the step's own recorded report and its own recorded selection, and nothing
+// else. That is deliberate — the join a human actually wants ("did it go where I pointed
+// it?") is answerable from those two alone, so the surface needs no catalog fetch and reads
+// identically for a run whose services were withdrawn afterwards.
+// ---------------------------------------------------------------------------
+
+/**
+ * What a step's binary-output record says happened, as one discriminant. Every member is a
+ * DIFFERENT fact with a different fix, and the renderer keys its copy off an exhaustive map so
+ * a sixth member fails the typecheck rather than rendering a missing key.
+ *
+ * There is deliberately no "was never briefed" member: that is {@link binaryOutputView}
+ * returning null and the surface disappearing, exactly as the effort and validation sections
+ * do. A row saying "no binary output was expected here" would ride every step of every run.
+ */
+export type BinaryOutputState =
+  /** The step selected a storage service and has not started yet, so there is nothing to have
+   *  recorded. Its own fact, for the same reason a SKIPPED step renders nothing: `configured`
+   *  says "running, or it died", and a queued step is neither. What it does say is worth
+   *  saying — this is where the artifacts will land — so it renders rather than disappearing. */
+  | 'not-started'
+  /** The step STARTED, selected a storage service, and no declaration has been recorded — it is
+   *  still running, or it died before settlement. NOT "stored nothing". */
+  | 'configured'
+  /** The step settled and its reply carried no declaration block at all. The agent may or may
+   *  not have stored something; nothing was recorded either way. */
+  | 'undeclared'
+  /** A declaration block was present and unreadable. Same practical outcome as `undeclared`,
+   *  different cause — and the only one of the two that is a prompt/model problem. */
+  | 'parse-failed'
+  /** The agent explicitly declared it stored nothing. A legitimate outcome, not an error. */
+  | 'declared-none'
+  /** The agent declared artifacts; {@link BinaryOutputView.rows} holds them. */
+  | 'stored'
+
+/** One declared artifact, with the two judgements the step's own record supports. */
+export interface BinaryOutputRow extends BinaryOutputArtifact {
+  /**
+   * The artifact was stored through a service OTHER than the one this step selected. Not an
+   * error the platform can settle — the agent may have had a reason — but it is the question a
+   * human opens this surface to answer, and nothing else records it.
+   */
+  misdirected: boolean
+  /** The named service was not in the resolved catalog when the declaration was parsed. */
+  unknown: boolean
+}
+
+/** The whole surface's read model: one state, the join, and every loss the report counted. */
+export interface BinaryOutputView {
+  state: BinaryOutputState
+  /**
+   * The storage service the STEP selected (`stepOptions.binaryOutput.storageServiceId`), or
+   * null when the step carries no selection. Null is a real state, not a gap to hide: a
+   * trait-carrying kind dispatched under an OVERRIDING kind records a declaration against a
+   * step that never held the selection, so there is genuinely nothing to compare against and
+   * the surface must say so rather than implying the artifacts went astray.
+   */
+  target: string | null
+  /** The context services the step selected, in selection order. */
+  contextServices: readonly string[]
+  rows: readonly BinaryOutputRow[]
+  /**
+   * The step's OWN configured target was not in the resolved catalog when the declaration was
+   * parsed — the catalog changed under the run, rather than the agent naming a service that
+   * never existed. Different causes, different fixes: re-register the service, versus correct
+   * the declaration.
+   */
+  targetUnknown: boolean
+  /**
+   * Unknown service ids the AGENT named, verbatim and EXCLUDING the step's own target, which
+   * {@link targetUnknown} already owns.
+   *
+   * The exclusion is what makes the two facts DISJOINT, and it lives here rather than in a
+   * renderer on purpose: the report's own `unknownServices` mixes them, so a surface reading it
+   * raw either reports the lost target twice or — the way this shipped — labels every unknown
+   * id as "this step's own storage service" and drops the invented ones entirely. Two fields
+   * that cannot overlap is the only shape where naming one cannot mis-state the other.
+   */
+  unknownDeclaredServices: readonly string[]
+  /** Entries dropped because they were not `{ service, location }` objects. */
+  invalidEntries: number
+  /** Valid entries dropped past the report's cap — so {@link rows} is a PREFIX. */
+  omitted: number
+  /** How many of {@link rows} went somewhere other than {@link target}. */
+  misdirected: number
+}
+
+/**
+ * The step's binary-output read model, or null when the step has no binary-output story at all
+ * (no recorded report AND no storage selection) — which is every step of every stock pipeline,
+ * so the surface simply does not render.
+ *
+ * A step carrying a SELECTION but no report still renders: it was briefed, and "briefed, with
+ * nothing recorded" is a fact worth stating on a run that died mid-generation. A step carrying
+ * a REPORT but no selection renders too, with a null target (see {@link BinaryOutputView.target}).
+ *
+ * The one exception is a step SKIPPED by estimate gating: it holds a selection it never ran
+ * with, so no state describing a dispatch is true of it, and the panel already marks it as
+ * skipped. A skipped step genuinely has no binary-output story, so it takes the same absence as
+ * an unbriefed one. A step that has not started YET is the neighbouring case and resolves the
+ * other way — it still has a story ahead of it, told by `not-started`. (Either with a REPORT is
+ * not reachable — nothing dispatched — but if one ever were, the record wins: a recorded claim
+ * is never hidden.)
+ */
+export function binaryOutputView(step: PipelineStep | null | undefined): BinaryOutputView | null {
+  const report = step?.binaryOutputs ?? null
+  const config = step?.stepOptions?.binaryOutput ?? null
+  if (!report && (!config || step?.skipped)) return null
+
+  const target = config?.storageServiceId ?? null
+  const contextServices = config?.contextServiceIds ?? []
+  if (!report) {
+    return {
+      // A step still queued has not had the chance to record anything, which is a different
+      // fact from having had it and not taken it.
+      state: step?.state === 'pending' ? 'not-started' : 'configured',
+      target,
+      contextServices,
+      rows: [],
+      targetUnknown: false,
+      unknownDeclaredServices: [],
+      invalidEntries: 0,
+      omitted: 0,
+      misdirected: 0,
+    }
+  }
+
+  const unknown = new Set(report.unknownServices)
+  const rows: BinaryOutputRow[] = report.stored.map((artifact) => ({
+    ...artifact,
+    // A null target cannot make anything misdirected: there is no place it was supposed to go.
+    misdirected: target !== null && artifact.service !== target,
+    unknown: unknown.has(artifact.service),
+  }))
+
+  return {
+    state: reportState(report),
+    target,
+    contextServices,
+    rows,
+    targetUnknown: target !== null && unknown.has(target),
+    unknownDeclaredServices: report.unknownServices.filter((id) => id !== target),
+    invalidEntries: report.invalidEntries,
+    omitted: report.omitted,
+    misdirected: rows.filter((row) => row.misdirected).length,
+  }
+}
+
+/**
+ * Which failure the report records, in the order the parser can produce them. `parseFailed`
+ * and `undeclared` are checked BEFORE the (always empty in those cases) `stored` list, so a
+ * missing or unreadable block is never reported as "the agent said it stored nothing".
+ */
+function reportState(report: BinaryOutputReport): BinaryOutputState {
+  if (report.parseFailed) return 'parse-failed'
+  if (report.undeclared) return 'undeclared'
+  return report.stored.length > 0 ? 'stored' : 'declared-none'
+}
+
+/**
+ * State → i18n keys, exhaustive over the discriminant so a sixth outcome fails the typecheck
+ * here rather than rendering a missing key. It lives beside the discriminant, not in a
+ * component, because BOTH surfaces read it: the collapsed section row shows `summary` (a few
+ * words, the outcome and nothing else) and the expanded panel shows `detail` (what the outcome
+ * means and what, if anything, to do). A single map is what keeps the row from claiming an
+ * outcome the panel below it then qualifies away.
+ *
+ * `stored` has an empty detail on purpose: the artifacts themselves are the statement, and a
+ * sentence above them would only restate the list's own length.
+ */
+export const BINARY_OUTPUT_STATE_KEYS: Record<
+  BinaryOutputState,
+  { icon: string; tone: string; summary: string; detail: string }
+> = {
+  'not-started': {
+    icon: 'i-lucide-clock',
+    tone: 'text-slate-400',
+    summary: 'binaryOutput.state.notStarted.summary',
+    detail: 'binaryOutput.state.notStarted.detail',
+  },
+  configured: {
+    icon: 'i-lucide-hourglass',
+    tone: 'text-slate-300',
+    summary: 'binaryOutput.state.configured.summary',
+    detail: 'binaryOutput.state.configured.detail',
+  },
+  undeclared: {
+    icon: 'i-lucide-circle-help',
+    tone: 'text-amber-300',
+    summary: 'binaryOutput.state.undeclared.summary',
+    detail: 'binaryOutput.state.undeclared.detail',
+  },
+  'parse-failed': {
+    icon: 'i-lucide-file-warning',
+    tone: 'text-amber-300',
+    summary: 'binaryOutput.state.parseFailed.summary',
+    detail: 'binaryOutput.state.parseFailed.detail',
+  },
+  'declared-none': {
+    icon: 'i-lucide-circle-slash',
+    tone: 'text-slate-300',
+    summary: 'binaryOutput.state.declaredNone.summary',
+    detail: 'binaryOutput.state.declaredNone.detail',
+  },
+  stored: {
+    icon: 'i-lucide-package-check',
+    tone: 'text-emerald-300',
+    summary: 'binaryOutput.state.stored.summary',
+    detail: '',
+  },
+}
+
+/**
+ * Whether the view carries any qualification a reader must see beside the artifacts —
+ * unknown service ids, dropped entries, a truncated list, or a misdirected artifact. Drives
+ * the collapsed summary row's tone, so a report with losses can't read as a clean one from
+ * the outside of a collapsed section.
+ */
+export function binaryOutputHasWarnings(view: BinaryOutputView): boolean {
+  return (
+    view.state === 'parse-failed' ||
+    view.state === 'undeclared' ||
+    view.targetUnknown ||
+    view.unknownDeclaredServices.length > 0 ||
+    view.invalidEntries > 0 ||
+    view.omitted > 0 ||
+    view.misdirected > 0
+  )
+}
+
+// ---------------------------------------------------------------------------
+// The pipeline builder's half: what is wrong with a step's SELECTION, before it is saved.
+// ---------------------------------------------------------------------------
+
+/**
+ * One thing wrong with a binary-generating step's selection, as the builder can see it.
+ *
+ * The two `*_service` members mirror the kernel's `BinaryOutputConfigIssue.problem` values
+ * VERBATIM, because the builder's job here is to surface the run-admission refusal
+ * (`binary_output_service_invalid`) BEFORE the round trip rather than to invent a second
+ * opinion about the same catalog. They are restated rather than imported: the SPA cannot see
+ * kernel, and the wire vocabulary that crosses to it (`@cat-factory/contracts`) carries the
+ * error code, not the issue enum. The remaining three are conditions the BUILDER alone can be
+ * in — nothing is picked yet, or there is nothing to pick from.
+ */
+export type BinaryOutputPickIssue =
+  /** The catalog read failed (the feature is unconfigured, or the request 503'd). Not the same
+   *  as an empty catalog: an empty picker reads as "no services exist", which is a claim. */
+  | 'catalog_unavailable'
+  /** The catalog resolved, but nothing in it declares the `asset-storage` capability. */
+  | 'no_storage_service'
+  /** An enabled generator step with no storage selection — refused at save AND at start. */
+  | 'not_selected'
+  /** The selected storage id is not in the resolved catalog (kernel's `unknown_service`). */
+  | 'unknown_service'
+  /** The selected storage service dropped its `asset-storage` tag (kernel's own spelling). */
+  | 'not_storage_capable'
+  /** One or more selected CONTEXT ids are not in the resolved catalog. */
+  | 'unknown_context_service'
+
+/** What the builder found wrong with one step's selection, and which ids to name. */
+export interface BinaryOutputPickState {
+  issues: readonly BinaryOutputPickIssue[]
+  /** The unresolved CONTEXT ids, for the message that names them. */
+  unknownContextIds: readonly string[]
+}
+
+/**
+ * Validate a step's selection against the workspace's RESOLVED catalog — the same catalog run
+ * admission re-validates against, which is the whole reason the picker offers only resolved
+ * services: an id offered from a stale client copy saves clean and fails at run START, one
+ * refusal cycle later.
+ *
+ * `available` is the catalog's own probe state, threaded separately because it distinguishes
+ * three things an empty array cannot: NOT PROBED YET (`null`), UNREACHABLE (`false`) and
+ * genuinely EMPTY (`true`) — opposite facts with opposite fixes, and only the last is worth a
+ * "register a storage service" hint. Every judgement about the CATALOG therefore requires
+ * `available === true`; only `not_selected`, which is a fact about the STEP, holds regardless.
+ * Without that a step would be flagged for re-pick during the load that is about to resolve it,
+ * and again during an outage that changed nothing about it.
+ *
+ * Returns EVERY issue, not the first, for the same reason `binaryOutputConfigIssues` does:
+ * naming one at a time costs a fix-and-retry cycle per lost service. The ONE subsumption is
+ * `no_storage_service`, which suppresses the per-selection storage judgements below it: both
+ * of those tell the user to pick another service, and there is none to pick — an instruction
+ * the surface cannot carry out is worse than silence, and the remedy that IS actionable
+ * (register one) is already stated. The CONTEXT half is unaffected: it is a different
+ * selection, judged on existence alone, and stays actionable whatever the storage tier looks
+ * like.
+ */
+export function binaryOutputPickIssues(
+  config: BinaryOutputConfig | undefined,
+  catalog: readonly Pick<ResolvedFoundationalService, 'id' | 'capabilities'>[],
+  available: boolean | null,
+): BinaryOutputPickState {
+  const resolved = available === true
+  const issues: BinaryOutputPickIssue[] = []
+  const noStorageService =
+    resolved && !catalog.some((s) => s.capabilities.includes(ASSET_STORAGE_CAPABILITY))
+  if (available === false) issues.push('catalog_unavailable')
+  else if (noStorageService) issues.push('no_storage_service')
+
+  const storageId = config?.storageServiceId?.trim()
+  if (!storageId) {
+    issues.push('not_selected')
+    return { issues, unknownContextIds: [] }
+  }
+
+  if (resolved && !noStorageService) {
+    const storage = catalog.find((s) => s.id === storageId)
+    if (!storage) issues.push('unknown_service')
+    else if (!storage.capabilities.includes(ASSET_STORAGE_CAPABILITY))
+      issues.push('not_storage_capable')
+  }
+
+  const known = new Set(catalog.map((s) => s.id))
+  const unknownContextIds = resolved
+    ? (config?.contextServiceIds ?? []).filter((id) => !known.has(id))
+    : []
+  if (unknownContextIds.length) issues.push('unknown_context_service')
+
+  return { issues, unknownContextIds }
+}

package/app/utils/tutorial.spec.ts

@@ -1,6 +1,18 @@
 import { describe, expect, it } from 'vitest'
-import { computeCoachMarkLayout, resolveTours, sortTours } from '~/utils/tutorial'
-import type { TutorialStep, TutorialTour } from '~/utils/tutorial'
+import en from '../../i18n/locales/en.json'
+import {
+  computeCoachMarkLayout,
+  launchActionFor,
+  needsReveal,
+  resolveTourCatalogue,
+  resolveTours,
+  sortTours,
+  tourState,
+  TUTORIAL_ACTION_KEYS,
+  TUTORIAL_STATUS_KEYS,
+  visibleArea,
+} from '~/utils/tutorial'
+import type { TutorialRequirement, TutorialStep, TutorialTour } from '~/utils/tutorial'
 import type { NavGates } from '~/modular/nav-contributions'
 
 const tour = (id: string, order: number): TutorialTour => ({
@@ -33,15 +45,22 @@ const step = (id: string, when?: TutorialStep['when']): TutorialStep => ({
   when,
 })
 
-const withSteps = (id: string, steps: TutorialStep[], when?: TutorialTour['when']): TutorialTour =>
-  ({ ...tour(id, 10), steps, when }) as TutorialTour
+/** A requirement over the one gate field these cases vary. */
+const needsAdvanced: TutorialRequirement = {
+  id: 'advanced',
+  labelKey: 'tutorial.requirements.boardWrite',
+  met: (g) => g.advancedMode,
+}
+
+const withSteps = (
+  id: string,
+  steps: TutorialStep[],
+  requires?: readonly TutorialRequirement[],
+): TutorialTour => ({ ...tour(id, 10), steps, requires })
 
 describe('resolveTours', () => {
-  it('drops a tour its own `when` rejects', () => {
-    const tours = [
-      withSteps('a', [step('one')], (g) => g.advancedMode),
-      withSteps('b', [step('one')]),
-    ]
+  it('drops a tour whose requirements are unmet', () => {
+    const tours = [withSteps('a', [step('one')], [needsAdvanced]), withSteps('b', [step('one')])]
     expect(resolveTours(tours, gates(false)).map((t) => t.id)).toEqual(['b'])
   })
 
@@ -64,6 +83,105 @@ describe('resolveTours', () => {
     const t = withSteps('a', [step('one')])
     expect(resolveTours([t], gates(true))[0]).toBe(t)
   })
+
+  it('withholds nothing when no gates service is wired', () => {
+    // Dev-open parity, and the case a bare install runs in: with nothing to gate against,
+    // a required tour is still offered and its branch steps are not silently thinned.
+    const t = withSteps('a', [step('one'), step('two', (g) => g.advancedMode)], [needsAdvanced])
+    expect(resolveTours([t], null)[0]?.steps.map((s) => s.id)).toEqual(['one', 'two'])
+  })
+})
+
+describe('resolveTourCatalogue', () => {
+  it('keeps an unavailable tour, saying which requirements are unmet', () => {
+    // The whole reason the catalogue resolves rather than filters: a tour dropped from the
+    // list is indistinguishable from one this deployment never shipped.
+    const t = withSteps('a', [step('one')], [needsAdvanced])
+    const [entry] = resolveTourCatalogue([t], gates(false))
+    expect(entry?.availability).toBe('blocked')
+    expect(entry?.unmet.map((r) => r.id)).toEqual(['advanced'])
+  })
+
+  it('reports only the requirements that are actually unmet', () => {
+    const met: TutorialRequirement = { id: 'met', labelKey: 'x', met: () => true }
+    const t = withSteps('a', [step('one')], [met, needsAdvanced])
+    expect(resolveTourCatalogue([t], gates(false))[0]?.unmet.map((r) => r.id)).toEqual(['advanced'])
+  })
+
+  it('separates "requirements unmet" from "no step applies here"', () => {
+    // Two different facts needing two different reactions: one names something the reader can
+    // go and do, the other names nothing at all — telling them to fix it would send them
+    // looking for a control that was never missing.
+    const t = withSteps('a', [step('advancedOnly', (g) => g.advancedMode)])
+    const [entry] = resolveTourCatalogue([t], gates(false))
+    expect(entry?.availability).toBe('not-applicable')
+    expect(entry?.unmet).toEqual([])
+  })
+
+  it('reports a tour that is both blocked and stepless as blocked', () => {
+    // Precedence, pinned. A step's `when` reads the same gates the requirements do, so with the
+    // requirements unmet the step filter is answering a hypothetical — what would apply on a
+    // board this one is by construction not. Calling that `not-applicable` would tell the reader
+    // nothing can be done about a tour they can in fact unlock.
+    const t = withSteps('a', [step('advancedOnly', (g) => g.advancedMode)], [needsAdvanced])
+    const [entry] = resolveTourCatalogue([t], gates(false))
+    expect(entry?.availability).toBe('blocked')
+    expect(entry?.unmet.map((r) => r.id)).toEqual(['advanced'])
+  })
+
+  it('is sorted, and agrees with resolveTours about what is ready', () => {
+    const tours = [
+      withSteps('c', [step('one')], [needsAdvanced]),
+      { ...withSteps('a', [step('one')]), order: 20 },
+      { ...withSteps('b', [step('one')]), order: 5 },
+    ]
+    const catalogue = resolveTourCatalogue(tours, gates(false))
+    expect(catalogue.map((e) => e.tour.id)).toEqual(['b', 'c', 'a'])
+    expect(resolveTours(tours, gates(false)).map((t) => t.id)).toEqual(
+      catalogue.filter((e) => e.availability === 'ready').map((e) => e.tour.id),
+    )
+  })
+})
+
+describe('tourState / launchActionFor', () => {
+  const state = (over: Partial<Parameters<typeof tourState>[0]>) =>
+    tourState({ active: false, resumable: false, completed: false, ...over })
+
+  it('reports a running tour as in progress, whatever else is true of it', () => {
+    expect(state({ active: true, resumable: true, completed: true })).toBe('inProgress')
+    expect(launchActionFor('inProgress')).toBe('continue')
+  })
+
+  it('prefers a broken-off position over a past completion', () => {
+    // Resume beats Completed: a tour taken again and broken off is offered where it stopped,
+    // rather than described by the badge it earned last time.
+    expect(state({ resumable: true, completed: true })).toBe('paused')
+    expect(launchActionFor('paused')).toBe('resume')
+  })
+
+  it('falls back to completion, then to untouched', () => {
+    expect(state({ completed: true })).toBe('completed')
+    expect(launchActionFor('completed')).toBe('restart')
+    expect(state({})).toBe('notStarted')
+    expect(launchActionFor('notStarted')).toBe('start')
+  })
+})
+
+describe('the status / action copy tables', () => {
+  it('resolves every key against the en catalog', () => {
+    // These are the lookups the typed-message-key check cannot see (a key assembled from a
+    // state), so a rename would otherwise reach the user as a raw path on a button.
+    const lookup = (key: string) =>
+      key
+        .split('.')
+        .reduce<unknown>((node, part) => (node as Record<string, unknown> | undefined)?.[part], en)
+    for (const key of [
+      ...Object.values(TUTORIAL_STATUS_KEYS),
+      ...Object.values(TUTORIAL_ACTION_KEYS),
+    ]) {
+      expect(typeof lookup(key), key).toBe('string')
+    }
+  })
 })
 
 const viewport = { width: 1000, height: 800 }
@@ -113,3 +231,55 @@ describe('computeCoachMarkLayout', () => {
     expect(layout.left).toBe(10)
   })
 })
+
+describe('needsReveal', () => {
+  const viewport = { width: 1000, height: 800 }
+
+  it('leaves a fully visible anchor alone', () => {
+    expect(needsReveal({ top: 100, left: 100, width: 120, height: 40 }, viewport)).toBe(false)
+  })
+
+  it('reveals an anchor scrolled or panned clean off screen', () => {
+    // The case the runtime could not see: an element off the viewport still has layout boxes,
+    // so it passed the visibility check and the ring was drawn at coordinates nobody can see.
+    expect(needsReveal({ top: -400, left: 100, width: 120, height: 40 }, viewport)).toBe(true)
+    expect(needsReveal({ top: 100, left: 1400, width: 120, height: 40 }, viewport)).toBe(true)
+  })
+
+  it('reveals a small anchor that is only slightly on screen', () => {
+    // 25% of its width inside the right edge: enough to have a rect, not enough to point at.
+    expect(needsReveal({ top: 100, left: 970, width: 120, height: 40 }, viewport)).toBe(true)
+  })
+
+  it('leaves an anchor BIGGER than the viewport alone while it fills the screen', () => {
+    // `board-canvas` and `sidebar` can never clear a fraction of their own area, so measuring
+    // against that would pan the camera on every step that points at one of them.
+    expect(needsReveal({ top: -200, left: -200, width: 2000, height: 1600 }, viewport)).toBe(false)
+  })
+
+  it('reveals an oversized anchor that has left the screen anyway', () => {
+    expect(needsReveal({ top: -1700, left: 0, width: 2000, height: 1600 }, viewport)).toBe(true)
+  })
+
+  it('never reveals a zero-area anchor', () => {
+    // There is no position to bring anywhere, and treating it as off-screen would make every
+    // degenerate rect trigger a camera move.
+    expect(needsReveal({ top: 0, left: 0, width: 0, height: 0 }, viewport)).toBe(false)
+  })
+})
+
+describe('visibleArea', () => {
+  const viewport = { width: 1000, height: 800 }
+
+  it('is the full area when the rect is inside', () => {
+    expect(visibleArea({ top: 10, left: 10, width: 100, height: 50 }, viewport)).toBe(5000)
+  })
+
+  it('is the clipped area when the rect straddles an edge', () => {
+    expect(visibleArea({ top: 10, left: -60, width: 100, height: 50 }, viewport)).toBe(40 * 50)
+  })
+
+  it('is zero for a rect with no overlap at all', () => {
+    expect(visibleArea({ top: 10, left: 2000, width: 100, height: 50 }, viewport)).toBe(0)
+  })
+})