@cat-factory/app 0.280.0 → 0.280.2

package/app/modular/result-views.ts

@@ -1,28 +1,65 @@
 import type { Component } from 'vue'
 import { defineModule } from '@modular-vue/core'
 import { RESULT_VIEW_IDS, type ResultViewId } from '@cat-factory/contracts'
-import OutcomeSummaryWindow from '~/components/outcome/OutcomeSummaryWindow.vue'
-import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
-import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
-import BrainstormWindow from '~/components/brainstorm/BrainstormWindow.vue'
-import TestReportWindow from '~/components/testing/TestReportWindow.vue'
-import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
-import VisualConfirmationWindow from '~/components/visualConfirm/VisualConfirmationWindow.vue'
-import GateResultView from '~/components/gates/GateResultView.vue'
-import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
-import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
-import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
-import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
-import BinaryCandidatesWindow from '~/components/binaryCandidates/BinaryCandidatesWindow.vue'
-import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
-import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
-import MergerResultView from '~/components/panels/MergerResultView.vue'
-import InitiativeTrackerWindow from '~/components/initiative/InitiativeTrackerWindow.vue'
-import InitiativePlanningWindow from '~/components/initiative/InitiativePlanningWindow.vue'
-import DocInterviewWindow from '~/components/docs/DocInterviewWindow.vue'
-import RalphLoopResultView from '~/components/ralph/RalphLoopResultView.vue'
-import JudgeResultView from '~/components/judge/JudgeResultView.vue'
 import type { ResultViewContribution } from './slots'
