@cat-factory/app 0.206.0 → 0.208.0

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { parseMediaTypeRequirement, sameFormats } from './BinaryOutputStepPicker.logic'
+
+describe('parseMediaTypeRequirement', () => {
+  it('stores the reduction the backend compares against, not what was typed', () => {
+    // The field is forgiving on the way in and exact on the way out. A locally-lowercased copy
+    // would store a format that matches nothing and then reads everywhere as one that was simply
+    // never emitted — indistinguishable from a real delivery failure.
+    expect(parseMediaTypeRequirement(' Model/GLTF-Binary , image/PNG ').usable).toEqual([
+      'model/gltf-binary',
+      'image/png',
+    ])
+  })
+
+  it('drops a parameter, because a requirement is a format and not one request encoding', () => {
+    expect(parseMediaTypeRequirement('model/gltf-binary; charset=binary').usable).toEqual([
+      'model/gltf-binary',
+    ])
+  })
+
+  it('NAMES what it refused rather than quietly shortening the requirement', () => {
+    // A requirement someone typed and the step does not carry is the "absent reads as fine"
+    // failure the rest of this surface is built to avoid, so the entry survives verbatim for the
+    // warning to quote.
+    const parsed = parseMediaTypeRequirement('gltf, model/obj, ')
+    expect(parsed.usable).toEqual(['model/obj'])
+    expect(parsed.unusable).toEqual(['gltf'])
+  })
+
+  it('deduplicates what two spellings reduce to, keeping first-stated order', () => {
+    const parsed = parseMediaTypeRequirement('model/obj, MODEL/OBJ, model/gltf-binary')
+    expect(parsed.usable).toEqual(['model/obj', 'model/gltf-binary'])
+  })
+
+  it('maps no synonyms, so a near neighbour stays a separate requirement', () => {
+    // `model/obj` and `application/x-tgif` are the same file. Collapsing them would make the
+    // admission check accept a GLB where an OBJ was required — the failure it exists to prevent.
+    const parsed = parseMediaTypeRequirement('model/obj, application/x-tgif')
+    expect(parsed.usable).toEqual(['model/obj', 'application/x-tgif'])
+  })
+
+  it('reads an empty requirement as no requirement', () => {
+    expect(parseMediaTypeRequirement('  ,  ')).toEqual({ usable: [], unusable: [] })
+  })
+})
+
+describe('sameFormats', () => {
+  it('treats an absent list and an empty one as the same write', () => {
+    // Clearing the field stores `undefined`, so the two spellings of "no requirement" must not
+    // read as a change that came from elsewhere.
+    expect(sameFormats(undefined, [])).toBe(true)
+  })
+
+  it('is order-sensitive, because the field writes back exactly what it read', () => {
+    expect(sameFormats(['a/b', 'c/d'], ['c/d', 'a/b'])).toBe(false)
+    expect(sameFormats(['a/b', 'c/d'], ['a/b', 'c/d'])).toBe(true)
+  })
+})

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

