@cat-factory/app 0.133.0 → 0.135.0

package/app/components/panels/StepResultViewHost.vue

@@ -1,98 +1,60 @@
 <script setup lang="ts">
-// Universal dedicated-result-view host. An agent archetype can declare a `resultView`
-// id (see `~/utils/catalog`); when a step of that kind is opened, `ui.resultView` is set
-// and this host renders the matching registered window instead of the generic
-// `AgentStepDetail` prose panel. Adding a bespoke visualization for a new agent is just:
-//   1. declare `resultView: '<id>'` on its archetype, and
-//   2. register `'<id>': <Component>` below.
-// No caller changes — every board/inspector entry point already routes through
-// `ui` dispatch. Each registered window builds on `useResultView(viewId, { onOpen })`,
-// which owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
-// window can't reintroduce the route-dependent empty-state bug by forgetting to fetch
-// on mount — declare an `onOpen` loader and it fires on every open.
-import { computed, type Component } from 'vue'
-import RequirementsReviewWindow from '~/components/requirements/RequirementsReviewWindow.vue'
-import ClarityReviewWindow from '~/components/clarity/ClarityReviewWindow.vue'
-import BrainstormWindow from '~/components/brainstorm/BrainstormWindow.vue'
-import TestReportWindow from '~/components/testing/TestReportWindow.vue'
-import HumanTestWindow from '~/components/humanTest/HumanTestWindow.vue'
-import VisualConfirmationWindow from '~/components/visualConfirm/VisualConfirmationWindow.vue'
-import GateResultView from '~/components/gates/GateResultView.vue'
-import ConsensusSessionWindow from '~/components/consensus/ConsensusSessionWindow.vue'
-import GenericStructuredResultView from '~/components/panels/GenericStructuredResultView.vue'
-import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
-import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
-import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
-import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
-import MergerResultView from '~/components/panels/MergerResultView.vue'
-import InitiativeTrackerWindow from '~/components/initiative/InitiativeTrackerWindow.vue'
-import InitiativePlanningWindow from '~/components/initiative/InitiativePlanningWindow.vue'
-import DocInterviewWindow from '~/components/docs/DocInterviewWindow.vue'
-import RalphLoopResultView from '~/components/ralph/RalphLoopResultView.vue'
+// Universal dedicated-result-view host (slice 2 of the modular-vue adoption —
+// docs/initiatives/modular-vue-adoption.md). An agent archetype can declare a
+// `resultView` id (see `~/utils/catalog`); when a step of that kind is opened,
+// `ui.resultView` is set and this host mounts the matching registered window
+// instead of the generic `AgentStepDetail` prose panel.
+//
+// The registry is no longer a hardcoded `Record` here — every built-in window is
+// contributed to the modular `resultViews` slot (`~/modular/result-views`), and
+// a consumer deployment adds its OWN window to the SAME slot from a
+// `registerAppModule` module. This host reads the merged slot reactively via
+// `useReactiveSlots` and indexes it with `resolveComponentRegistry`; the kind's
+// (or custom kind's) `resultView` id selects the component. Adding a bespoke
+// visualization for a new agent is: declare `resultView: '<id>'` on its
+// archetype + contribute `{ id: '<id>', component }` to the `resultViews` slot.
+//
+// Each registered window builds on `useResultView(viewId, { onOpen })`, which
+// owns the seam contract (open/blockId/close + Escape + load-on-open) so a new
+// window can't reintroduce the route-dependent empty-state bug by forgetting to
+// fetch on mount.
+import { computed, watchEffect, type Component } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import { pairById, resolveComponentRegistry } from '@modular-vue/core'
+import type { AppSlots } from '~/modular/slots'
 
 const ui = useUiStore()
+const agents = useAgentsStore()
+const slots = useReactiveSlots<AppSlots>()
 
