@cat-factory/app 0.17.0 → 0.17.2

package/app/components/board/BoardCanvas.vue

@@ -9,6 +9,7 @@ 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 { useFrameExpansion } from '~/composables/useFrameExpansion'
 
 const board = useBoardStore()
 const pipelines = usePipelinesStore()
@@ -21,8 +22,11 @@ const { onNodeDragStop, onViewportChange, screenToFlowCoordinate } = useVueFlow(
 
 // Gate which task cards expand their pipeline list on deep zoom: only on-screen
 // cards, and only the centre-most of any that would overlap (see useTaskExpansion).
+// The frame-level gate is the same idea one level up: which service frames may
+// auto-expand to their task canvas once zoomed in (see useFrameExpansion).
 const boardEl = ref<HTMLElement | null>(null)
 useTaskExpansion(boardEl)
+useFrameExpansion(boardEl)
 
 // Only frames are board nodes. Dependencies live on tasks (rendered inside the
 // frames), so there are no frame-to-frame edges on the canvas.

package/app/composables/useFrameExpansion.ts

@@ -0,0 +1,118 @@
+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 }
+
+function intersects(a: Rect, b: Rect) {
+  return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top
+}
+
+function sameSet(a: Set<string>, b: Set<string>) {
+  if (a.size !== b.size) return false
+  for (const id of a) if (!b.has(id)) return false
+  return true
+}
+
+/**
+ * Board-level driver deciding which service frames may auto-expand to their task
+ * canvas once zoomed past the `close` band. The frame analogue of
+ * `useTaskExpansion`: two gates, recomputed every frame against live DOM rects so
+ * they follow pan / zoom / drag / resize:
+ *
+ *  - visibility: a frame expands only while its card overlaps the board viewport,
+ *    so a service that isn't on screen at all never expands when you zoom in.
+ *  - overlap: walking the visible frames nearest-to-screen-centre first, a frame
+ *    expands only if its (expanded) footprint doesn't collide with one already
+ *    granted — so the small service the user centred on wins, and a larger
+ *    neighbour can't "snap out" over it.
+ *
+ * Writes the permitted id set into the `frameExpansion` store; `ui.isFrameExpanded`
+ * reads it. Manually-expanded frames bypass this gate entirely (see the store).
+ */
+export function useFrameExpansion(container: Ref<HTMLElement | null>) {
+  const board = useBoardStore()
+  const ui = useUiStore()
+  const store = useFrameExpansionStore()
+
+  // Last-known expanded size per frame. A frame's card balloons from a chip to its
+  // full task canvas only while it's granted, so its live rect collapses the moment
+  // it's denied. Testing overlap with the collapsed chip is what would cause
+  // flashing: a denied frame no longer overlaps its neighbour, gets re-granted,
+  // expands, overlaps again, gets denied — every frame. We cache the expanded
+  // extent while a frame is granted and project the footprint with it, so a denied
+  // frame is still tested at its expanded size and stays denied. Stable.
+  const expandedSize = new Map<string, { w: number; h: number }>()
+
+  function rectOf(id: string): DOMRect | null {
+    const el = document.querySelector(`[data-block-id="${id}"]`) as HTMLElement | null
+    return el ? el.getBoundingClientRect() : null
+  }
+
+  function recompute() {
+    // Frames only auto-expand at the `close` band and deeper; clear otherwise.
+    if (!lodAtLeast(ui.lod, 'close')) {
+      if (store.allowed.size) store.setAllowed(new Set())
+      return
+    }
+    const view = container.value?.getBoundingClientRect()
+    if (!view) return
+    const cx = view.left + view.width / 2
+    const cy = view.top + view.height / 2
+
+    const candidates: { id: string; rect: Rect; dist: number }[] = []
+    const liveIds = new Set<string>()
+    for (const f of board.frames) {
+      const rect = rectOf(f.id)
+      if (!rect) continue
+      liveIds.add(f.id)
+      // While granted the frame is rendered expanded, so its live rect is its
+      // expanded footprint — cache it. A denied frame keeps its last cached value.
+      if (store.allowed.has(f.id)) expandedSize.set(f.id, { w: rect.width, h: rect.height })
+      // Visibility: the card must intersect the board viewport (live rect).
+      if (!intersects(rect, view)) continue
+      // Project to the cached expanded extent so the overlap test is independent of
+      // the card's current (possibly collapsed-chip) state. A frame grows rightward
+      // and downward from its top-left, which stays put as it expands.
+      const cached = expandedSize.get(f.id)
+      const width = Math.max(rect.width, cached?.w ?? 0)
+      const height = Math.max(rect.height, cached?.h ?? 0)
+      const footprint: Rect = {
+        left: rect.left,
+        right: rect.left + width,
+        top: rect.top,
+        bottom: rect.top + height,
+      }
+      // Stable anchor: the card's top-left. It doesn't move as the frame grows, so
+      // the ordering can't oscillate as frames expand / collapse.
+      const dist = (rect.left - cx) ** 2 + (rect.top - cy) ** 2
+      candidates.push({ id: f.id, rect: footprint, dist })
+    }
+    // Drop cached sizes for frames that are gone, so the map can't grow unbounded.
+    for (const id of expandedSize.keys()) if (!liveIds.has(id)) expandedSize.delete(id)
+    candidates.sort((a, b) => a.dist - b.dist)
+
+    // Greedy by distance to centre: a frame is granted only if its projected
+    // footprint clears every footprint already granted, so the centre-most frame
+    // wins any overlap.
+    const claimed: Rect[] = []
+    const next = new Set<string>()
+    for (const c of candidates) {
+      if (claimed.some((r) => intersects(c.rect, r))) continue
+      next.add(c.id)
+      claimed.push(c.rect)
+    }
+    if (!sameSet(next, store.allowed)) store.setAllowed(next)
+  }
+
+  const { pause, resume } = useRafFn(recompute, { immediate: false })
+  onMounted(() => {
+    store.setDriverActive(true)
+    resume()
+  })
+  onBeforeUnmount(() => {
+    pause()
+    store.setDriverActive(false)
+  })
+}

