fix(state): model component useState as single source of truth

- edit-knowledge-base-modal: reset fields on closed→open via prevOpenRef
  render idiom instead of mirroring props into state through useEffect
  (a prop change while open no longer clobbers in-progress edits)
- use-verification: collapse contradictory isLoading/isVerified/isInvalidOtp
  booleans into a single status enum + errorMessage; consumer derives flags
- contact-form / demo-request-modal: derive busy/success from the mutation
  object; delete duplicated submitSuccess local state
- sim-hooks.md: add state-shape rule (no props-into-state, status enum,
  derive mutation state)

Author: waleedlatif1

.claude/rules/sim-hooks.md

@@ -48,3 +48,19 @@ export function useFeature({ id, onSelect }: UseFeatureProps) {
 4. Wrap returned functions in useCallback
 5. Server data goes through React Query (`hooks/queries/`), never `useState` + `fetch`
 6. Keep only UI/orchestration state in these hooks
+
+## State shape
+
+Never mirror a prop into state with `useState(prop)` + a syncing `useEffect` — a prop change clobbers in-progress local edits. Use the prop directly, reset via a remount `key`, or — when you must seed local state from a prop only on a transition (e.g. a modal opening) — reset during render with the `prevX` ref idiom:
+
+```typescript
+const prevOpenRef = useRef(open)
+if (prevOpenRef.current !== open) {
+  prevOpenRef.current = open
+  if (open) setName(initialName) // closed → open only
+}
+```
+
+Model mutually-exclusive flags as ONE `status` enum, not several contradictory booleans. `isLoading`/`isVerified`/`isInvalidOtp` describing one machine collapse to `status: 'idle' | 'verifying' | 'verified' | 'error'` (+ `errorMessage`); derive any boolean a consumer still needs (`status === 'error'`).
+
+Derive busy/success from the mutation object — never duplicate `mutation.isPending`/`mutation.isSuccess` into local `useState`. Read them directly (`mutation.isSuccess`) and reset with `mutation.reset()`.

apps/sim/app/(auth)/verify/use-verification.ts

@@ -9,6 +9,15 @@ import { validateCallbackUrl } from '@/lib/core/security/input-validation'
 
 const logger = createLogger('useVerification')
 
+/**
+ * Mutually-exclusive phases of the email-OTP verification machine.
+ * - `idle`: awaiting input
+ * - `verifying`: a verify request is in flight
+ * - `verified`: code accepted, redirecting
+ * - `error`: last verify attempt failed (paired with `errorMessage`)
+ */
+type VerificationStatus = 'idle' | 'verifying' | 'verified' | 'error'
+
 interface UseVerificationParams {
   hasEmailService: boolean
   isProduction: boolean
@@ -18,9 +27,8 @@ interface UseVerificationParams {
 interface UseVerificationReturn {
   otp: string
   email: string
-  isLoading: boolean
-  isVerified: boolean
-  isInvalidOtp: boolean
+  status: VerificationStatus
+  isResending: boolean
   errorMessage: string
   isOtpComplete: boolean
   hasEmailService: boolean
@@ -41,10 +49,9 @@ export function useVerification({
   const { refetch: refetchSession } = useSession()
   const [otp, setOtp] = useState('')
   const [email, setEmail] = useState('')
-  const [isLoading, setIsLoading] = useState(false)
-  const [isVerified, setIsVerified] = useState(false)
+  const [status, setStatus] = useState<VerificationStatus>('idle')
+  const [isResending, setIsResending] = useState(false)
   const [isSendingInitialOtp, setIsSendingInitialOtp] = useState(false)
-  const [isInvalidOtp, setIsInvalidOtp] = useState(false)
   const [errorMessage, setErrorMessage] = useState('')
   const [redirectUrl, setRedirectUrl] = useState<string | null>(null)
   const [isInviteFlow, setIsInviteFlow] = useState(false)
@@ -96,8 +103,7 @@ export function useVerification({
   async function verifyCode() {
     if (!isOtpComplete || !email) return
 
-    setIsLoading(true)
-    setIsInvalidOtp(false)
+    setStatus('verifying')
     setErrorMessage('')
 
     try {
@@ -108,7 +114,7 @@ export function useVerification({
       })
 
       if (response && !response.error) {
-        setIsVerified(true)
+        setStatus('verified')
 
         try {
           await refetchSession()
@@ -135,12 +141,9 @@ export function useVerification({
       } else {
         logger.info('Setting invalid OTP state - API error response')
         const message = 'Invalid verification code. Please check and try again.'
-        setIsInvalidOtp(true)
+        setStatus('error')
         setErrorMessage(message)
-        logger.info('Error state after API error:', {
-          isInvalidOtp: true,
-          errorMessage: message,
-        })
+        logger.info('Error state after API error:', { errorMessage: message })
         setOtp('')
       }
     } catch (error: any) {
@@ -155,23 +158,18 @@ export function useVerification({
         message = 'Too many failed attempts. Please request a new code.'
       }
 
-      setIsInvalidOtp(true)
+      setStatus('error')
       setErrorMessage(message)
-      logger.info('Error state after caught error:', {
-        isInvalidOtp: true,
-        errorMessage: message,
-      })
+      logger.info('Error state after caught error:', { errorMessage: message })
 
       setOtp('')
-    } finally {
-      setIsLoading(false)
     }
   }
 
   function resendCode() {
     if (!email || !hasEmailService || !isEmailVerificationEnabled) return
 
-    setIsLoading(true)
+    setIsResending(true)
     setErrorMessage('')
 
     const normalizedEmail = normalizeEmail(email)
@@ -185,32 +183,32 @@ export function useVerification({
         setErrorMessage('Failed to resend verification code. Please try again later.')
       })
       .finally(() => {
-        setIsLoading(false)
+        setIsResending(false)
       })
   }
 
   function handleOtpChange(value: string) {
-    if (value.length === 6) {
-      setIsInvalidOtp(false)
+    if (value.length === 6 && status === 'error') {
+      setStatus('idle')
       setErrorMessage('')
     }
     setOtp(value)
   }
 
   useEffect(() => {
-    if (otp.length === 6 && email && !isLoading && !isVerified) {
+    if (otp.length === 6 && email && status !== 'verifying' && status !== 'verified') {
       const timeoutId = setTimeout(() => {
         verifyCode()
       }, 300)
 
       return () => clearTimeout(timeoutId)
     }
-  }, [otp, email, isLoading, isVerified])
+  }, [otp, email, status])
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
       if (!isEmailVerificationEnabled) {
-        setIsVerified(true)
+        setStatus('verified')
 
         const handleRedirect = async () => {
           try {
@@ -234,9 +232,8 @@ export function useVerification({
   return {
     otp,
     email,
-    isLoading,
-    isVerified,
-    isInvalidOtp,
+    status,
+    isResending,
     errorMessage,
     isOtpComplete,
     hasEmailService,

apps/sim/app/(auth)/verify/verify-content.tsx

@@ -25,16 +25,19 @@ function VerificationForm({
   const {
     otp,
     email,
-    isLoading,
-    isVerified,
-    isInvalidOtp,
+    status,
+    isResending,
     errorMessage,
     isOtpComplete,
     verifyCode,
     resendCode,
     handleOtpChange,
   } = useVerification({ hasEmailService, isProduction, isEmailVerificationEnabled })
 
+  const isVerified = status === 'verified'
+  const isInvalidOtp = status === 'error'
+  const isBusy = status === 'verifying' || isResending
+
   const [countdown, setCountdown] = useState(0)
   const [isResendDisabled, setIsResendDisabled] = useState(false)
 
@@ -88,7 +91,7 @@ function VerificationForm({
                 maxLength={6}
                 value={otp}
                 onChange={handleOtpChange}
-                disabled={isLoading}
+                disabled={isBusy}
                 className={cn('gap-2', isInvalidOtp && 'otp-error')}
               >
                 <InputOTPGroup>
@@ -112,10 +115,10 @@ function VerificationForm({
 
           <button
             onClick={verifyCode}
-            disabled={!isOtpComplete || isLoading}
+            disabled={!isOtpComplete || isBusy}
             className={AUTH_SUBMIT_BTN}
           >
-            {isLoading ? (
+            {isBusy ? (
               <span className='flex items-center gap-2'>
                 <Loader className='size-4' animate />
                 Verifying…
@@ -138,7 +141,7 @@ function VerificationForm({
                   <button
                     className='font-medium text-[var(--landing-text)] underline-offset-4 transition hover:text-white hover:underline'
                     onClick={handleResend}
-                    disabled={isLoading || isResendDisabled}
+                    disabled={isBusy || isResendDisabled}
                   >
                     Resend
                   </button>

apps/sim/app/(landing)/components/contact/contact-form.tsx

@@ -69,7 +69,6 @@ export function ContactForm() {
       captureClientEvent('landing_contact_submitted', { topic: variables.topic })
       setForm(INITIAL_FORM_STATE)
       setErrors({})
-      setSubmitSuccess(true)
     },
     onError: () => {
       turnstileRef.current?.reset()
@@ -78,7 +77,6 @@ export function ContactForm() {
 
   const [form, setForm] = useState<ContactFormState>(INITIAL_FORM_STATE)
   const [errors, setErrors] = useState<ContactErrors>({})
-  const [submitSuccess, setSubmitSuccess] = useState(false)
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [website, setWebsite] = useState('')
   const [widgetReady, setWidgetReady] = useState(false)
@@ -141,6 +139,7 @@ export function ContactForm() {
   }
 
   const isBusy = contactMutation.isPending || isSubmitting
+  const submitSuccess = contactMutation.isSuccess
 
   const submitError = contactMutation.isError
     ? toError(contactMutation.error).message || 'Failed to send message. Please try again.'
@@ -161,7 +160,7 @@ export function ContactForm() {
         </p>
         <button
           type='button'
-          onClick={() => setSubmitSuccess(false)}
+          onClick={() => contactMutation.reset()}
           className='mt-6 font-season text-[13px] text-[var(--landing-text)] underline underline-offset-2 transition-opacity hover:opacity-80'
         >
           Send another message

apps/sim/app/(landing)/components/demo-request/demo-request-modal.tsx

@@ -69,22 +69,21 @@ export function DemoRequestModal({ children, theme = 'dark' }: DemoRequestModalP
   const [open, setOpen] = useState(false)
   const [form, setForm] = useState<DemoRequestFormState>(INITIAL_FORM_STATE)
   const [errors, setErrors] = useState<DemoRequestErrors>({})
-  const [submitSuccess, setSubmitSuccess] = useState(false)
 
   const demoMutation = useMutation({
     mutationFn: submitDemoRequest,
     onSuccess: (_data, variables) => {
       captureClientEvent('landing_demo_request_submitted', {
         company_size: variables.companySize,
       })
-      setSubmitSuccess(true)
     },
   })
 
+  const submitSuccess = demoMutation.isSuccess
+
   function resetForm() {
     setForm(INITIAL_FORM_STATE)
     setErrors({})
-    setSubmitSuccess(false)
     demoMutation.reset()
   }
 

apps/sim/app/workspace/[workspaceId]/knowledge/components/edit-knowledge-base-modal/edit-knowledge-base-modal.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { memo, useEffect, useState } from 'react'
+import { memo, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import {
@@ -44,15 +44,18 @@ export const EditKnowledgeBaseModal = memo(function EditKnowledgeBaseModal({
   const [isSubmitting, setIsSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
 
-  useEffect(() => {
+  // Reset form fields when the modal opens (open transitions false → true).
+  const prevOpenRef = useRef(open)
+  if (prevOpenRef.current !== open) {
+    prevOpenRef.current = open
     if (open) {
       setName(initialName)
       setDescription(initialDescription)
       setNameError(null)
       setDescriptionError(null)
       setError(null)
     }
-  }, [open, initialName, initialDescription])
+  }
 
   const validate = (): boolean => {
     let valid = true