+import { defineAsyncView } from '~/utils/asyncView'
+
+/**
+ * Every built-in window is CODE-SPLIT: a result window opens on a deliberate click (an agent
+ * step, a gate, an outcome card), and there are more than twenty of them, so importing the
+ * catalog statically put all of them plus their dependencies (markdown-it, the review windows'
+ * prose readers) into the initial bundle of a board that may open none. `defineAsyncView`
+ * returns an ordinary `Component`, so the slot entry, the exhaustiveness check below and
+ * `StepResultViewHost`'s `<component :is>` mount are unchanged; only the fetch moves to the
+ * open. It wraps `defineAsyncComponent` with the shared failure notice, so a window whose chunk
+ * 404s after a deploy says so rather than opening onto nothing. A consumer window may be
+ * contributed either way, and should copy this one.
+ */
+const OutcomeSummaryWindow = defineAsyncView(
+  () => import('~/components/outcome/OutcomeSummaryWindow.vue'),
+)
+const RequirementsReviewWindow = defineAsyncView(
+  () => import('~/components/requirements/RequirementsReviewWindow.vue'),
+)
+const ClarityReviewWindow = defineAsyncView(
+  () => import('~/components/clarity/ClarityReviewWindow.vue'),
+)
+const BrainstormWindow = defineAsyncView(
+  () => import('~/components/brainstorm/BrainstormWindow.vue'),
+)
+const TestReportWindow = defineAsyncView(() => import('~/components/testing/TestReportWindow.vue'))
+const HumanTestWindow = defineAsyncView(() => import('~/components/humanTest/HumanTestWindow.vue'))
+const VisualConfirmationWindow = defineAsyncView(
+  () => import('~/components/visualConfirm/VisualConfirmationWindow.vue'),
+)
+const GateResultView = defineAsyncView(() => import('~/components/gates/GateResultView.vue'))
+const ConsensusSessionWindow = defineAsyncView(
+  () => import('~/components/consensus/ConsensusSessionWindow.vue'),
+)
+const GenericStructuredResultView = defineAsyncView(
+  () => import('~/components/panels/GenericStructuredResultView.vue'),
+)
+const ServiceSpecWindow = defineAsyncView(() => import('~/components/spec/ServiceSpecWindow.vue'))
+const FollowUpWindow = defineAsyncView(() => import('~/components/followUp/FollowUpWindow.vue'))
+const BinaryCandidatesWindow = defineAsyncView(
+  () => import('~/components/binaryCandidates/BinaryCandidatesWindow.vue'),
+)
+const ForkDecisionWindow = defineAsyncView(
+  () => import('~/components/forkDecision/ForkDecisionWindow.vue'),
+)
+const PrReviewWindow = defineAsyncView(() => import('~/components/prReview/PrReviewWindow.vue'))
+const MergerResultView = defineAsyncView(() => import('~/components/panels/MergerResultView.vue'))
+const InitiativeTrackerWindow = defineAsyncView(
+  () => import('~/components/initiative/InitiativeTrackerWindow.vue'),
+)
+const InitiativePlanningWindow = defineAsyncView(
+  () => import('~/components/initiative/InitiativePlanningWindow.vue'),
+)
+const DocInterviewWindow = defineAsyncView(() => import('~/components/docs/DocInterviewWindow.vue'))
+const RalphLoopResultView = defineAsyncView(
+  () => import('~/components/ralph/RalphLoopResultView.vue'),
+)
+const JudgeResultView = defineAsyncView(() => import('~/components/judge/JudgeResultView.vue'))
 
 /**
  * The first-party result-view registry (slice 2 of the modular-vue adoption —

package/app/pages/index.vue

@@ -8,7 +8,6 @@ import TranslationWarningBanner from '~/components/layout/TranslationWarningBann
 import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
 import InspectorPanel from '~/components/panels/InspectorPanel.vue'
 import DecisionModal from '~/components/panels/DecisionModal.vue'
-import AgentStepDetail from '~/components/panels/AgentStepDetail.vue'
 import StepResultViewHost from '~/components/panels/StepResultViewHost.vue'
 import AppOverlayHost from '~/components/panels/AppOverlayHost.vue'
 import AddTaskModal from '~/components/board/AddTaskModal.vue'
@@ -18,126 +17,127 @@ import GitHubOnboarding from '~/components/github/GitHubOnboarding.vue'
 import CommandBar from '~/components/layout/CommandBar.vue'
 import PersonalCredentialModal from '~/components/providers/PersonalCredentialModal.vue'
 import ConfirmDialog from '~/components/common/ConfirmDialog.vue'
+import { defineAsyncView } from '~/utils/asyncView'
 import KeyboardShortcutsHelp from '~/components/common/KeyboardShortcutsHelp.vue'
 
-// Heavy, rarely-open panels — code-split into their own chunks via defineAsyncComponent
-// and mounted only while their ui open-flag is set (the v-if gates in the template), so
-// they stay out of the initial bundle and don't run setup/watchers while closed.
-const ObservabilityPanel = defineAsyncComponent(
+// The step-detail reader, mounted only while a step is open. It is the one always-mounted
+// surface whose chunk dominated the initial bundle: its prose reader pulls markdown-it (~200 kB
+// raw of the ~2.1 MB eager graph) purely to render an agent's output, which nothing can be
+// reading until a step has been opened. Store-gated like the panels below, so the reader loads
+// on the click that needs it.
+const AgentStepDetail = defineAsyncView(() => import('~/components/panels/AgentStepDetail.vue'))
+
+// Heavy, rarely-open panels, code-split into their own chunks via `defineAsyncView` and
+// mounted only while their ui open-flag is set (the v-if gates in the template), so they stay
+// out of the initial bundle and don't run setup/watchers while closed. The seam (rather than a
+// bare `defineAsyncComponent`) is what makes a chunk that 404s after a deploy say so.
+const ObservabilityPanel = defineAsyncView(
   () => import('~/components/panels/ObservabilityPanel.vue'),
 )
-const OperatorDashboardPanel = defineAsyncComponent(
+const OperatorDashboardPanel = defineAsyncView(
   () => import('~/components/panels/OperatorDashboardPanel.vue'),
 )
-const ReportsPanel = defineAsyncComponent(() => import('~/components/panels/ReportsPanel.vue'))
-const KaizenPanel = defineAsyncComponent(() => import('~/components/kaizen/KaizenPanel.vue'))
+const ReportsPanel = defineAsyncView(() => import('~/components/panels/ReportsPanel.vue'))
+const KaizenPanel = defineAsyncView(() => import('~/components/kaizen/KaizenPanel.vue'))
 // Occasional, externally store-gated surfaces — deferred to their own chunks like the
 // sibling document modals above. Each mounts only while its ui open-flag is set, so it
 // loads on first open instead of bloating the initial bundle.
-const BlockFocusView = defineAsyncComponent(() => import('~/components/focus/BlockFocusView.vue'))
-const TaskSourceConnectModal = defineAsyncComponent(
+const BlockFocusView = defineAsyncView(() => import('~/components/focus/BlockFocusView.vue'))
+const TaskSourceConnectModal = defineAsyncView(
   () => import('~/components/tasks/TaskSourceConnectModal.vue'),
 )
-const TaskImportModal = defineAsyncComponent(() => import('~/components/tasks/TaskImportModal.vue'))
-const BugHuntModal = defineAsyncComponent(() => import('~/components/tasks/BugHuntModal.vue'))
-const RecurringPipelineModal = defineAsyncComponent(
+const TaskImportModal = defineAsyncView(() => import('~/components/tasks/TaskImportModal.vue'))
+const BugHuntModal = defineAsyncView(() => import('~/components/tasks/BugHuntModal.vue'))
+const RecurringPipelineModal = defineAsyncView(
   () => import('~/components/board/RecurringPipelineModal.vue'),
 )
-const DocumentSourceConnectModal = defineAsyncComponent(
+const DocumentSourceConnectModal = defineAsyncView(
   () => import('~/components/documents/DocumentSourceConnectModal.vue'),
 )
-const DocumentImportModal = defineAsyncComponent(
+const DocumentImportModal = defineAsyncView(
   () => import('~/components/documents/DocumentImportModal.vue'),
 )
-const DocumentTemplatesModal = defineAsyncComponent(
+const DocumentTemplatesModal = defineAsyncView(
   () => import('~/components/documents/DocumentTemplatesModal.vue'),
 )
-const SpawnPreviewModal = defineAsyncComponent(
+const SpawnPreviewModal = defineAsyncView(
   () => import('~/components/documents/SpawnPreviewModal.vue'),
 )
-const StartFromDesignModal = defineAsyncComponent(
+const StartFromDesignModal = defineAsyncView(
   () => import('~/components/documents/StartFromDesignModal.vue'),
 )
-const BootstrapModal = defineAsyncComponent(
-  () => import('~/components/bootstrap/BootstrapModal.vue'),
-)
-const AddServiceFromRepoModal = defineAsyncComponent(
+const BootstrapModal = defineAsyncView(() => import('~/components/bootstrap/BootstrapModal.vue'))
+const AddServiceFromRepoModal = defineAsyncView(
   () => import('~/components/github/AddServiceFromRepoModal.vue'),
 )
-const GitHubPanel = defineAsyncComponent(() => import('~/components/github/GitHubPanel.vue'))
-const SlackPanel = defineAsyncComponent(() => import('~/components/slack/SlackPanel.vue'))
-const NotificationSettingsPanel = defineAsyncComponent(
+const GitHubPanel = defineAsyncView(() => import('~/components/github/GitHubPanel.vue'))
+const SlackPanel = defineAsyncView(() => import('~/components/slack/SlackPanel.vue'))
+const NotificationSettingsPanel = defineAsyncView(
   () => import('~/components/notifications/NotificationSettingsPanel.vue'),
 )
-const FragmentLibraryPanel = defineAsyncComponent(
+const FragmentLibraryPanel = defineAsyncView(
   () => import('~/components/fragments/FragmentLibraryPanel.vue'),
 )
-const FoundationalServicePanel = defineAsyncComponent(
+const FoundationalServicePanel = defineAsyncView(
   () => import('~/components/foundational/FoundationalServicePanel.vue'),
 )
 // Startup advisory for invalid / outdated pipelines — only mounted while open (auto-opened
 // at most once per session by the watcher below), so it stays out of the initial bundle.
-const PipelineHealthModal = defineAsyncComponent(
+const PipelineHealthModal = defineAsyncView(
   () => import('~/components/pipeline/PipelineHealthModal.vue'),
 )
 // Startup advisory for new / outdated built-in merge presets — same once-per-session pattern.
-const RiskPolicyHealthModal = defineAsyncComponent(
+const RiskPolicyHealthModal = defineAsyncView(
   () => import('~/components/settings/RiskPolicyHealthModal.vue'),
 )
 // Startup advisory for new / outdated built-in model presets — same once-per-session pattern.
-const ModelPresetHealthModal = defineAsyncComponent(
+const ModelPresetHealthModal = defineAsyncView(
   () => import('~/components/settings/ModelPresetHealthModal.vue'),
 )
-const IntegrationsHub = defineAsyncComponent(
-  () => import('~/components/layout/IntegrationsHub.vue'),
-)
-const ModelProvidersHub = defineAsyncComponent(
-  () => import('~/components/layout/ModelProvidersHub.vue'),
-)
-const PersonalSetupModal = defineAsyncComponent(
+const IntegrationsHub = defineAsyncView(() => import('~/components/layout/IntegrationsHub.vue'))
+const ModelProvidersHub = defineAsyncView(() => import('~/components/layout/ModelProvidersHub.vue'))
+const PersonalSetupModal = defineAsyncView(
   () => import('~/components/layout/PersonalSetupModal.vue'),
 )
-const WorkspaceSettingsPanel = defineAsyncComponent(
+const WorkspaceSettingsPanel = defineAsyncView(
   () => import('~/components/settings/WorkspaceSettingsPanel.vue'),
 )
-const AccountSettingsPanel = defineAsyncComponent(
+const AccountSettingsPanel = defineAsyncView(
   () => import('~/components/settings/AccountSettingsPanel.vue'),
 )
-const ObservabilityConnectionPanel = defineAsyncComponent(
+const ObservabilityConnectionPanel = defineAsyncView(
   () => import('~/components/settings/ObservabilityConnectionPanel.vue'),
 )
-const PackageRegistriesPanel = defineAsyncComponent(
+const PackageRegistriesPanel = defineAsyncView(
   () => import('~/components/settings/PackageRegistriesPanel.vue'),
 )
-const ApiTokensPanel = defineAsyncComponent(
-  () => import('~/components/settings/ApiTokensPanel.vue'),
-)
-const InfrastructureWindow = defineAsyncComponent(
+const ApiTokensPanel = defineAsyncView(() => import('~/components/settings/ApiTokensPanel.vue'))
+const InfrastructureWindow = defineAsyncView(
   () => import('~/components/settings/InfrastructureWindow.vue'),
 )
-const EnvironmentSetupWizard = defineAsyncComponent(
+const EnvironmentSetupWizard = defineAsyncView(
   () => import('~/components/environments/EnvironmentSetupWizard.vue'),
 )
-const ModelConfigurationPanel = defineAsyncComponent(
+const ModelConfigurationPanel = defineAsyncView(
   () => import('~/components/settings/ModelConfigurationPanel.vue'),
 )
-const LocalModelEndpointsPanel = defineAsyncComponent(
+const LocalModelEndpointsPanel = defineAsyncView(
   () => import('~/components/settings/LocalModelEndpointsPanel.vue'),
 )
-const SandboxPanel = defineAsyncComponent(() => import('~/components/sandbox/SandboxPanel.vue'))
-const UserSecretsSection = defineAsyncComponent(
+const SandboxPanel = defineAsyncView(() => import('~/components/sandbox/SandboxPanel.vue'))
+const UserSecretsSection = defineAsyncView(
   () => import('~/components/settings/UserSecretsSection.vue'),
 )
-const OpenRouterCatalogPanel = defineAsyncComponent(
+const OpenRouterCatalogPanel = defineAsyncView(
   () => import('~/components/settings/OpenRouterCatalogPanel.vue'),
 )
-const VendorCredentialsModal = defineAsyncComponent(
+const VendorCredentialsModal = defineAsyncView(
   () => import('~/components/providers/VendorCredentialsModal.vue'),
 )
-const AiProviderOnboardingModal = defineAsyncComponent(
+const AiProviderOnboardingModal = defineAsyncView(
   () => import('~/components/providers/AiProviderOnboardingModal.vue'),
 )
-const AiPresetMismatchDialog = defineAsyncComponent(
+const AiPresetMismatchDialog = defineAsyncView(
   () => import('~/components/providers/AiPresetMismatchDialog.vue'),
 )
 // The in-app tutorial: the launch prompt (auto-opened once for a user who never answered
@@ -145,19 +145,15 @@ const AiPresetMismatchDialog = defineAsyncComponent(
 // section or the palette, at any time), the coach-mark overlay that runs a tour, and the
 // contextual offer that raises the ONE walkthrough this board just made takeable. All
 // mount only while their store flag is set, so they cost the initial bundle nothing.
-const TutorialPrompt = defineAsyncComponent(
-  () => import('~/components/tutorial/TutorialPrompt.vue'),
-)
-const TutorialCatalogue = defineAsyncComponent(
+const TutorialPrompt = defineAsyncView(() => import('~/components/tutorial/TutorialPrompt.vue'))
+const TutorialCatalogue = defineAsyncView(
   () => import('~/components/tutorial/TutorialCatalogue.vue'),
 )
-const TutorialOverlay = defineAsyncComponent(
-  () => import('~/components/tutorial/TutorialOverlay.vue'),
-)
-const TutorialNudge = defineAsyncComponent(() => import('~/components/tutorial/TutorialNudge.vue'))
+const TutorialOverlay = defineAsyncView(() => import('~/components/tutorial/TutorialOverlay.vue'))
+const TutorialNudge = defineAsyncView(() => import('~/components/tutorial/TutorialNudge.vue'))
 // The first-run role question (Engineer / Product manager / Designer). Same shape as the tutorial
 // launch prompt: mounted only while its store flag is set, so an answered question costs nothing.
-const RolePrompt = defineAsyncComponent(() => import('~/components/layout/RolePrompt.vue'))
+const RolePrompt = defineAsyncView(() => import('~/components/layout/RolePrompt.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -479,7 +475,15 @@ watch(
         <!-- Always-mounted, fast-path surfaces. -->
         <PipelineBuilder />
         <DecisionModal />
-        <AgentStepDetail />
+        <!-- Code-split step-detail reader. Teleport + fade live here, not inside the component,
+             for the same reason the focus view's do: an inner Transition never animates the
+             mount its own v-if gate causes, and is unmounted before it could animate the
+             unmount. -->
+        <Teleport to="body">
+          <Transition name="reader-fade">
+            <AgentStepDetail v-if="ui.stepDetail" />
+          </Transition>
+        </Teleport>
         <StepResultViewHost />
         <!-- Consumer-contributed top-level overlays (extension slice D). Renders nothing until a
              consumer opens one via `ui.openOverlay` / `useAppOverlays().open(...)`. -->

package/app/stores/binaryCandidates.ts

@@ -21,6 +21,12 @@ export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
 
   /** True while a keep call is in flight (drives the button spinner / disabled state). */
   const keeping = ref(false)
