@cat-factory/app 0.280.0 → 0.280.1

package/app/components/panels/InspectorPanel.vue

@@ -332,9 +332,15 @@ const showOriginalDescription = ref(false)
        with the panel on top; the region now paints above at `z-40`, which only swaps which side
        loses). Sitting the panel below fixes it whichever way the stacking goes, and needs no
        left/right arithmetic to stay correct under RTL. -->
+  <!-- `data-inspector-block` names WHICH block the panel is showing, so a caller can tell a
+       panel left open on the previous selection from one that followed a new click. Deliberately
+       NOT `data-block-id`: that attribute is the board's card selector, which the canvas drivers
+       measure geometry through (`utils/blockRects.ts`), and a panel answering to it would offer
+       the arrows a rect that is not on the canvas at all. -->
   <div
     v-if="block && statusMeta && typeMeta"
     data-testid="inspector-panel"
+    :data-inspector-block="block.id"
     class="fixed inset-x-0 bottom-0 z-20 overflow-hidden rounded-t-2xl border border-slate-700 bg-slate-900/95 shadow-2xl backdrop-blur lg:absolute lg:inset-x-auto lg:bottom-auto lg:end-4 lg:top-16 lg:w-80 lg:rounded-2xl"
   >
     <div class="h-1.5 w-full" :style="{ backgroundColor: statusMeta.color }" />

package/app/composables/useBoardActivity.ts

@@ -1,4 +1,5 @@
 import { inject, onBeforeUnmount, onMounted, provide, type InjectionKey, type Ref } from 'vue'
+import { createWakeGate } from '~/utils/boardWakeGate'
 
 /**
  * The board's shared "something may have moved" pulse.
@@ -16,9 +17,13 @@ import { inject, onBeforeUnmount, onMounted, provide, type InjectionKey, type Re
  *  - a `MutationObserver` over the canvas subtree, watching structure plus `style` / `class`.
  *    That is every Vue-driven render change on the board, Vue Flow's own pan/zoom transform
  *    included. Attribute changes the drivers themselves write (`x1`/`y1` on the edge overlay)
- *    are outside the filter, so a driver cannot pulse itself awake forever.
+ *    are outside the filter, so a driver cannot pulse itself awake forever. These wakes are
+ *    RATE-LIMITED (see `boardWakeGate`): a live board re-renders its cards on every execution
+ *    event, and admitting each one kept the measuring loops from ever parking on exactly the
+ *    board where measuring costs the most. The gesture and camera signals below are admitted
+ *    unthrottled, so nothing the user is actually moving waits on an interval.
  *  - a `ResizeObserver` on the canvas, plus window `resize`: layout changes with no mutation.
- *  - pointer, wheel and scroll gestures on the canvas: the user moving something.
+ *  - pointer, wheel and scroll gestures, listened for on the WINDOW: the user moving something.
  *
  * What it does NOT catch is a reflow with no mutation and no gesture, such as a late-loading
  * image or font resizing a card. Those settle on the next pulse of any kind.
@@ -28,6 +33,14 @@ export type BoardActivity = {
   subscribe: (onPulse: () => void) => () => void
   /** Fire the pulse from a signal the observers above cannot see. */
   pulse: () => void
+  /**
+   * Where the pointer last was over the canvas (viewport coordinates), or null once it left.
+   *
+   * Owned here because the pulse already listens for the same gestures: a driver that wants the
+   * position registered a SECOND `pointermove` listener on the same element to learn what this
+   * one had just seen. Read inside a measurement pass, never subscribed to.
+   */
+  pointer: () => { x: number; y: number } | null
 }
 
 const boardActivityKey: InjectionKey<BoardActivity> = Symbol('boardActivity')
@@ -42,19 +55,62 @@ export function provideBoardActivity(container: Ref<HTMLElement | null>): BoardA
     for (const onPulse of subscribers) onPulse()
   }
 
