@cat-factory/app 0.79.0 → 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/components/panels/AgentStepDetail.vue

@@ -89,6 +89,14 @@ const executionId = computed(() => instance.value?.id ?? null)
 // "spinning up" phase, no spinner.
 const runFailed = computed(() => instance.value?.status === 'failed')
 
+// Whether the run is still doing something (can still spin infra up/down). A terminal
+// run (`done`/`failed`) has nothing left to provision, so the infra-attempts drawer
+// stops its background live-polling (manual refresh stays available).
+const runLive = computed(() => {
+  const status = instance.value?.status
+  return status != null && status !== 'done' && status !== 'failed'
+})
+
 // Live elapsed-time clock for the open step.
 const { isRunning, durationLabel } = useStepTimer({
   step: () => step.value,
@@ -406,6 +414,7 @@ async function copyOutput() {
                   v-if="showProvisioning"
                   class="mt-2"
                   :execution-id="executionId"
+                  :live="runLive"
                 />
               </div>
 

package/app/components/provisioning/ProvisioningLogsDrawer.vue

@@ -4,15 +4,28 @@
 // container), with its outcome and — for failures — the verbatim provider/runtime
 // error. Two modes, mutually exclusive: pass `subsystem` for the provider config
 // panels' drawer, or `executionId` for a run's "Infrastructure attempts" drawer (which
-// surfaces that run's container/runner/env attempts). Loaded on mount + re-loadable.
-import { onMounted } from 'vue'
+// surfaces that run's container/runner/env attempts).
+//
+// In `executionId` mode the drawer LIVE-tracks: while the run is active (`live`) it
+// silently re-polls so each container spin-up / tear-down appears with its timestamp as
+// it happens, and it does one final poll when the run goes terminal to catch the last
+// tear-down row (written just before the terminal event), after which the auto-poll
+// stops. Background polls never spin the refresh button (they're silent), but the manual
+// refresh control stays available even once the run is terminal — so a tear-down row that
+// was missed or not yet persisted at the terminal instant can always be refetched.
+import { onBeforeUnmount, onMounted, watch } from 'vue'
 import type {
   ProvisioningOperation,
   ProvisioningOutcome,
   ProvisioningSubsystem,
 } from '~/types/provisioningLogs'
 
-const props = defineProps<{ subsystem?: ProvisioningSubsystem; executionId?: string }>()
+const props = defineProps<{
+  subsystem?: ProvisioningSubsystem
+  executionId?: string
+  /** Run-details mode only: whether the run is still active (drives live polling). */
+  live?: boolean
+}>()
 
 const { t, d } = useI18n()
 
@@ -23,12 +36,47 @@ const state = computed(() =>
     : store.bySubsystem[props.subsystem ?? 'environment'],
 )
 
-function reload() {
-  if (props.executionId) void store.loadForExecution(props.executionId)
+function reload(silent = false) {
+  if (props.executionId) void store.loadForExecution(props.executionId, { silent })
   else if (props.subsystem) void store.load(props.subsystem)
 }
 
-onMounted(reload)
+// --- live polling (executionId mode only) --------------------------------
+const POLL_MS = 4000
+let timer: ReturnType<typeof setInterval> | undefined
+
+function stopPolling() {
+  if (timer) {
+    clearInterval(timer)
+    timer = undefined
+  }
+}
+
+function startPolling() {
+  stopPolling()
+  timer = setInterval(() => reload(true), POLL_MS)
+}
+
+watch(
+  () => props.live,
+  (live, wasLive) => {
+    if (live && props.executionId != null) {
+      startPolling()
+      return
+    }
+    // Cleanup must NOT depend on `executionId` still being set: when the run's instance
+    // clears, `live` and `executionId` fall away in the same tick, so stop the interval
+    // unconditionally or it leaks (firing no-op reloads) for the component's lifetime.
+    stopPolling()
+    // On the active→terminal transition, poll once more (silently) to pick up the
+    // tear-down row the engine writes just before it emits the terminal state.
+    if (wasLive && props.executionId != null) reload(true)
+  },
+  { immediate: true },
+)
+
+onMounted(() => reload())
+onBeforeUnmount(stopPolling)
 
 // Exhaustive enum→label maps of literal `t(...)` keys (keeps the typed-key drift guard
 // live for these runtime-indexed lookups).
@@ -62,7 +110,7 @@ function when(epochMs: number): string {
         variant="ghost"
         size="xs"
         :loading="state.loading"
-        @click="reload"
+        @click="reload()"
       >
         {{ t('provisioning.refresh') }}
       </UButton>

package/app/components/testing/TestReportWindow.vue

@@ -60,6 +60,12 @@ const qualityVerdicts = computed(() => [...(quality.value?.verdicts ?? [])].reve
 // run's infrastructure attempts + logs (container/runner/env spin-up), not just the
 // report. The container/subtask signals already flow onto the step via the generic poll.
 const runFailed = computed(() => instance.value?.status === 'failed')
+// A terminal run (done/failed) can't spin more infra: the attempts drawer stops its
+// background live-polling (manual refresh stays available).
+const runLive = computed(() => {
+  const status = instance.value?.status
+  return status != null && status !== 'done' && status !== 'failed'
+})
 const stepEnvironment = computed(() => step.value?.environment ?? null)
 const executionId = computed(() => instance.value?.id ?? null)
 // The infra-attempts log drawer is opened on demand (it fetches the per-run log rows).
@@ -486,6 +492,7 @@ const GROUP_STATUS_META: Record<ScenarioGroup['status'], { icon: string; text: s
                   v-if="showProvisioning"
                   class="mt-2"
                   :execution-id="executionId"
+                  :live="runLive"
                 />
               </div>
             </section>

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/stores/provisioningLogs.spec.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useProvisioningLogsStore } from '~/stores/provisioningLogs'
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { ProvisioningLogEntry } from '~/types/provisioningLogs'
+
+/** Minimal attempt-row factory — only the fields the store passes through. */
+function entry(over: Partial<ProvisioningLogEntry> = {}): ProvisioningLogEntry {
+  return {
+    id: 'p1',
+    workspaceId: 'ws1',
+    subsystem: 'container',
+    operation: 'dispatch',
+    outcome: 'success',
+    targetId: 'job1',
+    providerId: null,
+    blockId: null,
+    executionId: 'exec1',
+    error: null,
+    detail: null,
+    createdAt: 1,
+    ...over,
+  } as ProvisioningLogEntry
+}
+
+describe('provisioningLogs store — loadForExecution', () => {
+  beforeEach(() => {
+    useWorkspaceStore().workspaceId = 'ws1'
+  })
+
+  it('a visible load flips the loading spinner and stores the entries', async () => {
+    let resolveFetch!: (r: { entries: ProvisioningLogEntry[] }) => void
+    const pending = new Promise<{ entries: ProvisioningLogEntry[] }>((res) => {
+      resolveFetch = res
+    })
+    vi.stubGlobal('useApi', () => ({ listProvisioningLogs: () => pending }))
+
+    const store = useProvisioningLogsStore()
+    const load = store.loadForExecution('exec1')
+    // In flight: the button spinner is on.
+    expect(store.byExecution.exec1!.loading).toBe(true)
+
+    resolveFetch({ entries: [entry()] })
+    await load
+
+    expect(store.byExecution.exec1!.loading).toBe(false)
+    expect(store.byExecution.exec1!.entries).toHaveLength(1)
+  })
+
+  it('a silent poll never flips the loading spinner', async () => {
+    vi.stubGlobal('useApi', () => ({
+      listProvisioningLogs: () => Promise.resolve({ entries: [entry({ operation: 'release' })] }),
+    }))
+
+    const store = useProvisioningLogsStore()
+    await store.loadForExecution('exec1', { silent: true })
+
+    // Never went truthy — a background poll must not show a "refreshing" spinner.
+    expect(store.byExecution.exec1!.loading).toBe(false)
+    // But it still updates the timeline (the tear-down row now shows).
+    expect(store.byExecution.exec1!.entries[0]!.operation).toBe('release')
+  })
+
+  it('a silent poll failure keeps the last-good entries and surfaces no error', async () => {
+    const store = useProvisioningLogsStore()
+
+    // Seed a good snapshot via a visible load.
+    vi.stubGlobal('useApi', () => ({
+      listProvisioningLogs: () => Promise.resolve({ entries: [entry()] }),
+    }))
+    await store.loadForExecution('exec1')
+    expect(store.byExecution.exec1!.entries).toHaveLength(1)
+
+    // A background poll then blips — the drawer must keep showing what it had.
+    vi.stubGlobal('useApi', () => ({
+      listProvisioningLogs: () => Promise.reject(new Error('network')),
+    }))
+    await store.loadForExecution('exec1', { silent: true })
+
+    expect(store.byExecution.exec1!.entries).toHaveLength(1)
+    expect(store.byExecution.exec1!.error).toBeNull()
+  })
+
+  it('a visible load failure clears entries and reports the error', async () => {
+    vi.stubGlobal('useApi', () => ({
+      listProvisioningLogs: () => Promise.reject(new Error('503')),
+    }))
+
+    const store = useProvisioningLogsStore()
+    await store.loadForExecution('exec1')
+
+    expect(store.byExecution.exec1!.loading).toBe(false)
+    expect(store.byExecution.exec1!.entries).toHaveLength(0)
+    expect(store.byExecution.exec1!.error).toBe('503')
+  })
+})

package/app/stores/provisioningLogs.ts

@@ -47,22 +47,34 @@ export const useProvisioningLogsStore = defineStore('provisioningLogs', () => {
     }
   }
 
-  async function loadForExecution(executionId: string) {
+  /**
+   * Load a run's provisioning attempts. `silent` is for the drawer's background poll
+   * while the run is live: it must NOT flip the `loading` spinner (it would flicker
+   * every poll) and a transient failure must NOT clear the last-good entries or surface
+   * an error banner — the visible refresh path (initial open / manual refresh) owns those.
+   */
+  async function loadForExecution(executionId: string, opts?: { silent?: boolean }) {
     const ws = useWorkspaceStore()
     const s = (byExecution[executionId] ??= emptyState())
-    s.loading = true
-    s.error = null
+    if (!opts?.silent) {
+      s.loading = true
+      s.error = null
+    }
     try {
       const { entries } = await api.listProvisioningLogs(ws.requireId(), {
         executionId,
         limit: 200,
       })
       s.entries = entries
+      s.error = null
     } catch (err) {
-      s.error = err instanceof Error ? err.message : 'Failed to load logs'
-      s.entries = []
+      // A background poll keeps the last snapshot on a blip; only a visible load reports.
+      if (!opts?.silent) {
+        s.error = err instanceof Error ? err.message : 'Failed to load logs'
+        s.entries = []
+      }
     } finally {
-      s.loading = false
+      if (!opts?.silent) s.loading = false
     }
   }
 

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.0",
+  "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",