+  /**
+   * True while the warm-up read is in flight. The window renders no state until it settles, and
+   * "still fetching" must not render as the "nothing to choose between" empty state: on this
+   * surface that empty state is a claim the run generated nothing to compare.
+   */
+  const loading = ref(false)
   /** The last error message from an action, surfaced inline; cleared on the next action. */
   const error = ref<string | null>(null)
 
@@ -48,9 +54,24 @@ export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
     if (step) step.binaryCandidates = state
   }
 
-  /** Warm the live state from the GET (the stream also keeps it fresh). Best-effort. */
+  /**
+   * The most recent {@link load} attempt. Only the latest one may write `loading` or `error`: two
+   * reads do overlap (a Retry beside a window switching run, an open triggered while one is in
+   * flight), and a superseded attempt settling afterwards used to clear the spinner and stamp its
+   * own verdict over the newer read's. A slow failure landing after a fast success is the bad case,
+   * because it reports a load failure across candidates that are on screen.
+   */
+  let attempt = 0
+
+  /**
+   * Warm the live state from the GET (the stream also keeps it fresh). The failure is RECORDED
+   * rather than swallowed: with no state on the step, a failed read and a run that produced no
+   * candidates are the same `null` and opposite facts, and only one of them is worth a Retry.
+   */
   async function load(executionId: string): Promise<void> {
+    const mine = ++attempt
     error.value = null
+    loading.value = true
     try {
       await execution.echoAfter(
         executionId,
@@ -60,7 +81,9 @@ export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
         },
       )
     } catch (e) {
-      error.value = e instanceof Error ? e.message : 'Failed to load'
+      if (mine === attempt) error.value = e instanceof Error ? e.message : 'Failed to load'
+    } finally {
+      if (mine === attempt) loading.value = false
     }
   }
 
