@cat-factory/app 0.256.3 → 0.258.0

package/app/components/panels/AgentStepDetail.vue

@@ -21,7 +21,11 @@ import StepExecutionHistory from '~/components/board/StepExecutionHistory.vue'
 import { useStepTimer } from '~/composables/useStepTimer'
 import { useStepProse } from '~/composables/useStepProse'
 import { useStepApproval } from '~/composables/useStepApproval'
-import { dedicatedParkView } from '~/utils/pipelineRender'
+import {
+  REDIRECT_PARK_PRESENTATION,
+  type RedirectParkView,
+  dedicatedParkView,
+} from '~/utils/pipelineRender'
 import InputGateNotice from '~/components/inputGate/InputGateNotice.vue'
 
 // Detail overlay for a single pipeline step. Opened by clicking an agent in the
@@ -191,14 +195,37 @@ const genericApprovalPending = computed(
   () => approvalPending.value && !companionExceeded.value && !dedicatedPark.value,
 )
 
-/** Jump from this overlay to the window that can actually resolve the dedicated park. */
+/**
+ * How the park that holds this step presents itself (prose, icon, action label), or null when no
+ * window owns it. Read from the shared table rather than branched on here, so this overlay cannot
+ * go on naming the fork decision for a park that is not one.
+ */
+const parkPresentation = computed(() =>
+  dedicatedPark.value && dedicatedPark.value !== 'input-gate'
+    ? REDIRECT_PARK_PRESENTATION[dedicatedPark.value]
+    : null,
+)
+
+/**
+ * Jump from this overlay to the window that can actually resolve the dedicated park.
+ *
+ * A `Record` over the vocabulary rather than an `if` chain, for the reason the presentation table
+ * gives: an unhandled member falls out of a chain as a button that closes this overlay and opens
+ * NOTHING, which is indistinguishable from a misclick. Here a new park fails to compile until it
+ * names its opener.
+ */
+const PARK_OPENERS: Record<RedirectParkView, (instanceId: string, stepIndex: number) => void> = {
+  'follow-ups': (id, idx) => ui.openFollowUps(id, idx),
+  'fork-decision': (id, idx) => ui.openForkDecision(id, idx),
+  'binary-candidates': (id, idx) => ui.openBinaryCandidates(id, idx),
+}
+
 function openDedicatedWindow() {
   const c = ctx.value
   const park = dedicatedPark.value
-  if (!c || !park) return
+  if (!c || !park || park === 'input-gate') return
   close()
-  if (park === 'follow-ups') ui.openFollowUps(c.instanceId, c.stepIndex)
-  else if (park === 'fork-decision') ui.openForkDecision(c.instanceId, c.stepIndex)
+  PARK_OPENERS[park](c.instanceId, c.stepIndex)
 }
 
 // The GitHub-style approval/review state machine for a pending gate step. A park a