@@ -0,0 +1,55 @@
+import { mediaTypeSchema, normalizeMediaType } from '@cat-factory/contracts'
+import * as v from 'valibot'
+
+// The pure half of BinaryOutputStepPicker: reading a free-text FORMAT requirement, and telling
+// this field's own write apart from one that landed underneath it. Extracted for the reason every
+// `*.logic.ts` here is — a decision worth a test should not need a mounted component to reach.
+
+/** A parsed format requirement: what the step will carry, and what was refused on the way in. */
+export interface ParsedMediaTypeRequirement {
+  /** Normalised, deduplicated, order-preserving — exactly what gets stored. */
+  usable: string[]
+  /** Entries that are not a `type/subtype` at all, kept VERBATIM so the warning can quote them. */
+  unusable: string[]
+}
+
+/**
+ * Read a comma-separated format requirement the way the field accepts it and the way the backend
+ * will hold it.
+ *
+ * Forgiving on the way IN, exact on the way out, and both halves are the backend's own rules
+ * imported rather than re-implemented: `normalizeMediaType` is the same reduction the comparison
+ * uses at both ends (a divergent local lowercasing would store a format that matches nothing and
+ * reads everywhere as one that was simply never emitted), and `mediaTypeSchema` is what the save
+ * boundary holds this to — so what is refused here is exactly what would come back as a 422 one
+ * round trip later.
+ *
+ * A refused entry is REPORTED, never quietly dropped: a requirement someone typed and the step
+ * does not carry is the "absent reads as fine" failure the rest of this surface exists to avoid.
+ */
+export function parseMediaTypeRequirement(text: string): ParsedMediaTypeRequirement {
+  const usable: string[] = []
+  const unusable: string[] = []
+  for (const entry of text
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)) {
+    const normalized = normalizeMediaType(entry)
+    if (normalized && v.safeParse(mediaTypeSchema, normalized).success) usable.push(normalized)
+    else unusable.push(entry)
+  }
+  return { usable: [...new Set(usable)], unusable }
+}
+
+/**
+ * Whether two stored format lists are the same write.
+ *
+ * Order-sensitive on purpose: the field writes back what it read, so a differing order means the
+ * value came from somewhere else, which is precisely what the caller is asking about.
+ */
+export function sameFormats(
+  a: readonly string[] | undefined,
+  b: readonly string[] | undefined,
+): boolean {
+  return (a ?? []).join(',') === (b ?? []).join(',')
+}

package/app/components/pipeline/BinaryOutputStepPicker.vue

@@ -19,14 +19,16 @@
 // ride the workspace snapshot (`binaryGenerators`) rather than a catalog read. Both halves are
 // offered here because a step needs both to work, and only this surface can tell a human that the
 // content types it promises to deliver are not covered by anything it selected.
-import { computed } from 'vue'
+import { computed, ref, watch } from 'vue'
 import {
   ASSET_STORAGE_CAPABILITY,
   GENERATION_CONTEXT_CAPABILITY,
+  isBinaryModality,
   type BinaryModality,
   type BinaryOutputConfig,
 } from '@cat-factory/contracts'
 import { binaryOutputPickIssues, type BinaryOutputPickIssue } from '~/utils/binaryOutput'
+import { parseMediaTypeRequirement, sameFormats } from './BinaryOutputStepPicker.logic'
 
 const props = defineProps<{ index: number }>()
 
@@ -44,12 +46,42 @@ const MODALITY_LABELS: Record<BinaryModality, () => string> = {
   image: () => t('pipeline.builder.binaryOutputModality.image'),
   audio: () => t('pipeline.builder.binaryOutputModality.audio'),
   video: () => t('pipeline.builder.binaryOutputModality.video'),
-  '3d': () => t('pipeline.builder.binaryOutputModality.3d'),
+  '3d-model': () => t('pipeline.builder.binaryOutputModality.3d-model'),
+  '3d-scene': () => t('pipeline.builder.binaryOutputModality.3d-scene'),
   document: () => t('pipeline.builder.binaryOutputModality.document'),
 }