@@ -85,5 +108,5 @@ export const useBinaryCandidatesStore = defineStore('binaryCandidates', () => {
     }
   }
 
-  return { keeping, error, load, keep }
+  return { keeping, loading, error, load, keep }
 })

package/app/stores/ui/modals.ts

@@ -74,6 +74,17 @@ export interface ReviewFrictionModalContext {
   debt: ReviewDebtRow[]
   /** Retry the create with `acknowledgeReviewDebt` — present only for the soft `warn` tier. */
   onConfirm: (() => void) | null
+  /**
+   * Whether the opener's create is in flight right now, so "Create anyway" can show its spinner and
+   * refuse a second click (UX-78). A GETTER over the opener's own `saving` ref rather than a copied
+   * boolean: the dialog's context object is captured once at open, so a snapshot would be frozen at
+   * `false` for the whole retry. Reading it inside a `computed` keeps the reactivity.
+   *
+   * Load-bearing, not cosmetic: the retry's first await resolves the staged context attachments
+   * (a network round-trip per item), so a second click during that window filed a SECOND task and
+   * started a second pipeline run against the same request.
+   */
+  pending?: () => boolean
 }
 
 /** Clears both hub came-from markers; injected into the slices whose `open*` handlers reset them. */

package/app/utils/asyncView.ts