-const STEP_RESULT_VIEWS: Record<string, Component> = {
-  'requirements-review': RequirementsReviewWindow,
-  'clarity-review': ClarityReviewWindow,
-  // Shared by both brainstorm stages (requirements + architecture); the window reads the stage.
-  brainstorm: BrainstormWindow,
-  tester: TestReportWindow,
-  // The human-testing gate: env URL + confirm / request-fix / pull-main / recreate / destroy.
-  'human-test': HumanTestWindow,
-  // The visual-confirmation gate: actual-vs-reference screenshot gallery + approve / request-fix.
-  'visual-confirm': VisualConfirmationWindow,
-  // Shared by both polling gates (`ci` + `conflicts`); the window branches on agentKind.
-  gate: GateResultView,
-  // Opened for any step that ran the consensus mechanism (routed in `ui.dispatchStepView`).
-  'consensus-session': ConsensusSessionWindow,
-  // Default dedicated view for a registered CUSTOM kind's structured (`custom`) output —
-  // a read-only JSON viewer, so a proprietary agent ships a result view with no bespoke code.
-  'generic-structured': GenericStructuredResultView,
-  // The service's prescriptive spec tree (+ Gherkin), opened from the inspector's "View
-  // Requirements" button. Not a pipeline-step view — opened directly via `ui.openServiceSpec`.
-  'service-spec': ServiceSpecWindow,
-  // The future-looking Follow-up companion: the Coder's surfaced loose ends / questions.
-  // Opened directly via `ui.openFollowUps` (the blinking chip + the `followup_pending` card).
-  'follow-ups': FollowUpWindow,
-  // The implementation-fork decision: the proposer's materially different approaches + the
-  // human's pick / custom approach. Opened directly via `ui.openForkDecision` (the pipeline
-  // chip, the inspector button, and the `fork_decision_pending` card).
-  'fork-decision': ForkDecisionWindow,
-  // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
-  // Opened as the `pr-reviewer` step's result view and via the `pr_review_ready` inbox card.
-  'pr-review': PrReviewWindow,
-  // The merger's verdict: the PR's complexity/risk/impact scores + the engine's auto-merge
-  // or awaiting-review decision (and why), instead of the agent's raw JSON.
-  merger: MergerResultView,
-  // The initiative tracker: phases, per-item status + PR links, decisions, deviations,
-  // caveats. Opened from the initiative card / inspector (`ui.openInitiativeTracker`) and
-  // as the planner step's result view.
-  'initiative-tracker': InitiativeTrackerWindow,
-  'initiative-planning': InitiativePlanningWindow,
-  // The interactive document-interview gate (WS5): the interviewer's clarifying questions +
-  // answer / continue / proceed, opened as the `doc-interviewer` step's result view.
-  'doc-interview': DocInterviewWindow,
-  // The Ralph loop: the persistent retry-until-done iteration history + the programmatic
-  // validation command + its latest exit code / output. Opened as the `ralph` step's view.
-  'ralph-loop': RalphLoopResultView,
-}
+// Index the merged `resultViews` slot into an id → component registry. Duplicate
+// ids throw by default (`resolveComponentRegistry`) — two modules claiming the
+// same view id is a wiring bug, not a silent last-wins. Recomputed if a consumer
+// module's contributions change (they don't after boot, but the read is cheap).
+const registry = computed(() => resolveComponentRegistry(slots.value.resultViews ?? []))
 
 const active = computed<Component | null>(() => {
   const view = ui.resultView?.view
   if (!view) return null
-  const component = STEP_RESULT_VIEWS[view] ?? null
-  // An archetype declared a `resultView` id with no registered component — this used to
-  // silently fall back to the prose panel. The backend now validates `resultView` against the
-  // canonical id set, so this should only fire mid-development of a new view; make it loud.
-  if (!component && import.meta.dev) {
-    console.warn(
-      `[StepResultViewHost] no component registered for resultView "${view}". ` +
-        `Add it to STEP_RESULT_VIEWS (and to RESULT_VIEW_IDS in @cat-factory/contracts).`,
-    )
-  }
-  return component
+  return registry.value.get(view) ?? null
 })
+
+// Dev guard: surface any CUSTOM kind whose declared `resultView` id resolves to
+// no registered component (a dangling reference — e.g. a backend kind naming a
+// consumer view this build doesn't ship). `pairById`'s `missing` bucket makes
+// the degradation explicit instead of a silent fall-through to the prose panel.
+if (import.meta.dev) {
+  watchEffect(() => {
+    const { missing } = pairById(agents.customArchetypes, registry.value, (a) => a.resultView)
+    if (missing.length) {
+      console.warn(
+        `[StepResultViewHost] custom agent kind(s) reference unregistered resultView id(s): ` +
+          missing.map((m) => `${m.item.kind}→${m.id}`).join(', ') +
+          `. Register a component for the id in a resultViews-slot module.`,
+      )
+    }
+  })
+}
 </script>
 
 <template>

