@cat-factory/app 0.319.2 → 0.320.0

package/app/components/queue/QueueCard.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { agentKindMeta } from '~/utils/catalog'
 import { formatDuration, useNowTick } from '~/composables/useStepTimer'
-import { useFramePlacement } from '~/composables/useFramePlacement'
+import { useTaskReveal } from '~/composables/useTaskReveal'
 import { LANE_REASON_LABEL_KEYS } from '~/utils/swimlanes'
 import type { QueueEntry } from '~/utils/queueSections'
 import IconButton from '~/components/common/IconButton.vue'
@@ -25,8 +25,7 @@ const { t } = useI18n()
 const ui = useUiStore()
 const execution = useExecutionStore()
 const agentRuns = useAgentRunsStore()
-const views = useWorkViewStore()
-const { focusFrame } = useFramePlacement()
+const { revealTask } = useTaskReveal()
 // A shared 30s clock, so "waited 4m" advances on a quiet board instead of freezing until some
 // unrelated event re-evaluates the card.
 const nowTick = useNowTick(30_000)
@@ -125,13 +124,10 @@ function openTask() {
 /**
  * Leave the queue for the canvas, with this task selected and its service in view. The canvas
  * kept its own camera while the queue covered it, so without the pan the task is usually off
- * screen. A task has no position of its own (it lives in its frame's swimlanes), so the camera
- * centres on the frame.
+ * screen.
  */
 function showOnBoard() {
-  views.show('board')
-  ui.select(props.entry.task.id)
-  void focusFrame(props.entry.service?.id ?? props.entry.task.id)
+  revealTask(props.entry.task.id)
 }
 </script>
 

package/app/composables/useFramePlacement.ts

@@ -1,6 +1,7 @@
 import { nextTick } from 'vue'
 import { useVueFlow } from '@vue-flow/core'
 import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
+import { LOD_MIN_ZOOM } from '~/composables/useSemanticZoom'
 import {
   EMPTY_FRAME_SIZE,
   EPIC_NODE_SIZE,
@@ -27,7 +28,8 @@ const MIN_FOCUS_ZOOM = 0.6
 
 export function useFramePlacement() {
   const board = useBoardStore()
-  const { viewport, setCenter, screenToFlowCoordinate } = useVueFlow(BOARD_FLOW_ID)
+  const { viewport, setCenter, screenToFlowCoordinate, findNode, onNodesInitialized, onMoveStart } =
+    useVueFlow(BOARD_FLOW_ID)
 
   /**
    * Every existing top-level board node's rect in flow-space — both service frames
@@ -87,5 +89,83 @@ export function useFramePlacement() {
     setCenter(cx, cy, { zoom, duration: opts?.duration ?? 400 })
   }
 
-  return { freeFramePosition, focusFrame }
+  /** Whether the canvas has drawn the frame, so there is a measured node to centre on. */
+  function isRendered(id: string): boolean {
+    const node = findNode(id)
+    return !!node && node.dimensions.width > 0
+  }
+
+  /**
+   * Resolves once the canvas has measured the frame's node. A deep link followed on a fresh load
+   * arrives before the board has measured its nodes, and centring on a frame with no size yet puts
+   * the camera on its corner, or nowhere.
+   */
+  async function whenRendered(id: string): Promise<void> {
+    if (isRendered(id)) return
+    await new Promise<void>((resolve) => {
+      const { off } = onNodesInitialized(() => {
+        if (!isRendered(id)) return
+        off()
+        resolve()
+      })
+    })
+  }
+
+  /**
+   * Centre the camera on a task card, zoomed in to the level where the board renders a task's
+   * pipeline steps (`steps`), once the canvas has drawn its frame. A closer zoom is left alone. A
+   * task has no position of its own (it lives in its frame's swimlanes), so its centre is read off
+   * the card the frame drew; with no card to read, the camera centres on the frame instead.
+   */
+  async function focusTaskWhenRendered(taskId: string, frameId: string): Promise<void> {
+    if (!board.getBlock(frameId)) return
+    await whenRendered(frameId)
+    await nextTick()
+    const frameSelector = `.vue-flow__node[data-id="${CSS.escape(frameId)}"]`
+    // The card inside the frame's own node, not another surface that names the same task.
+    const cardSelector = `${frameSelector} [data-block-id="${CSS.escape(taskId)}"]`
+    if (!document.querySelector(cardSelector)) {
+      await focusFrame(frameId)
+      return
+    }
+    const zoom = Math.max(viewport.value.zoom, LOD_MIN_ZOOM.steps)
+    await centreOn(cardSelector, zoom, 400)
+    keepCentred(frameSelector, cardSelector, zoom)
+  }
+
+  /**
+   * Keep the card centred while the board settles around it, until the person moves the camera.
+   * At the `steps` level a frame lays its swimlanes out again as each card renders its steps, so
+   * the card moves inside its frame after the camera has landed on it. Each change of the frame's
+   * or the card's size re-centres on it; the first pan or zoom the person makes ends the follow.
+   */
+  function keepCentred(frameSelector: string, cardSelector: string, zoom: number): void {
+    const frame = document.querySelector(frameSelector)
+    const card = document.querySelector(cardSelector)
+    if (!frame || !card) return
+    const observer = new ResizeObserver(() => void centreOn(cardSelector, zoom, 0))
+    observer.observe(frame)
+    observer.observe(card)
+    const { off } = onMoveStart(({ event }) => {
+      // A programmatic move (this follow's own) carries no input event; a person's does.
+      const byPerson = 'sourceEvent' in event ? event.sourceEvent != null : true
+      if (!byPerson) return
+      observer.disconnect()
+      off()
+    })
+  }
+
+  /** Centre the camera on an element of the board at `zoom`, resolving when the move lands. */
+  async function centreOn(selector: string, zoom: number, duration: number): Promise<void> {
+    const element = document.querySelector(selector)
+    if (!element) return
+    const rect = element.getBoundingClientRect()
+    const centre = screenToFlowCoordinate({
+      x: rect.left + rect.width / 2,
+      y: rect.top + rect.height / 2,
+    })
+    await setCenter(centre.x, centre.y, { zoom, duration })
+  }
+
+  return { freeFramePosition, focusFrame, focusTaskWhenRendered }
 }

package/app/composables/useRunDeepLink.spec.ts

@@ -1,6 +1,6 @@
 import { createPinia, setActivePinia } from 'pinia'
-import { beforeEach, describe, expect, it } from 'vitest'
-import { captureRunDeepLink } from './useRunDeepLink'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { applyRunDeepLink, captureRunDeepLink, type PendingRunLink } from './useRunDeepLink'
 
 /** Point `window.location` + `history` at a URL the capture can read and rewrite. */
 function setUrl(search: string): void {
@@ -54,3 +54,61 @@ describe('captureRunDeepLink', () => {
     })
   })
 })
