@cat-factory/app 0.236.1 → 0.237.1

package/app/components/tasks/TaskImportModal.vue

@@ -1,20 +1,26 @@
 <script setup lang="ts">
-// Create a board task from a connected tracker's issue. Pick a container (service
-// frame or module), then use the inline picker below to find an issue (search by
-// title, pick an already-imported one, or paste a URL/key) — choosing one opens the
+// Create a board task from a connected tracker's issue. Use the inline picker to find an issue
+// (search by title, pick an already-imported one, or paste a URL/key): choosing one opens the
 // prefilled add-task form (title seeded, issue staged as linked context) where the
 // user confirms the pipeline / presets before it's created. This is the same picker
 // the add-task form uses for "context issues", so the two behave identically. A
 // pasted parent/epic reference can instead be spawned as a whole linked task group.
+//
+// Where the task lands depends on how the modal was opened, and `useContainerTargets` is the shared
+// answer (`<BugHuntModal>` is the same question from the same frame header). From a service frame's
+// own "create task from issue" button that frame settles the SERVICE, so the modal states it rather
+// than asking; a frame with modules still asks frame-or-which-module, scoped to that frame, because
+// the button never answered that half. Opened standalone (the command bar / the Integrations hub)
+// there is no frame behind it and every container on the board is a candidate.
 import type { TaskSourceKind } from '~/types/domain'
 import type { PendingContext } from '~/composables/useContextLinking'
+import { type AddSourceLabels, addChoicesOf, buildSourceChoices } from '~/utils/sourcePicker'
 import ContextIssuePicker from '~/components/tasks/ContextIssuePicker.vue'
 import IntegrationBackTitle from '~/components/layout/IntegrationBackTitle.vue'
 
 const { t } = useI18n()
 const ui = useUiStore()
 const tasks = useTasksStore()
