@cat-factory/app 0.287.0 → 0.288.1

package/README.md

@@ -342,6 +342,47 @@ projects through kernel's `applyMountLayout`. The resize path is where people hi
 because a `size`-only edit is the one frame patch with no other visible effect: the SPA upserts the
 authoritative block the mutation returned and the frame jumps to coordinates no board shows it at.
 
+**No two top-level board nodes may overlap**, and that is a standing invariant rather than a rule
+each write remembers. `useFrameOverlapGuard` (mounted by `BoardCanvas`) watches the rendered
+geometry of every frame and epic and, whenever two come to overlap, bounces them apart through
+`framePlacement.resolveFrameOverlaps`. Placement alone was not enough: `findFreeFramePosition`
+refuses to CREATE an overlap, but three later events make one anyway, and only one of them is a
+drag. A border drag grows a frame into its neighbour, and a frame GROWS ON ITS OWN when its first
+task arrives, because an empty service renders the "add the first task" panel and reserves a much
+smaller footprint than one rendering lanes. Watching the geometry covers all three, and covers the
+next write nobody has thought of yet.
+
+Three things about it are load-bearing:
+
+- **It runs in the SPA because only the SPA can measure a frame.** The footprint is derived from
+  the lane geometry the browser renders at (`containerSize`); the backend stores a position and at
+  most a size override, so it cannot tell whether two frames overlap.
+- **Correcting the VIEW and WRITING the correction are separate, and only a local gesture
+  authorises the write.** Every client always draws the board clear, which needs no coordination
+  because `resolveFrameOverlaps` is pure: two browsers holding one board draw it identically
+  whatever order their events arrived in, and a read-only viewer gets the corrected view for free.
+  Persisting is the narrower act, and a drag or border resize is the only cause with an
+  unambiguous single author, so that client settles the board when the gesture ends and writes what
+  it displaced. A frame that grew ON ITS OWN has no author, so its correction is drawn everywhere
+  and written by nobody: better than every open session racing to persist the same value, and
+  better behaved besides, since a projected neighbour comes back off the server's own geometry when
+  the frame shrinks again while a persisted one would stay pushed.
+- **The settlement ORDER is the whole policy** (`bySettlementOrder`), and it takes at most ONE
+  anchor: the node the local user is placing, held still while its neighbours move aside. A LIST of
+  anchors would carry an order of its own, and every order available to build one from is
+  per-client (the sequence a client's live events arrived in, or a history only the client that
+  watched the change has), so two clients would resolve one overlap to different positions and
+  write over each other. Everything else settles in READING ORDER, which is POSITIONAL: the node
+  nearest the top-left keeps its place. Note that this is not "the newcomer yields to the frames
+  already there": a block carries no shared creation stamp, so arrival is knowable only from a
+  client's own session, which is the per-client input this rules out.
+
+The guard stands down for the whole of a gesture. A drag previews a position on every pointer move,
+and bouncing neighbours off those in-flight positions displaces frames the user is merely passing
+OVER: each pass reads the neighbour where the previous pass pushed it, so the displacement
+accumulates instead of springing back. A frame drawn over its neighbours while the pointer holds it
+is what direct manipulation looks like; the board settles on release.
+
 **Dragging a card now only reparents** (`positioned: false` in `useBlockDrag`): between services,
 and into or out of a module via a module group header's drop zone. Which LANE a card is in is not
 something a drop can decide — the lane is derived from state, so dropping a not-started card on

package/app/components/board/BoardCanvas.vue

@@ -12,6 +12,7 @@ import { useTaskExpansion } from '~/composables/useTaskExpansion'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useFrameStacking } from '~/composables/useFrameStacking'
 import { useFramePlacement } from '~/composables/useFramePlacement'
+import { useFrameOverlapGuard } from '~/composables/useFrameOverlapGuard'
 import { useViewport } from '~/composables/useViewport'
 import { boardPanMode } from '~/utils/boardPanMode'
 import { createBoardNodeProjection } from './BoardCanvas.logic'
