feat: enhance InstructionsWizard to manage free text drafts and improve form submission handling

Author: spivx

.gitignore

@@ -117,3 +117,4 @@ pnpm-debug.log*
 
 # vercel
 .vercel/
+test-results/

components/instructions-wizard.tsx

@@ -30,6 +30,7 @@ import { WizardAnswerGrid } from "./wizard-answer-grid"
 import { WizardConfirmationDialog } from "./wizard-confirmation-dialog"
 
 const suffixSteps = getSuffixSteps()
+const buildStepSignature = (step: WizardStep) => `${step.id}::${step.questions.map((question) => question.id).join("|")}`
 
 export function InstructionsWizard({
   initialStackId,
@@ -46,6 +47,7 @@ export function InstructionsWizard({
     initialStackId ? { [STACK_QUESTION_ID]: initialStackId } : {}
   )
   const [freeTextResponses, setFreeTextResponses] = useState<FreeTextResponses>({})
+  const [freeTextDrafts, setFreeTextDrafts] = useState<Record<string, string>>({})
   const [dynamicSteps, setDynamicSteps] = useState<WizardStep[]>(() =>
     initialStackStep ? [initialStackStep] : []
   )
@@ -65,6 +67,9 @@ export function InstructionsWizard({
   const hasAppliedInitialStack = useRef<string | null>(
     initialStackStep && initialStackId ? initialStackId : null
   )
+  const lastAppliedStackStepSignature = useRef<string | null>(
+    initialStackStep ? buildStepSignature(initialStackStep) : null
+  )
   const [activeStackLabel, setActiveStackLabel] = useState<string | null>(initialStackLabel)
 
   const wizardSteps = useMemo(() => [stacksStep, ...dynamicSteps, ...suffixSteps], [dynamicSteps])
@@ -87,20 +92,32 @@ export function InstructionsWizard({
   const filterInputId = currentQuestion ? `answer-filter-${currentQuestion.id}` : "answer-filter"
 
   const currentAnswerValue = currentQuestion ? responses[currentQuestion.id] : undefined
-  const currentFreeTextValue = useMemo(() => {
+  const savedFreeTextValue = useMemo(() => {
     if (!currentQuestion) {
       return ""
     }
 
     const value = freeTextResponses[currentQuestion.id]
     return typeof value === "string" ? value : ""
   }, [currentQuestion, freeTextResponses])
+
+  const draftFreeTextValue = useMemo(() => {
+    if (!currentQuestion) {
+      return ""
+    }
+
+    const value = freeTextDrafts[currentQuestion.id]
+    return typeof value === "string" ? value : ""
+  }, [currentQuestion, freeTextDrafts])
+
+  const currentFreeTextValue =
+    draftFreeTextValue.length > 0 ? draftFreeTextValue : savedFreeTextValue
   const freeTextConfig = currentQuestion?.freeText ?? null
   const freeTextInputId = currentQuestion ? `free-text-${currentQuestion.id}` : "free-text"
   const canSubmitFreeText = Boolean(freeTextConfig?.enabled && currentFreeTextValue.trim().length > 0)
-  const hasSavedCustomFreeText = Boolean(freeTextConfig?.enabled && currentFreeTextValue.trim().length > 0)
+  const hasSavedCustomFreeText = Boolean(freeTextConfig?.enabled && savedFreeTextValue.trim().length > 0)
 
-  const savedCustomFreeTextValue = currentFreeTextValue.trim()
+  const savedCustomFreeTextValue = savedFreeTextValue.trim()
 
   const defaultAnswer = useMemo(
     () => currentQuestion?.answers.find((answer) => answer.isDefault) ?? null,
@@ -190,25 +207,47 @@ export function InstructionsWizard({
   const applyStackStep = useCallback(
     (step: WizardStep, label: string | null, options?: { skipFastTrackPrompt?: boolean; stackId?: string }) => {
       const skipFastTrackPrompt = options?.skipFastTrackPrompt ?? false
-      const nextStackId = options?.stackId
+      const nextStackId = options?.stackId ?? null
+      const stepSignature = buildStepSignature(step)
+      const previousSignature = lastAppliedStackStepSignature.current
+      const isSameStep = previousSignature === stepSignature
 
       setActiveStackLabel(label)
-      setDynamicSteps([step])
       setIsStackFastTrackPromptVisible(!skipFastTrackPrompt && step.questions.length > 0)
 
+      if (isSameStep) {
+        if (nextStackId) {
+          setResponses((prev) => {
+            if (prev[STACK_QUESTION_ID] === nextStackId) {
+              return prev
+            }
+
+            return {
+              ...prev,
+              [STACK_QUESTION_ID]: nextStackId,
+            }
+          })
+        }
+
+        lastAppliedStackStepSignature.current = stepSignature
+        return
+      }
+
+      const questionIds = new Set(step.questions.map((question) => question.id))
+
+      setDynamicSteps([step])
+
       setResponses((prev) => {
         const next: Responses = { ...prev }
 
         if (nextStackId) {
           next[STACK_QUESTION_ID] = nextStackId
         }
 
-        step.questions.forEach((question) => {
-          if (question.id === STACK_QUESTION_ID) {
-            return
+        questionIds.forEach((questionId) => {
+          if (questionId !== STACK_QUESTION_ID && questionId in next) {
+            delete next[questionId]
           }
-
-          delete next[question.id]
         })
 
         return next
@@ -222,13 +261,27 @@ export function InstructionsWizard({
         let didMutate = false
         const next = { ...prev }
 
-        step.questions.forEach((question) => {
-          if (question.id === STACK_QUESTION_ID) {
-            return
+        questionIds.forEach((questionId) => {
+          if (questionId !== STACK_QUESTION_ID && questionId in next) {
+            delete next[questionId]
+            didMutate = true
           }
+        })
+
+        return didMutate ? next : prev
+      })
+
+      setFreeTextDrafts((prev) => {
+        if (Object.keys(prev).length === 0) {
+          return prev
+        }
+
+        let didMutate = false
+        const next = { ...prev }
 
-          if (next[question.id] !== undefined) {
-            delete next[question.id]
+        questionIds.forEach((questionId) => {
+          if (questionId !== STACK_QUESTION_ID && questionId in next) {
+            delete next[questionId]
             didMutate = true
           }
         })
@@ -239,6 +292,8 @@ export function InstructionsWizard({
       setCurrentStepIndex(1)
       setCurrentQuestionIndex(0)
       setAutoFilledQuestionMap({})
+
+      lastAppliedStackStepSignature.current = stepSignature
     },
     []
   )
@@ -415,6 +470,7 @@ export function InstructionsWizard({
     })
 
     setFreeTextResponses((prev) => (Object.keys(prev).length > 0 ? {} : prev))
+    setFreeTextDrafts((prev) => (Object.keys(prev).length > 0 ? {} : prev))
 
     markQuestionsAutoFilled(autoFilledIds)
     setIsStackFastTrackPromptVisible(false)
@@ -517,7 +573,7 @@ export function InstructionsWizard({
       const { value } = event.target
       let didChange = false
 
-      setFreeTextResponses((prev) => {
+      setFreeTextDrafts((prev) => {
         const existing = prev[question.id]
 
         if (value.length === 0) {
@@ -569,7 +625,9 @@ export function InstructionsWizard({
   ) => {
     const allowAutoAdvance = options?.allowAutoAdvance ?? true
     const trimmedValue = rawValue.trim()
-    const existingValue = typeof freeTextResponses[question.id] === "string" ? freeTextResponses[question.id] : ""
+    const draftValue = typeof freeTextDrafts[question.id] === "string" ? freeTextDrafts[question.id] : ""
+    const savedValue = typeof freeTextResponses[question.id] === "string" ? freeTextResponses[question.id] : ""
+    const existingValue = savedValue
 
     if (trimmedValue === existingValue) {
       if (allowAutoAdvance && trimmedValue.length > 0 && !hasSelectionForQuestion(question)) {
@@ -578,6 +636,18 @@ export function InstructionsWizard({
         }, 0)
       }
 
+      if (draftValue.length > 0) {
+        setFreeTextDrafts((prev) => {
+          if (!(question.id in prev)) {
+            return prev
+          }
+
+          const next = { ...prev }
+          delete next[question.id]
+          return next
+        })
+      }
+
       return
     }
 
@@ -598,6 +668,26 @@ export function InstructionsWizard({
       }
     })
 
+    setFreeTextDrafts((prev) => {
+      if (trimmedValue.length === 0) {
+        if (!(question.id in prev)) {
+          return prev
+        }
+
+        const next = { ...prev }
+        delete next[question.id]
+        return next
+      }
+
+      if (!(question.id in prev)) {
+        return prev
+      }
+
+      const next = { ...prev }
+      delete next[question.id]
+      return next
+    })
+
     clearAutoFilledFlag(question.id)
 
     if (allowAutoAdvance && trimmedValue.length > 0 && !hasSelectionForQuestion(question)) {
@@ -660,6 +750,7 @@ export function InstructionsWizard({
     const stackIdToClear = selectedStackId
     setResponses({})
     setFreeTextResponses({})
+    setFreeTextDrafts({})
     setDynamicSteps([])
     setCurrentStepIndex(0)
     setCurrentQuestionIndex(0)
@@ -856,6 +947,7 @@ export function InstructionsWizard({
               <form
                 className="flex flex-col gap-2 sm:flex-row sm:items-center"
                 onSubmit={handleFreeTextSubmit}
+                data-testid="wizard-free-text-form"
               >
                 <Input
                   id={freeTextInputId}
@@ -866,7 +958,13 @@ export function InstructionsWizard({
                   autoComplete="off"
                 />
                 <div className="flex gap-2">
-                  <Button type="submit" size="sm" disabled={!canSubmitFreeText}>
+                  <Button
+                    type="submit"
+                    size="sm"
+                    disabled={!canSubmitFreeText}
+                    data-can-submit={canSubmitFreeText ? "true" : "false"}
+                    data-free-text-length={currentFreeTextValue.length}
+                  >
                     Save custom answer
                   </Button>
                   {currentFreeTextValue.length > 0 ? (

playwright/tests/wizard-free-text.spec.ts

@@ -29,15 +29,14 @@ test("wizard accepts custom free text answers and shows them in the summary", as
 
   await expect(customInput).toBeVisible()
   await customInput.click()
-  await customInput.fill("")
-  await customInput.type(customAnswer)
+  await customInput.fill(customAnswer)
   await expect(customInput).toHaveValue(customAnswer)
 
   const saveButton = page.getByRole("button", { name: "Save custom answer" })
   await expect(saveButton).toBeEnabled()
-  await customInput.press("Enter")
-
-  await expect(questionHeading).toHaveText("What language do you use?")
+  await page.getByTestId("wizard-free-text-form").evaluate((form) => {
+    (form as HTMLFormElement).requestSubmit()
+  })
 
   await expect.poll(
     () =>
@@ -58,6 +57,8 @@ test("wizard accepts custom free text answers and shows them in the summary", as
     { timeout: 15000 }
   ).toBe(customAnswer)
 
+  await expect(questionHeading).toHaveText("What language do you use?")
+
   const storedState = await page.evaluate(() => {
     const raw = window.localStorage.getItem("devcontext:wizard:react")
     return raw ? JSON.parse(raw) : null

playwright/tests/wizard.spec.ts

@@ -21,8 +21,8 @@ test('wizard supports filtering, defaults, and reset', async ({ page }) => {
 
   const defaultButton = page.getByRole('button', { name: 'Use default (Vite)' })
   await expect(defaultButton).toBeEnabled()
-  await defaultButton.click()
-  await expect(defaultButton).toBeDisabled()
+  await defaultButton.click({ noWaitAfter: true })
+  await expect(questionHeading).toHaveText('What language do you use?')
 
   await expect.poll(
     () =>