-const board = useBoardStore()
 const toast = useToast()
 
 const open = computed({
@@ -32,37 +38,42 @@ const source = ref<TaskSourceKind | undefined>(undefined)
 const ref_ = ref('')
 const importing = ref(false)
 
-// When opened from a service frame the modal is the "create a task from an issue"
-// surface; opened standalone it's the general tracker-issue browser/importer.
-const title = computed(() =>
-  ui.taskImport?.containerId ? t('tasks.import.titleCreate') : t('tasks.import.titleBrowse'),
-)
-
 const descriptor = computed(() => (source.value ? tasks.descriptorFor(source.value) : undefined))
 
-// The container (service frame or module) a new task is created in.
-const containerId = ref<string | undefined>(undefined)
+/**
+ * The trackers the "nothing connected yet" state offers, worded per add action off the shared
+ * builder rather than re-deciding `available ? enable : connect` here. `enable` is connected but
+ * toggled off for this workspace, so the user is never told to connect what they already have.
+ */
+const ADD_LABEL: AddSourceLabels<'connect' | 'enable'> = {
+  connect: (label) => t('tasks.import.connectSource', { label }),
+  enable: (label) => t('tasks.import.enableSource', { label }),
+}
+const addableSources = computed(() => addChoicesOf(buildSourceChoices(tasks.sources, source.value)))
 
-// Containers a new task can be created in: every service frame and module on the
-// board. Modules are labelled with their parent frame so the choice is unambiguous.
-const containerItems = computed(() =>
-  board.blocks
-    .filter((b) => b.level === 'frame' || b.level === 'module')
-    .map((b) => ({
-      label:
-        b.level === 'module'
-          ? `${board.getBlock(b.parentId ?? '')?.title ?? '?'} › ${b.title}`
-          : b.title,
-      value: b.id,
-    })),
+// Where the new task lands. `pinned` is re-resolved through the board on every read, so a frame
+// deleted while the modal sat open widens back to the whole board AND drops the selection that
+// pointed at it (`useContainerTargets`).
+const {
+  pinned: pinnedContainer,
+  items: containerItems,
+  containerId,
+  stated: containerStated,
+  reset: resetContainer,
+} = useContainerTargets(() => ui.taskImport?.containerId)
+
+// Which surface this is. Derived from the RESOLVED frame rather than the id the modal was opened
+// with, so the title cannot claim the frame-scoped surface while the body renders the standalone
+// browser: they answer "was this opened from a frame" from one source.
+const title = computed(() =>
+  pinnedContainer.value ? t('tasks.import.titleCreate') : t('tasks.import.titleBrowse'),
 )
+
 watch(open, (isOpen) => {
   if (isOpen) {
     ref_.value = ''
     source.value = ui.taskImport?.source ?? tasks.offeredSources[0]?.source ?? undefined
-    // Opened from a service frame → preselect it as the create-in target; otherwise
-    // fall back to the first container on the board.
-    containerId.value = ui.taskImport?.containerId ?? containerItems.value[0]?.value
+    resetContainer()
     tasks.loadTasks().catch(() => {})
   }
 })
@@ -125,18 +136,14 @@ async function doSpawnEpic() {
         <p class="text-sm text-slate-400">{{ t('tasks.import.connectFirst') }}</p>
         <div class="flex justify-center gap-2">
           <UButton
-            v-for="s in tasks.sources"
-            :key="s.source"
+            v-for="choice in addableSources"
+            :key="choice.source"
             color="primary"
             variant="soft"
-            :icon="s.icon"
-            @click="ui.openTaskConnect(s.source)"
+            :icon="choice.icon"
+            @click="ui.openTaskConnect(choice.source)"
           >
-            {{
-              s.available
-                ? t('tasks.import.enableSource', { label: s.label })
-                : t('tasks.import.connectSource', { label: s.label })
-            }}
+            {{ ADD_LABEL[choice.action](choice.label) }}
           </UButton>
         </div>
       </div>
@@ -148,8 +155,17 @@ async function doSpawnEpic() {
 
       <!-- Main form -->
       <div v-else class="space-y-4">
-        <!-- Where the new task lands (preselected when opened from a service frame). -->
-        <UFormField :label="t('tasks.import.createTasksIn')">
+        <!-- Where the new task lands. Stated when there is one legal target (opened from a service
+             frame that has no modules); otherwise a real choice, scoped to that frame when the
+             modal was opened from one. -->
+        <p v-if="containerStated" class="text-xs text-slate-400">
+          <i18n-t keypath="tasks.import.creatingIn" tag="span" scope="global">
+            <template #container>
+              <span class="font-medium text-slate-200">{{ pinnedContainer!.title }}</span>
+            </template>
+          </i18n-t>
+        </p>
+        <UFormField v-else :label="t('tasks.import.createTasksIn')">
           <USelect
             v-model="containerId"
             :items="containerItems"
@@ -160,7 +176,7 @@ async function doSpawnEpic() {
 
         <!-- Find an issue and create a task from it. Same picker the add-task form
              uses for context issues: search by title, pick an already-imported one,
-             or paste a URL/key — choosing one opens the prefilled add-task form. The
+             or paste a URL/key, and choosing one opens the prefilled add-task form. The
              search is scoped to the chosen container's repo (so a GitHub search stays
              in that service's repo and a pasted URL / bare number resolves there). -->
         <UFormField v-if="containerId" :label="t('tasks.import.searchIssues')">

package/app/composables/useContainerTargets.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import { nextTick, ref } from 'vue'
+import type { Block } from '~/types/domain'
+import { useBoardStore } from '~/stores/board'
+import { useContainerTargets } from '~/composables/useContainerTargets'
+
+/**
+ * Where the frame-header authoring surfaces create. Two properties matter and only one of them is
+ * about the happy path: the frame a surface was opened from narrows the choice to that service
+ * WITHOUT removing its modules as targets, and the answer follows a live board, because the frame
+ * can be deleted (by another member, over the socket) while the surface sits open.
+ */
+const block = (over: Partial<Block> & Pick<Block, 'id' | 'level' | 'title'>): Block =>
+  ({ parentId: null, ...over }) as Block
+
+/** A board with two services, one of which has modules, plus a task (never a container). */
+function seedBoard(): void {
+  useBoardStore().blocks = [
+    block({ id: 'f_auth', level: 'frame', title: 'Auth' }),
+    block({ id: 'm_login', level: 'module', title: 'Login', parentId: 'f_auth' }),
+    block({ id: 'm_tokens', level: 'module', title: 'Tokens', parentId: 'f_auth' }),
+    block({ id: 'f_billing', level: 'frame', title: 'Billing' }),
+    block({ id: 't_1', level: 'task', title: 'A task', parentId: 'f_billing' }),
+  ]
+}
+
+describe('useContainerTargets', () => {
+  it('scopes to the opening frame and its modules, keeping the module as a target', () => {
+    seedBoard()
+    const { items, containerId, stated, pinned, reset } = useContainerTargets(() => 'f_auth')
+    reset()
+    // The button that opened this names the service, so the modules need no parent prefix.
+    expect(items.value).toEqual([
+      { label: 'Auth', value: 'f_auth' },
+      { label: 'Login', value: 'm_login' },
+      { label: 'Tokens', value: 'm_tokens' },
+    ])
+    expect(pinned.value?.id).toBe('f_auth')
+    // A frame with modules did NOT answer frame-or-which-module, so the picker still asks,
+    // preselected to the frame itself.
+    expect(stated.value).toBe(false)
+    expect(containerId.value).toBe('f_auth')
+  })
+
+  it('states the target rather than asking when the opening frame has no modules', () => {
+    seedBoard()
+    const { items, containerId, stated, reset } = useContainerTargets(() => 'f_billing')
+    reset()
+    expect(items.value).toEqual([{ label: 'Billing', value: 'f_billing' }])
+    expect(stated.value).toBe(true)
+    expect(containerId.value).toBe('f_billing')
+  })
+
+  it('offers every container on the board, parent-labelled, when opened standalone', () => {
+    seedBoard()
+    const { items, stated, reset } = useContainerTargets(() => null)
+    reset()
+    expect(items.value).toEqual([
+      { label: 'Auth', value: 'f_auth' },
+      { label: 'Auth › Login', value: 'm_login' },
+      { label: 'Auth › Tokens', value: 'm_tokens' },
+      { label: 'Billing', value: 'f_billing' },
+    ])
+    expect(stated.value).toBe(false)
+  })
+
+  // The finding this composable exists for: an id is not evidence the block is still there, so the
+  // surface widens back to the whole board AND re-derives its selection. Leaving the selection
+  // behind is the silent half: the picker renders unselected while the search under it stays scoped
+  // to the deleted frame and the create lands on an id the board no longer has.
+  it('widens and re-selects when the opening frame is deleted underneath it', async () => {
+    seedBoard()
+    const openedFrom = ref<string | null>('f_auth')
+    const { items, containerId, stated, pinned } = useContainerTargets(() => openedFrom.value)
+    containerId.value = 'm_login'
+
+    const board = useBoardStore()
+    board.blocks = board.blocks.filter((b) => !['f_auth', 'm_login', 'm_tokens'].includes(b.id))
+    await nextTick()
+
+    expect(pinned.value).toBeUndefined()
+    expect(stated.value).toBe(false)
+    expect(items.value).toEqual([{ label: 'Billing', value: 'f_billing' }])
+    expect(containerId.value).toBe('f_billing')
+  })
+
+  it('keeps a still-legal selection when a sibling module is added', async () => {
+    seedBoard()
+    const { containerId } = useContainerTargets(() => 'f_auth')
+    containerId.value = 'm_login'
+
+    const board = useBoardStore()
+    board.blocks = [
+      ...board.blocks,
+      block({ id: 'm_sessions', level: 'module', title: 'Sessions', parentId: 'f_auth' }),
+    ]
+    await nextTick()
+
+    expect(containerId.value).toBe('m_login')
+  })
+
+  // A block id that resolves to something no task can live in is the same fact as an id that
+  // resolves to nothing: the surface has no frame behind it and must not pin to one.
+  it('ignores an opening id that is not a legal container', () => {
+    seedBoard()
+    const { pinned, items, reset, containerId } = useContainerTargets(() => 't_1')
+    reset()
+    expect(pinned.value).toBeUndefined()
+    expect(items.value).toHaveLength(4)
+    expect(containerId.value).toBe('f_auth')
+  })
+})

package/app/composables/useContainerTargets.ts

@@ -0,0 +1,62 @@
+import { computed, ref, watch, type Ref } from 'vue'
+import type { Block } from '~/types/domain'
+import { useBoardStore } from '~/stores/board'
+import {
+  containerTargets,
+  isTaskContainer,
+  reconcileContainer,
+  type ContainerTarget,
+} from '~/utils/containerTargets'
+
+/**
+ * Where a board-authoring surface creates, tracking a live board.
+ *
+ * `openedFrom` is the frame id the surface was opened WITH, and is resolved through the board on
+ * every read rather than trusted: an id alone cannot say whether the block still exists or was ever
+ * a legal container. When it resolves and the frame holds no modules there is exactly one answer,
+ * so `stated` is true and the caller renders a line naming it instead of a picker asking a question
+ * the header button already answered. A frame WITH modules did not answer it, so the picker stays,
+ * scoped to that frame.
+ *
+ * Shared by `<TaskImportModal>` and `<BugHuntModal>`, which are opened from the same two frame
+ * header buttons with the same payload: as two copies they disagreed about whether the frame was
+ * the answer or the question.
+ */
+export function useContainerTargets(openedFrom: () => string | null | undefined): {
+  /** The frame or module the surface was opened from, while the board still holds it. */
+  pinned: Ref<Block | undefined>
+  items: Ref<ContainerTarget[]>
+  containerId: Ref<string | undefined>
+  /** One legal target, so the surface states where the work lands rather than asking. */
+  stated: Ref<boolean>
+  /** Re-seed the selection; the caller invokes this when the surface opens. */
+  reset: () => void
+} {
+  const board = useBoardStore()
+
+  const pinned = computed<Block | undefined>(() => {
+    const id = openedFrom()
+    const block = id ? board.getBlock(id) : undefined
+    return isTaskContainer(block) ? block : undefined
+  })
+
+  const items = computed(() => containerTargets(board.blocks, pinned.value))
+
+  const containerId = ref<string | undefined>(undefined)
+
+  function reset() {
+    containerId.value = reconcileContainer(items.value, pinned.value?.id)
+  }
+
+  // The board is live, so what is on offer moves under the open surface: a deleted frame, a new
+  // module. Watching the TARGETS rather than seeding once is what keeps the selection legal, and
+  // it is the reason the pinned frame is re-resolved on every read instead of captured on open.
+  watch(items, (next) => {
+    const resolved = reconcileContainer(next, containerId.value)
+    if (resolved !== containerId.value) containerId.value = resolved
+  })
+
+  const stated = computed(() => !!pinned.value && items.value.length === 1)
+
+  return { pinned, items, containerId, stated, reset }
+}

package/app/docs/consumer-extensions.md

@@ -185,11 +185,15 @@ module). The SPA merges it into the create-task picker and the card-badge catalo
   `category` groups the picker (below).
 - **`fields`** are descriptor-driven create-form inputs over the shared descriptor-form vocabulary
   (`text` / `textarea` / `number` / `select` / `checkbox` / `checkbox-group` / `path`, with
-  defaults and `showWhen` visibility; `password` is excluded by construction because a task field
-  value reaches prompts and telemetry). Their values land in the task's sparse
-  `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is enforced
-  server-side on create as well (required answers, option lists, lengths); a code-shipped one is
-  known only to the SPA, so the create form is its only check (see the Validation note below).
+  defaults, `showWhen` visibility and a `section` grouping caption; `password` is excluded by
+  construction because a task field value reaches prompts and telemetry). Their values land in the
+  task's sparse `taskTypeFields.custom` bag (no migration). A BACKEND-registered descriptor is
+  enforced server-side on create as well (required answers, option lists, lengths); a code-shipped
+  one is known only to the SPA, so the create form is its only check (see the Validation note below).
+  A `section` groups a long form into captioned runs and changes nothing else; declare a section's
+  fields consecutively, since a backend registration whose form could caption one twice fails boot
+  and a code-shipped one would simply render the caption twice. Interleaving a section with a
+  mutually exclusive `showWhen` branch is not that fault: only one half is ever on screen.
 - **`formPanel`** optionally names a bespoke create-form section component you contribute to the
   `taskTypeFormPanels` slot (paired by that id, like `resultViews`); shown INSTEAD of `fields`. An
   unpaired id degrades to the descriptor fields.

package/app/stores/ui/navigation.ts

@@ -3,10 +3,14 @@ import type { LodLevel } from '~/types/domain'
 import { zoomToLod } from '~/composables/useSemanticZoom'
 
 /**
- * The board-navigation slice of the UI store: selection / focus, canvas zoom + the derived
- * level-of-detail, and the (retained) expanded-frame set. Hot paths (zoom/pan/select) live here,
- * isolated from the modal + result-view state, per refactoring candidate #4. Composed into
- * {@link useUiStore}; the returned refs/actions keep their names, so consumers are unchanged.
+ * The board-navigation slice of the UI store: selection / focus, and canvas zoom plus the derived
+ * level-of-detail. Hot paths (zoom/pan/select) live here, isolated from the modal + result-view
+ * state, per refactoring candidate #4. Composed into {@link useUiStore}; the returned refs/actions
+ * keep their names, so consumers are unchanged.
+ *
+ * There is deliberately no per-frame expanded/collapsed state: a service is always expanded to its
+ * task canvas, at every zoom level, so the board layout is fixed. The set that used to hold it
+ * outlived the last branch that read it and went with them.
  */
 export function createUiNavigation() {
   const selectedBlockId = ref<string | null>(null)
@@ -17,29 +21,6 @@ export function createUiNavigation() {
 
   const lod = computed<LodLevel>(() => zoomToLod(zoom.value))
 
-  /** Frames the user has manually expanded to reveal their tasks. */
-  const expandedFrames = ref<Set<string>>(new Set())
-
-  function toggleFrame(id: string) {
-    const next = new Set(expandedFrames.value)
-    if (next.has(id)) next.delete(id)
-    else next.add(id)
-    expandedFrames.value = next
-  }
-
-  function expandFrame(id: string) {
-    if (expandedFrames.value.has(id)) return
-    expandedFrames.value = new Set(expandedFrames.value).add(id)
-  }
-
-  /** Services are always expanded to their task canvas, at every zoom level, so the
-   * board layout is fixed: panning never changes it and zooming has no expand/collapse
-   * transition to snap on. (`expandedFrames`/`toggleFrame` are retained for callers but
-   * no longer gate rendering.) */
-  function isFrameExpanded(_id: string) {
-    return true
-  }
-
   function select(id: string | null) {
     selectedBlockId.value = id
   }
@@ -53,10 +34,6 @@ export function createUiNavigation() {
     focusBlockId,
     zoom,
     lod,
-    expandedFrames,
-    toggleFrame,
-    expandFrame,
-    isFrameExpanded,
     select,
     focus,
   }

package/app/utils/containerTargets.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a board-authoring surface creates: the containers a new task may land in, and how that
+ * answer follows a live board.
+ *
+ * Pure so the reconcile below can be pinned by a unit test. `<TaskImportModal>` and
+ * `<BugHuntModal>` ask the same two-part question (a source to read, a container to land in) and
+ * are opened from the same frame-header buttons, so both read this through
+ * {@link useContainerTargets} rather than each carrying its own copy.
+ */
+import type { Block } from '~/types/domain'
+
+/** A container offered as a select item. */
+export interface ContainerTarget {
+  label: string
+  value: string
+}
+
+/** Only a service frame or one of its modules can hold a task. */
+export function isTaskContainer(block: Block | undefined): block is Block {
+  return !!block && (block.level === 'frame' || block.level === 'module')
+}
+
+/**
+ * The containers on offer, given the frame the surface was opened from (if any).
+ *
+ * Opened from a service frame the answer is SCOPED to that frame: the frame itself plus its
+ * modules, each labelled by its own title because the frame is already named on the surface. The
+ * frame settles WHICH SERVICE the work belongs to, which is the part a header button can answer;
+ * it does not settle frame-or-which-module, so a frame that has modules still owes the user a
+ * choice. Opened standalone there is no frame behind it, so every container on the board is a
+ * candidate and a module carries its parent's title to keep the choice unambiguous.
+ *
+ * `pinned` is resolved through the board by the caller rather than trusted as an id, so a frame
+ * deleted while the surface sat open widens back to the whole board instead of scoping to
+ * something nothing can be created in.
+ */
+export function containerTargets(
+  blocks: readonly Block[],
+  pinned: Block | undefined,
+): ContainerTarget[] {
+  if (pinned) {
+    // Modules cannot nest, so a pinned module is already the only answer.
+    if (pinned.level === 'module') return [{ label: pinned.title, value: pinned.id }]
+    const modules = blocks.filter((b) => b.level === 'module' && b.parentId === pinned.id)
+    return [pinned, ...modules].map((b) => ({ label: b.title, value: b.id }))
+  }
+  const byId = new Map(blocks.map((b) => [b.id, b]))
+  return blocks.filter(isTaskContainer).map((b) => ({
+    label:
+      b.level === 'module' ? `${byId.get(b.parentId ?? '')?.title ?? '?'} › ${b.title}` : b.title,
+    value: b.id,
+  }))
+}
+
+/**
+ * The container a surface should hold as the board changes underneath it: the current selection
+ * while it is still on offer, else the first one that is.
+ *
+ * Needed because "where does this land" is answered once, when the surface opens, and the board is
+ * live: the frame it was opened from can be deleted, or a module added to it, while it sits there.
+ * A selection left pointing at a deleted block is the worst of the three states, because nothing
+ * looks wrong: the picker renders with nothing selected while the issue search under it is still
+ * scoped to the block that is gone, and the create lands on an id the board no longer has.
+ */
+export function reconcileContainer(
+  targets: readonly ContainerTarget[],
+  selected: string | undefined,
+): string | undefined {
+  if (selected && targets.some((t) => t.value === selected)) return selected
+  return targets[0]?.value
+}

package/app/utils/descriptorFields.spec.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest'
 import type { DescriptorField } from '~/types/domain'
 import {
   defaultDescriptorValues,
+  descriptorFormRows,
   descriptorGroupValue,
   setDescriptorCheckbox,
   setDescriptorValue,
@@ -124,3 +125,70 @@ describe('toggleDescriptorGroupValue', () => {
     })
   })
 })
+
+// The layout half of `section` grouping. What a caption SPANS is the shared contracts rule (tested
+// there); what these assert is the property that rule's rendering has to preserve, and the reason the
+// rows are flat at all: a field's identity survives a boundary move, so the keyed diff MOVES the
+// live input instead of remounting it.
+describe('descriptorFormRows', () => {
+  const keysOf = (rows: ReturnType<typeof descriptorFormRows>) => rows.map((r) => r.field.key)
+
+  it('carries each run caption on the field that OPENS it, once', () => {
+    const rows = descriptorFormRows(
+      [
+        field({ key: 'entity' }),
+        field({ key: 'style', section: 'Shape' }),
+        field({ key: 'verb', section: 'Shape' }),
+        field({ key: 'dir', type: 'path', section: 'Placement' }),
+      ],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.caption, r.startsGroup])).toEqual([
+      ['entity', undefined, false],
+      ['style', 'Shape', true],
+      ['verb', undefined, false],
+      ['dir', 'Placement', true],
+    ])
+  })
+
+  it('renders a sectionless form as the flat column, with no caption and no group gap', () => {
+    const rows = descriptorFormRows([field({ key: 'entity' }), field({ key: 'notes' })], {})
+    expect(rows.map((r) => [r.caption, r.startsGroup])).toEqual([
+      [undefined, false],
+      [undefined, false],
+    ])
+    expect(descriptorFormRows([], {})).toEqual([])
+  })
+
+  it('keeps a field key STABLE when a reveal moves it into another run', () => {
+    // The regression this shape exists for. `note` is unsectioned and gated, so revealing it splits
+    // the `Shape` run in two and re-captions `style`. Boot refuses THIS declaration (the split is
+    // reachable), and the renderer still has to be total over it, because a wire descriptor can
+    // arrive from a node whose build predates the refusal. Every field key present before is still
+    // present after, so Vue's keyed diff moves those nodes rather than unmounting them: typing into
+    // `advanced` (the trigger) cannot destroy the input being typed into.
+    const fields = [
+      field({ key: 'advanced', type: 'checkbox' }),
+      field({ key: 'verb', section: 'Shape' }),
+      field({ key: 'note', showWhen: { key: 'advanced', equals: true } }),
+      field({ key: 'style', section: 'Shape' }),
+    ]
+    expect(keysOf(descriptorFormRows(fields, {}))).toEqual(['advanced', 'verb', 'style'])
+
+    const revealed = descriptorFormRows(fields, { advanced: true })
+    expect(keysOf(revealed)).toEqual(['advanced', 'verb', 'note', 'style'])
+    // The caption moved (the second run needs its own) while the field identities did not.
+    expect(revealed.map((r) => r.caption)).toEqual([undefined, 'Shape', undefined, 'Shape'])
+  })
+
+  it('marks a later UNCAPTIONED run as opening a group too, so the gap is not caption-only', () => {
+    const rows = descriptorFormRows(
+      [field({ key: 'verb', section: 'Shape' }), field({ key: 'notes' })],
+      {},
+    )
+    expect(rows.map((r) => [r.field.key, r.startsGroup])).toEqual([
+      ['verb', false],
+      ['notes', true],
+    ])
+  })
+})

package/app/utils/descriptorFields.ts

@@ -1,4 +1,4 @@
-import { descriptorFieldDefaults } from '@cat-factory/contracts'
+import { descriptorFieldDefaults, descriptorFieldSections } from '@cat-factory/contracts'
 import type { DescriptorField, DescriptorFieldValue, DescriptorFieldValues } from '~/types/domain'
 
 // Form-side helpers over the shared descriptor-field vocabulary (`contracts/src/form-fields.ts`),
@@ -75,6 +75,45 @@ export function descriptorGroupValue(values: DescriptorFieldValues, key: string)
   return Array.isArray(value) ? value : []
 }
 
+/** One row of a rendered descriptor form: a field, plus the section chrome that precedes it. */
+export interface DescriptorFormRow {
+  /** The field to render. Its `key` is the row's identity in the keyed diff. */
+  field: DescriptorField
+  /** The caption to print above this field, set only on the field that OPENS a captioned run. */
+  caption?: string
+  /** Whether this field opens a run with another run before it, i.e. needs the between-runs gap. */
+  startsGroup: boolean
+}
+
+/**
+ * A descriptor form reduced to a FLAT list of rows: the shared `descriptorFieldSections` grouping,
+ * with each run's caption carried on the field that opens it rather than on a wrapper around it.
+ *
+ * Flat is the whole point, and it is a correctness rule rather than a layout preference. Run
+ * membership is DERIVED state that changes as `showWhen` reveals and hides fields, while a field's
+ * identity does not. Rendering the runs as nested `v-for`s re-parents a field the moment a boundary
+ * moves, and Vue cannot move a node between two parents: it unmounts and remounts it. The field being
+ * remounted is typically the one being TYPED INTO, because typing into a `showWhen` trigger is what
+ * moved the boundary, so the input loses focus, caret and any in-flight IME composition mid-keystroke.
+ * Keeping every field a sibling under one parent, keyed by `field.key`, makes that a MOVE, which
+ * preserves the live input: the behaviour the flat column had before sections existed.
+ *
+ * Presentation, so it lives here rather than in contracts: what a caption spans is the shared rule,
+ * and this is only how the SPA lays that out.
+ */
+export function descriptorFormRows(
+  fields: readonly DescriptorField[],
+  values: DescriptorFieldValues,
+): DescriptorFormRow[] {
+  return descriptorFieldSections(fields, values).flatMap((group, groupIndex) =>
+    group.fields.map((field, fieldIndex) => ({
+      field,
+      ...(fieldIndex === 0 && group.section !== undefined ? { caption: group.section } : {}),
+      startsGroup: fieldIndex === 0 && groupIndex > 0,
+    })),
+  )
+}
+
 /** One option toggled on/off in a `checkbox-group` field's value (deduped, order-preserving). */
 export function toggleDescriptorGroupValue(
   values: DescriptorFieldValues,