+
+describe('applyRunDeepLink', () => {
+  function surfaces() {
+    return {
+      revealTask: vi.fn(),
+      openRun: vi.fn(),
+      openOutcome: vi.fn(),
+      openObservability: vi.fn(),
+      openTestEvidence: vi.fn(),
+    }
+  }
+
+  function link(view: string | null, blockId: string | null = 'blk_1'): PendingRunLink {
+    return { workspaceId: 'ws_1', blockId, runId: 'exec_1', view }
+  }
+
+  it('brings the task into view and opens its running pipeline when no view is named', () => {
+    const opened = surfaces()
+    applyRunDeepLink(link(null), opened)
+    expect(opened.revealTask).toHaveBeenCalledWith('blk_1')
+    expect(opened.openRun).toHaveBeenCalledWith('blk_1')
+    expect(opened.openObservability).not.toHaveBeenCalled()
+  })
+
+  it('opens the running pipeline for view=run, the same as no view', () => {
+    const opened = surfaces()
+    applyRunDeepLink(link('run'), opened)
+    expect(opened.openRun).toHaveBeenCalledWith('blk_1')
+  })
+
+  it.each([
+    ['observability', 'openObservability', ['exec_1']],
+    ['test-evidence', 'openTestEvidence', ['exec_1']],
+    ['outcome', 'openOutcome', ['exec_1', 'blk_1']],
+  ] as const)('opens %s for its run, beside the task brought into view', (view, surface, args) => {
+    const opened = surfaces()
+    applyRunDeepLink(link(view), opened)
+    expect(opened.revealTask).toHaveBeenCalledWith('blk_1')
+    expect(opened[surface]).toHaveBeenCalledWith(...args)
+    expect(opened.openRun).not.toHaveBeenCalled()
+  })
+
+  it('lands on the task and opens nothing for a view it does not know', () => {
+    const opened = surfaces()
+    applyRunDeepLink(link('not-a-view'), opened)
+    expect(opened.revealTask).toHaveBeenCalledWith('blk_1')
+    for (const open of [opened.openRun, opened.openOutcome, opened.openObservability]) {
+      expect(open).not.toHaveBeenCalled()
+    }
+  })
+
+  it('opens no focus view and moves no camera for a link naming no task', () => {
+    const opened = surfaces()
+    applyRunDeepLink(link(null, null), opened)
+    expect(opened.revealTask).not.toHaveBeenCalled()
+    expect(opened.openRun).not.toHaveBeenCalled()
+  })
+})

package/app/composables/useRunDeepLink.ts