-const MODALITY_ORDER: BinaryModality[] = ['image', 'audio', 'video', '3d', 'document']
+const MODALITY_ORDER: BinaryModality[] = [
+  'image',
+  'audio',
+  'video',
+  '3d-model',
+  '3d-scene',
+  'document',
+]
+/**
+ * A content type in the reader's language, INCLUDING one this build no longer defines.
+ *
+ * The `Record` above is exhaustive over the union, so the lookup looks total — and is not, because
+ * `modalities` is PERSISTED: a step saved under an earlier vocabulary carries a member that has
+ * since been retired (`3d` did exactly that when it split into `3d-model` and `3d-scene`). Such a
+ * value is by construction uncovered by every registered integration, so it lands in the
+ * `modality_uncovered` warning below — the one line whose job is to tell someone what to re-pick —
+ * and a bare `MODALITY_LABELS[modality]()` there is a `TypeError` that takes the whole builder
+ * down, on exactly the surface the fix has to be made on.
+ *
+ * The guard is `isBinaryModality` (contracts, derived from the picklist itself) rather than an
+ * optional call on the `Record`, so the narrowing says WHY it is needed and a member added to the
+ * vocabulary is known here without anyone remembering to widen anything.
+ *
+ * The retired value is NAMED rather than silently dropped or guessed at a current member: nothing
+ * here knows which one was meant, and a modality quietly missing from the list reads as a step
+ * that never required it. This is the standing "absent is not zero" rule at the one place the
+ * typed-key check cannot reach — the key is static, but the LOOKUP is a runtime value.
+ */
 function modalityLabel(modality: BinaryModality): string {
-  return MODALITY_LABELS[modality]()
+  return isBinaryModality(modality)
+    ? MODALITY_LABELS[modality]()
+    : t('pipeline.builder.binaryOutputModalityRetired', { modality: String(modality) })
 }
 
 const config = computed(() => pipelines.draftBinaryOutput(props.index))
@@ -143,6 +175,64 @@ function setGenerators(ids: string[]) {
 function setModalities(modalities: BinaryModality[]) {
   patch({ modalities })
 }
+
+/**
+ * The FORMAT requirement is free text, not a pick from the selection, and that is deliberate: the
+ * whole reason a step states a format is that the selected integrations might not cover it, and a
+ * picker offering only what they declare could never express the requirement whose violation this
+ * feature exists to catch. What the selection declares is offered as a HINT below instead.
+ *
+ * Held in a local ref rather than bound straight to the config so a half-typed `model/` is not
+ * parsed on every keystroke, and so the normalisation the field applies is VISIBLE — the text
+ * snaps back to what was stored.
+ */
+const mediaTypeText = ref((config.value?.mediaTypes ?? []).join(', '))
+
+/**
+ * Entries that are not a `type/subtype` at all, named rather than silently dropped — a
+ * requirement someone typed and the step does not carry is exactly the "absent reads as fine"
+ * failure the rest of this surface is built to avoid.
+ */
+const unusableMediaTypes = ref<string[]>([])
+
+/**
+ * What this field last wrote, so the watch below can tell its OWN patch from a config that
+ * changed underneath it.
+ */
+let lastWritten: string[] | undefined = config.value?.mediaTypes
+
+watch(
+  () => config.value?.mediaTypes,
+  (mediaTypes) => {
+    mediaTypeText.value = (mediaTypes ?? []).join(', ')
+    // The rejected entries belong to the TEXT that was typed, so they outlive this field's own
+    // patch — clearing them on every config change would erase the warning in the same tick it
+    // was raised, since accepting `image/png` out of `foo, image/png` is itself a patch. Any
+    // OTHER route to a new value (the picker rebound to another step, the draft reloaded,
+    // storage cleared and the bag dropped) is describing text that no longer exists, and a
+    // warning about entries nobody can see is the same "absent reads as fine" failure pointed
+    // the other way.
+    if (!sameFormats(mediaTypes, lastWritten)) unusableMediaTypes.value = []
+    lastWritten = mediaTypes
+  },
+)
+
+function setMediaTypes(text: string) {
+  const { usable, unusable } = parseMediaTypeRequirement(text)
+  unusableMediaTypes.value = unusable
+  mediaTypeText.value = usable.join(', ')
+  // Claimed BEFORE the patch, so the watch above reads this write as its own however it is
+  // flushed, and the entries just rejected survive to be rendered.
+  lastWritten = usable.length ? usable : undefined
+  patch({ mediaTypes: lastWritten })
+}
+
+/** What the SELECTED integrations say they emit — the discoverable half of the free-text field. */
+const declaredFormats = computed(() => {
+  const byId = new Map(agents.binaryGenerators.map((generator) => [generator.id, generator]))
+  const selected = (config.value?.generatorIds ?? []).flatMap((id) => byId.get(id) ?? [])
+  return [...new Set(selected.flatMap((generator) => generator.mediaTypes ?? []))]
+})
 </script>
 
 <template>
@@ -216,6 +306,33 @@ function setModalities(modalities: BinaryModality[]) {
       />
     </div>
 
+    <!-- The FORMAT requirement, one notch finer than the content types above it and shown right
+         under them. Both tiers: like the rest of this picker it is not an override of a default —
+         a format nobody stated is a format the run does not check. -->
+    <div v-if="config?.storageServiceId" class="flex items-center gap-2">
+      <span class="text-[10px] text-slate-500">{{
+        t('pipeline.builder.binaryOutputMediaTypes')
+      }}</span>
+      <UInput
+        class="w-56"
+        :model-value="mediaTypeText"
+        size="xs"
+        :placeholder="t('pipeline.builder.binaryOutputMediaTypesPlaceholder')"
+        data-testid="binary-output-media-type-input"
+        @update:model-value="mediaTypeText = String($event)"
+        @change="setMediaTypes(mediaTypeText)"
+      />
+    </div>
+    <p
+      v-if="config?.storageServiceId && declaredFormats.length"
+      class="ms-1 text-[10px] text-slate-500"
+      data-testid="binary-output-declared-formats"
+    >
+      {{
+        t('pipeline.builder.binaryOutputDeclaredFormats', { formats: declaredFormats.join(', ') })
+      }}
+    </p>
+
     <!-- Every refusal this step would hit, named where it is fixable. Each is its own line
          with its own remedy: an unreachable catalog is not an empty one, a lost service is not
          an untagged one, and a lost CONTEXT service is not a lost storage target. -->
@@ -280,5 +397,42 @@ function setModalities(modalities: BinaryModality[]) {
         })
       }}
     </p>
