@cat-factory/app 0.259.3 → 0.260.1

package/README.md

@@ -68,6 +68,40 @@ Order within the column is by what the user loses by not reading it now; the too
 
 `app/components/layout/BoardTopOverlays.spec.ts` enforces the no-self-placement half, reading the member list from the component's own imports.
 
+### A board driver that MEASURES the DOM runs off the activity pulse, never a bare RAF
+
+Two board features cannot be derived from the stores alone: the dependency-edge overlay needs
+each card's on-screen rectangle, and the task-expansion driver needs the topmost card under the
+pointer. Both used `useRafFn`, so an open board paid O(edges) `querySelector` plus forced layout
+reads sixty times a second with nothing moving, and the edge overlay reassigned an
+equal-but-new segment array every frame on top of that.
+
+**A new driver of that kind pairs `useSettlingRaf(compute)` with the canvas pulse
+(`useBoardActivity`), and `compute` reports honestly whether it changed anything.** The pulse
+answers "something may have started moving" (DOM mutations under the canvas, its resize, the
+Vue Flow camera, pointer/wheel/scroll gestures) and the settling loop carries that wake through
+the animation that follows, parking once the output has held still for a few frames. Neither
+half works alone: a signal fires one frame BEFORE the transition it starts has any geometry, and
+a bare frame loop never stops.
+
+Two things this cost, both worth knowing before adding a third driver. `compute` returning
+`true` unconditionally silently restores the old behaviour, which is why the loop's contract is
+stated in terms of what the user can see rather than what the function did. And the pulse
+watches `style`/`class` attributes but not the geometry attributes the overlay itself writes,
+because a driver whose own output pulsed it awake would never settle.
+
+A `compute` that THROWS parks the loop and lets the error reach the frame callback, so the next
+pulse of any kind is what restarts it. Retrying the frame instead would turn one bad measurement
+into a 60Hz error storm, and staying awake with no frame scheduled would make every later poke a
+no-op and freeze the board for the session.
+
+What the pulse cannot see is a reflow with no mutation and no gesture, a late-loading image or
+font resizing a card. That leaves an arrow stale until the next pulse of any kind, which is the
+deliberate trade: firing too often costs a handful of frames, and the alternative is the loop
+that never sleeps.
+
+`app/utils/settlingLoop.spec.ts` pins the loop against a hand-driven frame clock.
+
 ### A store must be instantiable outside a component `setup`
 
 A Pinia setup store runs its body on the FIRST `useStore()` anywhere in the app, and that

package/app/components/board/BoardCanvas.vue

@@ -7,6 +7,7 @@ import TaskDependencyEdges from './TaskDependencyEdges.vue'
 import DependencyConnectOverlay from './DependencyConnectOverlay.vue'
 import { readDndPayload, blockIdFromEvent } from '~/utils/dnd'
 import { BOARD_FLOW_ID, BOARD_MIN_ZOOM, BOARD_MAX_ZOOM } from '~/composables/useBoardFlow'
+import { provideBoardActivity } from '~/composables/useBoardActivity'
 import { useTaskExpansion } from '~/composables/useTaskExpansion'
 import { useBlockDrag } from '~/composables/useBlockDrag'
 import { useFrameStacking } from '~/composables/useFrameStacking'