@@ -1,6 +1,11 @@
 /**
  * Boot-time replay of a RUN deep link: `?ws=<id>&block=<id>&run=<id>&view=<panel>`.
  *
+ * The task the link names is brought into view (`useTaskReveal`), and `view` picks what opens on
+ * it: `run` (also what a link with no `view` gets) opens the task's focus view, where its pipeline
+ * is followed step by step; `outcome`, `observability` and `test-evidence` open those result
+ * windows for the run. An unknown view still lands on the right board and task.
+ *
  * The engine's PR verification report links each PR back into the run: to the observability
  * panel (Model activity / Provided context), and to the Tester's result window holding the
  * evidence its environment-lifecycle section lists. Both are built from the deployment's public
@@ -13,11 +18,12 @@
  * is deleted rather than kept alongside it.
  */
 import { watch } from 'vue'
+import { useTaskReveal } from './useTaskReveal'
 import { useUiStore } from '../stores/ui'
 import { useWorkspaceStore } from '../stores/workspace'
 
 /** The parsed link, or null when the URL carried none. */
-interface PendingRunLink {
+export interface PendingRunLink {
   workspaceId: string | null
   blockId: string | null
   runId: string
@@ -50,13 +56,50 @@ export function captureRunDeepLink(): PendingRunLink | null {
   return link
 }
 
+/** The view a link with no `view` opens: the task's running pipeline. */
+export const RUN_LINK_DEFAULT_VIEW = 'run'
+
+/** What applying a run link can do, so which link opens what is testable without a board. */
+export interface RunLinkSurfaces {
+  revealTask: (blockId: string) => void
+  /** The task's focus view, with the pipeline of its current run. */
+  openRun: (blockId: string) => void
+  openOutcome: (runId: string, blockId: string | null) => void
+  openObservability: (runId: string) => void
+  openTestEvidence: (runId: string) => void
+}
+
+/** Apply a captured link to a hydrated board: the task brought into view, then its view. */
+export function applyRunDeepLink(link: PendingRunLink, surfaces: RunLinkSurfaces): void {
+  if (link.blockId) surfaces.revealTask(link.blockId)
+  switch (link.view ?? RUN_LINK_DEFAULT_VIEW) {
+    case 'run':
+      if (link.blockId) surfaces.openRun(link.blockId)
+      break
+    // `outcome` is passed the block as well as the run: it is the one view that stays readable on
+    // a task whose run the snapshot no longer carries, which a link followed weeks later is.
+    case 'outcome':
+      surfaces.openOutcome(link.runId, link.blockId)
+      break
+    case 'observability':
+      surfaces.openObservability(link.runId)
+      break
+    case 'test-evidence':
+      surfaces.openTestEvidence(link.runId)
+      break
+    default:
+      break
+  }
+}
+
 /**
  * Capture a run deep link and, once the board has hydrated, apply it. Returns nothing; the
  * caller mounts it once, next to `workspace.init()`.
  *
  * Applying WAITS for `workspace.ready`: opening the panel against a half-loaded board would
- * read an execution the snapshot hasn't delivered yet. The watcher is one-shot — a later
- * refresh must not re-open a panel the user closed.
+ * read an execution the snapshot hasn't delivered yet, and the camera waits further, for the
+ * canvas to have drawn the frame it centres on. The watcher is one-shot: a later refresh must
+ * not re-open a panel the user closed.
  */
 export function useRunDeepLink(): void {
   const link = captureRunDeepLink()
@@ -64,16 +107,17 @@ export function useRunDeepLink(): void {
 
   const workspace = useWorkspaceStore()
   const ui = useUiStore()
+  const { revealTask } = useTaskReveal()
 
   // Pin the board the link names BEFORE init resolves the active one, so the run's own board
   // opens rather than whichever one was last used on this device.
   if (link.workspaceId) workspace.workspaceId = link.workspaceId
 
-  // Applied at most once — a later refresh must not re-open a panel the user closed. The guard
-  // is a flag rather than `{ once: true }` (which would burn the single run on the immediate
-  // not-ready tick and never navigate) and `stop` is a `let` rather than a `const` (with
-  // `immediate`, the callback runs synchronously BEFORE the binding initialises, so an
-  // already-hydrated board would hit the temporal dead zone instead of navigating).
+  // Applied at most once. The guard is a flag rather than `{ once: true }` (which would burn the
+  // single run on the immediate not-ready tick and never navigate) and `stop` is a `let` rather
+  // than a `const` (with `immediate`, the callback runs synchronously BEFORE the binding
+  // initialises, so an already-hydrated board would hit the temporal dead zone instead of
+  // navigating).
   let applied = false
   let stop: (() => void) | undefined
   stop = watch(
@@ -81,20 +125,13 @@ export function useRunDeepLink(): void {
     (ready) => {
       if (!ready || applied) return
       applied = true
-      if (link.blockId) ui.select(link.blockId)
-      // Three views are served: the run's outcome summary (the non-code answer to "what did this
-      // change"), the observability panel, and the Tester's result window (where the screenshots
-      // the report's environment-lifecycle section lists are rendered). An unknown view still
-      // lands the user on the right board and task rather than failing the navigation.
-      //
-      // `outcome` is passed the block as well as the run: it is the one of the three that stays
-      // readable on a task whose run the snapshot no longer carries, and a link followed weeks
-      // after the work merged is exactly that case. The engine emits no `view=outcome` link
-      // today (its report links a REVIEWER to the two run-scoped panels); this is the entry
-      // point for one, and for a URL a person shares.
-      if (link.view === 'outcome') ui.openRunOutcome(link.runId, link.blockId)
-      else if (link.view === 'observability') ui.openObservability(link.runId)
-      else if (link.view === 'test-evidence') ui.openTestEvidence(link.runId)
+      applyRunDeepLink(link, {
+        revealTask,
+        openRun: (blockId) => ui.focus(blockId),
+        openOutcome: (runId, blockId) => ui.openRunOutcome(runId, blockId),
+        openObservability: (runId) => ui.openObservability(runId),
+        openTestEvidence: (runId) => ui.openTestEvidence(runId),
+      })
       stop?.()
     },
     { immediate: true },

package/app/composables/useSemanticZoom.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { LOD_MIN_ZOOM, zoomToLod } from './useSemanticZoom'
+
+describe('zoomToLod', () => {
+  it.each([
+    [0.2, 'far'],
+    [0.59, 'far'],
+    [0.6, 'mid'],
+    [1.19, 'mid'],
+    [1.2, 'close'],
+    [1.8, 'steps'],
+    [2.39, 'steps'],
+    [2.4, 'subtasks'],
+    [3, 'subtasks'],
+  ] as const)('reads zoom %s as %s', (zoom, lod) => {
+    expect(zoomToLod(zoom)).toBe(lod)
+  })
+
+  it('starts each level at its LOD_MIN_ZOOM', () => {
+    for (const [lod, zoom] of Object.entries(LOD_MIN_ZOOM)) expect(zoomToLod(zoom)).toBe(lod)
+  })
+})

package/app/composables/useSemanticZoom.ts

@@ -3,6 +3,15 @@ import type { LodLevel } from '~/types/domain'
 /** The LOD scale, shallow → deep. Index order lets callers ask "is at least". */
 const LOD_ORDER: LodLevel[] = ['far', 'mid', 'close', 'steps', 'subtasks']
 
+/** The zoom each level starts at; the level holds until the next one's. */
+export const LOD_MIN_ZOOM: Record<LodLevel, number> = {
+  far: 0,
+  mid: 0.6,
+  close: 1.2,
+  steps: 1.8,
+  subtasks: 2.4,
+}
+
 /** Map a raw zoom factor to a level-of-detail bucket. Shared by the main board
  * and the drill-down focus view so both honour the same thresholds.
  *
@@ -11,11 +20,7 @@ const LOD_ORDER: LodLevel[] = ['far', 'mid', 'close', 'steps', 'subtasks']
  * expands each step's live todo breakdown — the spatial analogue of opening a
  * task in the inspector. */
 export function zoomToLod(zoom: number): LodLevel {
-  if (zoom < 0.6) return 'far'
-  if (zoom < 1.2) return 'mid'
-  if (zoom < 1.8) return 'close'
-  if (zoom < 2.4) return 'steps'
-  return 'subtasks'
+  return LOD_ORDER.findLast((level) => zoom >= LOD_MIN_ZOOM[level]) ?? 'far'
 }
 
 /** True when `lod` is at least as deep as `min` on the LOD scale. */

package/app/composables/useTaskReveal.ts

@@ -0,0 +1,26 @@
+import { useFramePlacement } from '~/composables/useFramePlacement'
+import { useBoardStore } from '~/stores/board'
+import { useUiStore } from '~/stores/ui'
+import { useWorkViewStore } from '~/stores/workView'
+
+/**
+ * Bring a task in front of the person: the canvas rather than the queue, the task selected, and
+ * the camera centred on its card at the zoom where its pipeline steps render. What the queue's
+ * "show on board" does, and what a deep link naming a task does.
+ */
+export function useTaskReveal() {
+  const board = useBoardStore()
+  const ui = useUiStore()
+  const views = useWorkViewStore()
+  const { focusTaskWhenRendered } = useFramePlacement()
+
+  function revealTask(taskId: string): void {
+    views.show('board')
+    ui.select(taskId)
+    const task = board.getBlock(taskId)
+    if (!task) return
+    void focusTaskWhenRendered(taskId, board.serviceOf(task)?.id ?? taskId)
+  }
+
+  return { revealTask }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.319.2",
+  "version": "0.320.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",