@cat-factory/app 0.259.1 → 0.260.1

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)

package/app/stores/board/placement.ts

@@ -207,10 +207,17 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     }
   }
 
-  /** Patch the user-editable fields of a block (title, features, threshold…). */
-  async function updateBlock(id: string, patch: UpdateBlockInput) {
+  /**
+   * Patch the user-editable fields of a block (title, features, threshold…).
+   *
+   * Returns whether the patch was PERSISTED. Both failure modes are already reported here (an
+   * unknown block is a no-op, a rejected write rolls back and toasts), so an inspector control
+   * firing and forgetting stays correct. A caller that goes on to ASSERT what the patch achieved
+   * must read it, or it announces links the rollback has just undone.
+   */
+  async function updateBlock(id: string, patch: UpdateBlockInput): Promise<boolean> {
     const b = getBlock(id)
-    if (!b) return
+    if (!b) return false
     // Snapshot ONLY the fields this patch touches so a rejected write restores them exactly
     // (a patch may set several at once) rather than leaving a stale optimistic value stuck on
     // screen with no feedback — the same rollback contract the other mutations here follow.
@@ -224,6 +231,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     Object.assign(b, patch) // optimistic
     try {
       upsert(await api.updateBlock(useWorkspaceStore().requireId(), id, patch))
+      return true
     } catch (e) {
       // Re-resolve the block: a live event may have replaced its object reference (`upsert`
       // swaps in a fresh one) while the write was in flight, so `b` can be stale. Only revert
@@ -242,6 +250,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
         icon: 'i-lucide-triangle-alert',
         color: 'error',
       })
+      return false
     }
   }
 

package/app/stores/board.spec.ts

@@ -256,12 +256,22 @@ describe('board store read getters', () => {
     s.hydrate([frame('f1', { title: 'Original', description: 'orig' })])
     // With no active workspace, `requireId()` throws inside updateBlock's try — the same catch
     // that a rejected API write hits — so this exercises the optimistic-rollback + toast path.
-    await s.updateBlock('f1', { title: 'Edited', description: 'changed' })
+    // The outcome is REPORTED to the caller, not only toasted: a caller that goes on to announce
+    // what the patch achieved (the monorepo import's frontend wiring) has to see the rollback.
+    await expect(s.updateBlock('f1', { title: 'Edited', description: 'changed' })).resolves.toBe(
+      false,
+    )
     expect(s.getBlock('f1')?.title).toBe('Original')
     expect(s.getBlock('f1')?.description).toBe('orig')
     expect(addSpy).toHaveBeenCalledWith(expect.objectContaining({ color: 'error' }))
   })
 
+  it('updateBlock reports a no-op for a block that is not on the board', async () => {
+    // Nothing is patched and nothing is toasted, so the return value is the ONLY signal that the
+    // write did not happen.
+    await expect(store.updateBlock('missing', { title: 'Edited' })).resolves.toBe(false)
+  })
+
   it('hydrate replaces and upsert inserts/updates cached blocks', () => {
     store.hydrate([frame('f1')])
     store.upsert(task('t1', 'f1', { title: 'first' }))
@@ -305,11 +315,21 @@ describe('board store optimistic rollback', () => {
     }))
     const store = useBoardStore()
     store.hydrate([frame('f1'), task('t1', 'f1', { title: 'orig', description: 'keep' })])
-    await store.updateBlock('t1', { title: 'renamed' })
+    await expect(store.updateBlock('t1', { title: 'renamed' })).resolves.toBe(false)
     expect(store.getBlock('t1')?.title).toBe('orig')
     expect(store.getBlock('t1')?.description).toBe('keep')
   })
 
