@cat-factory/app 0.79.1 → 0.79.2

package/app/components/board/BoardCanvas.vue

@@ -10,6 +10,7 @@ import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
 import { useTaskExpansion } from '~/composables/useTaskExpansion'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useFrameStacking } from '~/composables/useFrameStacking'
+import { useFramePlacement } from '~/composables/useFramePlacement'
 import { useViewport } from '~/composables/useViewport'
 import { boardPanMode } from '~/utils/boardPanMode'
 
@@ -24,6 +25,7 @@ const { t } = useI18n()
 const { onNodeDragStop, onViewportChange, screenToFlowCoordinate } = useVueFlow(BOARD_FLOW_ID)
 const { draggingId } = useBlockDrag()
 const { hoveredFrameId } = useFrameStacking()
+const { freeFramePosition, focusFrame } = useFramePlacement()
 // Touch drives the canvas gestures: a touch-capable surface needs one-finger pan.
 // We gate on `hasTouch` (any-pointer: coarse), not `isTouch` (the *primary* pointer),
 // so a touchscreen laptop / 2-in-1 — whose primary pointer is the trackpad — still
@@ -121,10 +123,14 @@ async function onDrop(event: DragEvent) {
   if (!payload) return
 
   if (payload.kind === 'block') {
-    const position = screenToFlowCoordinate({ x: event.clientX, y: event.clientY })
+    // Drop where the cursor is, but nudge off any existing frame it lands on so a new
+    // frame never overlaps a neighbour; then centre the camera on it.
+    const dropped = screenToFlowCoordinate({ x: event.clientX, y: event.clientY })
+    const position = freeFramePosition({ near: dropped })
     try {
       const block = await board.addBlock(payload.blockType, position)
       ui.select(block.id)
+      await focusFrame(block.id)
     } catch {
       toast.add({
         title: t('board.canvas.addBlockFailedTitle'),

package/app/components/bootstrap/BootstrapModal.vue

@@ -13,7 +13,9 @@ const ui = useUiStore()
 const bootstrap = useBootstrapStore()
 const agentRuns = useAgentRunsStore()
 const github = useGitHubStore()
+const board = useBoardStore()
 const toast = useToast()
+const { freeFramePosition, focusFrame } = useFramePlacement()
 const { t } = useI18n()
 const { confirmAction, toastDone } = useConfirmAction()
 
@@ -242,6 +244,22 @@ async function launch() {
       instructions.value = ''
       // Reset the repo role too, so a later bootstrap doesn't silently inherit this one's type.
       selectedType.value = 'service'
+      // The provisional frame arrived (bootstrap() refreshed the board). Re-home it to
+      // free space so it never overlaps an existing service — the backend places it on a
+      // fixed diagonal stagger that can land on top of a large neighbour — then centre the
+      // camera on it. Best-effort: the run has already started, so a placement hiccup must
+      // NOT surface a bootstrap-failed toast or leave the dialog open — swallow it here
+      // rather than letting it reach the outer catch.
+      if (job.blockId && board.getBlock(job.blockId)) {
+        const id = job.blockId
+        try {
+          const position = freeFramePosition({ size: board.containerSize(id), exclude: id })
+          await board.moveBlock(id, position)
+          await focusFrame(id)
+        } catch {
+          // Placement is cosmetic; the run is tracked on the board regardless.
+        }
+      }
       // The run is now tracked on the board, so get out of the way: close the
       // dialog as soon as bootstrapping has actually started.
       ui.closeBootstrap()

package/app/components/github/AddServiceFromRepoModal.vue

@@ -28,6 +28,7 @@ const ui = useUiStore()
 const github = useGitHubStore()
 const board = useBoardStore()
 const toast = useToast()
+const { freeFramePosition, focusFrame } = useFramePlacement()
 
 const open = computed({
   get: () => ui.addServiceOpen,
@@ -218,9 +219,14 @@ async function add() {
       directory: isMonorepo.value ? selectedDirectory.value : undefined,
       isMonorepo: isMonorepo.value,
       type: selectedType.value,
+      // Place the imported frame in free space (centred in view) instead of the
+      // backend's default stagger, so it never overlaps an existing service.
+      position: freeFramePosition(),
     })
     // Refresh the projection so the new repo↔block link is reflected locally.
     await github.load()
+    // Centre the camera on the newly imported service.
+    await focusFrame(block.id)
     configuredBlockId.value = block.id
     configuredDirectory.value = isMonorepo.value ? selectedDirectory.value : undefined
     toast.add({

package/app/composables/useFramePlacement.ts

@@ -0,0 +1,91 @@
+import { nextTick } from 'vue'
+import { useVueFlow } from '@vue-flow/core'
+import { BOARD_FLOW_ID } from '~/composables/useBoardFlow'
+import {
+  EMPTY_FRAME_SIZE,
+  EPIC_NODE_SIZE,
+  findFreeFramePosition,
+  type Point,
+  type FrameRect,
+} from '~/utils/framePlacement'
+
+/**
+ * Placement + camera helpers for adding a service frame to the board, honouring the
+ * house rule: a new frame never overlaps an existing one and the camera centres on it.
+ *
+ * The board (Vue Flow) is the single source of truth for the camera, so this lives in a
+ * composable rather than the board store — every "add a frame" call site (palette drop,
+ * repo import, repo bootstrap) runs it right after the block exists.
+ */
+
+/**
+ * The floor we snap the camera zoom up to when centring a new frame, so one added while
+ * the board is zoomed far out still lands legibly on screen. We only ever zoom the user
+ * *in* to this floor — a closer zoom is left alone (`Math.max`).
+ */
+const MIN_FOCUS_ZOOM = 0.6
+
+export function useFramePlacement() {
+  const board = useBoardStore()
+  const { viewport, setCenter, screenToFlowCoordinate } = useVueFlow(BOARD_FLOW_ID)
+
+  /**
+   * Every existing top-level board node's rect in flow-space — both service frames
+   * (stored position + rendered size) and epic grouping cards — so a placed frame
+   * clears epics as well as frames (both are drawn as Vue Flow nodes; see `BoardCanvas`).
+   */
+  function existingNodeRects(exclude?: string): FrameRect[] {
+    const frames = board.frames
+      .filter((f) => f.id !== exclude)
+      .map((f) => {
+        const s = board.containerSize(f.id)
+        return { x: f.position.x, y: f.position.y, w: s.w, h: s.h }
+      })
+    const epics = board.epics
+      .filter((e) => e.id !== exclude)
+      .map((e) => ({ x: e.position.x, y: e.position.y, w: EPIC_NODE_SIZE.w, h: EPIC_NODE_SIZE.h }))
+    return [...frames, ...epics]
+  }
+
+  /**
+   * The flow-space top-left at which a frame of `size` would sit centred in the
+   * current view — the natural anchor for a frame added without a specific drop point
+   * (repo import / bootstrap), so it appears where the user is already looking.
+   */
+  function viewportCenteredAnchor(size: { w: number; h: number }): Point {
+    const c = screenToFlowCoordinate({ x: window.innerWidth / 2, y: window.innerHeight / 2 })
+    return { x: c.x - size.w / 2, y: c.y - size.h / 2 }
+  }
+
+  /**
+   * A non-overlapping top-left for a new frame. `near` is the preferred spot (a drop
+   * cursor's flow coords); omitted, the frame is anchored to the centre of the current
+   * view. `exclude` skips a frame's own rect when re-placing one that already exists
+   * (bootstrap re-homes its provisional frame).
+   */
+  function freeFramePosition(opts?: {
+    near?: Point
+    size?: { w: number; h: number }
+    exclude?: string
+  }): Point {
+    const size = opts?.size ?? EMPTY_FRAME_SIZE
+    const desired = opts?.near ?? viewportCenteredAnchor(size)
+    return findFreeFramePosition(existingNodeRects(opts?.exclude), size, desired)
+  }
+
+  /** Pan (and, if zoomed far out, gently zoom in) the camera to centre on a frame. */
+  async function focusFrame(id: string, opts?: { duration?: number }): Promise<void> {
+    const frame = board.getBlock(id)
+    if (!frame) return
+    const s = board.containerSize(id)
+    const cx = frame.position.x + s.w / 2
+    const cy = frame.position.y + s.h / 2
+    const zoom = Math.max(viewport.value.zoom, MIN_FOCUS_ZOOM)
+    // Let any layout the caller just triggered (e.g. the inspector opening on select)
+    // settle so the centre is computed against the real pane size.
+    await nextTick()
+    setCenter(cx, cy, { zoom, duration: opts?.duration ?? 400 })
+  }
+
+  return { freeFramePosition, focusFrame }
+}

package/app/stores/board.ts

@@ -90,13 +90,19 @@ export const useBoardStore = defineStore('board', () => {
    */
   async function addServiceFromRepo(
     repoGithubId: number,
-    opts?: { directory?: string; isMonorepo?: boolean; type?: FrameRepoType },
+    opts?: {
+      directory?: string
+      isMonorepo?: boolean
+      type?: FrameRepoType
+      position?: { x: number; y: number }
+    },
   ): Promise<Block> {
     const block = await api.addServiceFromRepo(useWorkspaceStore().requireId(), {
       repoGithubId,
       ...(opts?.directory ? { directory: opts.directory } : {}),
       ...(opts?.isMonorepo !== undefined ? { isMonorepo: opts.isMonorepo } : {}),
       ...(opts?.type ? { type: opts.type } : {}),
+      ...(opts?.position ? { position: opts.position } : {}),
     })
     upsert(block)
     return block

package/app/utils/framePlacement.spec.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import { findFreeFramePosition, framesCollide, FRAME_GAP, type FrameRect } from './framePlacement'
+
+const size = { w: 360, h: 220 }
+
+describe('framesCollide', () => {
+  it('reports overlapping rects as colliding', () => {
+    const a: FrameRect = { x: 0, y: 0, w: 100, h: 100 }
+    const b: FrameRect = { x: 50, y: 50, w: 100, h: 100 }
+    expect(framesCollide(a, b)).toBe(true)
+  })
+
+  it('treats rects separated by a clear channel as not colliding', () => {
+    const a: FrameRect = { x: 0, y: 0, w: 100, h: 100 }
+    const b: FrameRect = { x: 200, y: 0, w: 100, h: 100 }
+    expect(framesCollide(a, b)).toBe(false)
+  })
+
+  it('honours the gap margin: touching-but-clear rects collide once a gap is required', () => {
+    const a: FrameRect = { x: 0, y: 0, w: 100, h: 100 }
+    const b: FrameRect = { x: 100, y: 0, w: 100, h: 100 } // flush against `a`
+    expect(framesCollide(a, b)).toBe(false) // no gap: exactly touching clears
+    expect(framesCollide(a, b, 1)).toBe(true) // any required gap is violated
+  })
+})
+
+describe('findFreeFramePosition', () => {
+  it('returns the desired spot verbatim when it is already free', () => {
+    const desired = { x: 500, y: 500 }
+    expect(findFreeFramePosition([], size, desired)).toEqual(desired)
+  })
+
+  it('keeps a deliberate drop that clears every existing frame', () => {
+    const existing: FrameRect[] = [{ x: 0, y: 0, ...size }]
+    const desired = { x: 900, y: 0 }
+    expect(findFreeFramePosition(existing, size, desired)).toEqual(desired)
+  })
+
+  it('moves off a spot that overlaps an existing frame, and the result clears it', () => {
+    const existing: FrameRect[] = [{ x: 0, y: 0, ...size }]
+    const desired = { x: 40, y: 20 } // squarely on top of the existing frame
+    const placed = findFreeFramePosition(existing, size, desired)
+    const placedRect: FrameRect = { ...placed, ...size }
+    expect(framesCollide(placedRect, existing[0]!, FRAME_GAP)).toBe(false)
+  })
+
+  it('finds a free cell even when the desired spot is boxed in by neighbours', () => {
+    // Frames all around the origin; the desired centre cell is taken and crowded.
+    const step = size.w + FRAME_GAP
+    const existing: FrameRect[] = [
+      { x: 0, y: 0, ...size },
+      { x: step, y: 0, ...size },
+      { x: -step, y: 0, ...size },
+      { x: 0, y: size.h + FRAME_GAP, ...size },
+    ]
+    const placed = findFreeFramePosition(existing, size, { x: 0, y: 0 })
+    const placedRect: FrameRect = { ...placed, ...size }
+    for (const r of existing) {
+      expect(framesCollide(placedRect, r, FRAME_GAP)).toBe(false)
+    }
+  })
+
+  it('places the nearest free cell to the desired point', () => {
+    // Only the desired cell is occupied; the closest free cell is one step away.
+    const existing: FrameRect[] = [{ x: 0, y: 0, ...size }]
+    const placed = findFreeFramePosition(existing, size, { x: 0, y: 0 })
+    const step = size.w + FRAME_GAP
+    // The nearest ring cell is a single frame-step away on one axis.
+    const dist = Math.hypot(placed.x, placed.y)
+    expect(dist).toBeLessThanOrEqual(Math.hypot(step, step) + 1)
+    expect(dist).toBeGreaterThan(0)
+  })
+})

package/app/utils/framePlacement.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure geometry for placing a new service frame on the board without overlapping
+ * the ones already there. Split out from the composable that reads the live board
+ * so the placement decision is a plain, deterministically testable function.
+ *
+ * Everything here is flow-space (the absolute `{ x, y }` a block stores), with the
+ * origin at a frame's top-left corner — the same coordinate system Vue Flow renders
+ * nodes in. Sizes are the frame's rendered pixel footprint (see
+ * {@link useBlockQueries.containerSize}).
+ */
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface FrameRect extends Point {
+  w: number
+  h: number
+}
+
+/** Spacing kept between frames so a placed frame never sits flush against a neighbour. */
+export const FRAME_GAP = 48
+
+/**
+ * Footprint of a freshly-added, empty service frame in flow-space. Mirrors the
+ * empty-frame floor in {@link useBlockQueries.contentSize} (w 360, inner h 220) so a
+ * placement decision made BEFORE the block exists matches how it will actually render.
+ */
+export const EMPTY_FRAME_SIZE = { w: 360, h: 220 }
+
+/**
+ * Footprint of an epic grouping node in flow-space. Epics are top-level board nodes
+ * drawn alongside frames (see `BoardCanvas`), so a placed frame must clear them too.
+ * Mirrors the compact `EpicNode` card (`w-56` = 224px, ~96px tall); a slight
+ * over-estimate is harmless — it only widens the clearance around an epic.
+ */
+export const EPIC_NODE_SIZE = { w: 224, h: 96 }
+
+/**
+ * Do rects `a` and `b` come within `gap` px of each other — i.e. fail to clear? Two
+ * rects clear when a full `gap`-wide channel separates them on any axis; if none does,
+ * they collide.
+ */
+export function framesCollide(a: FrameRect, b: FrameRect, gap = 0): boolean {
+  return !(
+    a.x + a.w + gap <= b.x ||
+    b.x + b.w + gap <= a.x ||
+    a.y + a.h + gap <= b.y ||
+    b.y + b.h + gap <= a.y
+  )
+}
+
+function fits(candidate: FrameRect, existing: FrameRect[], gap: number): boolean {
+  return existing.every((r) => !framesCollide(candidate, r, gap))
+}
+
+function dist2(a: Point, b: Point): number {
+  const dx = a.x - b.x
+  const dy = a.y - b.y
+  return dx * dx + dy * dy
+}
+
+/**
+ * Find a top-left position for a new frame of `size` that clears every rect in
+ * `existing` by at least `gap`, staying as close as possible to `desired`.
+ *
+ * `desired` is used verbatim when it's already free, so a deliberate drop lands where
+ * the user aimed. Otherwise we spiral outward on a grid of frame-sized steps and take
+ * the nearest free cell. The ring search is bounded, so as a guaranteed last resort we
+ * drop the frame in a fresh column to the right of everything — a board can't have a
+ * position that never clears.
+ */
+export function findFreeFramePosition(
+  existing: FrameRect[],
+  size: { w: number; h: number },
+  desired: Point,
+  gap = FRAME_GAP,
+): Point {
+  const rectAt = (p: Point): FrameRect => ({ x: p.x, y: p.y, w: size.w, h: size.h })
+  if (fits(rectAt(desired), existing, gap)) return desired
+
+  const stepX = size.w + gap
+  const stepY = size.h + gap
+  const MAX_RADIUS = 12
+  for (let radius = 1; radius <= MAX_RADIUS; radius++) {
+    // The candidates on this square ring, nearest-to-`desired` first, so the chosen
+    // free cell is the closest one at this radius (a ring is scanned whole before we
+    // widen, so overall we still take the nearest free cell on the board).
+    const ring: Point[] = []
+    for (let dy = -radius; dy <= radius; dy++) {
+      for (let dx = -radius; dx <= radius; dx++) {
+        if (Math.max(Math.abs(dx), Math.abs(dy)) !== radius) continue
+        ring.push({ x: desired.x + dx * stepX, y: desired.y + dy * stepY })
+      }
+    }
+    ring.sort((p, q) => dist2(p, desired) - dist2(q, desired))
+    for (const c of ring) if (fits(rectAt(c), existing, gap)) return c
+  }
+
+  const rightmost = existing.reduce((m, r) => Math.max(m, r.x + r.w), desired.x)
+  return { x: rightmost + gap, y: desired.y }
+}

package/package.json

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