@@ -46,7 +47,10 @@ const panOnDrag = computed<boolean | number[]>(() => boardPanMode(hasTouch.value
 // centre-most of any that would overlap (see useTaskExpansion). Service frames have no
 // such gate — they are always expanded to their task canvas.
 const boardEl = ref<HTMLElement | null>(null)
-useTaskExpansion(boardEl)
+// The canvas owns the "something may have moved" pulse both DOM-measuring drivers run off:
+// this one directly, the dependency-edge overlay by injection. See useBoardActivity.
+const boardActivity = provideBoardActivity(boardEl)
+useTaskExpansion(boardEl, boardActivity)
 
 // Only frames are board nodes. Dependencies live on tasks (rendered inside the
 // frames), so there are no frame-to-frame edges on the canvas.
@@ -100,6 +104,10 @@ onNodeDragStop(({ node }) => {
 
 onViewportChange((vp) => {
   ui.zoom = vp.zoom
+  // Pan and zoom move every card on screen. Vue Flow does that by restyling its transform
+  // pane, which the pulse's observer would also catch, but the camera is too load-bearing for
+  // the overlays to depend on which DOM strategy Vue Flow uses to apply it.
+  boardActivity.pulse()
 })
 
 function onNodeClick({ node }: NodeMouseEvent) {

package/app/components/board/TaskDependencyEdges.vue

@@ -1,29 +1,31 @@
 <script setup lang="ts">
-import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
-import { useRafFn } from '@vueuse/core'
+import { ref, shallowRef, computed, watch } from 'vue'
+import { useBoardActivity } from '~/composables/useBoardActivity'
+import { useSettlingRaf } from '~/composables/useSettlingRaf'
+import { commitSegments, type EdgeSegment } from '~/utils/edgeSegments'
 
 /**
  * Draws dependency arrows between task cards as an SVG overlay on top of the
  * board. Tasks are plain DOM nodes (inside frame cards), so we resolve their
- * on-screen rectangles by `[data-block-id]` every frame — this makes arrows
- * follow pan / zoom / drag / expand for free. When a task's frame is collapsed
- * (its card isn't rendered), the arrow anchors to the frame card instead.
+ * on-screen rectangles by `[data-block-id]` — this makes arrows follow pan /
+ * zoom / drag / expand for free. When a task's frame is collapsed (its card
+ * isn't rendered), the arrow anchors to the frame card instead.
+ *
+ * Measuring is O(edges) `querySelector` + forced layout reads, so it runs only
+ * while something is actually moving: the board's activity pulse wakes it and
+ * `useSettlingRaf` parks it again once the resolved segments hold still.
  */
 const board = useBoardStore()
 
 const svg = ref<SVGSVGElement | null>(null)
 
-type Seg = { id: string; x1: number; y1: number; x2: number; y2: number; done: boolean }
-const segments = ref<Seg[]>([])
+const segments = shallowRef<EdgeSegment[]>([])
 // Epic→member membership links (distinct style from dependency edges).
-type MemberSeg = { id: string; x1: number; y1: number; x2: number; y2: number }
-const memberSegments = ref<MemberSeg[]>([])
+const memberSegments = shallowRef<EdgeSegment[]>([])
 // Frontend frame → bound service frame links (from a frontend's backend bindings).
-type FrontendSeg = { id: string; x1: number; y1: number; x2: number; y2: number }
-const frontendSegments = ref<FrontendSeg[]>([])
+const frontendSegments = shallowRef<EdgeSegment[]>([])
 // Service frame → connected provider service frame links (from serviceConnections).
-type ConnectionSeg = { id: string; x1: number; y1: number; x2: number; y2: number }
-const connectionSegments = ref<ConnectionSeg[]>([])
+const connectionSegments = shallowRef<EdgeSegment[]>([])
 
 // task → its dependencies, both ends being tasks
 const taskDeps = computed(() => {
@@ -129,8 +131,8 @@ function segmentBetween(sourceId: string, targetId: string, origin: DOMRect) {
 function linkSegments(
   links: { id: string; source: string; target: string }[],
   origin: DOMRect,
-): { id: string; x1: number; y1: number; x2: number; y2: number }[] {
-  const out: { id: string; x1: number; y1: number; x2: number; y2: number }[] = []
+): EdgeSegment[] {
+  const out: EdgeSegment[] = []
   for (const link of links) {
     const seg = segmentBetween(link.source, link.target, origin)
     if (seg) out.push({ id: link.id, ...seg })
@@ -138,27 +140,34 @@ function linkSegments(
   return out
 }
 
-function recompute() {
+/** Re-measure every overlay link; reports whether any of them moved. */
+function recompute(): boolean {
   const el = svg.value
-  if (!el) return
+  if (!el) return false
   const origin = el.getBoundingClientRect()
 
-  const next: Seg[] = []
+  const deps: EdgeSegment[] = []
   for (const d of taskDeps.value) {
     const seg = segmentBetween(d.source, d.target, origin)
     if (!seg) continue
-    next.push({ id: d.id, ...seg, done: board.getBlock(d.source)?.status === 'done' })
+    deps.push({ id: d.id, ...seg, done: board.getBlock(d.source)?.status === 'done' })
   }
-  segments.value = next
 
-  memberSegments.value = linkSegments(epicLinks.value, origin)
-  frontendSegments.value = linkSegments(frontendLinks.value, origin)
-  connectionSegments.value = linkSegments(connectionLinks.value, origin)
+  // An array literal, so every list is committed before the result is reduced: a `||` chain
+  // would short-circuit and leave the later overlays drawn at stale coordinates.
+  return [
+    commitSegments(segments, deps),
+    commitSegments(memberSegments, linkSegments(epicLinks.value, origin)),
+    commitSegments(frontendSegments, linkSegments(frontendLinks.value, origin)),
+    commitSegments(connectionSegments, linkSegments(connectionLinks.value, origin)),
+  ].some(Boolean)
 }
 
-const { pause, resume } = useRafFn(recompute, { immediate: false })
-onMounted(resume)
-onBeforeUnmount(pause)
+const { poke } = useSettlingRaf(recompute)
+useBoardActivity(poke)
+// A link set can change with no visible change to any card (toggling a dependency between two
+// tasks draws an arrow and nothing else), which the DOM-level pulse would never see.
+watch([taskDeps, epicLinks, frontendLinks, connectionLinks], poke)
 </script>
 
 <template>

package/app/components/github/AddServiceFromRepoModal.vue

@@ -12,7 +12,15 @@
 // browses its tree and multi-selects the service directories to add — from ANY
 // parent folder, in one pass — then adds them all at once. Directories that
 // already back a service on this board are shown but not selectable.
+//
+// One of those directories may be marked the FRONTEND for the rest: it is created as a
+// `frontend` frame instead of a service, pinned to its subdirectory, and bound to every
+// backend added beside it (`frontendConfig.backendBindings`, the frontend→service board
+// link). Every frontend frame the import creates also gets its subdirectory recorded on
+// `frontendConfig`, marked or not. The rules live in `~/utils/monorepoImport`, which also
+// explains why the bindings carry no env-var names.
 import type { FrameRepoType, GitHubAvailableRepo } from '~/types/domain'
+import type { CreatedMonorepoFrame } from '~/utils/monorepoImport'
 import RepoSearchEmpty from '~/components/github/RepoSearchEmpty.vue'
 import RepoTreeBrowser from '~/components/github/RepoTreeBrowser.vue'
 import VcsConnectSurfaces from '~/components/vcs/VcsConnectSurfaces.vue'
@@ -170,9 +178,53 @@ const addedDirectories = computed<string[]>(() => {
 })
 const addedDirSet = computed(() => new Set(addedDirectories.value))
 
+// What the next "Add N services" will actually create: the cart minus anything already backing a
+// service. THE population every frontend-mark decision reads, and the one `addServices` iterates.
+// The two can differ: a partial failure leaves the cart intact while its earlier creates stand, so
+// judging the mark by the raw cart would offer it (and count it) for frames that already exist.
+const pendingDirectories = computed(() =>
+  selectedDirectories.value.filter((d) => !addedDirSet.value.has(normalizeRepoPath(d))),
+)
+
+// The one picked directory marked as the frontend for the others, or undefined when the
+// selection is all backends. Empty string is the select's "none" option.
+const frontendDirectory = ref<string | undefined>(undefined)
+
+// Whether the mark is on offer at all (role must be `service`, at least two directories to
+// create): see `canDesignateFrontend`. The picker is hidden otherwise, so drop a mark that a role
+// change has made unofferable rather than leaving it to act unseen.
+const frontendOffered = computed(() =>
+  canDesignateFrontend(selectedType.value, pendingDirectories.value.length),
+)
+watch(frontendOffered, (offered) => {
+  if (!offered) frontendDirectory.value = undefined
+})
+// The pending set is the option list, so a directory that leaves it (removed from the cart, or
+// created by an earlier add) can no longer be the mark. The computed re-runs on the cart's
+// in-place mutations (`push`/`splice`), so no deep watch is needed on top of it.
+watch(pendingDirectories, (dirs) => {
+  if (frontendDirectory.value && !dirs.includes(frontendDirectory.value)) {
+    frontendDirectory.value = undefined
+  }
+})
+
+const frontendItems = computed(() => [
+  { label: t('github.addService.frontendNone'), value: '' },
+  ...pendingDirectories.value.map((d) => ({ label: d, value: d })),
+])
+
+// USelect needs a present value for its "none" row; the mark itself stays absent-or-a-path.
+const frontendSelection = computed({
+  get: () => frontendDirectory.value ?? '',
+  set: (value: string) => {
+    frontendDirectory.value = value || undefined
+  },
+})
+
 function toggleMonorepo(value: boolean) {
   isMonorepo.value = value
   selectedDirectories.value = []
+  frontendDirectory.value = undefined
 }
 
 // Add/remove a directory from the cart. Guards against an already-added directory (the
@@ -209,12 +261,14 @@ watch(selectedRepoId, (id) => {
   }
   isMonorepo.value = selectedRepo.value?.isMonorepo === true
   selectedDirectories.value = []
+  frontendDirectory.value = undefined
   configuredBlockId.value = undefined
 })
 
 function resetSelection() {
   selectedRepoId.value = undefined
   selectedDirectories.value = []
+  frontendDirectory.value = undefined
   isMonorepo.value = false
   configuredBlockId.value = undefined
   resetRepoSearch()
@@ -265,18 +319,13 @@ const canAddServices = computed(
     !needsConnection.value &&
     selectedRepoId.value !== undefined &&
     isMonorepo.value &&
-    selectedDirectories.value.length > 0,
+    pendingDirectories.value.length > 0,
 )
 
 // Directories the user has picked but NOT yet committed via "Add N services". Closing the
 // modal ("Done") would silently discard them — almost never what the user wants — so the
-// footer's Done is disabled while any remain (see the template). Filtered against the
-// already-added set for parity with `addServices`, so a stale cart entry can't block Done.
-const hasPendingSelection = computed(
-  () =>
-    isMonorepo.value &&
-    selectedDirectories.value.some((d) => !addedDirSet.value.has(normalizeRepoPath(d))),
-)
+// footer's Done is disabled while any remain (see the template).
+const hasPendingSelection = computed(() => isMonorepo.value && pendingDirectories.value.length > 0)
 
 async function add() {
   if (!canAdd.value || selectedRepoId.value === undefined) return
@@ -315,38 +364,71 @@ async function add() {
   }
 }
 
-// Add every directory in the cart as its own service, in one action. Each add lays the
-// frame out in free space (seeing the ones added earlier in the loop, so they don't
-// overlap); the projection is refreshed and the camera centres on the last one. The
-// just-added directories then move to `addedDirectories`, so the cart is cleared and the
-// tree marks them "added" — ready to pick more (from any folder) or close.
+// What the success toast says about the frontend wiring, which is the half of the add that can
+// fail on its own. A landed mark names the directory and points at the inspector for the env-var
+// names the import deliberately leaves empty; a patch that did not persist says SO, because the
+// frames are on the board either way and a silent omission reads exactly like a clean import. The
+// failure note covers an undesignated frontend frame too: it lost its subdirectory, so the harness
+// would build the repo root.
+function frontendNote(designatedDirectory: string | undefined, wiringLanded: boolean): string {
+  if (!wiringLanded) return t('github.addService.toast.frontendWiringFailedNote')
+  if (!designatedDirectory) return ''
+  return t('github.addService.toast.frontendLinkedNote', { directory: designatedDirectory })
+}
+
+// Add every pending directory as its own frame, in one action. Each add lays the frame out in free
+// space (seeing the ones added earlier in the loop, so they don't overlap); the projection is
+// refreshed and the camera centres on the last one. The just-added directories then move to
+// `addedDirectories`, so the cart is cleared and the tree marks them "added", ready to pick more
+// (from any folder) or close. That is why the pending set is SNAPSHOTTED before the first await:
+// each create refreshes the projection, so the live computed shrinks under the loop.
+//
+// A created `frontend` frame is then patched with its `frontendConfig`: its subdirectory always,
+// plus a binding per sibling frame when it is the marked one. Those patches can only run after the
+// loop, because the bindings name block ids the creates mint. The frame being wired is the one the
+// PLAN designated, never whichever entry happens to carry `type: 'frontend'` (see
+// `MonorepoImportEntry.designatedFrontend`). A patch that does not land leaves its frames standing
+// and is REPORTED: `updateBlock` toasts its own failure and answers whether it persisted, so the
+// success toast claims only the links that were actually written.
 async function addServices() {
   if (!canAddServices.value || selectedRepoId.value === undefined) return
-  const dirs = selectedDirectories.value.filter((d) => !addedDirSet.value.has(normalizeRepoPath(d)))
+  const dirs = [...pendingDirectories.value]
   if (dirs.length === 0) return
+  // The mark is handed over raw: `planMonorepoImport` applies `canDesignateFrontend` itself over
+  // the very directories it is creating, so there is no second copy of that condition to drift.
+  const plan = planMonorepoImport(dirs, selectedType.value, frontendDirectory.value)
+  const designatedDirectory = plan.find((entry) => entry.designatedFrontend)?.directory
   adding.value = true
   try {
-    let lastBlock: Awaited<ReturnType<typeof board.addServiceFromRepo>> | undefined
-    for (const directory of dirs) {
-      lastBlock = await board.addServiceFromRepo(selectedRepoId.value, {
-        directory,
+    const created: CreatedMonorepoFrame[] = []
+    for (const entry of plan) {
+      const block = await board.addServiceFromRepo(selectedRepoId.value, {
+        directory: entry.directory,
         isMonorepo: true,
-        type: selectedType.value,
+        type: entry.type,
         position: freeFramePosition(),
       })
+      created.push({ blockId: block.id, entry })
+    }
+    let wiringLanded = true
+    for (const patch of planFrontendConfigPatches(created)) {
+      const persisted = await board.updateBlock(patch.blockId, { frontendConfig: patch.config })
+      if (!persisted) wiringLanded = false
     }
     await github.load()
-    if (lastBlock) await focusFrame(lastBlock.id)
+    const lastBlockId = created.at(-1)?.blockId
+    if (lastBlockId) await focusFrame(lastBlockId)
     selectedDirectories.value = []
     toast.add({
       title: t('github.addService.toast.servicesAddedTitle'),
-      description: t(
-        'github.addService.toast.servicesAddedDescription',
-        { count: dirs.length },
-        dirs.length,
-      ),
-      icon: 'i-lucide-check',
-      color: 'success',
+      description: [
+        t('github.addService.toast.servicesAddedDescription', { count: dirs.length }, dirs.length),
+        frontendNote(designatedDirectory, wiringLanded),
+      ]
+        .filter(Boolean)
+        .join(' '),
+      icon: wiringLanded ? 'i-lucide-check' : 'i-lucide-triangle-alert',
+      color: wiringLanded ? 'success' : 'warning',
     })
   } catch (e) {
     toast.add({
@@ -498,6 +580,25 @@ function done() {
                 <p v-else class="text-xs text-slate-500">
                   {{ t('github.addService.noServicesSelected') }}
                 </p>
+
+                <!-- Mark one pick as the frontend for the others: it is created as a frontend
+                     app and bound to every backend added beside it. Only offered while the
+                     mark would wire something (see `canDesignateFrontend`). -->
+                <UFormField
+                  v-if="frontendOffered"
+                  :label="t('github.addService.frontendLabel')"
+                  :description="t('github.addService.frontendHint')"
+                >
+                  <USelect
+                    v-model="frontendSelection"
+                    :items="frontendItems"
+                    value-key="value"
+                    size="sm"
+                    class="w-full"
+                    data-testid="add-service-frontend-select"
+                  />
+                </UFormField>
+
                 <div class="flex justify-end">
                   <UButton
                     color="primary"
@@ -507,11 +608,13 @@ function done() {
                     :disabled="!canAddServices"
                     @click="addServices"
                   >
+                    <!-- Counts what the click will CREATE, not the raw cart: an entry whose frame
+                         already exists (a retry after a partial failure) is not added again. -->
                     {{
                       t(
                         'github.addService.addServices',
-                        { count: selectedDirectories.length },
-                        selectedDirectories.length,
+                        { count: pendingDirectories.length },
+                        pendingDirectories.length,
                       )
                     }}
                   </UButton>

package/app/composables/useBoardActivity.ts

@@ -0,0 +1,111 @@
+import { inject, onBeforeUnmount, onMounted, provide, type InjectionKey, type Ref } from 'vue'
+
+/**
+ * The board's shared "something may have moved" pulse.
+ *
+ * The two DOM-measuring drivers on the canvas (dependency edges, task expansion) cannot ask
+ * the DOM "did anything change since last frame" without doing the measurement that IS the
+ * cost, so each used to measure unconditionally every frame. This publishes the signals that
+ * can START a visible change instead; the drivers pair it with `useSettlingRaf`, which
+ * carries each wake through the animation that follows and parks once the output holds still.
+ *
+ * The signals are deliberately coarse. A pulse that fires when nothing moved costs a handful
+ * of frames; one that fails to fire leaves a stale arrow on screen, so this errs toward
+ * firing:
+ *
+ *  - a `MutationObserver` over the canvas subtree, watching structure plus `style` / `class`.
+ *    That is every Vue-driven render change on the board, Vue Flow's own pan/zoom transform
+ *    included. Attribute changes the drivers themselves write (`x1`/`y1` on the edge overlay)
+ *    are outside the filter, so a driver cannot pulse itself awake forever.
+ *  - a `ResizeObserver` on the canvas, plus window `resize`: layout changes with no mutation.
+ *  - pointer, wheel and scroll gestures on the canvas: the user moving something.
+ *
+ * What it does NOT catch is a reflow with no mutation and no gesture, such as a late-loading
+ * image or font resizing a card. Those settle on the next pulse of any kind.
+ */
+export type BoardActivity = {
+  /** Subscribe to the pulse. Returns the unsubscribe. */
+  subscribe: (onPulse: () => void) => () => void
+  /** Fire the pulse from a signal the observers above cannot see. */
+  pulse: () => void
+}
+
+const boardActivityKey: InjectionKey<BoardActivity> = Symbol('boardActivity')
+
+/**
+ * Installs the signal sources on the board canvas element and provides the pulse to the
+ * canvas's descendants. Returns it too, because a component cannot inject what it provides.
+ */
+export function provideBoardActivity(container: Ref<HTMLElement | null>): BoardActivity {
+  const subscribers = new Set<() => void>()
+  const pulse = () => {
+    for (const onPulse of subscribers) onPulse()
+  }
+
+  const activity: BoardActivity = {
+    subscribe(onPulse) {
+      subscribers.add(onPulse)
+      return () => subscribers.delete(onPulse)
+    },
+    pulse,
+  }
+  provide(boardActivityKey, activity)
+
+  const mutations = new MutationObserver(pulse)
+  const resizes = new ResizeObserver(pulse)
+  // `scroll` does not bubble, so it is caught in the capture phase; the gestures are
+  // passive listeners because the pulse never wants to cancel one.
+  const gestures = [
+    'pointerdown',
+    'pointermove',
+    'pointerup',
+    'pointerleave',
+    'wheel',
+    'scroll',
+  ] as const
+  const gestureOptions = { capture: true, passive: true }
+
+  onMounted(() => {
+    // The canvas binds this ref to its own root, so by mount it is always set; the narrowing is
+    // for the nullable template-ref type rather than a case that happens.
+    const el = container.value
+    if (!el) return
+    mutations.observe(el, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['style', 'class'],
+    })
+    resizes.observe(el)
+    for (const type of gestures) el.addEventListener(type, pulse, gestureOptions)
+    window.addEventListener('resize', pulse)
+  })
+
+  onBeforeUnmount(() => {
+    mutations.disconnect()
+    resizes.disconnect()
+    const el = container.value
+    for (const type of gestures) el?.removeEventListener(type, pulse, gestureOptions)
+    window.removeEventListener('resize', pulse)
+    subscribers.clear()
+  })
+
+  return activity
+}
+
+/** Keeps `onPulse` subscribed to a pulse the caller already holds, for the component's lifetime. */
+export function onBoardActivity(activity: BoardActivity, onPulse: () => void): void {
+  onBeforeUnmount(activity.subscribe(onPulse))
+}
+
+/**
+ * The same, for a descendant of the canvas that reads the pulse by injection. Throws when used
+ * outside the board canvas: a driver that silently subscribed to nothing would measure once and
+ * then freeze, which reads as a layout bug rather than the wiring one it is. The canvas itself
+ * cannot inject what it provides, so it passes the returned pulse to `onBoardActivity` instead.
+ */
+export function useBoardActivity(onPulse: () => void): void {
+  const activity = inject(boardActivityKey, null)
+  if (!activity) throw new Error('useBoardActivity() requires a board canvas ancestor')
+  onBoardActivity(activity, onPulse)
+}

package/app/composables/useSettlingRaf.ts

@@ -0,0 +1,32 @@
+import { onBeforeUnmount, onMounted } from 'vue'
+import { createSettlingLoop, type SettlingLoop } from '~/utils/settlingLoop'
+
+/**
+ * Vue lifecycle wrapper around {@link createSettlingLoop}: an animation-frame loop that runs
+ * while `compute()` keeps changing something and parks once it settles. The caller wakes it
+ * with the returned `poke`, wired to whatever signals can start a change (see
+ * `useBoardActivity` for the board's shared set).
+ *
+ * `compute` MUST report honestly whether it changed anything: returning `true` unconditionally
+ * turns this back into the unconditional 60fps loop it replaced.
+ */
+export function useSettlingRaf(
+  compute: () => boolean,
+  options: { settleFrames?: number } = {},
+): Pick<SettlingLoop, 'poke'> {
+  const loop = createSettlingLoop({
+    compute,
+    settleFrames: options.settleFrames,
+    scheduler: {
+      schedule: (run) => requestAnimationFrame(run),
+      cancel: (handle) => cancelAnimationFrame(handle),
+    },
+  })
+
+  // The first frame runs on mount: the board arrives with blocks already laid out, and
+  // nothing would poke a loop that had never measured anything.
+  onMounted(loop.poke)
+  onBeforeUnmount(loop.stop)
+
+  return { poke: loop.poke }
+}

package/app/composables/useTaskExpansion.ts

@@ -1,7 +1,8 @@
 import type { Ref } from 'vue'
 import { onMounted, onBeforeUnmount } from 'vue'
-import { useRafFn } from '@vueuse/core'
 import { lodAtLeast } from '~/composables/useSemanticZoom'
+import { onBoardActivity, type BoardActivity } from '~/composables/useBoardActivity'
+import { useSettlingRaf } from '~/composables/useSettlingRaf'
 import { headerDistanceSq, type Rect } from '~/utils/taskExpansionRanking'
 
 function intersects(a: Rect, b: Rect) {
@@ -33,8 +34,12 @@ function sameSet(a: Set<string>, b: Set<string>) {
  *
  * Only tasks with a running pipeline (steps to show) are candidates for either grant — a
  * task that wouldn't expand never blocks a neighbour and never lifts an empty card.
+ *
+ * Deciding costs a rect per candidate plus an `elementFromPoint`, so it runs only while the
+ * board is moving: the canvas activity pulse wakes it and `useSettlingRaf` parks it again once
+ * the two grants stop changing.
  */
-export function useTaskExpansion(container: Ref<HTMLElement | null>) {
+export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: BoardActivity) {
   const board = useBoardStore()
   const execution = useExecutionStore()
   const ui = useUiStore()
@@ -79,21 +84,29 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
     return id
   }
 
-  function recompute() {
+  /** Re-decide both grants; reports whether either of them changed. */
+  function recompute(): boolean {
     // Hover expands a card at ANY zoom band, so the pointer hit is resolved BEFORE the
     // zoom gate below — resolving it after would collapse the hovered card the moment the
     // user zoomed back out past the `steps` band.
     const hovered = hoveredTaskId()
-    if (store.hoveredId !== hovered) store.setHovered(hovered)
+    let changed = false
+    if (store.hoveredId !== hovered) {
+      store.setHovered(hovered)
+      changed = true
+    }
 
     // The zoom-driven expansion (every on-screen card, overlap-resolved) is deep-band
     // only; clear its grants otherwise. The hover grant above stands on its own.
     if (!lodAtLeast(ui.lod, 'steps')) {
-      if (store.allowed.size) store.setAllowed(new Set())
-      return
+      if (store.allowed.size) {
+        store.setAllowed(new Set())
+        changed = true
+      }
+      return changed
     }
     const view = container.value?.getBoundingClientRect()
-    if (!view) return
+    if (!view) return changed
     const cx = view.left + view.width / 2
     const cy = view.top + view.height / 2
 
@@ -145,19 +158,24 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>) {
       next.add(c.id)
       claimed.push(c.rect)
     }
-    if (!sameSet(next, store.allowed)) store.setAllowed(next)
+    if (!sameSet(next, store.allowed)) {
+      store.setAllowed(next)
+      changed = true
+    }
+    return changed
   }
 
-  const { pause, resume } = useRafFn(recompute, { immediate: false })
+  const { poke } = useSettlingRaf(recompute)
+  // The pointer listeners below only record where the pointer IS; the pulse (which watches the
+  // same gestures) is what schedules the frame that acts on it.
+  onBoardActivity(activity, poke)
   onMounted(() => {
     store.setDriverActive(true)
     const el = container.value
     el?.addEventListener('pointermove', onPointerMove)
     el?.addEventListener('pointerleave', onPointerLeave)
-    resume()
   })
   onBeforeUnmount(() => {
-    pause()
     const el = container.value
     el?.removeEventListener('pointermove', onPointerMove)
     el?.removeEventListener('pointerleave', onPointerLeave)