@cat-factory/app 0.30.3 → 0.30.5

package/app/components/board/BoardCanvas.vue

@@ -11,7 +11,8 @@ import { STATUS_META } from '~/utils/catalog'
 import { readDndPayload, blockIdFromEvent } from '~/utils/dnd'
 import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
 import { useTaskExpansion } from '~/composables/useTaskExpansion'
-import { computeDisplacement } from '~/utils/boardDisplacement'
+import { useBlockDrag } from '~/composables/useBlockDrag'
+import { useFrameStacking } from '~/composables/useFrameStacking'
 
 const board = useBoardStore()
 const pipelines = usePipelinesStore()
@@ -21,10 +22,12 @@ const github = useGitHubStore()
 const toast = useToast()
 
 const { onNodeDragStop, onViewportChange, screenToFlowCoordinate } = useVueFlow(BOARD_FLOW_ID)
+const { draggingId } = useBlockDrag()
+const { hoveredFrameId } = useFrameStacking()
 
 // Gate which task cards expand their pipeline list on deep zoom: on-screen, and the
 // centre-most of any that would overlap (see useTaskExpansion). Service frames have no
-// such gate — they are always expanded to their task canvas (see frameOffsets below).
+// such gate — they are always expanded to their task canvas.
 const boardEl = ref<HTMLElement | null>(null)
 useTaskExpansion(boardEl)
 
@@ -36,83 +39,41 @@ useTaskExpansion(boardEl)
 // and fill much of the viewport, so leaving them draggable would turn the whole canvas
 // into a dead zone. We therefore make every frame non-draggable (the pane pans straight
 // through it) and move it via its header handle instead.
