feat(web): convert Blueprint Builder to 4-step wizard

[Nether403]

Summary

Phase 4 gap #1. The Blueprint Builder was a single form; this PR turns it into a guided 4-step wizard that also integrates the scaffold export flow so users can go from idea to downloadable starter in one page.

Wizard steps

1. Idea — required textarea, distraction-free
2. Constraints — optional free-form constraints plus structured fields for budget, timeline, team size (all wired to the existing BlueprintRequest schema — previously unused)
3. Results — existing BlueprintOutputCard rendered inside the wizard
4. Export — scaffold generation via POST /api/v1/scaffolds with project name input, file list preview, warnings panel, and client-side ZIP download via the existing archive-generator

UX

• Progress indicator with completed/active/pending states
• Back / Next controls with per-step loading states
• "Start over" action on the final step
• Inline error surfaces with retry affordances on both blueprint and scaffold failures
• Regenerate button on the export step for project-name tweaks

Evidence

Playwright walks the whole flow: idea → constraints (with budget/timeline selects) → results (asserts "Recommended Architecture", "Primary Stack", "Harmony Score") → export (asserts "Download ZIP"). A screenshot is captured at each step to test-results/wizard-step-*.png.

Full E2E suite result:

4 passed (2.2m)
 ok [chromium] searches the tool catalog (3.8s)
 ok [chromium] shows a basic migration path (4.5s)
 ok [chromium] analyzes pairwise compatibility (4.1s)
 ok [chromium] generates an idea-to-stack blueprint (33.6s)

Quality gate (local)

• pnpm -r type-check — 0 errors
• pnpm -r lint — 0 errors
• pnpm -r test — 60 unit/API tests pass
• pnpm -r build — web + api + packages
• pnpm test:e2e — 4/4 passed

Notes

• Bumped the wizard E2E test timeout to 180s because blueprint generation can take ~25-30s when the Gemini provider does the full parallel fan-out (explainStack + generateRoadmap + per-alternative tradeoffs + whyNot).
• The one Gemini fallback log in the E2E run (summarizeTradeoffs returned >8 items, Zod schema caps at 8) is the design working correctly — fallback to heuristic happens automatically with no user-visible impact.

Next

Phase 4 gap #2 (compatibility heatmap) and gap #3 (TanStack Query sweep) will ship as separate PRs.

---

---

Summary by cubic

Converted the Blueprint Builder into a 4-step wizard and integrated scaffold export so users can go from idea to a downloadable starter in one page. Adds progress UX, structured constraints, and inline error handling.

• New Features
  • Four steps: Idea → Constraints (budget, timeline, team size wired to BlueprintRequest) → Results → Export (POST /api/v1/scaffolds; project name used for archive and package.json; file list + applied recipe count + generated timestamp; warnings; client-side ZIP via archive-generator).
  • Progress indicator (completed/active/pending with test-id), Back/Next with per-step loading, Start over on final step, inline errors with retry for blueprint and scaffold, Regenerate on export.
  • E2E: tests/e2e/mvp-flows.spec.ts walks all steps, saves step screenshots, asserts "Recommended Architecture" and "Download ZIP", and bumps timeout to 180s.

^{Written for commit 2732880. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/web/src/pages/BlueprintBuilder.tsx">

<violation number="1" location="apps/web/src/pages/BlueprintBuilder.tsx:119">
P2: Normalize `projectName` in download/archive generation the same way as scaffold generation to avoid invalid or inconsistent archive names.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Normalize projectName in download/archive generation the same way as scaffold generation to avoid invalid or inconsistent archive names.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/web/src/pages/BlueprintBuilder.tsx, line 119:

<comment>Normalize `projectName` in download/archive generation the same way as scaffold generation to avoid invalid or inconsistent archive names.</comment>

<file context>
@@ -1,112 +1,637 @@
+    if (!scaffold) return;
+    setDownloadError(null);
+    try {
+      const blob = await generateArchive(scaffold.files, scaffold.format, projectName);
+      downloadArchive(blob, `${projectName || "stackfast-app"}.${scaffold.format}`);
+    } catch (error) {
</file context>

Suggested change

	const blob = await generateArchive(scaffold.files, scaffold.format, projectName);
	downloadArchive(blob, `${projectName || "stackfast-app"}.${scaffold.format}`);
	const normalizedProjectName = projectName.trim() || "stackfast-app";
	const blob = await generateArchive(scaffold.files, scaffold.format, normalizedProjectName);
	downloadArchive(blob, `${normalizedProjectName}.${scaffold.format}`);

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🟡 Scaffold generation errors are invisible when triggered from the results step

When the user clicks "Continue to export" on the results step, handleGenerateScaffold is called (BlueprintBuilder.tsx:199). If the scaffold mutation fails, the onSuccess callback never fires, so step stays at "results". However, the scaffoldError is only rendered inside the ExportStep component, which is conditionally mounted only when step === "export" (BlueprintBuilder.tsx:176). This means the error is stored but never displayed — the user just sees the "Continue to export" button become re-enabled with no feedback about the failure. This is inconsistent with how blueprint generation errors are handled: those errors correctly display inside the ConstraintsStep where the action is initiated (BlueprintBuilder.tsx:393-400).

Prompt for agents

The scaffold generation error (scaffoldError) is only displayed inside ExportStep, which is gated behind step === 'export'. But when scaffold generation fails, the step stays at 'results' because onSuccess never fires. The user needs to see the error.

Possible approaches:
1. Add scaffold error display to the results step section (around line 170-174 in BlueprintBuilder.tsx), similar to how generateError is shown inside ConstraintsStep.
2. Alternatively, always navigate to the export step when scaffold generation is initiated (move setStep('export') outside of onSuccess), and let the ExportStep handle both loading and error states. This would require adjusting handleGenerateScaffold to call setStep('export') before or alongside generateScaffold, rather than only onSuccess.

Approach 1 is simpler and consistent with the existing pattern for blueprint errors.

---

Was this helpful? React with 👍 or 👎 to provide feedback.