package/app/composables/useTaskExpansion.ts

@@ -35,6 +35,15 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
   const ui = useUiStore()
   const store = useTaskExpansionStore()
 
+  // Last-known expanded height per task. A card grows downward only while it's
+  // granted (its pipeline list is rendered), so its live height collapses the
+  // moment it's denied. Testing overlap with that collapsed height is what causes
+  // the flashing: a denied card no longer overlaps its neighbour, gets re-granted,
+  // expands, overlaps again, gets denied — every frame. We cache the expanded
+  // height while a card is granted and project the footprint with it, so a denied
+  // card is still tested at its expanded extent and stays denied. Stable.
+  const expandedHeight = new Map<string, number>()
+
   function rectOf(id: string): DOMRect | null {
     const el = document.querySelector(`[data-block-id="${id}"]`) as HTMLElement | null
     return el ? el.getBoundingClientRect() : null
@@ -51,26 +60,43 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
     const cx = view.left + view.width / 2
     const cy = view.top + view.height / 2
 
-    const candidates: { id: string; rect: DOMRect; dist: number }[] = []
+    const candidates: { id: string; rect: Rect; dist: number }[] = []
+    const liveIds = new Set<string>()
     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
-      // Visibility: the card must intersect the board viewport.
+      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.
+      if (store.allowed.has(t.id)) expandedHeight.set(t.id, rect.height)
+      // Visibility: the card must intersect the board viewport (live rect).
       if (!intersects(rect, view)) continue
+      // Project the footprint downward to the expanded extent so the overlap test
+      // is independent of the card's current (possibly collapsed) state.
+      const height = Math.max(rect.height, expandedHeight.get(t.id) ?? 0)
+      const footprint: Rect = {
+        left: rect.left,
+        right: rect.right,
+        top: rect.top,
+        bottom: rect.top + height,
+      }
       // Stable anchor: the card's top-centre. It doesn't move as the card grows
       // downward, so the ordering can't oscillate as cards expand / collapse.
       const ax = rect.left + rect.width / 2
       const ay = rect.top
       const dist = (ax - cx) ** 2 + (ay - cy) ** 2
-      candidates.push({ id: t.id, rect, dist })
+      candidates.push({ id: t.id, rect: footprint, dist })
     }