-
-// Services are always expanded to their full task canvas. An expanded card grows
-// rightward / downward from its stored (chip-sized) top-left and would overlap its
-// neighbours, so compressed space pushes the neighbours away by that growth: the
-// footprint never overlaps a neighbour it wasn't already overlapping. Because the
-// expanded set never changes, the layout is fixed — panning never shifts it and there
-// is no expand/collapse transition to snap on. Render-only; stored positions untouched.
-const FRAME_COLLAPSED_W = 224 // the stored chip footprint (`w-56`) the layout reserves
-const FRAME_COLLAPSED_H = 150
-const FRAME_CHROME_W = 40 // border + padding around the inner task canvas
-const FRAME_CHROME_H = 120 // top bar + header row + paddings above the canvas
-
-const frameOffsets = computed(() => {
-  const boxes = [
-    ...board.frames.map((b) => {
-      const c = board.containerSize(b.id)
-      return {
-        id: b.id,
-        x: b.position.x,
-        y: b.position.y,
-        w: FRAME_COLLAPSED_W,
-        h: FRAME_COLLAPSED_H,
-        growX: Math.max(0, c.w + FRAME_CHROME_W - FRAME_COLLAPSED_W),
-        growY: Math.max(0, c.h + FRAME_CHROME_H - FRAME_COLLAPSED_H),
-      }
-    }),
-    // Epics never expand, but they're pushed aside like any other box so an expanded
-    // frame doesn't end up rendered on top of one.
-    ...board.epics.map((b) => ({
-      id: b.id,
-      x: b.position.x,
-      y: b.position.y,
-      w: FRAME_COLLAPSED_W,
-      h: FRAME_COLLAPSED_H,
-      growX: 0,
-      growY: 0,
-    })),
-  ]
-  return computeDisplacement(boxes)
-})
-
-function offsetOf(id: string) {
-  return frameOffsets.value.get(id) ?? { dx: 0, dy: 0 }
+//
+// Frames are rendered exactly at their stored position and may overlap freely —
+// moving one never shifts another. The frame being dragged is lifted to the top,
+// then the hovered frame (the un-obscured one under the pointer), so overlapping
+// services can always be reached and reordered. See useFrameStacking.
+function frameZIndex(id: string) {
+  if (draggingId.value === id) return 1000
+  if (hoveredFrameId.value === id) return 100
+  return 1
 }
 
 const nodes = computed(() => [
-  ...board.frames.map((b) => {
-    const o = offsetOf(b.id)
-    return {
-      id: b.id,
-      type: 'block',
-      position: { x: b.position.x + o.dx, y: b.position.y + o.dy },
-      // Always-expanded frames fill the viewport; keep them non-draggable so the pane
-      // pans through them (they move via their header handle, see BlockNode).
-      draggable: false,
-      data: {},
-    }
-  }),
+  ...board.frames.map((b) => ({
+    id: b.id,
+    type: 'block',
+    position: { x: b.position.x, y: b.position.y },
+    // Always-expanded frames fill the viewport; keep them non-draggable so the pane
+    // pans through them (they move via their header handle, see BlockNode).
+    draggable: false,
+    zIndex: frameZIndex(b.id),
+    data: {},
+  })),
   // Epics are top-level grouping nodes (non-structural), drawn alongside frames and
   // linked to their member tasks by the dependency-edge overlay.
-  ...board.epics.map((b) => {
-    const o = offsetOf(b.id)
-    return {
-      id: b.id,
-      type: 'epic',
-      position: { x: b.position.x + o.dx, y: b.position.y + o.dy },
-      draggable: true,
-      data: {},
-    }
-  }),
+  ...board.epics.map((b) => ({
+    id: b.id,
+    type: 'epic',
+    position: { x: b.position.x, y: b.position.y },
+    draggable: true,
+    data: {},
+  })),
 ])
 
 onNodeDragStop(({ node }) => {
-  // node.position carries the render offset (compressed space can have pushed this node
-  // aside); subtract it so we persist the un-displaced position.
-  const o = offsetOf(node.id)
-  board.moveBlock(node.id, { x: node.position.x - o.dx, y: node.position.y - o.dy })
+  board.moveBlock(node.id, node.position)
 })
 
 onViewportChange((vp) => {

package/app/components/board/nodes/BlockNode.vue

@@ -8,6 +8,7 @@ import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useFrameResize } from '~/composables/useFrameResize'
+import { useFrameStacking } from '~/composables/useFrameStacking'
 
 // Vue Flow passes the node's `id` and `data` as props to custom node components.
 // Only frames are rendered as board nodes; their tasks live inside the card.
@@ -91,13 +92,20 @@ function toggleExpand() {
 }
 
 // Expanded frames are not Vue Flow-draggable (so the pane can pan through them),
-// so they're repositioned by grabbing the header handle instead. Frames live in
-// free-floating flow space, hence `clamp: false`.
+// so they're repositioned by grabbing the header instead. The whole header bar is
+// the grab surface — only the action buttons (marked `.nodrag`) opt out, so a press
+// on them clicks rather than starts a drag. Frames live in free-floating flow space,
+// hence `clamp: false`.
 const { startDrag } = useBlockDrag()
 function onFrameHandle(e: PointerEvent) {
+  if ((e.target as HTMLElement).closest('.nodrag')) return
   if (block.value) startDrag(block.value, e, { clamp: false })
 }
 
+// Lift this frame above any overlapping neighbours while the pointer is over it
+// (see useFrameStacking + BoardCanvas's frameZIndex).
+const { enter: enterFrame, leave: leaveFrame } = useFrameStacking()
+
 // Miro-style frame resizing: drag the right / bottom edges or the corner. Handles
 // live on the expanded card's drop zone (see template); the composable clamps to
 // the frame's content extent and persists the size on release.
@@ -158,7 +166,13 @@ const ITEM_ICON: Record<string, string> = {
 </script>
 
 <template>
-  <div v-if="block" class="relative" :data-block-id="block.id">
+  <div
+    v-if="block"
+    class="relative"
+    :data-block-id="block.id"
+    @pointerenter="enterFrame(block.id)"
+    @pointerleave="leaveFrame(block.id)"
+  >
     <!-- decision / approval indicator floats above the card at all zoom levels -->
     <div
       v-if="blockDecisions.length || blockApprovals.length"
@@ -341,16 +355,17 @@ const ITEM_ICON: Record<string, string> = {
         <AgentFailureCard :run="run" variant="expanded" />
       </div>
       <div class="space-y-3 p-4">
-        <!-- frame header (doubles as the drag handle for the expanded frame) -->
-        <div class="flex items-start justify-between gap-2">
-          <!-- `nopan` stops Vue Flow's pane from panning on a left-drag that starts on
-               this handle (it pans via d3-zoom's mousedown, which our pointerdown
-               stopPropagation can't intercept), so the grab drives the frame move. -->
-          <div
-            class="nopan flex cursor-grab items-center gap-2 active:cursor-grabbing"
-            title="Drag service"
-            @pointerdown="onFrameHandle"
-          >
+        <!-- frame header: the whole bar is the drag handle for the expanded frame.
+             `nopan` stops Vue Flow's pane from panning on a left-drag that starts here
+             (it pans via d3-zoom's mousedown, which our pointerdown stopPropagation
+             can't intercept), so the grab drives the frame move. The action buttons
+             on the right opt out via `.nodrag` (onFrameHandle ignores them). -->
+        <div
+          class="nopan flex cursor-grab items-start justify-between gap-2 active:cursor-grabbing"
+          title="Drag service"
+          @pointerdown="onFrameHandle"
+        >
+          <div class="flex items-center gap-2">
             <div
               class="flex h-8 w-8 items-center justify-center rounded-lg"
               :style="{ backgroundColor: typeMeta!.accent + '22' }"

package/app/components/board/nodes/DraggableTask.vue

@@ -4,9 +4,14 @@ import { useBlockDrag } from '~/composables/useBlockDrag'
 
 const props = defineProps<{ taskId: string }>()
 const board = useBoardStore()
+const expansion = useTaskExpansionStore()
 const task = computed(() => board.getBlock(props.taskId))
 const { draggingId, startDrag } = useBlockDrag()
 
+// An expanded pipeline grows downward over its neighbours, so it must stack above the
+// other (compact) task cards — never let a neighbour render on top of the pipeline.
+const expanded = computed(() => expansion.allowed.has(props.taskId))
+
 // Once a task is merged it stops being a unit of work and becomes part of the
 // architecture: it no longer renders as a draggable card (arrows fall back to its
 // container), so we never leave a zero-size anchor behind.
@@ -22,11 +27,11 @@ function onHandle(e: PointerEvent) {
     <!-- in-flight task → draggable work card (merged tasks render nothing) -->
     <div
       v-if="!merged"
-      class="absolute w-[180px]"
+      class="absolute w-[210px]"
       :style="{
         left: task.position.x + 'px',
         top: task.position.y + 'px',
-        zIndex: draggingId === taskId ? 60 : 10,
+        zIndex: draggingId === taskId ? 60 : expanded ? 20 : 10,
         // While this task is being dragged it must not capture hit-tests, so the
         // drop-zone (service or module) beneath the cursor can be resolved on
         // release — including the drag handle, which lives in this wrapper above

package/app/components/board/nodes/TaskCard.vue

@@ -182,7 +182,9 @@ function selectTask() {
     ]"
     @click.stop="selectTask"
   >
-    <!-- header row -->
+    <!-- meta row: status dot, recurring icon, status label + connect handle. The
+         status label is a fixed-width-ish stub ("APPROVAL NEEDED" etc.), so it sits
+         on its own row rather than stealing horizontal space from the title. -->
     <div class="flex items-center gap-1.5">
       <span class="h-2 w-2 shrink-0 rounded-full" :style="{ backgroundColor: statusMeta.color }" />
       <UIcon
@@ -191,19 +193,8 @@ function selectTask() {
         class="h-3 w-3 shrink-0 text-indigo-400"
         :title="schedule.enabled ? 'Recurring pipeline' : 'Recurring pipeline (paused)'"
       />
-      <span class="truncate text-[11px] font-semibold text-slate-100">{{ task.title }}</span>
-      <!-- drag-to-connect handle: drag onto another task to make it depend on this one -->
-      <button
-        type="button"
-        class="nodrag ml-1 shrink-0 cursor-crosshair rounded-full p-0.5 text-slate-500 hover:bg-slate-800 hover:text-amber-400"
-        title="Drag onto another task to make it depend on this one"
-        @pointerdown.stop="startConnect(task.id, $event)"
-        @click.stop
-      >
-        <UIcon name="i-lucide-spline" class="h-3 w-3" />
-      </button>
       <span
-        class="ml-auto shrink-0 text-[9px] uppercase tracking-wide"
+        class="ml-auto truncate text-[9px] uppercase tracking-wide"
         :class="
           runFailed
             ? 'text-rose-400'
@@ -216,6 +207,25 @@ function selectTask() {
       >
         {{ statusText }}
       </span>
+      <!-- drag-to-connect handle: drag onto another task to make it depend on this one -->
+      <button
+        type="button"
+        class="nodrag shrink-0 cursor-crosshair rounded-full p-0.5 text-slate-500 hover:bg-slate-800 hover:text-amber-400"
+        title="Drag onto another task to make it depend on this one"
+        @pointerdown.stop="startConnect(task.id, $event)"
+        @click.stop
+      >
+        <UIcon name="i-lucide-spline" class="h-3 w-3" />
+      </button>
+    </div>
+
+    <!-- title gets a full-width row so long titles wrap to two lines rather than
+         truncating to an unreadable stub; the full text stays available on hover. -->
+    <div
+      class="mt-1 line-clamp-2 break-words text-[11px] font-semibold leading-snug text-slate-100"
+      :title="task.title"
+    >
+      {{ task.title }}
     </div>
 
     <!-- a failed run: the shared failure banner + retry, never a stuck bar -->

package/app/composables/useBlockDrag.ts

@@ -1,17 +1,23 @@
 import { ref } from 'vue'
 import type { Block } from '~/types/domain'
 
+// Only one block is ever dragged at a time, so the dragged id is a module-level
+// singleton: the component that starts the drag and a sibling that needs to react
+// to it (e.g. BoardCanvas elevating the dragged service frame's z-index) read the
+// same ref instead of separate per-call copies.
+const draggingId = ref<string | null>(null)
+
 /**
  * Pointer-driven dragging for blocks positioned inside a container's 2D canvas
- * (tasks inside services/modules, modules inside services). Movement is divided
- * by the board zoom so the block tracks the cursor. When `reparent` is set, the
- * drop point is hit-tested against `[data-drop-zone]` ancestors so a task can be
- * dragged from a service into a module (or back out).
+ * (tasks inside services/modules, modules inside services) and for free-floating
+ * service frames (via their header handle). Movement is divided by the board zoom
+ * so the block tracks the cursor. When `reparent` is set, the drop point is
+ * hit-tested against `[data-drop-zone]` ancestors so a task can be dragged from a
+ * service into a module (or back out).
  */
 export function useBlockDrag() {
   const board = useBoardStore()
   const ui = useUiStore()
-  const draggingId = ref<string | null>(null)
 
   function startDrag(
     block: Block,

package/app/composables/useBlockQueries.ts

@@ -117,7 +117,7 @@ export function useBlockQueries(blocks: Ref<Block[]>) {
   function contentSize(id: string): { w: number; h: number } {
     const b = getBlock(id)
     const isModule = b?.level === 'module'
-    const TASK_W = 180
+    const TASK_W = 210
     const TASK_H = 160
     const headerH = isModule ? 30 : 0
     let w = isModule ? 200 : 360

package/app/composables/useFrameStacking.ts

@@ -0,0 +1,18 @@
+import { ref } from 'vue'
+
+// Service frames can overlap freely on the board. The frame the pointer is over
+// is, by definition, the un-obscured one at that point (pointerenter fires on the
+// topmost element), so we track it and lift it above every overlapping neighbour.
+// Module-level singleton: BlockNode sets it on hover, BoardCanvas reads it to set
+// the Vue Flow node's z-index.
+const hoveredFrameId = ref<string | null>(null)
+
+export function useFrameStacking() {
+  function enter(id: string) {
+    hoveredFrameId.value = id
+  }
+  function leave(id: string) {
+    if (hoveredFrameId.value === id) hoveredFrameId.value = null
+  }
+  return { hoveredFrameId, enter, leave }
+}

package/app/composables/useTaskExpansion.ts

@@ -2,8 +2,7 @@ import type { Ref } from 'vue'
 import { onMounted, onBeforeUnmount } from 'vue'
 import { useRafFn } from '@vueuse/core'
 import { lodAtLeast } from '~/composables/useSemanticZoom'
-
-type Rect = { left: number; right: number; top: number; bottom: number }
+import { headerDistanceSq, type Rect } from '~/utils/taskExpansionRanking'
 
 function intersects(a: Rect, b: Rect) {
   return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top
@@ -21,9 +20,13 @@ function sameSet(a: Set<string>, b: Set<string>) {
  * frame against live DOM rects so they follow pan / zoom / drag / resize:
  *
  *  - visibility: a task expands only while its card overlaps the board viewport.
- *  - overlap: walking the visible candidates nearest-to-screen-centre first, a task
- *    expands only if its footprint doesn't collide with one already granted, so the
- *    centre-most task wins an overlap and the rest stay compact.
+ *  - overlap: walking the visible candidates nearest-header-to-screen-centre first, a
+ *    task expands only if its footprint doesn't collide with one already granted, so the
+ *    card you're looking at wins an overlap and the rest stay compact.
+ *  - hover: the task directly under the pointer is granted first, so hovering any card
+ *    expands its pipeline regardless of its position on screen. "Under the pointer" is
+ *    the TOPMOST card at the cursor (document.elementFromPoint), so hovering a region
+ *    already covered by another open pipeline keeps that pipeline, not the card beneath.
  *
  * Writes the permitted id set into the `taskExpansion` store; `TaskPipelineMini` reads it.
  * Only tasks with a running pipeline (steps to show) are candidates — a task that
@@ -44,11 +47,30 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
   // 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.
+  function hoveredTaskId(): string | null {
+    if (!pointer) return null
+    const hit = document.elementFromPoint(pointer.x, pointer.y)
+    return hit?.closest('[data-block-id]')?.getAttribute('data-block-id') ?? null
+  }
+
   function recompute() {
     // Task cards only expand at the deep zoom bands; clear everything otherwise.
     if (!lodAtLeast(ui.lod, 'steps')) {
@@ -82,28 +104,29 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
         top: rect.top,
         bottom: rect.top + height,
       }
-      // Rank by the screen centre's distance to the card's projected footprint — 0
-      // whenever the centre sits over the card. So a tall card the viewport is parked
-      // inside wins over a shorter neighbour whose top edge merely happens to be nearer
-      // the centre line (the old top-centre anchor penalised a card you'd scrolled into
-      // once its top scrolled above the viewport). The footprint is the stable expanded
-      // extent — its top doesn't move and its bottom uses the cached expanded height —
-      // so the ranking can't oscillate as cards expand / collapse.
-      const ddx = Math.max(footprint.left - cx, 0, cx - footprint.right)
-      const ddy = Math.max(footprint.top - cy, 0, cy - footprint.bottom)
-      const dist = ddx * ddx + ddy * ddy
-      candidates.push({ id: t.id, rect: footprint, dist })
+      // Rank by the screen centre's distance to the card's stable header (top edge),
+      // so the card you're looking at wins and a tall card's expanded body can't claim
+      // the centre just by covering it. See utils/taskExpansionRanking.ts.
+      candidates.push({ id: t.id, rect: footprint, dist: headerDistanceSq(footprint, cx, cy) })
     }
     // Drop cached heights for cards that are gone, so the map can't grow unbounded.
     for (const id of expandedHeight.keys()) if (!liveIds.has(id)) expandedHeight.delete(id)
     candidates.sort((a, b) => a.dist - b.dist)
 
-    // Greedy by distance to centre: a candidate is granted only if its projected
-    // footprint clears every footprint already granted, so the centre-most card
-    // wins any overlap.
+    // Greedy by header distance: a candidate is granted only if its projected footprint
+    // clears every footprint already granted, so the centre-most card wins any overlap.
+    // The hovered card is granted FIRST, so hovering a card expands it regardless of its
+    // distance from the centre (and a centre-most neighbour it overlaps yields to it).
+    const hovered = hoveredTaskId()
     const claimed: Rect[] = []
     const next = new Set<string>()
+    const hoveredCard = hovered ? candidates.find((c) => c.id === hovered) : undefined
+    if (hoveredCard) {
+      next.add(hoveredCard.id)
+      claimed.push(hoveredCard.rect)
+    }
     for (const c of candidates) {
+      if (c.id === hoveredCard?.id) continue
       if (claimed.some((r) => intersects(c.rect, r))) continue
       next.add(c.id)
       claimed.push(c.rect)
@@ -114,10 +137,16 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
   const { pause, resume } = useRafFn(recompute, { immediate: false })
   onMounted(() => {
     store.setDriverActive(true)
+    const el = container.value
+    el?.addEventListener('pointermove', onPointerMove)
+    el?.addEventListener('pointerleave', onPointerLeave)
     resume()
   })
   onBeforeUnmount(() => {
     pause()
+    const el = container.value
+    el?.removeEventListener('pointermove', onPointerMove)
+    el?.removeEventListener('pointerleave', onPointerLeave)
     store.setDriverActive(false)
   })
 }

package/app/stores/board.spec.ts

@@ -173,7 +173,7 @@ describe('board store read getters', () => {
       ])
       // module inner width/height fit the task, plus the 30px module header.
       const size = store.containerSize('m1')
-      expect(size.w).toBe(300 + 180 + 12)
+      expect(size.w).toBe(300 + 210 + 12)
       expect(size.h).toBe(200 + 160 + 12 + 30)
     })
 

package/app/stores/taskExpansion.ts

@@ -7,8 +7,9 @@ import { ref } from 'vue'
  * Deep-zoom (`steps`/`subtasks`) grows a task card downward, and cards are
  * absolutely positioned in their frame, so several expanded cards stacked
  * vertically pile on top of each other. The board driver (`useTaskExpansion`)
- * recomputes a permitted set every frame — only on-screen cards, and only the
- * one closest to the screen centre when two would overlap — and writes it here.
+ * recomputes a permitted set every frame — only on-screen cards, the one closest to
+ * the screen centre when two would overlap, plus whichever card the pointer is hovering
+ * (hover expands a card regardless of position) — and writes it here.
  * `TaskPipelineMini` reads `canExpand` to decide whether to expand or stay compact.
  *
  * `driverActive` lets the gate degrade gracefully: with no board driver mounted

package/app/utils/taskExpansionRanking.spec.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { headerDistanceSq, type Rect } from './taskExpansionRanking'
+
+/** Rank a set of cards against a screen centre, best (would-expand) first. */
+function rank(cards: Record<string, Rect>, cx: number, cy: number): string[] {
+  return Object.entries(cards)
+    .map(([id, rect]) => ({ id, dist: headerDistanceSq(rect, cx, cy) }))
+    .sort((a, b) => a.dist - b.dist)
+    .map((c) => c.id)
+}
+
+describe('headerDistanceSq', () => {
+  it('measures from the centre of the card top edge', () => {
+    const r: Rect = { left: 0, right: 100, top: 200, bottom: 600 }
+    // top-centre is (50, 200); centre (50, 240) → dy 40 → 40² = 1600
+    expect(headerDistanceSq(r, 50, 240)).toBe(1600)
+    // 30px to the right of the top-centre, level with the top → 30² = 900
+    expect(headerDistanceSq(r, 80, 200)).toBe(900)
+  })
+
+  it('ignores the expanded height — only the top edge counts', () => {
+    const short: Rect = { left: 0, right: 100, top: 200, bottom: 260 }
+    const tall: Rect = { left: 0, right: 100, top: 200, bottom: 2000 }
+    expect(headerDistanceSq(short, 50, 240)).toBe(headerDistanceSq(tall, 50, 240))
+  })
+})
+
+describe('ranking', () => {
+  // The regression from the screenshot: a tall card parked at the top of the screen
+  // expands its pipeline down past the centre, so its body covers the centre. A compact
+  // card whose header sits right at the centre must still win — the one you're looking at.
+  it('prefers the card whose header is at the centre over a tall card bleeding down from the top', () => {
+    const top: Rect = { left: 0, right: 200, top: 30, bottom: 700 } // header far up, body covers centre
+    const here: Rect = { left: 0, right: 200, top: 320, bottom: 520 } // header at the centre
+    expect(rank({ top, here }, 100, 340)).toEqual(['here', 'top'])
+    // document order can't flip the winner
+    expect(rank({ here, top }, 100, 340)).toEqual(['here', 'top'])
+  })
+
+  it('ranks by the header nearest the centre regardless of expansion state', () => {
+    const above: Rect = { left: 0, right: 200, top: 100, bottom: 800 }
+    const below: Rect = { left: 0, right: 200, top: 360, bottom: 420 }
+    expect(rank({ above, below }, 100, 320)).toEqual(['below', 'above'])
+  })
+
+  it('uses horizontal offset to break a vertical tie', () => {
+    const near: Rect = { left: 0, right: 100, top: 100, bottom: 200 }
+    const far: Rect = { left: 400, right: 500, top: 100, bottom: 200 }
+    expect(rank({ far, near }, 80, 100)).toEqual(['near', 'far'])
+  })
+})

package/app/utils/taskExpansionRanking.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure ranking for the task-expansion gate (see `composables/useTaskExpansion.ts`).
+ *
+ * A task card grows DOWNWARD when it expands its pipeline, so its `top`/`left`/`right`
+ * never move — only its height does. We rank candidates by the screen centre's distance
+ * to each card's stable HEADER anchor (the top edge), which is what the user reads as
+ * "the card I'm looking at". Ranking on the header (not the expanded footprint) is what
+ * stops a tall card from winning just because its expanded body happens to cover the
+ * centre: a compact card whose header sits right at the centre beats a neighbour whose
+ * header is parked at the top of the screen, even when both bodies overlap the centre.
+ *
+ * Because the anchor uses only top/left/right (all stable as the card expands and
+ * collapses), the ordering can't oscillate. A tall card you've scrolled past the top of
+ * is no longer kept expanded by the ranking itself — the hover "pin" in the driver keeps
+ * the pipeline you're pointing at from collapsing while you scroll.
+ */
+export type Rect = { left: number; right: number; top: number; bottom: number }
+
+/**
+ * Squared distance from the screen centre `(cx, cy)` to a card's stable header anchor
+ * (the centre of its top edge). Smaller = nearer the centre = ranks first.
+ */
+export function headerDistanceSq(card: Rect, cx: number, cy: number): number {
+  const ax = (card.left + card.right) / 2
+  const dx = ax - cx
+  const dy = card.top - cy
+  return dx * dx + dy * dy
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "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",

package/app/utils/boardDisplacement.spec.ts

@@ -1,63 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { computeDisplacement, type DisplacementBox } from '~/utils/boardDisplacement'
-
-function box(p: Partial<DisplacementBox> & { id: string }): DisplacementBox {
-  return { x: 0, y: 0, w: 10, h: 10, growX: 0, growY: 0, ...p }
-}
-
-describe('computeDisplacement', () => {
-  it('pushes a right-hand neighbour by the expanded box growth, preserving the gap', () => {
-    // A at x=0 w=10 grows by 90; B sits 20 to the right (x=30) in the same row.
-    const offsets = computeDisplacement([
-      box({ id: 'A', x: 0, w: 10, growX: 90 }),
-      box({ id: 'B', x: 30 }),
-    ])
-    expect(offsets.get('A')).toEqual({ dx: 0, dy: 0 })
-    // B moves right by 90, so the 20px gap (A's new right edge 100 → B's new left 120) is kept.
-    expect(offsets.get('B')).toEqual({ dx: 90, dy: 0 })
-  })
-
-  it('does not push a neighbour that was already overlapping the box horizontally', () => {
-    // B starts inside A's collapsed extent (x=5 < A.right=10): already overlapping, left as-is.
-    const offsets = computeDisplacement([
-      box({ id: 'A', x: 0, w: 10, growX: 90 }),
-      box({ id: 'B', x: 5 }),
-    ])
-    expect(offsets.get('B')).toEqual({ dx: 0, dy: 0 })
-  })
-
-  it('accumulates the growth of every expanded box to the left (chains)', () => {
-    const offsets = computeDisplacement([
-      box({ id: 'A', x: 0, w: 10, growX: 90 }),
-      box({ id: 'B', x: 30, w: 10, growX: 50 }),
-      box({ id: 'C', x: 60 }),
-    ])
-    // C is right of both A and B → pushed by 90 + 50.
-    expect(offsets.get('C')!.dx).toBe(140)
-    // B is right of A only → pushed by 90.
-    expect(offsets.get('B')!.dx).toBe(90)
-  })
-
-  it('does not cross-push boxes that are disjoint on the other axis', () => {
-    // A grows rightward but B is far below it (no shared rows) → no horizontal push.
-    const offsets = computeDisplacement([
-      box({ id: 'A', x: 0, y: 0, w: 10, h: 10, growX: 90 }),
-      box({ id: 'B', x: 30, y: 500, w: 10, h: 10 }),
-    ])
-    expect(offsets.get('B')).toEqual({ dx: 0, dy: 0 })
-  })
-
-  it('pushes a box below an expanded box downward', () => {
-    const offsets = computeDisplacement([
-      box({ id: 'A', x: 0, y: 0, w: 10, h: 10, growY: 100 }),
-      box({ id: 'B', x: 0, y: 30, w: 10, h: 10 }),
-    ])
-    expect(offsets.get('B')).toEqual({ dx: 0, dy: 100 })
-  })
-
-  it('returns a zero offset for every box when nothing is expanded', () => {
-    const offsets = computeDisplacement([box({ id: 'A', x: 0 }), box({ id: 'B', x: 30 })])
-    expect(offsets.get('A')).toEqual({ dx: 0, dy: 0 })
-    expect(offsets.get('B')).toEqual({ dx: 0, dy: 0 })
-  })
-})

package/app/utils/boardDisplacement.ts

@@ -1,62 +0,0 @@
-/**
- * Compressed-space layout for the board. When a box (a service frame, or a task
- * card inside a frame) expands, it grows rightward / downward from its stored
- * top-left. Rather than letting the expanded footprint overlap its neighbours —
- * and then collapsing one of them to resolve the clash, which is what made a
- * zoomed-in service "snap out" as you scrolled across it — we PUSH the neighbours
- * away by the growth, so an expanded box never overlaps a neighbour it wasn't
- * already overlapping. The box stays expanded; you just scroll a bit further to
- * reach the next one.
- *
- * The result is a render-only offset per box; stored positions are never mutated.
- */
-export type DisplacementBox = {
-  id: string
-  /** Stored top-left, in flow units. */
-  x: number
-  y: number
-  /** Collapsed size, in flow units. */
-  w: number
-  h: number
-  /** Extra size when expanded (0 for a collapsed box). */
-  growX: number
-  growY: number
-}
-
-export type Offset = { dx: number; dy: number }
-
-/** Do the two boxes' collapsed extents overlap on the y-axis? */
-function overlapsY(a: DisplacementBox, b: DisplacementBox) {
-  return a.y < b.y + b.h && b.y < a.y + a.h
-}
-
-/** Do the two boxes' collapsed extents overlap on the x-axis? */
-function overlapsX(a: DisplacementBox, b: DisplacementBox) {
-  return a.x < b.x + b.w && b.x < a.x + a.w
-}
-
-/**
- * The render offset for every box. A box B is pushed right by the horizontal
- * growth of each expanded box E that sits to B's left (B starts past E's collapsed
- * right edge, so it isn't already overlapping E on x) and shares B's rows (their
- * collapsed y-extents overlap, so E growing rightward would actually reach B).
- * Symmetric for the downward push. Offsets only ever grow, so the function can
- * never create a new overlap, preserves left-to-right / top-to-bottom order and
- * the gaps between boxes, and chained expansions accumulate (the sum is taken from
- * the stable stored positions, so it doesn't oscillate). O(N x expanded).
- */
-export function computeDisplacement(boxes: DisplacementBox[]): Map<string, Offset> {
-  const expanded = boxes.filter((e) => e.growX > 0 || e.growY > 0)
-  const out = new Map<string, Offset>()
-  for (const b of boxes) {
-    let dx = 0
-    let dy = 0
-    for (const e of expanded) {
-      if (e.id === b.id) continue
-      if (e.growX > 0 && b.x >= e.x + e.w && overlapsY(e, b)) dx += e.growX
-      if (e.growY > 0 && b.y >= e.y + e.h && overlapsX(e, b)) dy += e.growY
-    }
-    out.set(b.id, { dx, dy })
-  }
-  return out
-}