@@ -0,0 +1,24 @@
+import { defineAsyncComponent, type AsyncComponentLoader, type Component } from 'vue'
+import AsyncViewError from '~/components/common/AsyncViewError.vue'
+
+/**
+ * Define a code-split surface (a window, a panel, a modal, the step reader) that STATES it when
+ * its chunk fails to load.
+ *
+ * A bare `defineAsyncComponent` renders nothing on a rejected loader, and the rejection is
+ * routine rather than exotic: the SPA is a hashed-chunk build, so a deployment that lands while
+ * a tab is open makes every not-yet-fetched chunk a 404, and the first click on a window the
+ * session had never opened resolves to a blank screen with no message. On the surfaces these
+ * windows serve, that blank is the one a person approves or rejects a run from, so it reads as
+ * "there is nothing to review" rather than as a failure. Same rule as the backend's: absent and
+ * empty must never render the same.
+ *
+ * The remedy is a reload rather than a retry, because the chunk the running document is asking
+ * for is gone from the origin and re-requesting the same URL cannot bring it back.
+ *
+ * Use this instead of `defineAsyncComponent` for every surface the app splits out, so a
+ * consumer copying the nearest example copies the loud one.
+ */
+export function defineAsyncView(loader: AsyncComponentLoader): Component {
+  return defineAsyncComponent({ loader, errorComponent: AsyncViewError })
+}