@@ -32,6 +33,11 @@ const { onNodeDragStop, onViewportChange, screenToFlowCoordinate } = useVueFlow(
 const { draggingId } = useBlockDrag()
 const { hoveredFrameId } = useFrameStacking()
 const { freeFramePosition, focusFrame } = useFramePlacement()
+// The board's "no two top-level nodes overlap" invariant: whenever a frame comes to overlap a
+// neighbour (dragged onto it, grown into it by a border drag, or grown by its first task), the two
+// are bounced apart. Every client draws that correction; only the one whose own gesture caused the
+// overlap writes it back. See useFrameOverlapGuard.
+useFrameOverlapGuard()
 // 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
@@ -62,10 +68,11 @@ useTaskExpansion(boardEl, boardActivity)
 // 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.
 //
-// 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.
+// Frames are rendered at the position the overlap guard keeps clear of every other top-level
+// node, so a frame is never hidden behind a neighbour once it has settled. Stacking still decides
+// what is on top of what while a drag is in flight (the guard stands down for the whole gesture,
+// so a dragged frame does cross its neighbours) and for the frame chrome that extends past the
+// box: the dragged frame is lifted to the top, then the hovered one. 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

package/app/composables/useFrameOverlapGuard.spec.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { effectScope, nextTick, ref, type EffectScope } from 'vue'
+import type { Block } from '~/types/domain'
+import { useBoardStore } from '~/stores/board'
+import { useBlockDrag } from '~/composables/useBlockDrag'
+import { useFrameOverlapGuard } from '~/composables/useFrameOverlapGuard'
+import { EMPTY_FRAME_SIZE, FRAME_GAP, framesCollide } from '~/utils/framePlacement'
+
+/**
+ * The guard is the wiring around `resolveFrameOverlaps` (whose geometry is pinned in
+ * `framePlacement.spec.ts`). What is worth testing here is not the bouncing but the two policies
+ * layered over it, because both are invisible in the geometry and both were wrong once:
+ *
+ * - WHEN it corrects: never against the geometry of a gesture still under the pointer, because
+ *   those corrections displace frames the user is only dragging past.
+ * - WHO writes the correction back: only the client whose own gesture caused it, and only through
+ *   `moveBlock`, whose rollback needs to find the position the server actually holds.
+ */
+const canWriteBoard = ref(true)
+
+function frame(id: string, x: number, y: number): Block {
+  return {
+    id,
+    title: id,
+    type: 'service',
+    description: '',
+    position: { x, y },
+    status: 'planned',
+    progress: 0,
+    dependsOn: [],
+    executionId: null,
+    level: 'frame',
+    parentId: null,
+  }
+}
+
+interface Write {
+  id: string
+  to: { x: number; y: number }
+  /** What the STORE still held when the write was asked for: the value a rollback restores. */
+  storedAtCall: { x: number; y: number }
+}
+
+describe('useFrameOverlapGuard', () => {
+  let scope: EffectScope
+  let board: ReturnType<typeof useBoardStore>
+  let writes: Write[]
+
+  beforeEach(() => {
+    canWriteBoard.value = true
+    vi.stubGlobal('useUiStore', () => ({ zoom: 1 }))
+    vi.stubGlobal('useWorkspaceAccess', () => ({ canWriteBoard }))
+    board = useBoardStore()
+    writes = []
+    // Stands in for the real `moveBlock`, which records nothing but does apply its position
+    // optimistically before the round-trip, which is the behaviour the guard leans on to correct the view
+    // and write it in one act. The snapshot is taken BEFORE that, so the rollback assertion below
+    // reads the position the real one would restore to.
+    board.moveBlock = ((id: string, to: { x: number; y: number }) => {
+      writes.push({ id, to, storedAtCall: { ...board.getBlock(id)!.position } })
+      board.previewMove(id, to)
+      return Promise.resolve()
+    }) as unknown as typeof board.moveBlock
+    // The composables under test reach the store through Nuxt's auto-import, which plain Vitest
+    // does not provide; hand them the same instance the assertions read.
+    vi.stubGlobal('useBoardStore', () => board)
+    scope = effectScope()
+  })
+
+  afterEach(() => scope.stop())
+
+  /** Start the guard over the frames the board currently holds and let its first pass run. */
+  async function guard() {
+    scope.run(() => useFrameOverlapGuard())
+    await nextTick()
+  }
+
+  const rectOf = (id: string) => ({ ...board.getBlock(id)!.position, ...EMPTY_FRAME_SIZE })
+  const written = () => writes.map((w) => w.id)
+
+  it('draws an overlapping board clear without writing anything back', async () => {
+    board.hydrate([frame('a', 0, 0), frame('b', 100, 0)])
+    await guard()
+
+    expect(framesCollide(rectOf('a'), rectOf('b'), FRAME_GAP)).toBe(false)
+    // Nobody authored this overlap locally, so nobody writes it: every client draws the same
+    // correction from the same rects, and one write per open session would be pure amplification.
+    expect(written()).toEqual([])
+  })
+
+  it('leaves a board whose frames already clear each other alone', async () => {
+    board.hydrate([frame('a', 0, 0), frame('b', EMPTY_FRAME_SIZE.w + FRAME_GAP, 0)])
+    await guard()
+
+    expect(board.getBlock('b')!.position).toEqual({ x: EMPTY_FRAME_SIZE.w + FRAME_GAP, y: 0 })
+    expect(written()).toEqual([])
+  })
+
+  it('separates a frame that grew into its neighbour, keeping the grown frame in place', async () => {
+    // Two empty services a gap apart, then the first one gains a task: it stops rendering the
+    // "add the first task" panel and grows to the lane footprint, over its neighbour.
+    board.hydrate([frame('a', 0, 0), frame('b', EMPTY_FRAME_SIZE.w + FRAME_GAP, 0)])
+    await guard()
+
+    board.upsert({ ...frame('t1', 0, 0), level: 'task', parentId: 'a' })
+    await nextTick()
+
+    expect(board.getBlock('a')!.position).toEqual({ x: 0, y: 0 })
+    expect(
+      framesCollide(
+        { ...board.getBlock('a')!.position, ...board.containerSize('a') },
+        rectOf('b'),
+        FRAME_GAP,
+      ),
+    ).toBe(false)
+    expect(written()).toEqual([])
+  })
+
+  it('leaves the frames a drag passes over alone, and settles once the pointer is released', async () => {
+    board.hydrate([frame('a', 0, 0), frame('b', 600, 0), frame('c', 1200, 0)])
+    await guard()
+
+    // Stand in for a header-handle drag: the dragged frame's position is previewed on every
+    // pointer move, and `draggingId` marks it as the one the guard must not move.
+    const { draggingId } = useBlockDrag()
+    draggingId.value = 'a'
+    // Dragged ACROSS `b` on the way to its resting place beside `c`. Bouncing `b` here would
+    // persist a rearrangement of a service the user never touched.
+    board.previewMove('a', { x: 600, y: 0 })
+    await nextTick()
+    expect(board.getBlock('b')!.position).toEqual({ x: 600, y: 0 })
+    expect(written()).toEqual([])
+
+    board.previewMove('a', { x: 1180, y: 0 })
+    await nextTick()
+    expect(board.getBlock('b')!.position).toEqual({ x: 600, y: 0 })
+
+    // Release: the drop commits `a` itself, and the guard settles the board around it.
+    draggingId.value = null
+    await nextTick()
+
+    expect(board.getBlock('a')!.position).toEqual({ x: 1180, y: 0 })
+    expect(written()).toEqual(['c'])
+    expect(framesCollide(rectOf('a'), rectOf('c'), FRAME_GAP)).toBe(false)
+  })
+
+  it('writes through moveBlock alone, so a refused correction can still roll back', async () => {
+    board.hydrate([frame('a', 0, 0), frame('b', 600, 0)])
+    await guard()
+
+    const { draggingId } = useBlockDrag()
+    draggingId.value = 'a'
+    board.previewMove('a', { x: 580, y: 0 })
+    await nextTick()
+    draggingId.value = null
+    await nextTick()
+
+    // `moveBlock` snapshots the position it finds and restores it if the write is refused. A
+    // `previewMove` ahead of it would hand it the CORRECTION as the value to roll back to,
+    // leaving the board showing a position the server never stored.
+    expect(writes).toHaveLength(1)
+    expect(writes[0]!.storedAtCall).toEqual({ x: 600, y: 0 })
+    expect(writes[0]!.to).not.toEqual(writes[0]!.storedAtCall)
+  })
+
+  it('writes nothing for a drag that was cancelled rather than dropped', async () => {
+    board.hydrate([frame('a', 0, 0), frame('b', 600, 0)])
+    await guard()
+
+    const { draggingId } = useBlockDrag()
+    draggingId.value = 'a'
+    board.previewMove('a', { x: 580, y: 0 })
+    await nextTick()
+    // A `pointercancel` (or the dragged component unmounting) puts the frame back and commits
+    // nothing. The board it leaves behind is already clear, so settling finds no work: the
+    // neighbour displacement a cancelled gesture caused must not outlive it.
+    board.previewMove('a', { x: 0, y: 0 })
+    draggingId.value = null
+    await nextTick()
+
+    expect(board.getBlock('b')!.position).toEqual({ x: 600, y: 0 })
+    expect(written()).toEqual([])
+  })
+
+  it('corrects the view for a read-only viewer but writes nothing', async () => {
+    canWriteBoard.value = false
+    board.hydrate([frame('a', 0, 0), frame('b', 100, 0)])
+    await guard()
+
+    expect(framesCollide(rectOf('a'), rectOf('b'), FRAME_GAP)).toBe(false)
+    expect(written()).toEqual([])
+  })
+})

package/app/composables/useFrameOverlapGuard.ts

@@ -0,0 +1,145 @@
+import { computed, watch } from 'vue'
+import { useBlockDrag } from '~/composables/useBlockDrag'
+import { useFrameResize } from '~/composables/useFrameResize'
+import { EPIC_NODE_SIZE, resolveFrameOverlaps, type PlacedRect } from '~/utils/framePlacement'
+
+/**
+ * The board's standing "no two top-level nodes overlap" invariant.
+ *
+ * Frames used to be rendered exactly where they were stored and allowed to overlap freely, with
+ * hover-driven stacking as the way to reach the one underneath. That only ever worked for the
+ * frame you were pointing at: everything under a neighbour was invisible, and nothing on the
+ * board said it was there. Placement already refused to CREATE an overlap
+ * (`findFreeFramePosition`), but three later events could still make one (dragging a frame onto
+ * a neighbour, dragging a border out into one, and a frame growing when its first task arrives,
+ * since an empty service reserves a much smaller footprint than one rendering lanes), so the rule
+ * was true of a board nobody had touched and of no other.
+ *
+ * This closes it as an invariant rather than as a check on each of those writes: it watches the
+ * rendered geometry of every top-level board node and, whenever two come to overlap, bounces them
+ * apart (`resolveFrameOverlaps`). Being cause-agnostic is the point: a future write that moves or
+ * grows a frame is covered without knowing this exists.
+ *
+ * ## Correcting the view and writing the correction are two different jobs
+ *
+ * They have opposite requirements, and the guard keeps them apart, because conflating them is
+ * what makes a layout fixer fight itself across clients:
+ *
+ * - **Every client corrects what it DRAWS, always.** `resolveFrameOverlaps` is a pure function of
+ *   the rects, so this needs no coordination: two browsers holding one board draw it the same way
+ *   whatever order their events arrived in. A read-only viewer gets the corrected view for free,
+ *   which is the point (the invariant is about what is VISIBLE).
+ * - **Exactly one client may WRITE a correction, and only a local GESTURE elects it.** A drag or
+ *   a border resize has an unambiguous single author: the browser the pointer is in. That client
+ *   settles the board when the gesture ends and persists the neighbours it displaced.
+ *
+ * So a correction is persisted only where the local user caused it. That is a deliberate limit,
+ * not an oversight, and the third cause above is what it costs: a frame that grows on its own has
+ * NO author (the task may have arrived from a pipeline, with no browser involved), so its
+ * correction is DRAWN everywhere and WRITTEN by nobody. The stored position stays the one someone
+ * chose, and the board derives a clear presentation from it, this session and the next.
+ *
+ * The alternative is worse in both directions. Having every writer-capable client persist what it
+ * resolved costs a write and a board-wide event per open session for one overlap, and the first of
+ * those writes moves the geometry the others are still resolving. And a persisted correction is
+ * not even the better answer where it lands: a frame that grew for its first task shrinks again
+ * when that task is deleted, and a neighbour bounced by a WRITE stays where it was pushed, while a
+ * neighbour bounced by a projection is recomputed off the server's own geometry on the next
+ * hydrate and simply comes back.
+ *
+ * ## Why it runs in the SPA
+ *
+ * A frame's footprint is derived from the lane geometry the browser renders it at
+ * (`containerSize`), which the server cannot compute: it stores a position and, at most, a size
+ * override. So the only layer that can tell whether two frames overlap is the one drawing them.
+ *
+ * Epics take part as well as frames. They are top-level nodes on the same canvas (placement
+ * already reserves space around them), so an epic card parked over a frame hides exactly as much
+ * of it as another frame would.
+ */
+export function useFrameOverlapGuard() {
+  const board = useBoardStore()
+  const access = useWorkspaceAccess()
+  const { draggingId } = useBlockDrag()
+  const { resizingId } = useFrameResize()
+
+  /** Every top-level node's rendered rect, in the flow-space coordinates blocks are stored in. */
+  const nodeRects = computed<PlacedRect[]>(() => [
+    ...board.frames.map((f) => {
+      const size = board.containerSize(f.id)
+      return { id: f.id, x: f.position.x, y: f.position.y, w: size.w, h: size.h }
+    }),
+    ...board.epics.map((e) => ({
+      id: e.id,
+      x: e.position.x,
+      y: e.position.y,
+      ...EPIC_NODE_SIZE,
+    })),
+  ])
+
+  /** The node the local pointer is placing right now, if any. */
+  const gestureId = computed(() => draggingId.value ?? resizingId.value)
+
+  /**
+   * Bounce the overlapping nodes apart, holding `anchorId` still.
+   *
+   * `persist` picks the channel, and the two are mutually exclusive on purpose.
+   * {@link useBoardStore.moveBlock} ALREADY applies its position optimistically and restores the
+   * previous one if the write is refused, so it is both the local correction and the write. A
+   * `previewMove` ahead of it would break exactly that: `moveBlock` snapshots the position it
+   * finds, so a rollback would restore the correction rather than undo it, leaving the SPA
+   * showing a position the server never stored.
+   */
+  function bounce(anchorId: string | null, persist: boolean) {
+    for (const [id, position] of resolveFrameOverlaps(nodeRects.value, { anchorId })) {
+      if (persist) void board.moveBlock(id, position)
+      else board.previewMove(id, position)
+    }
+  }
+
+  /**
+   * Draw the board clear, on every client, writing nothing.
+   *
+   * Held for the duration of a gesture. A drag previews a new position on every pointer move, and
+   * bouncing neighbours off those in-flight positions displaces frames the user is only passing
+   * OVER: each pass reads the neighbour at the spot the previous pass pushed it to, so the
+   * displacement accumulates instead of springing back, and a drag across a populated board
+   * rearranges services nobody touched. A frame drawn on top of its neighbours while the pointer
+   * is holding it is what direct manipulation looks like; the board settles when it is let go.
+   *
+   * Anchorless, because a change with no local gesture behind it has no frame the user is
+   * placing: it is a growth, or another client's write arriving. Reading order decides, and it is
+   * the same reading order everywhere.
+   */
+  function project() {
+    if (gestureId.value) return
+    bounce(null, false)
+  }
+
+  // Default `pre` flush: the correction is applied before the board re-renders, so an overlap
+  // never reaches the screen even for one frame. Re-entrant by construction (correcting a
+  // position invalidates `nodeRects`), but `resolveFrameOverlaps` is idempotent, so the second
+  // pass finds a settled board and stops there.
+  watch(nodeRects, project, { immediate: true })
+
+  /**
+   * Settle the board around the node the local user just placed, and persist what moved.
+   *
+   * `post` flush so the gesture's own commit has landed first: a drop calls `moveBlock` (and a
+   * released border `resizeBlock`) before clearing the id, and both apply their geometry
+   * optimistically, so by the time this runs `nodeRects` already holds the placed node's final
+   * footprint. The resolution is therefore computed from live geometry rather than replayed from
+   * anything the gesture accumulated, which is what makes every way a gesture can end correct
+   * without a case for each: a `pointercancel` (or the dragged component unmounting) restores the
+   * pre-drag position, so this finds a clear board and writes nothing at all.
+   */
+  watch(
+    gestureId,
+    (now, before) => {
+      if (now || !before) return
+      // Access can be revoked mid-session; a viewer still gets the corrected view.
+      bounce(before, access.canWriteBoard.value)
+    },
+    { flush: 'post' },
+  )
+}

package/app/composables/useFrameResize.ts

@@ -22,6 +22,16 @@ const HANDLES = {
 
 export type ResizeEdge = keyof typeof HANDLES
 
+/**
+ * Id of the container currently being resized, for cursor/grip styling and for the board's
+ * overlap guard, which stands down while a border is still under the pointer and settles the
+ * board around this container once it is released.
+ *
+ * Module-level for the same reason as `useBlockDrag`'s `draggingId`: only one container is ever
+ * resized at a time, and the grips that start the drag are not the only reader.
+ */
+const resizingId = ref<string | null>(null)
+
 /** The grips in render order, so a component can `v-for` them instead of listing eight blocks. */
 export const RESIZE_EDGES = Object.keys(HANDLES) as ResizeEdge[]
 
@@ -51,8 +61,6 @@ export function useFrameResize() {
   const board = useBoardStore()
   const ui = useUiStore()
   const access = useWorkspaceAccess()
-  /** Id of the container currently being resized, for cursor/grip styling. */
-  const resizingId = ref<string | null>(null)
 
   /**
    * How far the origin may travel INWARD before the nearest child would land at a negative
@@ -136,10 +144,15 @@ export function useFrameResize() {
       window.removeEventListener('pointercancel', onUp)
       body.style.cursor = priorCursor
       body.style.userSelect = priorUserSelect
-      resizingId.value = null
       // A press with no movement is not a resize: committing it would emit a coarse board signal
       // (every other client re-hydrates) to store the geometry it already had.
+      //
+      // Committed BEFORE the id is released, matching `useBlockDrag`'s drop: `resizeBlock` applies
+      // the final bounds optimistically, and the overlap guard settles the board on the release of
+      // this id, so clearing it first would have the guard read the geometry of a resize that had
+      // not landed yet.
       if (moved) void board.resizeBlock(block.id, bounds, from)
+      resizingId.value = null
     }
     window.addEventListener('pointermove', onMove)
     window.addEventListener('pointerup', onUp)

package/app/composables/useFrameStacking.ts

@@ -1,10 +1,12 @@
 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.
+// Service frames are kept clear of one another once settled (see useFrameOverlapGuard), but their
+// boxes are not all there is to stack: chrome hangs outside the box, the guard stands down for the
+// whole of a drag so a dragged frame crosses its neighbours freely, and Vue Flow needs SOME order
+// regardless. 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 its neighbours. 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() {

package/app/utils/framePlacement.spec.ts

@@ -1,5 +1,12 @@
 import { describe, it, expect } from 'vitest'
-import { findFreeFramePosition, framesCollide, FRAME_GAP, type FrameRect } from './framePlacement'
+import {
+  findFreeFramePosition,
+  framesCollide,
+  resolveFrameOverlaps,
+  FRAME_GAP,
+  type FrameRect,
+  type PlacedRect,
+} from './framePlacement'
 
 const size = { w: 360, h: 220 }
 
@@ -71,3 +78,133 @@ describe('findFreeFramePosition', () => {
     expect(dist).toBeGreaterThan(0)
   })
 })
+
+/** Every pair on the resolved board clears the gap: the invariant the guard exists to hold. */
+function assertNoOverlap(rects: PlacedRect[], moved: Map<string, { x: number; y: number }>) {
+  const settled = rects.map((r) => ({ ...r, ...moved.get(r.id) }))
+  for (const [i, a] of settled.entries()) {
+    for (const b of settled.slice(i + 1)) {
+      expect({ pair: [a.id, b.id], collides: framesCollide(a, b, FRAME_GAP) }).toEqual({
+        pair: [a.id, b.id],
+        collides: false,
+      })
+    }
+  }
+}
+
+describe('resolveFrameOverlaps', () => {
+  it('leaves a board whose frames already clear each other untouched', () => {
+    const rects: PlacedRect[] = [
+      { id: 'a', x: 0, y: 0, ...size },
+      { id: 'b', x: size.w + FRAME_GAP, y: 0, ...size },
+    ]
+    expect(resolveFrameOverlaps(rects)).toEqual(new Map())
+  })
+
+  it('bounces the neighbour off an anchored frame dropped on top of it, keeping the drop', () => {
+    const rects: PlacedRect[] = [
+      { id: 'dropped', x: 40, y: 0, ...size },
+      { id: 'sitting', x: 0, y: 0, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects, { anchorId: 'dropped' })
+    // The frame the user placed keeps the exact spot they aimed at.
+    expect(moved.has('dropped')).toBe(false)
+    expect(moved.has('sitting')).toBe(true)
+    assertNoOverlap(rects, moved)
+  })
+
+  it('takes the shortest way out: a small overlap moves by a little, not a whole frame', () => {
+    const rects: PlacedRect[] = [
+      { id: 'anchor', x: 0, y: 0, ...size },
+      { id: 'nudged', x: size.w - 10, y: 0, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects, { anchorId: 'anchor' })
+    // Clearing rightwards costs 10px of penetration plus the gap; going around would cost a
+    // whole frame width.
+    expect(moved.get('nudged')).toEqual({ x: size.w + FRAME_GAP, y: 0 })
+  })
+
+  it('separates a frame that grew into its neighbour, keeping the grown frame in place', () => {
+    // An empty service (360x220) with a neighbour placed a gap away, then its first task
+    // arrives and it grows to the lane footprint.
+    const grown = { w: 694, h: 486 }
+    const rects: PlacedRect[] = [
+      { id: 'grown', x: 0, y: 0, ...grown },
+      { id: 'neighbour', x: 360 + FRAME_GAP, y: 0, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects, { anchorId: 'grown' })
+    expect(moved.has('grown')).toBe(false)
+    assertNoOverlap(rects, moved)
+  })
+
+  it('untangles a pile of frames stacked on one spot', () => {
+    const rects: PlacedRect[] = ['a', 'b', 'c', 'd', 'e'].map((id) => ({ id, x: 0, y: 0, ...size }))
+    assertNoOverlap(rects, resolveFrameOverlaps(rects))
+  })
+
+  it('answers the same way whatever order the rects arrive in', () => {
+    const rects: PlacedRect[] = [
+      { id: 'a', x: 0, y: 0, ...size },
+      { id: 'b', x: 30, y: 20, ...size },
+      { id: 'c', x: 60, y: 500, ...size },
+      { id: 'd', x: 10, y: 480, ...size },
+    ]
+    // Two clients hold the same board in whatever order their events arrived; a resolution that
+    // depended on that order would have them write different positions and fight.
+    const first = resolveFrameOverlaps(rects)
+    const second = resolveFrameOverlaps([...rects].reverse())
+    expect([...second].sort()).toEqual([...first].sort())
+  })
+
+  it('is idempotent: re-running over the resolved board moves nothing', () => {
+    const rects: PlacedRect[] = [
+      { id: 'a', x: 0, y: 0, ...size },
+      { id: 'b', x: 12, y: 8, ...size },
+      { id: 'c', x: 24, y: 16, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects)
+    const settled = rects.map((r) => ({ ...r, ...moved.get(r.id) }))
+    expect(resolveFrameOverlaps(settled)).toEqual(new Map())
+  })
+
+  it('clears fractional positions outright, so a pass cannot leave a sub-pixel to shave again', () => {
+    // A drag divides the pointer delta by the board zoom, so the stored positions really are
+    // fractional; rounding a correction the wrong way would leave a sliver of overlap behind.
+    const rects: PlacedRect[] = [
+      { id: 'a', x: 0.5, y: 0.25, ...size },
+      { id: 'b', x: 10.75, y: 0.5, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects, { anchorId: 'a' })
+    assertNoOverlap(rects, moved)
+    const settled = rects.map((r) => ({ ...r, ...moved.get(r.id) }))
+    expect(resolveFrameOverlaps(settled, { anchorId: 'a' })).toEqual(new Map())
+  })
+
+  it('settles the unanchored board in reading order: the top-left node keeps its place', () => {
+    // The policy with no anchor is POSITIONAL, not temporal. Whichever node is nearer the top of
+    // the board holds its spot and the one below it yields, regardless of which of the two arrived
+    // first: a block carries no shared creation stamp, so "the newcomer yields" is only knowable
+    // from a client's own history and two clients would answer it differently.
+    const rects: PlacedRect[] = [
+      { id: 'upper', x: 0, y: 480, ...size },
+      { id: 'lower', x: 0, y: 500, ...size },
+    ]
+    const moved = resolveFrameOverlaps(rects)
+    expect(moved.has('upper')).toBe(false)
+    expect(moved.has('lower')).toBe(true)
+    assertNoOverlap(rects, moved)
+  })
+
+  it('falls back to reading order when the anchor is not on the board', () => {
+    // The guard anchors on the id of whatever gesture just ended, which is routinely a task card
+    // rather than a top-level node. An anchor nothing matches must resolve exactly as none at all,
+    // or a task drag would settle the board differently from the growth it caused.
+    const rects: PlacedRect[] = [
+      { id: 'a', x: 0, y: 0, ...size },
+      { id: 'b', x: 40, y: 0, ...size },
+    ]
+    expect(resolveFrameOverlaps(rects, { anchorId: 'task-not-a-frame' })).toEqual(
+      resolveFrameOverlaps(rects),
+    )
+  })
+})

package/app/utils/framePlacement.ts

@@ -106,3 +106,111 @@ export function findFreeFramePosition(
   const rightmost = existing.reduce((m, r) => Math.max(m, r.x + r.w), desired.x)
   return { x: rightmost + gap, y: desired.y }
 }
+
+/** A rect on the board that knows which block it belongs to. */
+export interface PlacedRect extends FrameRect {
+  readonly id: string
+}
+
+/**
+ * How many times one rect may be pushed off a neighbour before we stop nudging and fall back to
+ * the ring search. Each push clears the rect it hit but can walk it into a third one, so a dense
+ * cluster needs several; a cluster that needs more than this is one the incremental nudge is not
+ * going to untangle, and {@link findFreeFramePosition} always answers.
+ */
+const MAX_SEPARATION_PUSHES = 8
+
+/**
+ * The nearest place `moving` can sit that clears `settled` by `gap`: the minimum translation
+ * along whichever axis it is cheapest to leave by, which is what makes a frame nudged onto a
+ * neighbour bounce off the nearest border rather than teleport around it.
+ *
+ * Each candidate edge is rounded OUTWARD, away from the rect being cleared. A drag divides the
+ * pointer delta by the board zoom, so the positions coming in here are routinely fractional, and
+ * rounding the other way would leave a sub-pixel of the overlap behind for the next pass to find
+ * and shave again.
+ *
+ * Ties are broken in a fixed order (right before left, horizontal before vertical) rather than by
+ * anything read off the board, because every client resolves the same overlap independently and
+ * two of them answering differently would have the frames trade places on every refresh. A tie
+ * only arises when the two rects are exactly concentric on that axis.
+ */
+function separatedPosition(moving: FrameRect, settled: FrameRect, gap: number): Point {
+  const right = Math.ceil(settled.x + settled.w + gap)
+  const left = Math.floor(settled.x - gap - moving.w)
+  const down = Math.ceil(settled.y + settled.h + gap)
+  const up = Math.floor(settled.y - gap - moving.h)
+  const x = Math.abs(right - moving.x) <= Math.abs(left - moving.x) ? right : left
+  const y = Math.abs(down - moving.y) <= Math.abs(up - moving.y) ? down : up
+  return Math.abs(x - moving.x) <= Math.abs(y - moving.y) ? { x, y: moving.y } : { x: moving.x, y }
+}
+
+/**
+ * Order the rects for settlement: `anchorId` first if it is on the board, then everything else in
+ * reading order (top row first, then left to right), with the id as the final tie-break.
+ *
+ * The order IS the policy. A rect settles into the space the ones before it have already taken, so
+ * whatever comes first keeps its exact position and later ones bounce off it. Naming the frame the
+ * local user is placing as the anchor is what makes a deliberate drop land where it was aimed
+ * while its neighbours move aside, instead of the other way round.
+ *
+ * There is at most ONE anchor, and that is deliberate rather than a simplification. A list would
+ * carry an order of its own, and the only orders available to build one from are per-client (the
+ * order a client's live events happened to arrive in, or a history only the client that watched
+ * the change has). Two clients ordering two anchors differently resolve the same overlap to
+ * different positions and then write over each other, which is the one failure mode a pure
+ * resolution exists to rule out. A single anchor has no order to disagree about.
+ *
+ * Everything else settles in READING ORDER, which is a POSITIONAL policy, not a temporal one: the
+ * node nearest the top-left of the board keeps its place and those below and to the right yield.
+ * It is worth being exact about this, because "a frame arriving on the board yields to the frames
+ * already there" is the rule one would reach for first and it is not implementable here. A block
+ * carries no shared creation or update stamp (see `blockSchema`), so arrival is only knowable from
+ * a client's own session history, which is precisely the per-client input ruled out above. Reading
+ * order is the strongest rule every client can agree on from the board alone.
+ */
+function bySettlementOrder(anchorId: string | null | undefined) {
+  const priority = (r: PlacedRect) => (r.id === anchorId ? 0 : 1)
+  return (a: PlacedRect, b: PlacedRect): number =>
+    priority(a) - priority(b) || a.y - b.y || a.x - b.x || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+}
+
+/**
+ * Push apart every board node that overlaps another, returning the new top-left of each one that
+ * had to move (and nothing for the ones that did not, so an already-clear board answers empty).
+ *
+ * This is the board's standing layout invariant, not a placement decision: a frame can come to
+ * overlap a neighbour long after it was placed, by being dragged onto it, by a border drag, or by
+ * growing when its first task arrives (an empty service reserves a much smaller footprint than
+ * one rendering lanes). All three land here, so the rule is stated once rather than at each of
+ * the writes that can break it.
+ *
+ * The result is a pure function of the rects and the single `anchorId`, with tie-breaks fixed in
+ * code rather than read off the board, so every client holding the same board computes the same
+ * answer whatever order its own events arrived in. That is what lets each of them correct what it
+ * DRAWS without any of them having to agree first; who may WRITE a correction back is a separate
+ * question, settled in {@link useFrameOverlapGuard}.
+ */
+export function resolveFrameOverlaps(
+  rects: readonly PlacedRect[],
+  opts?: { anchorId?: string | null; gap?: number },
+): Map<string, Point> {
+  const gap = opts?.gap ?? FRAME_GAP
+  const settled: FrameRect[] = []
+  const moved = new Map<string, Point>()
+  for (const rect of [...rects].sort(bySettlementOrder(opts?.anchorId))) {
+    let at: FrameRect = { ...rect }
+    for (let push = 0; push < MAX_SEPARATION_PUSHES; push++) {
+      const blocker = settled.find((s) => framesCollide(at, s, gap))
+      if (!blocker) break
+      at = { ...at, ...separatedPosition(at, blocker, gap) }
+    }
+    if (!fits(at, settled, gap)) {
+      const free = findFreeFramePosition(settled, rect, { x: rect.x, y: rect.y }, gap)
+      at = { ...rect, x: free.x, y: free.y }
+    }
+    settled.push(at)
+    if (at.x !== rect.x || at.y !== rect.y) moved.set(rect.id, { x: at.x, y: at.y })
+  }
+  return moved
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.287.0",
+  "version": "0.288.1",
   "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",
@@ -44,7 +44,7 @@
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.2",
-    "happy-dom": "^20.11.12",
+    "happy-dom": "^20.11.15",
     "msw": "^2.15.0",
     "nuxt": "^4.5.2",
     "typescript": "^6.0.3",