GeezerVison

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/forms.md`:
- Around line 353-364: The example uses createForm but the import only lists
schema and field; update the import statement to include createForm so the
snippet compiles — e.g., add createForm to the named imports alongside schema
and field in the top import (refer to createForm, schema, and field in the
example).

In `@src/component/component.ts`:
- Around line 212-218: setProp currently assigns the value directly which can
leave required prop tracking stale and skips validator logic; update setProp
(and use existing helpers like cloneProps, missingRequiredProps,
definition.props) to: 1) run the prop validator if
definition.props[name]?.validator exists and only accept the value if it passes
(or coerce/normalize as your attribute path does), 2) if the prop was previously
in missingRequiredProps and a valid value is now provided remove that name from
missingRequiredProps and, if missingRequiredProps becomes empty, allow the
initial mount to proceed, and 3) still call this.render(true, previousProps,
undefined, true) after successful validation/mutations so behavior matches
attribute-driven updates.

In `@src/component/slots.ts`:
- Around line 68-73: The code attaches 'slotchange' only to the initially found
slot, so if the <slot> element is replaced the new element is never observed;
update useSlot/finding logic (the block that calls schedule -> findSlot(host,
name) -> slot.addEventListener('slotchange', update)) to detect slot
replacements: track the currentSlot element, and whenever you call findSlot
re-check if it's different, remove the old listener from currentSlot, attach the
'slotchange' listener to the new slot, and store currentSlot; ensure this
cleanup happens when disposed (remove listener and disconnect any observer).
Apply the same change to the other identical block (the second scheduled
findSlot block) so both code paths rebind listeners when the slot node is
replaced.

In `@src/core/utils/object.ts`:
- Around line 517-528: The Map/Set branches in deep equality (compare) use
identity checks (right.has / right.has(value)) which fails for structurally
equal but non-identical objects; update the Map handling in the compare function
to iterate left entries and for each key/value perform recursive comparison
against right's entries (use compare for keys and compare for values rather than
right.has/right.get identity checks), and update the Set handling to, for each
value in left, search through right's elements and use compare to find a
structurally equal match (removing matched elements or tracking matches to
respect multiplicity), ensuring both Map and Set use recursive compare for keys
and values instead of identity membership.

In `@src/forms/schema.ts`:
- Around line 131-137: The type guard isFieldConfig currently treats any object
with an own 'initialValue' property as FieldConfig, so raw initial-value objects
like { initialValue: 'x', other: 1 } are misclassified; update isFieldConfig to
check for 'initialValue' plus at least one other known FieldConfig-specific key
(e.g., 'validate', 'disabled', or whatever keys are defined on the
FieldConfig<T> interface) or validate that the object shape exactly matches
FieldConfig (import/compare against the FieldConfig type keys), so only true
config objects (not ordinary objects that happen to have an initialValue key)
return true; adjust the guard logic in isFieldConfig to reference those
FieldConfig keys (and update any uses in the same module such as where initial
values are stored) so object-shaped initial values are preserved.

In `@tests/motion-timeline-extras.test.ts`:
- Around line 107-109: The current assertion
expect(updates.length).toBeGreaterThanOrEqual(0) is tautological; change it to
assert the expected reduced-motion behavior by checking that no updates occurred
(e.g., expect(updates).toHaveLength(0) or expect(updates).toEqual([])). Locate
the test that builds the updates array (variable updates in this test block) and
replace the length check with a direct behavioral assertion, ensuring the test
sets the reduced-motion preference before running the timeline so the no-updates
expectation is valid.

In `@tests/motion.test.ts`:
- Around line 511-526: The test sets global reduced-motion state via
setReducedMotion(true) but resets it at the end unprotected, risking leakage if
an assertion throws; modify the test around the call to animateTo/expect
assertions to ensure setReducedMotion(null) runs in a finally block (e.g., wrap
the body after setReducedMotion(true) in try { ... } finally {
setReducedMotion(null); }) so reduced-motion is always cleared; reference
setReducedMotion and animateTo in the change.

---

Nitpick comments:
In `@src/forms/bind.ts`:
- Around line 13-20: Add `@internal` JSDoc tags to the non-exported helper
type-guard functions so they are marked as internal utilities: add a short JSDoc
block with `@internal` above isInput, isTextarea, isSelect, and isButton, and
likewise add `@internal` to the other non-exported helpers in the file (the ones
around lines 22-90 and 189-200) so all internal, non-public functions comply
with the repo rule; keep the JSDoc minimal (description optional) and place it
immediately above each function declaration.

In `@src/forms/ssr.ts`:
- Around line 41-60: The JSDoc for the public function readSerializedFormState
is missing an `@example` usage; update the comment block above the exported
readSerializedFormState<T> function to include an `@example` that demonstrates
importing readSerializedFormState, calling it with a typed id (e.g.
readSerializedFormState<MyFormValues>('register')), checking the returned
FormSnapshot<T> and restoring a form (e.g. form.restore(snapshot)); keep the
text concise, use TypeScript fenced code example, and ensure it references
FormSnapshot and the id string so consumers see the client-side hydration
pattern.
- Around line 62-71: Add a JSDoc `@example` block to the hydrateForm function's
comment that demonstrates importing createForm and hydrateForm, creating a form
instance, calling hydrateForm(form, 'register'), and handling the false return
(no serialized state found) — update the comment above hydrateForm (referencing
hydrateForm, Form, and readSerializedFormState) to include that illustrative
example following the project's JSDoc style.

In `@src/motion/effects.ts`:
- Around line 42-105: Add an `@example` block to the JSDoc for the exported
magnetic function showing typical usage and cleanup: update the comment above
export const magnetic(...) to include a short code snippet (e.g., obtaining an
element, calling magnetic(element, { strength: 0.4, radius: 100 }), and later
calling the returned cleanup()) so consumers see how to integrate and tear down
the effect.
- Around line 107-196: The JSDoc for the exported tilt function lacks an
`@example` showing how to call it; add an `@example` block to the tilt(...) JSDoc
that demonstrates typical usage (import/selection of an element, calling
tilt(el, { max, perspective, scale, respectReducedMotion }) and handling the
returned cleanup function). Update the comment above export const tilt so it
references the TiltOptions shape and shows a minimal real-world example
(including calling the returned EffectCleanup to detach listeners) to help
consumers understand usage.

In `@tests/motion-timeline-extras.test.ts`:
- Around line 12-26: The helper createElement currently creates a detached
element (el) and mock animation (anim) but does not follow the repo pattern of
appending and explicit removal; update createElement to append the created el to
document.body before returning and expose a clear way to remove it (either
return the el so callers can call el.remove(), or return a cleanup function as
part of the result), leaving anim and the mocked animate implementation intact;
this ensures tests using createElement follow the "append to document.body, then
call .remove()" lifecycle and avoid DOM state leakage.