package/app/utils/binaryCandidates.spec.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 import type { PipelineStep } from '~/types/execution'
-import { binaryCandidateHasWarnings, binaryCandidateView } from './binaryCandidates'
+import {
+  binaryCandidateAbsence,
+  binaryCandidateHasWarnings,
+  binaryCandidateView,
+} from './binaryCandidates'
 
 function step(overrides: Record<string, unknown> = {}): PipelineStep {
   // The candidate override MERGES into the base state rather than replacing it, so a case that
@@ -108,3 +112,43 @@ describe('binaryCandidateHasWarnings', () => {
     }
   })
 })
+
+describe('binaryCandidateAbsence', () => {
+  const RUN = 'exec_1'
+
+  // The window used to render a titled shell with a blank body for all four of these (UX-80).
+  // They are different facts, and only one of them is a claim about the RUN.
+  it('separates no run, a read in flight, a failed read, and a run that compared nothing', () => {
+    expect(binaryCandidateAbsence(false, null, null)).toBe('no_run')
+    expect(binaryCandidateAbsence(true, null, RUN)).toBe('loading')
+    expect(binaryCandidateAbsence(false, 'network down', RUN)).toBe('load_failed')
+    expect(binaryCandidateAbsence(false, null, RUN)).toBe('nothing_compared')
+  })
+
+  // A Retry re-enters `loading` while the PREVIOUS attempt's message is still recorded. Reporting
+  // the stale failure over the live attempt would make the button look like it did nothing.
+  it('lets a fresh attempt outrank the error it is clearing', () => {
+    expect(binaryCandidateAbsence(true, 'network down', RUN)).toBe('loading')
+  })
+
+  // 'nothing_compared' renders "nothing to compare", which is a statement about what the run
+  // produced. A request that never landed knows nothing about that, so it must never reach here.
+  it('never claims emptiness on the strength of a request that failed', () => {
+    for (const error of ['boom', 'Failed to load']) {
+      expect(binaryCandidateAbsence(false, error, RUN)).not.toBe('nothing_compared')
+    }
+  })
+
+  // With no run the warm-up read is never started, so the store's flags belong to some OTHER
+  // window's read. Reporting them here would describe a run nobody asked about, and falling through
+  // to emptiness would claim this run compared nothing without ever having looked.
+  it('never reports a state it did not read, nor emptiness, when there is no run', () => {
+    for (const loading of [true, false]) {
+      for (const error of [null, 'network down']) {
+        for (const run of [null, undefined, '']) {
+          expect(binaryCandidateAbsence(loading, error, run)).toBe('no_run')
+        }
+      }
+    }
+  })
+})