@@ -476,9 +503,11 @@ async function copyOutput() {
                 @resolve="resolveCompanionCap"
               />
 
-              <!-- a park a dedicated window owns (fork choice / follow-up triage): the
-                   generic approval rail can't resolve it (the server refuses), so point
-                   the human at the window that can -->
+              <!-- a park a dedicated window owns (fork choice / follow-up triage / candidate
+                   comparison): the generic approval rail can't resolve it (the server refuses),
+                   so point the human at the window that can. Copy and icon come from the shared
+                   per-park table, so a park added to the vocabulary can never inherit another
+                   one's wording here. -->
               <!-- the pre-dispatch input gate holds this step: answered here, in place -->
               <InputGateNotice
                 v-if="inputGateVerdict && instance"
@@ -489,30 +518,23 @@ async function copyOutput() {
               />
 
               <div
-                v-if="dedicatedPark && dedicatedPark !== 'input-gate'"
+                v-if="parkPresentation"
                 class="rounded-xl border border-amber-500/30 bg-amber-500/5 p-4"
                 data-testid="dedicated-park-redirect"
+                :data-park="dedicatedPark"
               >
                 <p class="text-[13px] leading-relaxed text-amber-200/90">
-                  {{
-                    dedicatedPark === 'follow-ups'
-                      ? t('panels.stepDetail.followUpsParked')
-                      : t('panels.stepDetail.forkParked')
-                  }}
+                  {{ t(parkPresentation.noticeKey) }}
                 </p>
                 <UButton
                   class="mt-3"
                   color="primary"
                   size="sm"
-                  :icon="dedicatedPark === 'follow-ups' ? 'i-lucide-compass' : 'i-lucide-git-fork'"
+                  :icon="parkPresentation.icon"
                   data-testid="dedicated-park-open"
                   @click="openDedicatedWindow"
                 >
-                  {{
-                    dedicatedPark === 'follow-ups'
-                      ? t('panels.stepDetail.openFollowUps')
-                      : t('panels.stepDetail.chooseApproach')
-                  }}
+                  {{ t(parkPresentation.actionKey) }}
                 </UButton>
               </div>
 

package/app/components/panels/InspectorPanel.vue

@@ -7,6 +7,7 @@ import { inspectorPanels } from '~/modular/panels/inspector.logic'
 import IconButton from '~/components/common/IconButton.vue'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
+import { BLUEPRINT_AGENT_KIND } from '@cat-factory/contracts'
 import { VCS_PROVIDER_ICONS } from '~/utils/vcs'
 
 const board = useBoardStore()
@@ -244,6 +245,22 @@ const runMenu = computed(() => {
   ]
 })
 
+// Mapping a service: one run of the mapping agent against this frame, started by KIND (no
+// pipeline). The button owns only its in-flight state — a refusal is already surfaced as a toast
+// by the command, and the run itself then reports through the ordinary board/run projection, so
+// there is nothing for this component to remember about it afterwards.
+const mappingService = ref(false)
+async function mapService() {
+  const id = block.value?.id
+  if (!id) return
+  mappingService.value = true
+  try {
+    await execution.startAgentKind(id, BLUEPRINT_AGENT_KIND)
+  } finally {
+    mappingService.value = false
+  }
+}
+
 // Delegate to the shared confirm-gated deletion so the button and the keyboard shortcut
 // (Delete/Backspace) follow the exact same prompt + optimistic-delete + rollback path.
 const { deleteBlock, archiveBlock } = useBlockDeletion()
@@ -514,6 +531,28 @@ const showOriginalDescription = ref(false)
         {{ t('panels.inspector.viewRequirements') }}
       </UButton>
 
+      <!-- service (frame): (re)map the repository into the service → modules blueprint and
+           populate the board. A SINGLE-KIND run of the mapping agent, not a pipeline — the
+           preset that used to wrap this one step is retired. Needs a linked repo to read, so it
+           is disabled (with the reason) until the frame has one. -->
+      <UButton
+        v-if="isFrame"
+        block
+        color="neutral"
+        variant="soft"
+        size="sm"
+        icon="i-lucide-map"
+        :loading="mappingService"
+        :disabled="!serviceRepo || mappingService"
+        :title="serviceRepo ? undefined : t('panels.inspector.mapServiceNoRepo')"
+        @click="mapService"
+      >
+        {{ t('panels.inspector.mapService') }}
+      </UButton>
+      <p v-if="isFrame && !serviceRepo" class="text-[11px] text-slate-500">
+        {{ t('panels.inspector.mapServiceNoRepo') }}
+      </p>
+
       <!-- The level/type-keyed inspector body: the `inspectorPanels` panel group
            (slice 4 of the modular-vue adoption). `<PanelsOutlet>` renders every
            panel whose `when(block)` matches, ordered, with the selected block

package/app/components/panels/ResultWindowShell.logic.spec.ts

@@ -27,6 +27,10 @@ const SHELL_DEFAULT_WIDTH: ResultWindowWidth = '3xl'
  * not made the decision.
  */
 const WINDOWS: Record<string, { width: ResultWindowWidth; why: string }> = {
+  'binaryCandidates/BinaryCandidatesWindow.vue': {
+    width: '5xl',
+    why: 'a preview grid of generated candidates grouped by subject, read side by side to be compared, with no rail beside it',
+  },
   'brainstorm/BrainstormWindow.vue': {
     width: 'full',
     why: 'options column + the choose/dismiss action rail',

package/app/components/panels/inspector/TaskExecution.vue

@@ -8,6 +8,8 @@ import {
   isCompanionKind,
   containerPhaseLabel,
   dedicatedParkView,
+  REDIRECT_PARK_PRESENTATION,
+  type RedirectParkView,
 } from '~/utils/pipelineRender'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentFailureHistory from '~/components/board/AgentFailureHistory.vue'
@@ -184,15 +186,28 @@ function openStep(i: number) {
   if (instance.value) ui.openStepDetail(instance.value.id, i)
 }
 
-// Open the implementation-fork decision window for a coder step parked awaiting a choice.
-function openForkFor(i: number) {
-  if (instance.value) ui.openForkDecision(instance.value.id, i)
+/**
+ * The window-owned park holding a step, or null. `input-gate` is filtered out because it has no
+ * window: it is answered by the inline notice this list renders above itself, so offering a
+ * button here would send a human to an overlay that does not exist.
+ */
+function redirectPark(step: PipelineStep): RedirectParkView | null {
+  const park = dedicatedParkView(step, instance.value)
+  return park && park !== 'input-gate' ? park : null
+}
+
+/**
+ * Open the window that resolves a park. A `Record` over the vocabulary, so a park added to it
+ * fails to compile until it names its opener rather than rendering a button that does nothing.
+ */
+const PARK_OPENERS: Record<RedirectParkView, (instanceId: string, stepIndex: number) => void> = {
+  'follow-ups': (id, idx) => ui.openFollowUps(id, idx),
+  'fork-decision': (id, idx) => ui.openForkDecision(id, idx),
+  'binary-candidates': (id, idx) => ui.openBinaryCandidates(id, idx),
 }
 
-// Open the follow-up triage window for a coder step parked on undecided follow-up items
-// (its dedicated chip — the generic approve resolver refuses this park server-side).
-function openFollowUpsFor(i: number) {
-  if (instance.value) ui.openFollowUps(instance.value.id, i)
+function openParkFor(park: RedirectParkView, i: number) {
+  if (instance.value) PARK_OPENERS[park](instance.value.id, i)
 }
 
 // Open the PR deep-review findings-selection window for a pr-reviewer step parked awaiting
@@ -471,38 +486,23 @@ async function mergePr() {
             >
               {{ t('inspector.execution.decide') }}
             </UButton>
-            <!-- A coder step parked on the implementation-fork decision: pick an approach
-                 (or enter a custom one) in the dedicated window, not a plain approval. -->
-            <UButton
-              v-else-if="
-                s.approval &&
-                s.approval.status === 'pending' &&
-                dedicatedParkView(s, instance) === 'fork-decision'
-              "
-              color="primary"
-              variant="soft"
-              size="xs"
-              icon="i-lucide-git-fork"
-              @click="openForkFor(i)"
-            >
-              {{ t('inspector.execution.chooseApproach') }}
-            </UButton>
-            <!-- A coder step parked on undecided follow-up items: triage them (file /
-                 send back / answer / dismiss) in the dedicated window, not a plain
-                 approval — the generic approve resolver refuses this park. -->
+            <!-- A step parked on something a dedicated WINDOW answers: the implementation-fork
+                 choice, undecided follow-up items, or a candidate comparison. None of them is a
+                 plain approval (the generic resolver refuses all three server-side), and all
+                 three present the same way here: one button into the window that can resolve
+                 it. Driven by the shared per-park table rather than a branch each, because a
+                 branch each is how the candidate park shipped with no button at all. -->
             <UButton
-              v-else-if="
-                s.approval &&
-                s.approval.status === 'pending' &&
-                dedicatedParkView(s, instance) === 'follow-ups'
-              "
+              v-else-if="s.approval && s.approval.status === 'pending' && redirectPark(s)"
               color="primary"
               variant="soft"
               size="xs"
-              icon="i-lucide-compass"
-              @click="openFollowUpsFor(i)"
+              :icon="REDIRECT_PARK_PRESENTATION[redirectPark(s)!].icon"
+              :data-park="redirectPark(s)"
+              data-testid="dedicated-park-open"
+              @click="openParkFor(redirectPark(s)!, i)"
             >
-              {{ t('inspector.execution.triageFollowUps') }}
+              {{ t(REDIRECT_PARK_PRESENTATION[redirectPark(s)!].railActionKey) }}
             </UButton>
             <!-- A pr-reviewer step parked awaiting a finding selection: open the dedicated
                  findings-selection window, not the generic approval gate. -->

package/app/components/pipeline/BinaryOutputStepPicker.logic.spec.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'vitest'
-import { parseMediaTypeRequirement, sameFormats } from './BinaryOutputStepPicker.logic'
+import { MAX_BINARY_PIXEL_EXTENT } from '@cat-factory/contracts'
+import {
+  formatExtent,
+  formatReferenceImages,
+  generationControlOffer,
+  parseExtent,
+  parseMediaTypeRequirement,
+  parseReferenceImages,
+  sameFormats,
+} from './BinaryOutputStepPicker.logic'
 
 describe('parseMediaTypeRequirement', () => {
   it('stores the reduction the backend compares against, not what was typed', () => {
@@ -56,3 +65,112 @@ describe('sameFormats', () => {
     expect(sameFormats(['a/b', 'c/d'], ['a/b', 'c/d'])).toBe(true)
   })
 })
+
+describe('parseReferenceImages', () => {
+  it('reads the role, the location and the optional service off each line', () => {
+    const { usable, unusable } = parseReferenceImages(
+      ['subject|assets/hero.png|asset-store', 'style|https://cdn.example/palette.png'].join('\n'),
+    )
+    expect(usable).toEqual([
+      { role: 'subject', location: 'assets/hero.png', service: 'asset-store' },
+      { role: 'style', location: 'https://cdn.example/palette.png' },
+    ])
+    expect(unusable).toEqual([])
+  })
+
+  // A reference someone typed and the step does not carry is a generation that silently ignores
+  // it, which is the "absent reads as fine" failure the rest of this surface exists to avoid.
+  it('reports a refused line rather than dropping it', () => {
+    const { usable, unusable } = parseReferenceImages(
+      ['mood|assets/hero.png', 'subject|', 'subject|assets/ok.png'].join('\n'),
+    )
+    expect(usable.map((ref) => ref.location)).toEqual(['assets/ok.png'])
+    expect(unusable).toEqual(['mood|assets/hero.png', 'subject|'])
+  })
+
+  it('round-trips through the text the field shows', () => {
+    const text = 'base|assets/hero.png|asset-store'
+    expect(formatReferenceImages(parseReferenceImages(text).usable)).toBe(text)
+  })
+})
+
+describe('parseExtent', () => {
+  it('accepts exactly what the save boundary accepts', () => {
+    expect(parseExtent(' 96 ')).toBe(96)
+    expect(parseExtent(String(MAX_BINARY_PIXEL_EXTENT))).toBe(MAX_BINARY_PIXEL_EXTENT)
+  })
+
+  it('refuses everything the schema would refuse, so a typed size is a saveable one', () => {
+    // Including ZERO, which is the one that mattered: an unset half written as 0 stored a config
+    // the schema rejects, so the step became unsaveable behind an opaque validation error and the
+    // untouched field rendered "0" back at whoever had not touched it.
+    expect(parseExtent('0')).toBeNull()
+    expect(parseExtent('-8')).toBeNull()
+    expect(parseExtent('96.5')).toBeNull()
+    expect(parseExtent('wide')).toBeNull()
+    expect(parseExtent(String(MAX_BINARY_PIXEL_EXTENT + 1))).toBeNull()
+  })
+
+  it('reads a blank field as nothing typed', () => {
+    expect(parseExtent('')).toBeNull()
+    expect(parseExtent('   ')).toBeNull()
+    // And the round trip holds: what a stored size renders as is what parses back to it.
+    expect(parseExtent(formatExtent(96))).toBe(96)
+    expect(formatExtent(undefined)).toBe('')
+  })
+})
+
+describe('generationControlOffer', () => {
+  const declaring = (...capabilities: string[]) => ({ capabilities }) as never
+
+  it('offers everything while a selected integration has declared nothing', () => {
+    // An integration that pinned nothing down is not a denial: hiding a control would be a claim
+    // about a vendor's API that nobody established. The advisory line says it is unconfirmed.
+    const offers = generationControlOffer([declaring('seed'), declaring()], undefined)
+    expect(offers('seed')).toBe(true)
+    expect(offers('tileable')).toBe(true)
+  })
+
+  it('offers everything when nothing is selected yet', () => {
+    expect(generationControlOffer([], undefined)('upscale')).toBe(true)
+  })
+
+  it('hides a control once every selection has declared and none has the capability', () => {
+    const offers = generationControlOffer([declaring('seed'), declaring('aspect-ratio')], undefined)
+    expect(offers('seed')).toBe(true)
+    expect(offers('aspect-ratio')).toBe(true)
+    expect(offers('tileable')).toBe(false)
+  })
+
+  // The regression this pins. Changing the selection does not clear options authored against the
+  // old one, so a stored option whose capability nothing declares still REFUSES the run at
+  // admission. Hiding its control leaves the reader an error saying to remove an option and no
+  // control that removes it: a step that cannot be run and cannot be fixed from the surface that
+  // configures it.
+  it('keeps offering a control whose option is already SET, whatever the selection declares', () => {
+    const selection = [declaring('seed')]
+    expect(generationControlOffer(selection, {})('tileable')).toBe(false)
+    expect(generationControlOffer(selection, { tileable: true })('tileable')).toBe(true)
+  })
+
+  it('keeps the control for every option shape that carries a requirement', () => {
+    const selection = [declaring('seed')]
+    // Each of these is stored differently (a flag, a number that may be zero, a list, a mode), and
+    // the requirement is derived from the same helper admission uses rather than re-read here.
+    const offers = generationControlOffer(selection, {
+      seed: 0,
+      aspectRatio: '16:9',
+      negativePrompt: 'blurry',
+      edit: { mode: 'mask' },
+      referenceImages: [{ role: 'subject', location: 'assets/hero.png' }],
+    } as never)
+    for (const capability of [
+      'aspect-ratio',
+      'negative-prompt',
+      'mask-edit',
+      'reference-image',
+    ] as const) {
+      expect(offers(capability)).toBe(true)
+    }
+  })
+})

package/app/components/pipeline/BinaryOutputStepPicker.logic.ts

@@ -1,4 +1,13 @@
-import { mediaTypeSchema, normalizeMediaType } from '@cat-factory/contracts'
+import {
+  binaryReferenceImageSchema,
+  MAX_BINARY_PIXEL_EXTENT,
+  mediaTypeSchema,
+  normalizeMediaType,
+  requiredBinaryCapabilities,
+  type BinaryGenerationOptions,
+  type BinaryGeneratorCapability,
+  type BinaryReferenceImage,
+} from '@cat-factory/contracts'
 import * as v from 'valibot'
 
 // The pure half of BinaryOutputStepPicker: reading a free-text FORMAT requirement, and telling
@@ -53,3 +62,108 @@ export function sameFormats(
 ): boolean {
   return (a ?? []).join(',') === (b ?? []).join(',')
 }
+
+/** A parsed reference-image list: what the step will carry, and what was refused on the way in. */
+export interface ParsedReferenceImages {
+  /** Well-formed entries, in the order typed: exactly what gets stored. */
+  usable: BinaryReferenceImage[]
+  /** Lines that are not `role|location[|service]`, kept VERBATIM so the warning can quote them. */
+  unusable: string[]
+}
+
+/**
+ * Read a reference-image list from the one-per-line `role|location[|service]` text the builder
+ * accepts.
+ *
+ * Free TEXT rather than a picker, for the reason the format requirement beside it is: what a
+ * reference points at is an object in the org's own storage or a URL, and neither is a set the
+ * platform can enumerate. The three fields are positional because the shape is small and a
+ * three-input row per reference would dominate a step row that is already dense; the ROLE comes
+ * first because it is the constrained field, so a typo lands on the half the parser can name.
+ *
+ * A refused line is REPORTED, never quietly dropped, exactly as a refused format is: a reference
+ * someone typed and the step does not carry is a generation that silently ignores it.
+ */
+export function parseReferenceImages(text: string): ParsedReferenceImages {
+  const usable: BinaryReferenceImage[] = []
+  const unusable: string[] = []
+  for (const line of text
+    .split('\n')
+    .map((part) => part.trim())
+    .filter(Boolean)) {
+    const [role, location, service] = line.split('|').map((part) => part.trim())
+    const parsed = v.safeParse(binaryReferenceImageSchema, {
+      role,
+      location,
+      ...(service ? { service } : {}),
+    })
+    if (parsed.success) usable.push(parsed.output)
+    else unusable.push(line)
+  }
+  return { usable, unusable }
+}
+
+/** Render a stored reference list back into the text the field shows. */
+export function formatReferenceImages(
+  references: readonly BinaryReferenceImage[] | undefined,
+): string {
+  return (references ?? [])
+    .map((ref) => [ref.role, ref.location, ref.service].filter(Boolean).join('|'))
+    .join('\n')
+}
+
+/**
+ * Read one half of an exact output size out of the field, or null when what is typed is not a
+ * pixel extent the step could carry.
+ *
+ * Held to the SAME bounds the schema holds it to, {@link MAX_BINARY_PIXEL_EXTENT} imported rather
+ * than repeated, so a number this accepts is one the save accepts. Blank is null like anything
+ * else here: the caller's job is to tell "nothing typed yet" from "typed and unusable", and it has
+ * the raw text to do it with.
+ */
+export function parseExtent(raw: string): number | null {
+  const text = raw.trim()
+  if (!text) return null
+  const value = Number(text)
+  if (!Number.isInteger(value) || value < 1 || value > MAX_BINARY_PIXEL_EXTENT) return null
+  return value
+}
+
+/** Render a stored extent back into the text its field shows; absent is an empty field. */
+export function formatExtent(value: number | undefined): string {
+  return value === undefined ? '' : String(value)
+}
+
+/**
+ * Build the predicate that decides whether the control for a generation option is OFFERED, given
+ * what the step's selected integrations declare and what its stored options already require.
+ *
+ * Three rules, and the third is the one that is easy to miss:
+ *
+ *  - An integration that declares NOTHING pins nothing down, so while one is selected (or nothing
+ *    is) every control stays offered and the advisory line says the support is unconfirmed.
+ *    Hiding one would be a claim about a vendor's API that nobody established.
+ *  - Otherwise a control is offered exactly when something selected declares its capability.
+ *  - And a control whose option is ALREADY SET stays offered whatever the selection says. Changing
+ *    the selection does not clear options authored against the old one, so hiding the control on
+ *    the way past strands a stored requirement that refuses the run at admission, under an error
+ *    telling the reader to remove an option whose only control has just disappeared. The platform
+ *    will not silently drop an authored requirement, so the person who stated it needs the control
+ *    that withdraws it. This is the SPA's standing rule that a hidden field must leave behind
+ *    exactly the default it would have shown.
+ *
+ * Returned as a closure over ONE pass across the selection rather than recomputed per capability:
+ * the template asks it once per control, and the sets are the same for all of them.
+ */
+export function generationControlOffer(
+  selected: readonly { capabilities?: readonly BinaryGeneratorCapability[] }[],
+  options: BinaryGenerationOptions | undefined,
+): (capability: BinaryGeneratorCapability) => boolean {
+  const declared = new Set(selected.flatMap((generator) => generator.capabilities ?? []))
+  const undeclared =
+    selected.length === 0 || selected.some((g) => (g.capabilities ?? []).length === 0)
+  // The same derivation admission judges the step by, imported rather than re-implemented, so the
+  // control a person is offered and the requirement the run is refused for cannot disagree.
+  const required = new Set(requiredBinaryCapabilities(options))
+  return (capability) => undeclared || declared.has(capability) || required.has(capability)
+}