@cat-factory/app 0.259.3 → 0.261.0

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/auth/LoginScreen.vue

@@ -5,6 +5,7 @@ import SecretInput from '~/components/common/SecretInput.vue'
 import type { VcsProvider } from '~/types/domain'
 import { VCS_PROVIDER_ICONS, VCS_PROVIDER_LABELS, vcsTokenCreateUrl } from '~/utils/vcs'
 import { SSO_ERROR_MESSAGE_KEYS } from '~/utils/sso'
+import { postSignInUrl } from '~/utils/postSignIn'
 
 const auth = useAuthStore()
 const { t } = useI18n()
@@ -62,7 +63,7 @@ async function submitPat(provider: PatProvider) {
   patBusy.value = true
   try {
     await auth.patLogin({ provider })
-    if (typeof window !== 'undefined') window.location.assign(window.location.pathname)
+    if (typeof window !== 'undefined') window.location.assign(postSignInUrl(window.location))
   } catch (e) {
     patError.value = apiErrorEnvelope(e)?.message ?? t('auth.localMode.failed')
   } finally {
@@ -105,7 +106,7 @@ async function submitPassword() {
       await auth.passwordLogin({ email: email.value, password: password.value })
     }
     // Reload so the app boots with the new session.
-    if (typeof window !== 'undefined') window.location.assign(window.location.pathname)
+    if (typeof window !== 'undefined') window.location.assign(postSignInUrl(window.location))
   } catch (e) {
     error.value = apiErrorEnvelope(e)?.message ?? t('auth.login.signInFailed')
   } finally {
@@ -177,7 +178,7 @@ async function submitRemotePat() {
   remotePatBusy.value = true
   try {
     await auth.patLogin({ provider: remotePatProvider.value, token: remotePatToken.value.trim() })
-    if (typeof window !== 'undefined') window.location.assign(window.location.pathname)
+    if (typeof window !== 'undefined') window.location.assign(postSignInUrl(window.location))
   } catch (e) {
     remotePatError.value = apiErrorEnvelope(e)?.message ?? t('auth.login.signInFailed')
   } finally {

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>