@reformer/core 1.1.0-beta.8 → 2.0.0-beta.2

package/llms.txt

@@ -1,6 +1,6 @@
 # ReFormer - LLM Integration Guide
 
-## 1. QUICK REFERENCE
+## 1. API Reference
 
 ### Imports (CRITICALLY IMPORTANT)
 
@@ -30,16 +30,16 @@
 | `useFormControl(field)` | `{ value, errors, disabled, touched, ... }` | All signals | Full field state, form inputs |
 | `useFormControlValue(field)` | `T` (value directly) | Only value signal | Conditional rendering |
 
-⚠️ **CRITICAL**: Do NOT destructure `useFormControlValue`! It returns `T` directly, NOT `{ value: T }`.
+**CRITICAL**: Do NOT destructure `useFormControlValue`! It returns `T` directly, NOT `{ value: T }`.
 
 ```typescript
-// ❌ WRONG - will always be undefined!
+// WRONG - will always be undefined!
 const { value: loanType } = useFormControlValue(control.loanType);
 
-// ✅ CORRECT
+// CORRECT
 const loanType = useFormControlValue(control.loanType);
 
-// ✅ CORRECT - useFormControl returns object, destructuring OK
+// CORRECT - useFormControl returns object, destructuring OK
 const { value, errors, disabled } = useFormControl(control.loanType);
 ```
 