+  // Renders reach the pulse through the gate; everything the user is moving goes straight to it.
+  const renderWakes = createWakeGate({
+    wake: pulse,
+    // `window.setTimeout` rather than the bare global: the DOM overload returns the numeric
+    // handle the gate's scheduler is typed on, where Node's returns a `Timeout` object.
+    scheduler: {
+      schedule: (run, delayMs) => window.setTimeout(run, delayMs),
+      cancel: (handle) => window.clearTimeout(handle),
+    },
+  })
+
+  let pointer: { x: number; y: number } | null = null
+
+  /**
+   * Track the pointer and pulse, in that order, off the SAME listener.
+   *
+   * `pointerleave` does not bubble, but a CAPTURE-phase listener sees one fired at any element
+   * below it, and the pointer moving from a card onto the canvas around it is exactly that
+   * event. So only the canvas's OWN leave clears the position; treating a descendant's as "the
+   * pointer is gone" would collapse the hovered card the moment the pointer crossed one of its
+   * inner elements. That check is on the TARGET, so it reads the same from the window as it did
+   * from the canvas.
+   */
+  const onGesture = (event: Event) => {
+    if (event.type === 'pointerleave') {
+      if (event.target === container.value) pointer = null
+    } else if (event.type === 'pointermove' || event.type === 'pointerdown') {
+      const { clientX, clientY } = event as PointerEvent
+      pointer = { x: clientX, y: clientY }
+    }
+    pulse()
+  }
+
   const activity: BoardActivity = {
     subscribe(onPulse) {
       subscribers.add(onPulse)
       return () => subscribers.delete(onPulse)
     },
     pulse,
+    pointer: () => pointer,
   }
   provide(boardActivityKey, activity)
 
-  const mutations = new MutationObserver(pulse)
+  const mutations = new MutationObserver(renderWakes.request)
   const resizes = new ResizeObserver(pulse)
   // `scroll` does not bubble, so it is caught in the capture phase; the gestures are
   // passive listeners because the pulse never wants to cancel one.
+  //
+  // They are bound to the WINDOW rather than to the canvas, because a drag does not end at the
+  // canvas's edge: `useBlockDrag` tracks the pointer on the window precisely so a card keeps
+  // following it, and the toolbar region and the inspector are SIBLINGS painted over the canvas,
+  // not descendants of it. Bound to the canvas, a drag whose cursor crossed one of them stopped
+  // delivering the gesture that keeps the measuring loops awake, and the arrows fell back to the
+  // rate-limited mutation wake for as long as the cursor was over it: a visible lag in the one
+  // interaction this pulse exists to keep smooth. Capture on the window sees every one of those
+  // events wherever it is dispatched, so nothing else about the handler changes.
   const gestures = [
     'pointerdown',
     'pointermove',
@@ -77,15 +133,15 @@ export function provideBoardActivity(container: Ref<HTMLElement | null>): BoardA
       attributeFilter: ['style', 'class'],
     })
     resizes.observe(el)
-    for (const type of gestures) el.addEventListener(type, pulse, gestureOptions)
+    for (const type of gestures) window.addEventListener(type, onGesture, gestureOptions)
     window.addEventListener('resize', pulse)
   })
 
   onBeforeUnmount(() => {
     mutations.disconnect()
     resizes.disconnect()
-    const el = container.value
-    for (const type of gestures) el?.removeEventListener(type, pulse, gestureOptions)
+    renderWakes.cancel()
+    for (const type of gestures) window.removeEventListener(type, onGesture, gestureOptions)
     window.removeEventListener('resize', pulse)
     subscribers.clear()
   })

package/app/composables/useTaskExpansion.ts

@@ -3,6 +3,7 @@ import { onMounted, onBeforeUnmount } from 'vue'
 import { lodAtLeast } from '~/composables/useSemanticZoom'
 import { onBoardActivity, type BoardActivity } from '~/composables/useBoardActivity'
 import { useSettlingRaf } from '~/composables/useSettlingRaf'