+    <p
+      v-if="has('media_type_uncovered')"
+      class="text-[10px] text-amber-400"
+      data-testid="binary-output-media-type-uncovered"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUncovered', {
+          formats: pick.uncoveredMediaTypes.join(', '),
+        })
+      }}
+    </p>
+    <!-- ADVISORY, and styled apart from every line above it: the step starts. The backend admits
+         a format requirement it could not judge, because a generator that declares no formats has
+         said only that its formats are unknown — and a surface that dressed that up as a refusal
+         would send someone editing a selection that is fine. -->
+    <p
+      v-if="has('media_type_unverifiable')"
+      class="text-[10px] text-slate-500"
+      data-testid="binary-output-media-type-unverifiable"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUnverifiable', {
+          formats: pick.unverifiableMediaTypes.join(', '),
+        })
+      }}
+    </p>
+    <p
+      v-if="unusableMediaTypes.length"
+      class="text-[10px] text-amber-400"
+      data-testid="binary-output-media-type-unusable"
+    >
+      {{
+        t('pipeline.builder.binaryOutputMediaTypeUnusable', {
+          entries: unusableMediaTypes.join(', '),
+        })
+      }}
+    </p>
   </div>
 </template>

package/app/components/pipeline/PipelineBuilder.vue

@@ -455,7 +455,10 @@ async function clone(p: Pipeline) {
            columns filling the full height. -->
       <div class="grid grid-cols-1 gap-4 lg:h-full lg:grid-cols-3">
         <!-- agent palette -->
-        <div class="flex flex-col lg:min-h-0 lg:overflow-hidden">
+        <div
+          class="flex flex-col lg:min-h-0 lg:overflow-hidden"
+          data-testid="pipeline-builder-palette"
+        >
           <div class="mb-2 flex shrink-0 items-center justify-between gap-2">
             <h3 class="text-xs font-semibold uppercase tracking-wide text-slate-400">
               {{ t('pipeline.builder.agentPalette') }}
@@ -476,7 +479,10 @@ async function clone(p: Pipeline) {
         </div>
 
         <!-- draft chain -->
-        <div class="flex flex-col lg:min-h-0 lg:overflow-hidden">
+        <div
+          class="flex flex-col lg:min-h-0 lg:overflow-hidden"
+          data-testid="pipeline-builder-draft"
+        >
           <div class="mb-2 flex items-center justify-between gap-2">
             <h3 class="text-xs font-semibold uppercase tracking-wide text-slate-400">
               {{ t('pipeline.builder.pipeline') }}
@@ -1294,6 +1300,7 @@ async function clone(p: Pipeline) {
           icon="i-lucide-save"
           size="sm"
           :disabled="pipelines.draft.length === 0 || stepsDisallowedByPurpose.length > 0"
+          data-testid="pipeline-builder-save"
           @click="save"
         >
           {{ pipelines.editingId ? t('pipeline.builder.update') : t('pipeline.builder.save') }}

package/app/components/tutorial/TutorialPrompt.vue

@@ -1,13 +1,15 @@
 <script setup lang="ts">
 // The tutorial launch prompt: asks once on first launch whether the user wants a guided tour,
-// listing the tours this board can actually run right now (first-party + consumer, resolved
-// against the same gates the nav uses), so it grows with the catalog rather than hard-coding
-// tours.
+// listing the first-run tours this board can actually run right now (first-party + consumer,
+// resolved against the same gates the nav uses), so it grows with the catalog rather than
+// hard-coding tours.
 //
-// It is the OFFER, not the library: the full list — including the walkthroughs this board
-// can't run yet and what would unlock them — is `TutorialCatalogue.vue`, one button away in
-// the footer and permanently reachable from the sidebar's Help section. That split is why
-// this stays a short, answerable question instead of growing into a browsing surface.
+// It is the OFFER, not the library: the full list — the platform walkthroughs that are kept out
+// of this question (`offeredAtLaunch: false`), plus the ones this board can't run yet and what
+// would unlock them — is `TutorialCatalogue.vue`, one button away in the footer and permanently
+// reachable from the sidebar's Help section. That split is why this stays a short, answerable
+// question instead of growing into a browsing surface, and why it reads `offered` rather than
+// every startable tour.
 //
 // The decision semantics live in the store: starting a tour or "No thanks" is SAVED (the
 // prompt never auto-opens again), while closing without answering defers to next launch.
@@ -15,7 +17,7 @@ import { TUTORIAL_ACTION_KEYS } from '~/utils/tutorial'
 
 const { t } = useI18n()
 const tutorial = useTutorialStore()
-const { tours } = useTutorialTours()
+const { offered } = useTutorialTours()
 // Start / Resume / Repeat is decided in one place for both surfaces — see `useTutorialLaunch`.
 const { actionFor, launch } = useTutorialLaunch()
 
@@ -41,7 +43,7 @@ const undecided = computed(() => tutorial.decision === null)
         <p class="text-sm text-slate-300">{{ t('tutorial.prompt.intro') }}</p>
         <ul class="space-y-2">
           <li
-            v-for="tour in tours"
+            v-for="tour in offered"
             :key="tour.id"
             class="flex items-center gap-3 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
           >
@@ -75,9 +77,15 @@ const undecided = computed(() => tutorial.decision === null)
             </UButton>
           </li>
         </ul>
-        <!-- Every tour gated away (e.g. a viewer on a write-only catalog): say so rather
-             than showing an unexplained empty list. -->
-        <p v-if="tours.length === 0" class="text-sm text-slate-400">
+        <!-- Every first-run tour gated away: say so rather than showing an unexplained empty
+             list. The copy points at the catalogue rather than declaring the deployment empty,
+             because with the split this state no longer implies there is nothing to take: what
+             is missing is the FIRST-RUN arc, and the catalogue-only walkthroughs gate on a
+             permission that this user may well hold. (Unreachable with the built-in catalog
+             alone, where `board-basics` requires nothing at all — but a consumer's own slot
+             filter can produce it, and "no tours exist" would be the wrong thing to say then.)
+             The footer's browse button is the way on, so it stays. -->
+        <p v-if="offered.length === 0" class="text-sm text-slate-400">
           {{ t('tutorial.prompt.empty') }}
         </p>
       </div>

package/app/composables/useTutorialTours.ts

@@ -1,7 +1,7 @@
 import { computed } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
 import { createSharedComposables } from '@modular-vue/vue'
-import { resolveTourCatalogue } from '~/utils/tutorial'
+import { isLaunchOffer, resolveTourCatalogue } from '~/utils/tutorial'
 import type { TutorialCatalogueEntry, TutorialTour } from '~/utils/tutorial'
 import type { AppDeps } from '~/modular/registry'
 import type { AppSlots } from '~/modular/nav-contributions'
@@ -21,10 +21,13 @@ const { useOptional } = createSharedComposables<AppDeps>()
 /**
  * The tutorial catalog as this board sees it, resolved ONCE for every surface that reads it.
  *
- * Two views over one resolution, and the difference between them is the point:
+ * Three views over one resolution, and the differences between them are the point:
  *
- *  - `tours` — what can be started right now. The launch prompt offers these, and the overlay
- *    resolves a running tour from them, exactly as when this gating lived in `navSlotFilter`.
+ *  - `tours` — what can be started right now. The overlay resolves a running tour from these,
+ *    exactly as when this gating lived in `navSlotFilter`.
+ *  - `offered` — the subset the launch prompt asks about: startable AND part of the first-run
+ *    arc (see `TutorialTour.offeredAtLaunch`). The prompt is one answerable question, so it
+ *    stays the delivery loop even as the catalog grows to cover the platform surfaces.
  *  - `catalogue` — EVERY tour this deployment ships, each carrying why it is or isn't
  *    available. The catalogue surface needs the unavailable ones: a list that quietly omits
  *    four of six tours is indistinguishable from a deployment that ships two, and the user it
@@ -42,5 +45,6 @@ export function useTutorialTours() {
   const tours = computed<TutorialTour[]>(() =>
     catalogue.value.filter((entry) => entry.availability === 'ready').map((entry) => entry.tour),
   )
-  return { tours, catalogue }
+  const offered = computed<TutorialTour[]>(() => tours.value.filter(isLaunchOffer))
+  return { tours, offered, catalogue }
 }

package/app/docs/architecture.md

@@ -1,4 +1,4 @@
-# Frontend architecture — state & data flow
+# Frontend architecture: state & data flow
 
 How the SPA stays in sync with the backend. The app is a **thin client**: it holds
 no business logic, calls the Worker for every mutation, and hydrates its stores
@@ -14,11 +14,11 @@ REST (useApi)  ─────────────▶  Worker  ────
 stores (Pinia)  ◀── patch ──  useWorkspaceStream  ◀── WebSocket push (events hub)
 ```
 
-- **Read path** — the `workspace` store loads the full snapshot and fans it into
+- **Read path**: the `workspace` store loads the full snapshot and fans it into
   `board`, `pipelines`, `execution`, `spend`, etc.
-- **Write path** — components call `useApi` → Worker; the response (or a pushed
+- **Write path**: components call `useApi` → Worker; the response (or a pushed
   event) patches the relevant store. No optimistic business logic.
-- **Live path** — `useWorkspaceStream` opens one WebSocket to
+- **Live path**: `useWorkspaceStream` opens one WebSocket to
   `GET /workspaces/:ws/events?token=…`, patches `execution` / `agentRuns` /
   `board` as events arrive, and refreshes on reconnect to reconcile anything
   missed.