package/app/utils/binaryCandidates.ts

@@ -127,6 +127,39 @@ export function binaryCandidateHasWarnings(view: BinaryCandidateView): boolean {
   return invalidEntries > 0 || omitted > 0 || unusablePreviews > 0
 }
 
+/**
+ * Why the window has no comparison to render. Four different facts that a single blank body
+ * conflated (UX-80), each needing a different reaction from the reader: nothing to read from, wait,
+ * retry, or accept that the run compared nothing. `nothing_compared` is a CLAIM about the run, so
+ * it is only ever the answer once a read of that run has settled and not failed.
+ */
+export type BinaryCandidateAbsence = 'no_run' | 'loading' | 'load_failed' | 'nothing_compared'
+
+/**
+ * The absence to render when {@link binaryCandidateView} produced nothing.
+ *
+ * Precedence is the point, and it is stated here rather than in the template's branch order:
+ *
+ *  - No RUN outranks everything. The window is keyed to an execution and the warm-up read is
+ *    skipped without one, so `loading`/`error` can only be describing some other window's read;
+ *    reporting either would attribute a state to a run nobody asked about, and reporting emptiness
+ *    would claim this run compared nothing on the strength of never having looked.
+ *  - An in-flight read outranks a stale error from the previous attempt, so a Retry does not keep
+ *    showing the failure it is busy clearing.
+ *  - A recorded error outranks emptiness, so a request that never landed cannot render as "this run
+ *    generated nothing to compare".
+ */
+export function binaryCandidateAbsence(
+  loading: boolean,
+  error: string | null | undefined,
+  executionId: string | null | undefined,
+): BinaryCandidateAbsence {
+  if (!executionId) return 'no_run'
+  if (loading) return 'loading'
+  if (error) return 'load_failed'
+  return 'nothing_compared'
+}
+
 /**
  * State → the i18n key for the line explaining why no choice was offered.
  *

package/app/utils/blockRects.spec.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { measureBlocks } from './blockRects'
+
+function card(id: string): HTMLElement {
+  const el = document.createElement('div')
+  el.setAttribute('data-block-id', id)
+  return el
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('measureBlocks', () => {
+  it('resolves each rendered card by its block id', () => {
+    const a = card('a')
+    const b = card('b')
+    document.body.append(a, b)
+
+    const blocks = measureBlocks(document)
+    expect(blocks.elementFor('a')).toBe(a)
+    expect(blocks.elementFor('b')).toBe(b)
+    expect(blocks.elementFor('missing')).toBeNull()
+  })
+
+  it('resolves the first card in document order, as a bare querySelector did', () => {
+    const onBoard = card('a')
+    const inOverlay = card('a')
+    document.body.append(onBoard, inOverlay)
+
+    expect(measureBlocks(document).elementFor('a')).toBe(onBoard)
+  })
+
+  it('measures an element once per pass however many links read it', () => {
+    const a = card('a')
+    document.body.append(a)
+    const measure = vi.spyOn(a, 'getBoundingClientRect')
+
+    const blocks = measureBlocks(document)
+    const first = blocks.rectFor(a)
+    expect(blocks.rectFor(a)).toBe(first)
+    expect(measure).toHaveBeenCalledTimes(1)
+  })
+
+  it('is a snapshot: a later pass measures again', () => {
+    const a = card('a')
+    document.body.append(a)
+    const measure = vi.spyOn(a, 'getBoundingClientRect')
+
+    measureBlocks(document).rectFor(a)
+    measureBlocks(document).rectFor(a)
+    expect(measure).toHaveBeenCalledTimes(2)
+  })
+
+  it('queries nothing until something is actually looked up', () => {
+    // The edge overlay builds a pass every awake frame of a pan and, on a board with no links
+    // of any kind, asks it for no card at all. Deferring is what keeps that pass free.
+    const root = document.createElement('div')
+    root.append(card('a'))
+    document.body.append(root)
+    const query = vi.spyOn(root, 'querySelectorAll')
+
+    const blocks = measureBlocks(root)
+    expect(query).not.toHaveBeenCalled()
+
+    blocks.elementFor('a')
+    blocks.elementFor('a')
+    expect(query).toHaveBeenCalledTimes(1)
+  })
+
+  it('scopes the pass to the root it was given', () => {
+    const outside = card('a')
+    const root = document.createElement('div')
+    const inside = card('b')
+    root.append(inside)
+    document.body.append(outside, root)
+
+    const blocks = measureBlocks(root)
+    expect(blocks.elementFor('b')).toBe(inside)
+    expect(blocks.elementFor('a')).toBeNull()
+  })
+})