+import { measureBlocks, type BlockMeasurements } from '~/utils/blockRects'
 import { headerDistanceSq, type Rect } from '~/utils/taskExpansionRanking'
 
 function intersects(a: Rect, b: Rect) {
@@ -54,21 +55,6 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   // card is still tested at its expanded extent and stays denied. Stable.
   const expandedHeight = new Map<string, number>()
 
-  // Last pointer position over the board (viewport coords), or null when the pointer has
-  // left it. The card under the pointer is expanded on hover (see `hoveredTaskId`).
-  let pointer: { x: number; y: number } | null = null
-  function onPointerMove(e: PointerEvent) {
-    pointer = { x: e.clientX, y: e.clientY }
-  }
-  function onPointerLeave() {
-    pointer = null
-  }
-
-  function rectOf(id: string): DOMRect | null {
-    const el = document.querySelector(`[data-block-id="${id}"]`) as HTMLElement | null
-    return el ? el.getBoundingClientRect() : null
-  }
-
   // The task whose card is topmost at the pointer, or null. Using elementFromPoint (not a
   // rect test) means an open pipeline stacked above a neighbour wins the hit, so hovering
   // a region obscured by another pipeline doesn't switch to the card hidden beneath it.
@@ -77,6 +63,9 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   // a frame, a module, or a task with no run expands to nothing, and granting it would
   // still lift an empty card over its neighbours (see LaneTask's z-index).
   function hoveredTaskId(): string | null {
+    // Where the pointer is comes from the pulse, which already listens for the same gestures on
+    // the same element (see `BoardActivity.pointer`).
+    const pointer = activity.pointer()
     if (!pointer) return null
     const hit = document.elementFromPoint(pointer.x, pointer.y)
     const id = hit?.closest('[data-block-id]')?.getAttribute('data-block-id') ?? null
@@ -107,6 +96,8 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
     }
     const view = container.value?.getBoundingClientRect()
     if (!view) return changed
+    // One DOM query for the whole sweep instead of one per candidate task (see `measureBlocks`).
+    const blocks: BlockMeasurements = measureBlocks()
     const cx = view.left + view.width / 2
     const cy = view.top + view.height / 2
 
@@ -115,8 +106,9 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
     for (const t of board.allTasks) {
       // Only tasks whose run actually has steps would expand a pipeline list.
       if (!execution.getByBlock(t.id)?.steps.length) continue
-      const rect = rectOf(t.id)
-      if (!rect) continue
+      const el = blocks.elementFor(t.id)
+      if (!el) continue
+      const rect = blocks.rectFor(el)
       liveIds.add(t.id)
       // While a card is granted it's rendered expanded, so its live height is its
       // expanded footprint — cache it. A denied card keeps its last cached value.
@@ -166,19 +158,12 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   }
 
   const { poke } = useSettlingRaf(recompute)
-  // The pointer listeners below only record where the pointer IS; the pulse (which watches the
-  // same gestures) is what schedules the frame that acts on it.
+  // The pulse both records where the pointer is and schedules the frame that acts on it.
   onBoardActivity(activity, poke)
   onMounted(() => {
     store.setDriverActive(true)
-    const el = container.value
-    el?.addEventListener('pointermove', onPointerMove)
-    el?.addEventListener('pointerleave', onPointerLeave)
   })
   onBeforeUnmount(() => {
-    const el = container.value
-    el?.removeEventListener('pointermove', onPointerMove)
-    el?.removeEventListener('pointerleave', onPointerLeave)
     store.setDriverActive(false)
   })
 }

package/app/docs/consumer-extensions.md

@@ -102,6 +102,15 @@ An unpaired id degrades to the generic prose panel (a dev-console warning names
 id); a structured kind with no bespoke window gets the built-in `generic-structured` viewer
 for free.
 
+**Contribute the component asynchronously.** Every first-party window is registered as
+`defineAsyncView(() => import('...'))`, so its code is fetched on the click that opens it rather
+than on every board load; an async component is an ordinary `Component`, so the slot entry and the
+host's mount are identical either way. A window is a modal opened deliberately, so copy that shape
+unless yours is small enough not to matter. Prefer the seam over a bare `defineAsyncComponent`: it
+attaches the shared failure notice, so a chunk that 404s (which is what a deploy landing under an
+open tab makes of every chunk the session had not yet fetched) states itself instead of opening
+your window onto a blank screen.
+
 ### Navigation
 
 A consumer nav item carries its own `run` closure (first-party items use a typed `action`

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/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 })
+}