+    // 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 rect clears
-    // every rect already granted, so the centre-most card wins any overlap.
-    const claimed: DOMRect[] = []
+    // 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.
+    const claimed: Rect[] = []
     const next = new Set<string>()
     for (const c of candidates) {
       if (claimed.some((r) => intersects(c.rect, r))) continue

package/app/stores/frameExpansion.ts

@@ -0,0 +1,38 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+/**
+ * Which service frames may auto-expand to reveal their tasks once zoomed in.
+ *
+ * Past the `close` band a frame opens from a chip to its full task canvas, which
+ * can balloon across the viewport. Expanding *every* frame at once (the old
+ * behaviour) made a large off-centre service "snap out" over the small one the
+ * user was actually centred on, and expanded services that weren't even on screen.
+ * The board driver (`useFrameExpansion`) recomputes a permitted set every frame —
+ * only on-screen frames, and only the one closest to the screen centre when two
+ * expanded footprints would overlap — and writes it here. `ui.isFrameExpanded`
+ * reads `canExpand` to decide whether the zoom band may open a frame.
+ *
+ * `driverActive` lets the gate degrade gracefully: with no board driver mounted
+ * (e.g. the focus view, or a frame rendered in isolation / tests) `canExpand`
+ * falls back to "allowed", so the plain zoom behaviour is unchanged.
+ */
+export const useFrameExpansionStore = defineStore('frameExpansion', () => {
+  const allowed = ref<Set<string>>(new Set())
+  const driverActive = ref(false)
+
+  function setAllowed(ids: Set<string>) {
+    allowed.value = ids
+  }
+
+  function setDriverActive(active: boolean) {
+    driverActive.value = active
+    if (!active) allowed.value = new Set()
+  }
+
+  function canExpand(id: string) {
+    return driverActive.value ? allowed.value.has(id) : true
+  }
+
+  return { allowed, driverActive, setAllowed, setDriverActive, canExpand }
+})

package/app/stores/ui.ts

@@ -4,6 +4,7 @@ import type { DocumentSourceKind, TaskSourceKind, LodLevel } from '~/types/domai
 import type { PendingContext } from '~/composables/useContextLinking'
 import { zoomToLod, lodAtLeast } from '~/composables/useSemanticZoom'
 import { useExecutionStore } from '~/stores/execution'
+import { useFrameExpansionStore } from '~/stores/frameExpansion'
 import { agentKindMeta } from '~/utils/catalog'
 
 /** Values used to seed the add-task form when it is opened from another surface. */
@@ -159,9 +160,14 @@ export const useUiStore = defineStore('ui', () => {
   }
 
   /** A frame shows its tasks when manually expanded OR once zoomed in to `close`
-   * or any deeper band (`steps`/`subtasks` drill further into those tasks). */
+   * or any deeper band (`steps`/`subtasks` drill further into those tasks). The
+   * zoom-driven branch is gated by the board's frame-expansion driver so only
+   * on-screen, centre-most frames open — a large off-centre or off-screen service
+   * no longer snaps out over the one the user is focused on. The gate degrades to
+   * "allowed" when no board driver is mounted (focus view / tests). */
   function isFrameExpanded(id: string) {
-    return expandedFrames.value.has(id) || lodAtLeast(lod.value, 'close')
+    if (expandedFrames.value.has(id)) return true
+    return lodAtLeast(lod.value, 'close') && useFrameExpansionStore().canExpand(id)
   }
 
   function select(id: string | null) {

package/package.json

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