@cat-factory/app 0.30.4 → 0.30.6

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,46 @@ 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.
+//
+// `elevate-nodes-on-select` is turned OFF on <VueFlow> for this to work: Vue Flow's
+// default adds +1000 to a selected node's z-index, so a frame stayed pinned on top
+// after a click and no amount of hovering another frame could surface it. Stacking
+// is driven purely by hover/drag here; the selection highlight is the ring, not z.
+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) => {
@@ -202,6 +168,7 @@ async function onDrop(event: DragEvent) {
       :max-zoom="3"
       :default-viewport="{ x: 40, y: 20, zoom: 0.85 }"
       :pan-on-drag="[0, 2]"
+      :elevate-nodes-on-select="false"
       fit-view-on-init
       @node-click="onNodeClick"
       @node-double-click="onNodeDoubleClick"

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/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/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/package.json

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