+  it('updateBlock reports the patch persisted when the API accepts it', async () => {
+    vi.stubGlobal('useApi', () => ({
+      updateBlock: async () => task('t1', 'f1', { title: 'renamed' }),
+    }))
+    const store = useBoardStore()
+    store.hydrate([frame('f1'), task('t1', 'f1', { title: 'orig' })])
+    await expect(store.updateBlock('t1', { title: 'renamed' })).resolves.toBe(true)
+    expect(store.getBlock('t1')?.title).toBe('renamed')
+  })
+
   it('previewResize translates the children when the drag moves the content origin', () => {
     // A child's position is relative to its container's content origin, so growing the frame
     // 40px west (origin -40) has to move every direct child +40 or the whole content slides with

package/app/utils/binaryOutput.spec.ts

@@ -521,6 +521,91 @@ describe('binaryOutputPickIssues, generative half', () => {
     expect(pick.conflictingSizeOptions).toEqual(['upscale'])
   })
 
+  // The refusal a value axis adds over the capability one: every selected endpoint takes an
+  // aspect ratio and none of them takes THIS ratio. Stated here because the builder is where the
+  // fix is (pick a listed ratio, or select an integration that renders this one), and because the
+  // set it names is already on the snapshot the picker is holding.
+  it('names a value nothing selected accepts, and what they do accept', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', generatorIds: ['bucketed'], generation: { aspectRatio: '7:3' } },
+      catalog,
+      true,
+      [
+        {
+          id: 'bucketed',
+          modalities: ['image' as const],
+          capabilities: ['aspect-ratio' as const],
+          accepts: { aspectRatios: ['1:1', '16:9'] },
+        },
+      ],
+    )
+    expect(pick.issues).toContain('option_value_unaccepted')
+    expect(pick.unacceptedValues).toEqual([
+      { option: 'aspectRatio', requested: '7:3', accepted: ['1:1', '16:9'] },
+    ])
+  })
+
+  // ADVISORY, and the state that keeps the refusal above from firing on a working selection: one
+  // integration refuses the ratio and another has not said what it takes.
+  it('advises rather than refuses when a silent declarer might still serve the value', () => {
+    const pick = binaryOutputPickIssues(
+      {
+        storageServiceId: 'files',
+        generatorIds: ['bucketed', 'open'],
+        generation: { aspectRatio: '7:3' },
+      },
+      catalog,
+      true,
+      [
+        {
+          id: 'bucketed',
+          modalities: ['image' as const],
+          capabilities: ['aspect-ratio' as const],
+          accepts: { aspectRatios: ['1:1', '16:9'] },
+        },
+        { id: 'open', modalities: ['image' as const], capabilities: ['aspect-ratio' as const] },
+      ],
+    )
+    expect(pick.issues).toContain('option_value_unverifiable')
+    expect(pick.issues).not.toContain('option_value_unaccepted')
+    expect(pick.unverifiableValues).toEqual(['aspectRatio'])
+  })
+
+  // ADVISORY too, and the one the reader can act on precisely: one selected endpoint takes the
+  // ratio and another has written down that it does not. Naming the second is the whole remedy,
+  // and it is the finding a first-accepting-declarer short-circuit reported as nothing at all.
+  it('names the integrations that enumerated a value away when another accepts it', () => {
+    const pick = binaryOutputPickIssues(
+      {
+        storageServiceId: 'files',
+        generatorIds: ['wide', 'bucketed'],
+        generation: { aspectRatio: '7:3' },
+      },
+      catalog,
+      true,
+      [
+        {
+          id: 'wide',
+          modalities: ['image' as const],
+          capabilities: ['aspect-ratio' as const],
+          accepts: { aspectRatios: ['7:3', '1:1'] },
+        },
+        {
+          id: 'bucketed',
+          modalities: ['image' as const],
+          capabilities: ['aspect-ratio' as const],
+          accepts: { aspectRatios: ['1:1', '16:9'] },
+        },
+      ],
+    )
+    expect(pick.issues).toContain('option_value_partial')
+    expect(pick.issues).not.toContain('option_value_unaccepted')
+    expect(pick.issues).not.toContain('option_value_unverifiable')
+    expect(pick.partiallyAcceptedValues).toEqual([
+      { option: 'aspectRatio', requested: '7:3', refusedBy: ['bucketed'] },
+    ])
+  })
+
   it('reports BOTH faults when an unknown id was the one covering a requirement', () => {
     // One edit should clear the step. Naming only the missing id would leave the user to
     // discover the uncovered requirement on the next round trip.

package/app/utils/binaryOutput.ts

@@ -3,6 +3,7 @@ import {
   binaryCapabilityCoverage,
   binaryFormatCoverage,
   binaryModalityOverlaps,
+  binaryValueCoverage,
   conflictingOutputSizeOptions,
   isBinaryModality,
   modalityCarriesPixelDimensions,
@@ -13,6 +14,9 @@ import type {
   BinaryGeneratorCapability,
   BinaryModality,
   BinaryModalityOverlap,
+  BinaryPartiallyAcceptedValue,
+  BinaryUnacceptedValue,
+  BinaryValueOption,
   ConflictingOutputSizeOption,
   RegisteredBinaryGenerator,
 } from '@cat-factory/contracts'
@@ -532,6 +536,28 @@ export type BinaryOutputPickIssue =
    * flag most working selections in the product.
    */
   | 'capability_unverifiable'
+  /**
+   * A generation option every selected integration can be ASKED for and none of them accepts the
+   * step's VALUE at: a `7:3` aspect ratio against endpoints whose picklists offer ten others
+   * (kernel's `option_value_unaccepted` spelling verbatim, like the members above it). A refusal.
+   */
+  | 'option_value_unaccepted'
+  /**
+   * A selected integration ACCEPTS the step's value and another has enumerated it away, so the
+   * step is servable by part of what it selected and the rest would quietly deliver something
+   * else. ADVISORY, and the reason is the same one that makes a capability covered when a single
+   * integration declares it: which endpoint renders which artifact is the agent's call. What is
+   * NOT optional is naming the ones that refuse it, since routing around them is the whole remedy.
+   */
+  | 'option_value_partial'
+  /**
+   * The step's value is on no stated set, and a selected integration that declares the capability
+   * states no set at all, so it may still be served. ADVISORY, for the reason
+   * `capability_unverifiable` is, and it is deliberately silent where NOBODY states a set: that is
+   * the state every registration is in until an endpoint is audited, and a line that fired there
+   * would ride nearly every step carrying an aspect ratio.
+   */
+  | 'option_value_unverifiable'
   /**
    * The step states an exact output size AND another option that restates the delivered
    * dimensions (`aspectRatio`, `upscale`). A refusal, mirroring `assertUnambiguousOutputSize` at
@@ -567,6 +593,14 @@ export interface BinaryOutputPickState {
   unsupportedCapabilities: readonly BinaryGeneratorCapability[]
   /** The ones that could not be judged, kept apart from the refusal above. */
   unverifiableCapabilities: readonly BinaryGeneratorCapability[]
+  /** The requested option values nothing selected accepts, each with what IS accepted, so the
+   *  message names a value the reader can pick instead of only the one they cannot. */
+  unacceptedValues: readonly BinaryUnacceptedValue[]
+  /** The requested values a selected integration accepts and another enumerated away, naming the
+   *  ones that refuse them, since the remedy is dropping or re-routing around those. */
+  partiallyAcceptedValues: readonly BinaryPartiallyAcceptedValue[]
+  /** The ones a silent declarer left open, kept apart from the refusal above. */
+  unverifiableValues: readonly BinaryValueOption[]
   /** The options restating the delivered dimensions beside an exact size, for the line that names
    *  which field to delete. Computed through contracts' own rule, so this cannot come to a
    *  different answer from the save that refuses it. */
@@ -598,7 +632,7 @@ function generatorPickIssues(
   config: BinaryOutputConfig | undefined,
   generators: readonly Pick<
     RegisteredBinaryGenerator,
-    'id' | 'modalities' | 'mediaTypes' | 'capabilities'
+    'id' | 'modalities' | 'mediaTypes' | 'capabilities' | 'accepts'
   >[],
   unavailable: boolean,
 ): {
@@ -610,6 +644,9 @@ function generatorPickIssues(
   overlaps: BinaryModalityOverlap[]
   unsupportedCapabilities: BinaryGeneratorCapability[]
   unverifiableCapabilities: BinaryGeneratorCapability[]
+  unacceptedValues: BinaryUnacceptedValue[]
+  partiallyAcceptedValues: BinaryPartiallyAcceptedValue[]
+  unverifiableValues: BinaryValueOption[]
 } {
   const none = {
     unknownGeneratorIds: [],
@@ -619,6 +656,9 @@ function generatorPickIssues(
     overlaps: [],
     unsupportedCapabilities: [],
     unverifiableCapabilities: [],
+    unacceptedValues: [],
+    partiallyAcceptedValues: [],
+    unverifiableValues: [],
   }
   if (unavailable) return { issues: ['generators_unavailable'], ...none }
   const byId = new Map(generators.map((g) => [g.id, g]))
@@ -646,6 +686,10 @@ function generatorPickIssues(
     requiredBinaryCapabilities(config?.generation),
     selected,
   )
+  // One notch finer: the option is supported and the VALUE is not. Imported like every rule
+  // beside it, so the line this surface shows and the refusal the backend raises are one
+  // judgement rather than two that agree until somebody edits one of them.
+  const value = binaryValueCoverage(config?.generation, selected)
   const issues: BinaryOutputPickIssue[] = []
   if (unknownGeneratorIds.length) issues.push('unknown_generator')
   if (uncovered.length) issues.push('modality_uncovered')
@@ -654,6 +698,9 @@ function generatorPickIssues(
   if (overlaps.length) issues.push('generator_overlap')
   if (capability.uncovered.length) issues.push('capability_unsupported')
   if (capability.unverifiable.length) issues.push('capability_unverifiable')
+  if (value.unaccepted.length) issues.push('option_value_unaccepted')
+  if (value.partial.length) issues.push('option_value_partial')
+  if (value.unverifiable.length) issues.push('option_value_unverifiable')
   return {
     issues,
     unknownGeneratorIds,
@@ -663,6 +710,9 @@ function generatorPickIssues(
     overlaps,
     unsupportedCapabilities: capability.uncovered,
     unverifiableCapabilities: capability.unverifiable,
+    unacceptedValues: value.unaccepted,
+    partiallyAcceptedValues: value.partial,
+    unverifiableValues: value.unverifiable,
   }
 }
 
@@ -699,7 +749,7 @@ export function binaryOutputPickIssues(
   // stays a legitimate value rather than a hole.
   generators: readonly Pick<
     RegisteredBinaryGenerator,
-    'id' | 'modalities' | 'mediaTypes' | 'capabilities'
+    'id' | 'modalities' | 'mediaTypes' | 'capabilities' | 'accepts'
   >[] = [],
   // Whether the deployment's integrations could not be READ. Defaulted to `false` — the honest
   // default, since every deployment but a mothership-mode node reads them in-process and cannot
@@ -737,6 +787,9 @@ export function binaryOutputPickIssues(
       generatorOverlaps: generative.overlaps,
       unsupportedCapabilities: generative.unsupportedCapabilities,
       unverifiableCapabilities: generative.unverifiableCapabilities,
+      unacceptedValues: generative.unacceptedValues,
+      partiallyAcceptedValues: generative.partiallyAcceptedValues,
+      unverifiableValues: generative.unverifiableValues,
       conflictingSizeOptions,
     }
   }
@@ -764,6 +817,9 @@ export function binaryOutputPickIssues(
     generatorOverlaps: generative.overlaps,
     unsupportedCapabilities: generative.unsupportedCapabilities,
     unverifiableCapabilities: generative.unverifiableCapabilities,
+    unacceptedValues: generative.unacceptedValues,
+    partiallyAcceptedValues: generative.partiallyAcceptedValues,
+    unverifiableValues: generative.unverifiableValues,
     conflictingSizeOptions,
   }
 }

package/app/utils/edgeSegments.spec.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { shallowRef } from 'vue'
+import { commitSegments, sameSegments, type EdgeSegment } from './edgeSegments'
+
+const line = (over: Partial<EdgeSegment> = {}): EdgeSegment => ({
+  id: 'a__b',
+  x1: 0,
+  y1: 0,
+  x2: 10,
+  y2: 10,
+  ...over,
+})
+
+describe('sameSegments', () => {
+  it('accepts a freshly measured list that resolved to the same overlay', () => {
+    expect(sameSegments([line()], [line()])).toBe(true)
+  })
+
+  it('rejects a moved endpoint, however slightly', () => {
+    expect(sameSegments([line()], [line({ y2: 10.5 })])).toBe(false)
+  })
+
+  it('rejects a changed link set', () => {
+    expect(sameSegments([line()], [])).toBe(false)
+    expect(sameSegments([line()], [line({ id: 'a__c' })])).toBe(false)
+  })
+
+  it('rejects a dependency whose source finished, since it restyles the arrow', () => {
+    expect(sameSegments([line({ done: false })], [line({ done: true })])).toBe(false)
+  })
+})
+
+describe('commitSegments', () => {
+  it('publishes a changed list and reports it', () => {
+    const target = shallowRef<EdgeSegment[]>([line()])
+    const next = [line({ x2: 20 })]
+    expect(commitSegments(target, next)).toBe(true)
+    expect(target.value).toBe(next)
+  })
+
+  it('leaves the published array untouched when nothing moved', () => {
+    const published = [line()]
+    const target = shallowRef<EdgeSegment[]>(published)
+    // Identity has to survive, not just the values: reassigning an equal-but-new array is
+    // what re-rendered the whole overlay on every frame of an idle board.
+    expect(commitSegments(target, [line()])).toBe(false)
+    expect(target.value).toBe(published)
+  })
+})

package/app/utils/edgeSegments.ts

@@ -0,0 +1,49 @@
+import type { Ref } from 'vue'
+
+/**
+ * One drawable link on the board's screen-space overlay: a border-to-border line between two
+ * block cards. `done` rides only on dependency edges, where it picks the stroke and arrowhead.
+ */
+export type EdgeSegment = {
+  id: string
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+  done?: boolean
+}
+
+/** Whether two resolved segment lists would draw exactly the same overlay. */
+export function sameSegments(a: readonly EdgeSegment[], b: readonly EdgeSegment[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    const left = a[i]!
+    const right = b[i]!
+    if (
+      left.id !== right.id ||
+      left.x1 !== right.x1 ||
+      left.y1 !== right.y1 ||
+      left.x2 !== right.x2 ||
+      left.y2 !== right.y2 ||
+      left.done !== right.done
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Publish a freshly measured list, and report whether it moved anything. Writing an
+ * equal-but-new array every frame is what re-rendered the whole overlay 60 times a second on
+ * a board where nothing was moving, and it is also the signal the settling frame loop reads
+ * to decide it can park.
+ *
+ * The target is a `shallowRef`: the lists are replaced wholesale, so deep-proxying every
+ * segment object would be pure overhead.
+ */
+export function commitSegments(target: Ref<EdgeSegment[]>, next: EdgeSegment[]): boolean {
+  if (sameSegments(target.value, next)) return false
+  target.value = next
+  return true
+}

package/app/utils/monorepoImport.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import type { CreatedMonorepoFrame } from './monorepoImport'
+import {
+  canDesignateFrontend,
+  planFrontendConfigPatches,
+  planMonorepoImport,
+} from './monorepoImport'
+
+/** Pair a plan with block ids, the way the modal does as each create call returns. */
+function created(entries: ReturnType<typeof planMonorepoImport>): CreatedMonorepoFrame[] {
+  return entries.map((entry, i) => ({ blockId: `blk_${i}`, entry }))
+}
+
+describe('canDesignateFrontend', () => {
+  it('offers the mark for two or more backend services', () => {
+    expect(canDesignateFrontend('service', 2)).toBe(true)
+    expect(canDesignateFrontend('service', 5)).toBe(true)
+  })
+
+  it('withholds it below two directories: there is no rest to bind to', () => {
+    expect(canDesignateFrontend('service', 1)).toBe(false)
+    expect(canDesignateFrontend('service', 0)).toBe(false)
+  })
+
+  it('withholds it for roles a backend binding cannot point at', () => {
+    // A binding's `service` source names a `service` frame; a library/document frame is not one,
+    // and when everything is already a frontend the mark divides nothing.
+    expect(canDesignateFrontend('library', 3)).toBe(false)
+    expect(canDesignateFrontend('document', 3)).toBe(false)
+    expect(canDesignateFrontend('frontend', 3)).toBe(false)
+  })
+})
+
+describe('planMonorepoImport', () => {
+  it('creates the marked directory as a frontend and the rest with the picked role', () => {
+    expect(
+      planMonorepoImport(['apps/web', 'services/api', 'services/auth'], 'service', 'apps/web'),
+    ).toEqual([
+      { directory: 'apps/web', type: 'frontend', designatedFrontend: true },
+      { directory: 'services/api', type: 'service', designatedFrontend: false },
+      { directory: 'services/auth', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('keeps the picked order, wherever the marked directory sits in it', () => {
+    const plan = planMonorepoImport(['services/api', 'apps/web'], 'service', 'apps/web')
+    expect(plan.map((e) => e.directory)).toEqual(['services/api', 'apps/web'])
+    expect(plan[1]?.type).toBe('frontend')
+  })
+
+  it('gives every directory the picked role when nothing is marked', () => {
+    expect(planMonorepoImport(['a', 'b'], 'service', undefined)).toEqual([
+      { directory: 'a', type: 'service', designatedFrontend: false },
+      { directory: 'b', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('ignores a mark on a directory that is not being created', () => {
+    // The cart entry was removed (or was already on the board and got filtered out) after being
+    // marked. Designating nothing is right; promoting some other frame to frontend would not be.
+    expect(planMonorepoImport(['a', 'b'], 'service', 'apps/web')).toEqual([
+      { directory: 'a', type: 'service', designatedFrontend: false },
+      { directory: 'b', type: 'service', designatedFrontend: false },
+    ])
+  })
+
+  it('designates nobody when the whole cart is imported under the frontend role', () => {
+    // Every entry is `type: 'frontend'` here, so the flag is the ONLY thing that separates
+    // "the app the others talk to" from "a cart of frontends". A mark is never on offer for this
+    // role (`canDesignateFrontend`), and one carried over from a role change must not act.
+    const plan = planMonorepoImport(['apps/web', 'apps/admin'], 'frontend', 'apps/web')
+    expect(plan.every((e) => e.type === 'frontend')).toBe(true)
+    expect(plan.some((e) => e.designatedFrontend)).toBe(false)
+  })
+})
+
+describe('planFrontendConfigPatches', () => {
+  it('binds the designated frontend to every other frame created beside it', () => {
+    const plan = planMonorepoImport(
+      ['apps/web', 'services/api', 'services/auth'],
+      'service',
+      'apps/web',
+    )
+    expect(planFrontendConfigPatches(created(plan))).toEqual([
+      {
+        blockId: 'blk_0',
+        config: {
+          directory: 'apps/web',
+          backendBindings: [
+            { envVar: '', source: { kind: 'service', serviceBlockId: 'blk_1' } },
+            { envVar: '', source: { kind: 'service', serviceBlockId: 'blk_2' } },
+          ],
+        },
+      },
+    ])
+  })
+
+  it('leaves every env var name empty rather than inventing one', () => {
+    const plan = planMonorepoImport(['apps/web', 'services/api'], 'service', 'apps/web')
+    const [patch] = planFrontendConfigPatches(created(plan))
+    expect(patch?.config.backendBindings.every((b) => b.envVar === '')).toBe(true)
+  })
+
+  it('carries the subdirectory to every frontend frame, designated or not', () => {
+    // `frontendConfig.directory` is what the harness's install/build/serve reads; the service-level
+    // directory that scopes an agent's checkout is a different field and does not stand in. A cart
+    // imported under the `frontend` role has no designated frame, and every frame in it would
+    // otherwise build the repo root.
+    const plan = planMonorepoImport(['apps/web', 'apps/admin'], 'frontend', undefined)
+    expect(planFrontendConfigPatches(created(plan))).toEqual([
+      { blockId: 'blk_0', config: { directory: 'apps/web', backendBindings: [] } },
+      { blockId: 'blk_1', config: { directory: 'apps/admin', backendBindings: [] } },
+    ])
+  })
+
+  it('patches nothing when the import creates no frontend frame', () => {
+    const plan = planMonorepoImport(['services/api', 'services/auth'], 'service', undefined)
+    expect(planFrontendConfigPatches(created(plan))).toEqual([])
+  })
+})