@@ -143,7 +143,7 @@ validateTree(validator: (ctx) => ValidationError | null, options?: { targetField
 // Conditional validation (3 arguments!)
 applyWhen(fieldPath, condition: (fieldValue) => boolean, validatorsFn: (path) => void)
 
-// ⚠️ applyWhen Examples - CRITICALLY IMPORTANT
+// applyWhen Examples - CRITICALLY IMPORTANT
 // applyWhen takes 3 arguments: triggerField, condition, validators
 
 // Example 1: Simple condition
@@ -176,7 +176,7 @@ applyWhen(
   }
 );
 
-// ❌ WRONG - only 2 arguments (React Hook Form pattern)
+// WRONG - only 2 arguments (React Hook Form pattern)
 applyWhen(
   (form) => form.loanType === 'mortgage',  // WRONG!
   () => { required(path.propertyValue); }
@@ -197,8 +197,8 @@ disableWhen(path, condition: (form) => boolean)
 // Computed fields (same nesting level)
 computeFrom(sourcePaths[], targetPath, compute: (values) => result, options?: { debounce?: number; condition?: (form) => boolean })
 
-// Watch field changes
-watchField(path, callback: (value, ctx: BehaviorContext) => void, options?: { immediate?: boolean; debounce?: number })
+// Watch field changes (ALWAYS use { immediate: false } to prevent cycle detection!)
+watchField(path, callback: (value, ctx: BehaviorContext) => void, options: { immediate: false; debounce?: number })
 
 // Copy values between fields
 copyFrom(sourcePath, targetPath, options?: { when?: (form) => boolean; fields?: string[]; transform?: (value) => value })
@@ -206,8 +206,8 @@ copyFrom(sourcePath, targetPath, options?: { when?: (form) => boolean; fields?:
 // Reset field when condition met
 resetWhen(path, condition: (form) => boolean, options?: { toValue?: any })
 
-// Re-validate when another field changes
-revalidateWhen(triggerPath, targetPath)
+// Re-validate target field when any trigger changes
+revalidateWhen(targetPath, triggerPaths[], options?: { debounce?: number })
 
 // Sync multiple fields
 syncFields(paths[], options?: { bidirectional?: boolean })
@@ -220,7 +220,7 @@ transformers.trim, transformers.toUpperCase, transformers.toLowerCase, transform
 interface BehaviorContext<TForm> {
   form: GroupNodeWithControls<TForm>;            // Form proxy with typed field access
   setFieldValue: (path: string, value: any) => void;
-  // ⚠️ To READ field values, use: ctx.form.fieldName.value.value
+  // To READ field values, use: ctx.form.fieldName.value.value
 }
 ```
 
@@ -241,7 +241,7 @@ enableWhen(path.mortgageFields, (form) => form.loanType === 'mortgage', {
 // Use watchField instead:
 watchField(path.nested.field, (value, ctx) => {
   ctx.setFieldValue('rootField', computedValue);
-});
+}, { immediate: false });
 ```
 
 ### Type-Safe useFormControl
@@ -250,31 +250,60 @@ watchField(path.nested.field, (value, ctx) => {
 const { value } = useFormControl(form.field as FieldNode<ExpectedType>);
 ```
 
-## 4. ⚠️ COMMON MISTAKES
+### Validation Priority (IMPORTANT)
+
+**Always prefer built-in validators over custom ones:**
+
+```typescript
+// 1. BEST: Use built-in validators when available
+required(path.email);
+email(path.email);
+min(path.age, 18);
+minLength(path.password, 8);
+pattern(path.phone, /^\+7\d{10}$/);
+
+// 2. GOOD: Use validate() only when no built-in validator exists
+validate(path.customField, (value, ctx) => {
+  // Custom logic that can't be expressed with built-in validators
+  if (customCondition(value)) {
+    return { code: 'custom', message: 'Custom error' };
+  }
+  return null;
+});
+
+// 3. WRONG: Don't recreate built-in validators
+validate(path.email, (value) => {
+  if (!value) return { code: 'required', message: 'Required' };  // Use required() instead!
+  if (!value.includes('@')) return { code: 'email', message: 'Invalid' };  // Use email() instead!
+  return null;
+});
+```
+
+## 4. COMMON MISTAKES
 
 ### useFormControlValue (CRITICAL)
 
 ```typescript
-// ❌ WRONG - useFormControlValue returns T directly, NOT { value: T }
+// WRONG - useFormControlValue returns T directly, NOT { value: T }
 const { value: loanType } = useFormControlValue(control.loanType);
 // Result: loanType is ALWAYS undefined! Conditional rendering will fail.
 
-// ✅ CORRECT
+// CORRECT
 const loanType = useFormControlValue(control.loanType);
 
-// ✅ ALSO CORRECT - useFormControl returns object
+// ALSO CORRECT - useFormControl returns object
 const { value, errors } = useFormControl(control.loanType);
 ```
 
 ### Reading Field Values in BehaviorContext (CRITICAL)
 
 ```typescript
-// ❌ WRONG - getFieldValue does NOT exist!
+// WRONG - getFieldValue does NOT exist!
 watchField(path.amount, (amount, ctx) => {
   const rate = ctx.getFieldValue('rate'); // ERROR: Property 'getFieldValue' does not exist
 });
 
-// ✅ CORRECT - use ctx.form.fieldName.value.value
+// CORRECT - use ctx.form.fieldName.value.value
 watchField(path.amount, (amount, ctx) => {
   const rate = ctx.form.rate.value.value;  // Read via signal
   ctx.setFieldValue('total', amount * rate);
@@ -284,21 +313,21 @@ watchField(path.amount, (amount, ctx) => {
 ### Validators
 
 ```typescript
-// ❌ WRONG
+// WRONG
 required(path.email, 'Email is required');
 
-// ✅ CORRECT
+// CORRECT
 required(path.email, { message: 'Email is required' });
 ```
 
 ### Types
 
 ```typescript
-// ❌ WRONG
+// WRONG
 amount: number | null;
 [key: string]: unknown;
 
-// ✅ CORRECT
+// CORRECT
 amount: number | undefined;
 // No index signature
 ```
@@ -306,10 +335,10 @@ amount: number | undefined;
 ### computeFrom
 
 ```typescript
-// ❌ WRONG - different nesting levels
+// WRONG - different nesting levels
 computeFrom([path.nested.a, path.nested.b], path.root, ...)
 
-// ✅ CORRECT - use watchField
+// CORRECT - use watchField
 watchField(path.nested.a, (_, ctx) => {
   ctx.setFieldValue('root', computed);
 });
@@ -318,10 +347,10 @@ watchField(path.nested.a, (_, ctx) => {
 ### Imports
 
 ```typescript
-// ❌ WRONG - types are not in submodules
+// WRONG - types are not in submodules
 import { ValidationSchemaFn } from '@reformer/core/validators';
 
-// ✅ CORRECT - types from main module
+// CORRECT - types from main module
 import type { ValidationSchemaFn } from '@reformer/core';
 import { required, email } from '@reformer/core/validators';
 ```
@@ -335,6 +364,7 @@ import { required, email } from '@reformer/core/validators';
 | `FormFields[]` instead of concrete type                | Type inference issue           | Use `as FieldNode<T>`             |
 | `Type 'X' is missing properties from type 'Y'`         | Cross-level computeFrom        | Use watchField instead            |
 | `Module has no exported member`                        | Wrong import source            | Types from core, functions from submodules |
+| `Cycle detected`                                       | Multiple watchers on same field calling disable/setValue | See 22-cycle-detection.md |
 
 ## 6. COMPLETE IMPORT EXAMPLE
 
@@ -361,7 +391,7 @@ import { computeFrom, enableWhen, watchField, copyFrom } from '@reformer/core/be
 ## 7. FORM TYPE DEFINITION
 
 ```typescript
-// ✅ CORRECT form type definition
+// CORRECT form type definition
 interface MyForm {
   // Required fields
   name: string;
@@ -390,7 +420,7 @@ interface MyForm {
 
 ## 8. FORMSCHEMA FORMAT (CRITICALLY IMPORTANT)
 
-⚠️ **Every field MUST have `value` and `component` properties!**
+**Every field MUST have `value` and `component` properties!**
 
 ### FieldConfig Interface
 
@@ -477,13 +507,13 @@ const schema: FormSchema<MyForm> = {
 };
 ```
 
-### ❌ WRONG - This will NOT compile
+### WRONG - This will NOT compile
 
 ```typescript
 // Missing value and component - TypeScript will error!
 const schema = {
-  name: '',           // ❌ Wrong
-  email: '',          // ❌ Wrong
+  name: '',           // Wrong
+  email: '',          // Wrong
 };
 ```
 
@@ -503,7 +533,7 @@ form.address.city.value.value; // Get current value
 form.items.push({ id: '1', name: 'Item' }); // Array operations
 ```
 
-### ⚠️ createForm Returns a Proxy
+### createForm Returns a Proxy
 
 ```typescript
 // createForm() returns GroupNodeWithControls<T> (a Proxy wrapper around GroupNode)
@@ -514,12 +544,12 @@ form.email           // FieldNode<string> - TypeScript knows the type!
 form.address.city    // FieldNode<string> - nested access works
 form.items.at(0)     // GroupNodeWithControls<ItemType> - array items
 
-// ⚠️ IMPORTANT: Proxy doesn't pass instanceof checks!
+// IMPORTANT: Proxy doesn't pass instanceof checks!
 // Use type guards instead:
 import { isFieldNode, isGroupNode, isArrayNode } from '@reformer/core';
 
-if (isFieldNode(node)) { /* ... */ }   // ✅ Works with Proxy
-if (node instanceof FieldNode) { /* ... */ } // ❌ Fails with Proxy!
+if (isFieldNode(node)) { /* ... */ }   // Works with Proxy
+if (node instanceof FieldNode) { /* ... */ } // Fails with Proxy!
 ```
 
 ## 9. ARRAY SCHEMA FORMAT
@@ -527,7 +557,7 @@ if (node instanceof FieldNode) { /* ... */ } // ❌ Fails with Proxy!
 **Array items are sub-forms!** Each array element is a complete sub-form with its own fields, validation, and behavior.
 
 ```typescript
-// ✅ CORRECT - use tuple format for arrays
+// CORRECT - use tuple format for arrays
 // The template item defines the sub-form schema for each array element
 const itemSchema = {
   id: { value: '', component: Input },
@@ -548,7 +578,7 @@ form.items.map((item) => {
 ```
 
 ```typescript
-// ❌ WRONG - object format is NOT supported
+// WRONG - object format is NOT supported
 const schema = {
   items: { schema: itemSchema, initialItems: [] }, // This will NOT work
 };
@@ -578,7 +608,7 @@ validateItems(path.items, (itemPath) => {
 ## 10. ASYNC WATCHFIELD (CRITICALLY IMPORTANT)
 
 ```typescript
-// ✅ CORRECT - async watchField with ALL safeguards
+// CORRECT - async watchField with ALL safeguards
 watchField(
   path.parentField,
   async (value, ctx) => {
@@ -595,7 +625,7 @@ watchField(
   { immediate: false, debounce: 300 }  // REQUIRED options
 );
 
-// ❌ WRONG - missing safeguards
+// WRONG - missing safeguards
 watchField(path.field, async (value, ctx) => {
   const { data } = await fetchData(value);  // Will fail silently!
 });
@@ -610,7 +640,7 @@ watchField(path.field, async (value, ctx) => {
 ## 11. ARRAY CLEANUP PATTERN
 
 ```typescript
-// ✅ CORRECT - cleanup array when checkbox unchecked
+// CORRECT - cleanup array when checkbox unchecked
 watchField(
   path.hasItems,
   (hasItems, ctx) => {
@@ -621,7 +651,7 @@ watchField(
   { immediate: false }
 );
 
-// ❌ WRONG - no immediate: false, no null check
+// WRONG - no immediate: false, no null check
 watchField(path.hasItems, (hasItems, ctx) => {
   if (!hasItems) ctx.form.items.clear();  // May crash on init!
 });
@@ -709,17 +739,17 @@ function MultiStepForm() {
 }
 ```
 
-## 13. ⚠️ EXTENDED COMMON MISTAKES
+## 13. EXTENDED COMMON MISTAKES
 
 ### Behavior Composition (Cycle Error)
 
 ```typescript
-// ❌ WRONG - apply() in behavior causes "Cycle detected"
+// WRONG - apply() in behavior causes "Cycle detected"
 const mainBehavior: BehaviorSchemaFn<Form> = (path) => {
   apply(addressBehavior, path.address);  // WILL FAIL!
 };
 
-// ✅ CORRECT - inline or use setup function
+// CORRECT - inline or use setup function
 const setupAddressBehavior = (path: FieldPath<Address>) => {
   watchField(path.region, async (region, ctx) => {
     // ...
@@ -734,12 +764,12 @@ const mainBehavior: BehaviorSchemaFn<Form> = (path) => {
 ### Infinite Loop in watchField
 
 ```typescript
-// ❌ WRONG - causes infinite loop
+// WRONG - causes infinite loop
 watchField(path.field, (value, ctx) => {
   ctx.form.field.setValue(value.toUpperCase());  // Loop!
 });
 
-// ✅ CORRECT - write to different field OR add guard
+// CORRECT - write to different field OR add guard
 watchField(path.input, (value, ctx) => {
   const upper = value?.toUpperCase() || '';
   if (ctx.form.display.value.value !== upper) {
@@ -748,13 +778,53 @@ watchField(path.input, (value, ctx) => {
 }, { immediate: false });
 ```
 
+### Multiple Watchers on Same Field (Cycle Error)
+
+```typescript
+// WRONG - multiple watchers on insuranceType + missing { immediate: false }
+watchField(path.insuranceType, (_, ctx) => {
+  ctx.form.vehicle.vin.disable();
+  ctx.form.vehicle.vin.setValue('');
+});  // NO OPTIONS - BAD!
+watchField(path.insuranceType, (_, ctx) => {
+  ctx.form.property.type.disable();  // CYCLE!
+});  // NO OPTIONS - BAD!
+
+// CORRECT - consolidate into ONE watcher with guards AND { immediate: false }
+watchField(path.insuranceType, (_, ctx) => {
+  const type = ctx.form.insuranceType.value.value;
+  const isVehicle = type === 'casco';
+
+  // Guard: only disable if not already disabled
+  if (!isVehicle && !ctx.form.vehicle.vin.disabled.value) {
+    ctx.form.vehicle.vin.disable();
+  }
+  // Guard: only setValue if value differs
+  if (!isVehicle && ctx.form.vehicle.vin.getValue() !== '') {
+    ctx.form.vehicle.vin.setValue('');
+  }
+  // Arrays: compare by length, not reference
+  if (!isVehicle) {
+    const drivers = ctx.form.drivers.getValue();
+    if (Array.isArray(drivers) && drivers.length > 0) {
+      ctx.form.drivers.setValue([]);
+    }
+  }
+}, { immediate: false });  // REQUIRED!
+
+// BEST - use enableWhen instead of watchField
+enableWhen(path.vehicle.vin, (form) => form.insuranceType === 'casco', { resetOnDisable: true });
+```
+
+See `22-cycle-detection.md` for complete pattern.
+
 ### validateTree Typing
 
 ```typescript
-// ❌ WRONG - implicit any
+// WRONG - implicit any
 validateTree((ctx) => { ... });
 
-// ✅ CORRECT - explicit typing
+// CORRECT - explicit typing
 validateTree((ctx: { form: MyForm }) => {
   if (ctx.form.field1 > ctx.form.field2) {
     return { code: 'error', message: 'Invalid' };
@@ -891,11 +961,7 @@ interface SelectFieldProps<T extends string> {
   options: Array<{ value: T; label: string }>;
 }
 
-function SelectField<T extends string>({
-  control,
-  label,
-  options
-}: SelectFieldProps<T>) {
+function SelectField<T extends string>({ control, label, options }: SelectFieldProps<T>) {
   const { value, errors, disabled, touched } = useFormControl(control);
 
   return (
@@ -912,9 +978,7 @@ function SelectField<T extends string>({
           </option>
         ))}
       </select>
-      {touched && errors[0] && (
-        <span className="error-message">{errors[0].message}</span>
-      )}
+      {touched && errors[0] && <span className="error-message">{errors[0].message}</span>}
     </div>
   );
 }
@@ -933,11 +997,7 @@ function ShadcnFormField({ control, label }: FormFieldProps<string>) {
   return (
     <div className="space-y-2">
       <Label>{label}</Label>
-      <Input
-        value={value}
-        onChange={(e) => control.setValue(e.target.value)}
-        disabled={disabled}
-      />
+      <Input value={value} onChange={(e) => control.setValue(e.target.value)} disabled={disabled} />
       {errors[0] && <p className="text-red-500">{errors[0].message}</p>}
     </div>
   );
@@ -946,9 +1006,9 @@ function ShadcnFormField({ control, label }: FormFieldProps<string>) {
 
 ## 15. NON-EXISTENT API (DO NOT USE)
 
-⚠️ **The following APIs do NOT exist in @reformer/core:**
+**The following APIs do NOT exist in @reformer/core:**
 
-| ❌ Wrong | ✅ Correct | Notes |
+| Wrong | Correct | Notes |
 |----------|-----------|-------|
 | `useForm` | `createForm` | There is no useForm hook |
 | `FieldSchema` | `FieldConfig<T>` | Type for individual field config |
@@ -965,13 +1025,13 @@ function ShadcnFormField({ control, label }: FormFieldProps<string>) {
 ### Common Import Errors
 
 ```typescript
-// ❌ WRONG - These do NOT exist
+// WRONG - These do NOT exist
 import { useForm } from '@reformer/core';           // NO!
 import { when } from '@reformer/core/validators';   // NO!
 import type { FieldSchema } from '@reformer/core';  // NO!
 import type { FormFields } from '@reformer/core';   // NO!
 
-// ✅ CORRECT
+// CORRECT
 import { createForm, useFormControl } from '@reformer/core';
 import { applyWhen } from '@reformer/core/validators';
 import type { FieldConfig, FieldNode } from '@reformer/core';
@@ -980,13 +1040,13 @@ import type { FieldConfig, FieldNode } from '@reformer/core';
 ### FormSchema Common Mistakes
 
 ```typescript
-// ❌ WRONG - Simple values don't work
+// WRONG - Simple values don't work
 const schema = {
   name: '',           // Missing { value, component }
   email: '',          // Missing { value, component }
 };
 
-// ✅ CORRECT - Every field needs value and component
+// CORRECT - Every field needs value and component
 const schema: FormSchema<MyForm> = {
   name: {
     value: '',
@@ -1001,97 +1061,14 @@ const schema: FormSchema<MyForm> = {
 };
 ```
 
-## 15.5 REACT HOOK FORM MIGRATION
-
-If you're familiar with React Hook Form, here's how to translate patterns to ReFormer:
-
-| React Hook Form | ReFormer | Notes |
-|-----------------|----------|-------|
-| `const { register, handleSubmit } = useForm()` | `const form = createForm({...})` | Call OUTSIDE component |
-| `register('fieldName')` | `useFormControl(form.fieldName)` | Returns control object |
-| `watch('fieldName')` | `useFormControlValue(form.fieldName)` | Returns value directly (NOT `{ value }`) |
-| `setValue('field', value)` | `form.field.setValue(value)` | Direct method call |
-| `getValues('field')` | `form.field.value.value` | Signal-based |
-| `formState.errors` | `useFormControl(form.field).errors` | Per-field errors array |
-| `formState.isValid` | `form.valid.value` | Signal |
-| `formState.isDirty` | `form.dirty.value` | Signal |
-| `handleSubmit(onSubmit)` | `form.submit(onSubmit)` | Built-in validation |
-| `<FormProvider form={...}>` | `<Component form={form} />` | Props, NOT context |
-| `useFormContext()` | Not needed | Pass form via props |
-| `useFieldArray({ name: 'items' })` | `form.items` (ArrayNode) | Direct array access |
-| `fields.map((field, index) => ...)` | `form.items.map((item, index) => ...)` | item is sub-form |
-| `append(data)` | `form.items.push(data)` | Add item |
-| `remove(index)` | `form.items.removeAt(index)` | Remove item |
-| `control` prop | Not needed | Form IS the control |
-
-### Key Differences
-
-1. **No Provider/Context** - Pass form directly via props
-   ```typescript
-   // ❌ React Hook Form pattern - doesn't exist in ReFormer
-   <FormProvider form={form}>
-     <NestedComponent />
-   </FormProvider>
-
-   // ✅ ReFormer pattern - pass via props
-   <NestedComponent form={form} />
-   ```
-
-2. **Form Creation Location** - Create outside component
-   ```typescript
-   // ❌ WRONG - creates new form on every render
-   function MyComponent() {
-     const form = createForm({...});
-   }
-
-   // ✅ CORRECT - create once, outside component
-   const form = createForm({...});
-   function MyComponent() {
-     const ctrl = useFormControl(form.name);
-   }
-   ```
-
-3. **Type-Safe Field Access** - No string paths
-   ```typescript
-   // React Hook Form
-   register('user.address.city')
-
-   // ReFormer - fully typed
-   form.user.address.city.setValue('New York')
-   ```
-
-4. **Array Items are Sub-Forms**
-   ```typescript
-   // React Hook Form
-   fields.map((field, index) => (
-     <input {...register(`items.${index}.name`)} />
-   ))
-
-   // ReFormer - each item is a typed GroupNode
-   form.items.map((item, index) => (
-     <FormField control={item.name} />  // item.name is FieldNode
-   ))
-   ```
-
-5. **Reading Values in Behaviors**
-   ```typescript
-   // React Hook Form
-   watch('fieldName')
-
-   // ReFormer in watchField callback
-   watchField(path.trigger, (value, ctx) => {
-     const other = ctx.form.otherField.value.value;  // Signal access
-   });
-   ```
-
 ## 16. READING FIELD VALUES (CRITICALLY IMPORTANT)
 
 ### Why .value.value?
 
 ReFormer uses `@preact/signals-core` for reactivity:
-- `field.value` → `Signal<T>` (reactive container)
-- `field.value.value` → `T` (actual value)
-- `field.getValue()` → `T` (shorthand method, non-reactive)
+- `field.value` -> `Signal<T>` (reactive container)
+- `field.value.value` -> `T` (actual value)
+- `field.getValue()` -> `T` (shorthand method, non-reactive)
 
 ```typescript
 // Reading values in different contexts:
@@ -1102,14 +1079,14 @@ const email = useFormControlValue(control.email);    // Value directly
 
 // In BehaviorContext (watchField, etc.)
 watchField(path.firstName, (firstName, ctx) => {
-  // ⚠️ ctx.form is typed as the PARENT GROUP of the watched field!
+  // ctx.form is typed as the PARENT GROUP of the watched field!
   // For path.nested.field: ctx.form = NestedType, NOT RootForm!
 
   const lastName = ctx.form.lastName.value.value;  // Read sibling field
 
   // Use setFieldValue with full path for root-level fields
   ctx.setFieldValue('fullName', `${firstName} ${lastName}`);
-});
+}, { immediate: false });  // REQUIRED to prevent cycle detection!
 
 // Direct access on form controls
 form.email.value.value;           // Read current value
@@ -1119,24 +1096,24 @@ form.address.city.value.value;    // Read nested value
 ### Reading Nested Values in watchField
 
 ```typescript
-// ⚠️ IMPORTANT: ctx.form type depends on the watched path!
+// IMPORTANT: ctx.form type depends on the watched path!
 
 // Watching root-level field
 watchField(path.loanAmount, (amount, ctx) => {
   // ctx.form is MyForm - can access all fields
   const rate = ctx.form.interestRate.value.value;
   ctx.setFieldValue('monthlyPayment', amount * rate / 12);
-});
+}, { immediate: false });
 
 // Watching nested field
 watchField(path.personalData.lastName, (lastName, ctx) => {
   // ctx.form is PersonalData, NOT MyForm!
-  const firstName = ctx.form.firstName.value.value;   // ✅ Works
-  const middleName = ctx.form.middleName.value.value; // ✅ Works
+  const firstName = ctx.form.firstName.value.value;   // Works
+  const middleName = ctx.form.middleName.value.value; // Works
 
   // For root-level field, use setFieldValue with full path
   ctx.setFieldValue('fullName', `${lastName} ${firstName}`);
-});
+}, { immediate: false });
 ```
 
 ## 17. COMPUTE FROM vs WATCH FIELD
@@ -1144,21 +1121,21 @@ watchField(path.personalData.lastName, (lastName, ctx) => {
 ### computeFrom - Same Nesting Level Only
 
 ```typescript
-// ✅ Works: all source fields and target at same level
+// Works: all source fields and target at same level
 computeFrom(
   [path.price, path.quantity],
   path.total,
   ({ price, quantity }) => (price || 0) * (quantity || 0)
 );
 
-// ✅ Works: all nested at same level
+// Works: all nested at same level
 computeFrom(
   [path.address.houseNumber, path.address.streetName],
   path.address.fullAddress,
   ({ houseNumber, streetName }) => `${houseNumber} ${streetName}`
 );
 
-// ❌ FAILS: different nesting levels
+// FAILS: different nesting levels
 computeFrom(
   [path.nested.price, path.nested.quantity],
   path.rootTotal,  // Different level - won't work!
@@ -1169,13 +1146,13 @@ computeFrom(
 ### watchField - Any Level
 
 ```typescript
-// ✅ Works for cross-level computation
+// Works for cross-level computation
 watchField(path.nested.price, (price, ctx) => {
   const quantity = ctx.form.quantity.value.value;  // Sibling in nested
   ctx.setFieldValue('rootTotal', price * quantity); // Full path to root
-});
+}, { immediate: false });  // REQUIRED!
 
-// ✅ Works for multiple dependencies
+// Works for multiple dependencies
 watchField(path.loanAmount, (amount, ctx) => {
   const term = ctx.form.loanTerm.value.value;
   const rate = ctx.form.interestRate.value.value;
@@ -1184,7 +1161,7 @@ watchField(path.loanAmount, (amount, ctx) => {
     const monthly = calculateMonthlyPayment(amount, term, rate);
     ctx.setFieldValue('monthlyPayment', monthly);
   }
-});
+}, { immediate: false });  // REQUIRED!
 ```
 
 ### Rule of Thumb
@@ -1198,18 +1175,18 @@ watchField(path.loanAmount, (amount, ctx) => {
 
 ## 18. ARRAY OPERATIONS
 
-### ⚠️ Array Access - CRITICAL
+### Array Access - CRITICAL
 
 ```typescript
-// ❌ WRONG - bracket notation does NOT work!
+// WRONG - bracket notation does NOT work!
 const first = form.items[0];        // undefined or error
 const second = form.items[1];       // undefined or error
 
-// ✅ CORRECT - use .at() method
+// CORRECT - use .at() method
 const first = form.items.at(0);     // GroupNodeWithControls<ItemType> | undefined
 const second = form.items.at(1);    // GroupNodeWithControls<ItemType> | undefined
 
-// ✅ CORRECT - iterate with map (most common pattern)
+// CORRECT - iterate with map (most common pattern)
 form.items.map((item, index) => {
   // item is fully typed GroupNode
   item.name.setValue('New Name');
@@ -1292,3 +1269,171 @@ validateTree((ctx: { form: MyForm }) => {
   }
   return null;
 }, { targetField: 'items' });
+```
+
+## Cycle Detection Prevention Checklist
+
+**ALWAYS follow these rules to prevent "Cycle detected" error:**
+
+1. ✅ **ONE watchField per trigger field** - consolidate all logic into single handler
+2. ✅ **ALWAYS use `{ immediate: false }`** - required option for watchField
+3. ✅ **Guard all disable/enable calls** - check `field.disabled.value` before calling
+4. ✅ **Guard all setValue calls** - only call if value actually differs
+5. ✅ **Arrays: compare by length** - `[] !== []` is always true, use `.length`
+6. ✅ **Prefer enableWhen over watchField** - for simple enable/disable logic
+
+---
+
+## Cycle Detected Error
+
+### Problem
+
+Error `Cycle detected` occurs when reactive system detects circular dependency during field updates.
+
+### Root Cause
+
+Multiple `watchField` handlers on the same field (e.g., `path.insuranceType`) each calling `disable()` and `setValue()` creates reactive cycles:
+
+```typescript
+// WRONG - Multiple watchers on same field + missing { immediate: false }
+watchField(path.insuranceType, (_, ctx) => {
+  // Handler 1: vehicle fields
+  if (!isVehicle) {
+    ctx.form.vehicle.vin.disable();
+    ctx.form.vehicle.vin.setValue('');
+  }
+});  // NO OPTIONS - BAD!
+
+watchField(path.insuranceType, (_, ctx) => {
+  // Handler 2: property fields - CAUSES CYCLE!
+  if (!isProperty) {
+    ctx.form.property.type.disable();
+    ctx.form.property.type.setValue('');
+  }
+});  // NO OPTIONS - BAD!
+
+// More watchers on same field = more cycles
+```
+
+### Solution
+
+1. **Consolidate all watchers for same field into ONE handler**
+2. **Check state before calling disable/enable/setValue**
+3. **ALWAYS add `{ immediate: false }` option**
+
+```typescript
+// CORRECT - Single consolidated watcher with guards AND { immediate: false }
+watchField(path.insuranceType, (_value, ctx) => {
+  const insuranceType = ctx.form.insuranceType.value.value;
+  const isVehicle = insuranceType === 'casco' || insuranceType === 'osago';
+  const isProperty = insuranceType === 'property';
+
+  // Helper: check if array value needs update (compare by length, not reference)
+  const needsValueUpdate = <T>(current: T, defaultVal: T): boolean => {
+    if (Array.isArray(current) && Array.isArray(defaultVal)) {
+      return current.length !== defaultVal.length;
+    }
+    return current !== defaultVal;
+  };
+
+  // Helper: disable only if not already disabled, setValue only if different
+  const disableAndReset = <T>(
+    field: { disable: () => void; setValue: (v: T) => void; getValue: () => T; disabled: { value: boolean } } | undefined,
+    defaultValue: T
+  ) => {
+    if (field) {
+      if (!field.disabled.value) {
+        field.disable();
+      }
+      if (needsValueUpdate(field.getValue(), defaultValue)) {
+        field.setValue(defaultValue);
+      }
+    }
+  };
+
+  const enableField = (field: { enable: () => void; disabled: { value: boolean } } | undefined) => {
+    if (field && field.disabled.value) {
+      field.enable();
+    }
+  };
+
+  // --- All vehicle fields in one place ---
+  if (isVehicle) {
+    enableField(ctx.form.vehicle.vin);
+    enableField(ctx.form.vehicle.brand);
+  } else {
+    disableAndReset(ctx.form.vehicle.vin, '');
+    disableAndReset(ctx.form.vehicle.brand, '');
+  }
+
+  // --- All property fields in one place ---
+  if (isProperty) {
+    enableField(ctx.form.property.type);
+  } else {
+    disableAndReset(ctx.form.property.type, '');
+  }
+
+  // --- Arrays: compare by length ---
+  if (isVehicle) {
+    enableField(ctx.form.drivers);
+  } else {
+    disableAndReset(ctx.form.drivers, []); // Won't call setValue if already empty
+  }
+}, { immediate: false });  // REQUIRED!
+```
+
+### Prefer Built-in Behaviors
+
+**Instead of complex watchField with guards, use built-in behaviors when possible:**
+
+```typescript
+// ❌ COMPLEX - watchField with manual guards (error-prone)
+watchField(path.insuranceType, (_value, ctx) => {
+  const isVehicle = ctx.form.insuranceType.value.value === 'casco';
+  if (isVehicle) {
+    if (ctx.form.vehicle.vin.disabled.value) ctx.form.vehicle.vin.enable();
+  } else {
+    if (!ctx.form.vehicle.vin.disabled.value) ctx.form.vehicle.vin.disable();
+    if (ctx.form.vehicle.vin.getValue() !== '') ctx.form.vehicle.vin.setValue('');
+  }
+}, { immediate: false });
+
+// ✅ SIMPLE - enableWhen with resetOnDisable (recommended)
+enableWhen(path.vehicle.vin, (form) => form.insuranceType === 'casco', { resetOnDisable: true });
+enableWhen(path.vehicle.brand, (form) => form.insuranceType === 'casco', { resetOnDisable: true });
+```
+
+### Key Rules
+
+1. **ONE watcher per trigger field** - consolidate all logic for `insuranceType` into single `watchField`
+2. **ALWAYS use `{ immediate: false }`** - prevents execution during initialization
+3. **Guard disable()** - only call if `!field.disabled.value`
+4. **Guard enable()** - only call if `field.disabled.value`
+5. **Guard setValue()** - only call if value actually differs
+6. **Arrays special case** - compare by `.length`, not by reference (`[] !== []` is always true)
+
+### Other Watchers
+
+For watchers on different fields (e.g., `path.health.isSmoker`), apply same guards:
+
+```typescript
+watchField(path.health.isSmoker, (_value, ctx) => {
+  const isSmoker = ctx.form.health.isSmoker.value.value;
+  const smokingYearsField = ctx.form.health.smokingYears;
+
+  if (smokingYearsField) {
+    if (isSmoker) {
+      if (smokingYearsField.disabled.value) {
+        smokingYearsField.enable();
+      }
+    } else {
+      if (!smokingYearsField.disabled.value) {
+        smokingYearsField.disable();
+      }
+      if (smokingYearsField.getValue() !== null) {
+        smokingYearsField.setValue(null);
+      }
+    }
+  }
+}, { immediate: false });  // REQUIRED!
+```