package/app/modular/agent-kinds.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildAgentCapabilitiesManifest,
+  capabilitiesManifestVersion,
+  customKindToArchetype,
+  WORKSPACE_CAPABILITIES_MANIFEST_ID,
+} from './agent-kinds'
+import type { AgentKind, CustomAgentKind } from '~/types/domain'
+
+const kind = (
+  over: Partial<CustomAgentKind['presentation']> = {},
+  kindId = 'acme-audit',
+): CustomAgentKind => ({
+  kind: kindId as AgentKind,
+  container: true,
+  presentation: {
+    label: 'Audit',
+    icon: 'i-lucide-shield',
+    color: '#fff',
+    description: 'd',
+    ...over,
+  },
+})
+
+describe('buildAgentCapabilitiesManifest', () => {
+  it('models the snapshot kinds as one remote capability manifest carrying the agentKinds slot', () => {
+    const kinds = [kind(), kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    expect(manifest.id).toBe(WORKSPACE_CAPABILITIES_MANIFEST_ID)
+    expect(manifest.slots?.agentKinds).toEqual(kinds)
+  })
+
+  it('copies the input (no aliasing of the caller array)', () => {
+    const kinds = [kind()]
+    const manifest = buildAgentCapabilitiesManifest(kinds)
+    kinds.push(kind())
+    expect(manifest.slots?.agentKinds).toHaveLength(1)
+  })
+
+  it('derives an identical version for identical content (so an unchanged re-hydrate no-ops)', () => {
+    // A fresh, structurally-equal kinds array (a new snapshot re-delivering the same kinds)
+    // must produce the same version — that's what lets `hydrateCustomKinds` skip the swap.
+    expect(buildAgentCapabilitiesManifest([kind()]).version).toBe(
+      buildAgentCapabilitiesManifest([kind()]).version,
+    )
+  })
+
+  it('changes the version when a display/pairing field or the kind set differs', () => {
+    const base = capabilitiesManifestVersion([kind()])
+    expect(capabilitiesManifestVersion([kind({ label: 'Renamed' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({ resultView: 'acme:audit' })])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind({}, 'acme-other')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([kind(), kind({}, 'acme-two')])).not.toBe(base)
+    expect(capabilitiesManifestVersion([])).not.toBe(base)
+  })
+})
+
+describe('customKindToArchetype', () => {
+  it('projects presentation onto the display archetype', () => {
+    expect(customKindToArchetype(kind())).toEqual({
+      kind: 'acme-audit',
+      label: 'Audit',
+      icon: 'i-lucide-shield',
+      color: '#fff',
+      description: 'd',
+    })
+  })
+
+  it('carries category and resultView through when present', () => {
+    const a = customKindToArchetype(kind({ category: 'review', resultView: 'acme:audit' }))
+    expect(a.category).toBe('review')
+    expect(a.resultView).toBe('acme:audit')
+  })
+
+  it('omits category/resultView when absent (no undefined keys)', () => {
+    const a = customKindToArchetype(kind())
+    expect('category' in a).toBe(false)
+    expect('resultView' in a).toBe(false)
+  })
+})

package/app/modular/agent-kinds.ts

@@ -0,0 +1,83 @@
+import type { RemoteModuleManifest } from '@modular-vue/core'
+import type { AgentArchetype, CustomAgentKind } from '~/types/domain'
+import type { AppSlots } from './slots'
+
+/**
+ * Custom agent kinds as remote capability manifests (slice 2 of the modular-vue
+ * adoption — docs/initiatives/modular-vue-adoption.md).
+ *
+ * A deployment's BACKEND-registered agent kinds arrive in the workspace snapshot
+ * as `customAgentKinds` (wire data). Rather than mutating a module-global
+ * catalog, they're modeled as a single {@link RemoteModuleManifest} whose
+ * `agentKinds` slot carries the data. cat-factory holds ONE active manifest per
+ * workspace (swapped on snapshot), so the agents store reads its `.slots`
+ * directly — the sanctioned single-active-manifest shape (the merge-many
+ * `mergeRemoteManifests` helper is for holding several manifests at once, which
+ * we don't). CODE-shipped consumer kinds instead enter via the static
+ * `agentKinds` slot (a `registerAppModule` module); the store merges both.
+ */
+
+/** The stable id for the per-workspace capability manifest built from the snapshot. */
+export const WORKSPACE_CAPABILITIES_MANIFEST_ID = 'cat-factory:workspace-capabilities'
+
+/**
+ * A deterministic, key-order-independent content signature of the custom kinds, used as the
+ * manifest `version`. The workspace snapshot re-delivers the SAME deployment-registered kinds on
+ * every board-event refresh (a full `workspace.refresh()` runs `hydrateCustomKinds` each time), so
+ * a content-derived version lets the store skip re-projecting an UNCHANGED catalog — otherwise
+ * every refresh would replace the `customAgentKindMeta` read-model and needlessly invalidate the
+ * ~17 `agentKindMeta` / `isKnownAgentKind` consumers. It still changes (and swaps wholesale) when a
+ * different workspace's kinds actually differ. Serialized as fixed-order tuples of only the fields
+ * that affect display/pairing, so a re-serialization with reordered object keys can't spuriously
+ * differ.
+ */
+export function capabilitiesManifestVersion(kinds: readonly CustomAgentKind[]): string {
+  return JSON.stringify(
+    kinds.map((k) => [
+      k.kind,
+      k.container,
+      k.presentation.label,
+      k.presentation.icon,
+      k.presentation.color,
+      k.presentation.description,
+      k.presentation.category ?? null,
+      k.presentation.resultView ?? null,
+    ]),
+  )
+}
+
+/**
+ * Model the snapshot's `customAgentKinds` as a single remote capability manifest. The `version` is
+ * a {@link capabilitiesManifestVersion content signature} so identical snapshots produce an
+ * identical manifest — which `useAgentsStore().hydrateCustomKinds` uses to no-op an unchanged
+ * re-hydrate. Swapped wholesale (not diffed) when the content genuinely changes.
+ */
+export function buildAgentCapabilitiesManifest(
+  kinds: readonly CustomAgentKind[],
+): RemoteModuleManifest<AppSlots> {
+  return {
+    id: WORKSPACE_CAPABILITIES_MANIFEST_ID,
+    version: capabilitiesManifestVersion(kinds),
+    slots: { agentKinds: [...kinds] },
+  }
+}
+
+/**
+ * Project a wire `CustomAgentKind` onto the frontend's display `AgentArchetype`
+ * (icon/label/color/description + optional category/resultView). The inverse of
+ * the backend `agentPresentationSchema` — the SAME mapping the removed
+ * `registerCustomKinds` did inline, now pure and shared by the consumer-slot and
+ * backend-manifest paths.
+ */
+export function customKindToArchetype(kind: CustomAgentKind): AgentArchetype {
+  const { presentation: p } = kind
+  return {
+    kind: kind.kind,
+    label: p.label,
+    icon: p.icon,
+    color: p.color,
+    description: p.description,
+    ...(p.category ? { category: p.category } : {}),
+    ...(p.resultView ? { resultView: p.resultView } : {}),
+  }
+}

package/app/modular/journeys/environmentSetup.frame.ts

@@ -0,0 +1,31 @@
+import { type MaybeRefOrGetter, toValue, watch } from 'vue'
+import { useEnvironmentWizardStore } from '~/stores/environmentWizard'
+
+/**
+ * Bridge a journey step's target frame (`ModuleEntryProps.input.frameId`) into
+ * the `environmentWizard` data store (slice 3 of the modular-vue adoption).
+ *
+ * The journey owns per-frame NAVIGATION (its state carries the resolved
+ * `frameId`), but the heavy per-step DATA lives in the singleton
+ * `environmentWizard` store, which holds exactly ONE frame at a time. Every step
+ * that READS that store therefore has to (re)assert the frame it was entered for
+ * — otherwise the store can be pointing at a DIFFERENT frame than the one the
+ * journey is on, and the step renders (or `save()` persists) the wrong frame's
+ * recipe. That desync is reachable within a single session: configure frame A up
+ * to the preflight step, open the wizard for frame B (its review step repoints
+ * the store to B), then reopen A and RESUME at preflight — a step that never
+ * re-bridged would show B's data under A's journey.
+ *
+ * `beginForFrame` is idempotent per frame (a no-op when the store already targets
+ * `frameId`), so calling this from every data step is free on the happy path and
+ * only re-seeds when the store actually drifted. `immediate` so the store is
+ * targeted before the step's first render reads it.
+ */
+export function useEnvironmentWizardTarget(frameId: MaybeRefOrGetter<string | null>): void {
+  const store = useEnvironmentWizardStore()
+  watch(
+    () => toValue(frameId),
+    (id) => store.beginForFrame(id),
+    { immediate: true },
+  )
+}

package/app/modular/journeys/environmentSetup.logic.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ENV_STEP_ORDER,
+  envInitialState,
+  envNextAfter,
+  envStartStep,
+} from './environmentSetup.logic'
+
+// Pure navigation graph for the environment-setup journey (slice 3). `envNextAfter`
+// is the source of truth the journey's `advance` transitions derive their target
+// entries from (see `environmentSetup.ts`), so pinning the order, start branch, and
+// forward edges here means a wiring regression can't silently reorder or drop a step.
+describe('environment-setup journey logic', () => {
+  it('orders the steps pick → review → preflight → save', () => {
+    expect(ENV_STEP_ORDER).toEqual(['pick', 'review', 'preflight', 'save'])
+  })
+
+  it('seeds state from the launch input', () => {
+    expect(envInitialState({ frameId: 'blk_1' })).toEqual({ frameId: 'blk_1' })
+    expect(envInitialState({ frameId: null })).toEqual({ frameId: null })
+  })
+
+  it('skips the picker when a frame was preselected, else starts at pick', () => {
+    expect(envStartStep({ frameId: 'blk_1' }, { frameId: 'blk_1' })).toBe('review')
+    expect(envStartStep({ frameId: null }, { frameId: null })).toBe('pick')
+  })
+
+  it('advances linearly and terminates after save', () => {
+    expect(envNextAfter('pick')).toBe('review')
+    expect(envNextAfter('review')).toBe('preflight')
+    expect(envNextAfter('preflight')).toBe('save')
+    expect(envNextAfter('save')).toBe('done')
+  })
+})

package/app/modular/journeys/environmentSetup.logic.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure navigation logic for the environment-setup journey (slice 3 of the
+ * modular-vue adoption — docs/initiatives/modular-vue-adoption.md).
+ *
+ * The journey owns only the WIZARD NAVIGATION — the ordered steps
+ * (pick → review → preflight → save), the forward transitions, and the
+ * back/rewind + resume that used to live as a hand-rolled `STEP_ORDER` + `step`
+ * ref + `goToStep` in `stores/environmentWizard.ts`. The heavy per-step DATA and
+ * async actions (detect / deep-analysis / recipe editing / preflight / save /
+ * trial) stay in that Pinia store, which the step components still drive; the
+ * journey just decides WHICH step shows and threads the target frame id.
+ *
+ * This file is deliberately free of Vue/`.vue`/`defineModule` imports so the
+ * transition graph is unit-tested directly (`environmentSetup.spec.ts`); the
+ * component wiring lives in `environmentSetup.ts`, which feeds these helpers into
+ * `defineJourney`'s `transitions` map.
+ */
+
+/** The journey's ordered step entries (also the module's `entryPoints` keys). */
+export const ENV_STEP_ORDER = ['pick', 'review', 'preflight', 'save'] as const
+export type EnvStep = (typeof ENV_STEP_ORDER)[number]
+
+/** The single module id every step entry lives under. */
+export const ENV_MODULE_ID = 'cat-factory:environment-setup' as const
+
+/** The picker's exit — carries the chosen frame into journey state. */
+export const ENV_SELECT_EXIT = 'select'
+/** Every other step's forward exit — void, just advances. */
+export const ENV_ADVANCE_EXIT = 'advance'
+
+/** Payload of the picker's `select` exit. */
+export interface EnvSelectOutput {
+  frameId: string
+}
+
+/** The journey's serializable state — just the resolved target frame. Everything
+ *  else is derived live in the `environmentWizard` store, so this stays tiny and
+ *  cheap to persist/resume. */
+export interface EnvSetupState {
+  frameId: string | null
+}
+
+/** The journey's start input — the frame the launcher preselected, or `null` to
+ *  begin at the pick step. `keyFor` scopes resume to this frame. */
+export interface EnvSetupInput {
+  frameId: string | null
+}
+
+/** Seed the journey state from the launch input. */
+export function envInitialState(input: EnvSetupInput): EnvSetupState {
+  return { frameId: input.frameId }
+}
+
+/** First step: skip the picker when the launcher already chose a frame. */
+export function envStartStep(_state: EnvSetupState, input: EnvSetupInput): EnvStep {
+  return input.frameId ? 'review' : 'pick'
+}
+
+/**
+ * The step reached by advancing from `from` via its forward exit, or `'done'`
+ * when the flow completes. The pick step advances via `select` (a distinct
+ * exit); the rest via `advance`. Pure and total over `EnvStep`.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the linear forward chain: the journey
+ * definition (`environmentSetup.ts`) derives its `advance` transitions' target
+ * entries from it, so pinning this function in `environmentSetup.logic.spec.ts`
+ * genuinely guards the wired graph against a silent reorder/drop. The overloads
+ * narrow the return to a concrete entry (or `'done'`) so a transition handler can
+ * feed the result straight into a `StepSpec` without a widened `EnvStep | 'done'`.
+ */
+export function envNextAfter(from: 'pick'): 'review'
+export function envNextAfter(from: 'review'): 'preflight'
+export function envNextAfter(from: 'preflight'): 'save'
+export function envNextAfter(from: 'save'): 'done'
+export function envNextAfter(from: EnvStep): EnvStep | 'done' {
+  switch (from) {
+    case 'pick':
+      return 'review'
+    case 'review':
+      return 'preflight'
+    case 'preflight':
+      return 'save'
+    case 'save':
+      return 'done'
+  }
+}

package/app/modular/journeys/environmentSetup.ts

@@ -0,0 +1,143 @@
+import { defineModule } from '@modular-vue/core'
+import { defineExit } from '@modular-frontend/core'
+import { defineJourney, defineJourneyHandle } from '@modular-vue/journeys'
+import EnvPickStep from '~/components/environments/steps/EnvPickStep.vue'
+import EnvReviewStep from '~/components/environments/steps/EnvReviewStep.vue'
+import EnvPreflightStep from '~/components/environments/steps/EnvPreflightStep.vue'
+import EnvSaveStep from '~/components/environments/steps/EnvSaveStep.vue'
+import { catFactoryJourneyPersistence } from '~/modular/journeys/persistence'
+import {
+  ENV_ADVANCE_EXIT,
+  ENV_MODULE_ID,
+  ENV_SELECT_EXIT,
+  type EnvSelectOutput,
+  type EnvSetupInput,
+  type EnvSetupState,
+  envInitialState,
+  envNextAfter,
+  envStartStep,
+} from '~/modular/journeys/environmentSetup.logic'
+
+/**
+ * The environment-setup journey — the slice-3 pilot of the modular-vue adoption
+ * (docs/initiatives/modular-vue-adoption.md). It replaces the wizard's hand-rolled
+ * `STEP_ORDER` + `step` ref + `goToStep` navigation (in `stores/environmentWizard.ts`)
+ * with a typed, back/rewind-capable, resumable journey; the per-step data + async
+ * actions stay in that Pinia store, driven by the step components below.
+ *
+ * Authoring notes (co-evolution): `defineModule` comes from the `@modular-vue/core`
+ * binding, but the exit helper `defineExit` is only exported from the neutral
+ * `@modular-frontend/core` engine (a direct dep) — the Vue binding doesn't re-export
+ * the entry/exit authoring helpers yet. That's a small binding-surface gap to close
+ * upstream (mirrors slice 2's remote-manifest re-export), not a blocker.
+ *
+ * Each step's `input` (the target frame) is threaded explicitly on the `next` step
+ * specs rather than via an entry `buildInput` factory: the frame is fixed once at the
+ * pick step and never changes mid-flow, so the snapshot input a transition places is
+ * always current — even on `preserve-state` back-navigation — which keeps the module
+ * type simple (no `buildInput`-optionality quirk) and the flow fully explicit.
+ *
+ * This file imports the step `.vue` components, so — like `result-views.ts` — it's
+ * registered from the client plugin, keeping the unit-tested `registry.ts` /
+ * `*.logic.ts` import graph free of SFCs.
+ */
+
+/**
+ * The step module: one module, four `journey`-mounted entries (the wizard steps),
+ * and two exits — `select` (the picker's chosen frame) and `advance` (every other
+ * step's void forward). Each non-initial entry opts into `preserve-state` back so
+ * the host's Back control rewinds a step without discarding the operator's edits.
+ */
+export const environmentSetupModule = defineModule({
+  id: ENV_MODULE_ID,
+  version: '1.0.0',
+  entryPoints: {
+    pick: { mountKinds: ['journey'] as const, component: EnvPickStep },
+    review: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvReviewStep,
+    },
+    preflight: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvPreflightStep,
+    },
+    save: {
+      mountKinds: ['journey'] as const,
+      allowBack: 'preserve-state' as const,
+      component: EnvSaveStep,
+    },
+  },
+  exitPoints: {
+    [ENV_SELECT_EXIT]: defineExit<EnvSelectOutput>(),
+    [ENV_ADVANCE_EXIT]: defineExit(),
+  },
+})
+
+type EnvModules = { [ENV_MODULE_ID]: typeof environmentSetupModule }
+
+/**
+ * The journey definition. `start` skips the picker when a frame was preselected;
+ * transitions are the linear pick → review → preflight → save chain, terminating
+ * with `complete` off the save step's `advance`. Back-navigation is handled by the
+ * entries' `allowBack`, not explicit transitions.
+ */
+export const environmentSetupJourney = defineJourney<EnvModules, EnvSetupState>()({
+  id: 'environment-setup',
+  version: '1.0.0',
+  initialState: (input: EnvSetupInput) => envInitialState(input),
+  start: (state, input: EnvSetupInput) =>
+    envStartStep(state, input) === 'review'
+      ? ({ module: ENV_MODULE_ID, entry: 'review', input: { frameId: state.frameId } } as const)
+      : ({ module: ENV_MODULE_ID, entry: 'pick', input: { frameId: state.frameId } } as const),
+  transitions: {
+    [ENV_MODULE_ID]: {
+      pick: {
+        [ENV_SELECT_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: 'review',
+            input: { frameId: ctx.output.frameId },
+          } as const,
+          state: { frameId: ctx.output.frameId },
+        }),
+      },
+      review: {
+        [ENV_ADVANCE_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: envNextAfter('review'),
+            input: { frameId: ctx.state.frameId },
+          } as const,
+        }),
+      },
+      preflight: {
+        [ENV_ADVANCE_EXIT]: (ctx) => ({
+          next: {
+            module: ENV_MODULE_ID,
+            entry: envNextAfter('preflight'),
+            input: { frameId: ctx.state.frameId },
+          } as const,
+        }),
+      },
+      // `save` advances to `envNextAfter('save') === 'done'`, i.e. journey completion.
+      save: {
+        [ENV_ADVANCE_EXIT]: () => ({ complete: undefined }),
+      },
+    },
+  },
+})
+
+/** Typed launch handle — callers `runtime.start(handle, { frameId })`. */
+export const environmentSetupHandle = defineJourneyHandle(environmentSetupJourney)
+
+/**
+ * Pinia-backed persistence keyed by the target frame, so reopening the wizard for
+ * the same frame RESUMES at the step it was left on (and a different frame is a
+ * fresh flow). A null frame (launched at the picker) is a single transient key.
+ */
+export const environmentSetupPersistence = catFactoryJourneyPersistence<
+  EnvSetupInput,
+  EnvSetupState
+>(({ journeyId, input }) => `${journeyId}:${input.frameId ?? 'new'}`)