react-grab AGENTS.md

General Rules

• MUST: Use @antfu/ni. Use ni to install, nr SCRIPT_NAME to run. nun to uninstall.
• MUST: Use TypeScript interfaces over types.
• MUST: Keep all types in the global scope.
• MUST: Use arrow functions over function declarations
• MUST: Default to NO comments. Only add a comment when the user explicitly asks, or when the "why" is truly non-obvious - browser quirks, platform bugs, performance tradeoffs, fragile internal patching, or counter-intuitive design decisions. Never add comments that restate what the code does or what a well-named function/variable already conveys. When in doubt, leave the comment out.
  • Do not delete descriptive comments >3 lines without confirming with the user
• MUST: Use kebab-case for files
• MUST: Use descriptive names for variables (avoid shorthands, or 1-2 character names).
  • Example: for .map(), you can use innerX instead of x
  • Example: instead of moved use didPositionChange
• MUST: Frequently re-evaluate and refactor variable names to be more accurate and descriptive.
• MUST: Do not type cast ("as") unless absolutely necessary
• MUST: Remove unused code and don't repeat yourself.
• MUST: Always search the codebase, think of many solutions, then implement the most elegant solution.
• MUST: Put all magic numbers in constants.ts using SCREAMING_SNAKE_CASE with unit suffixes (_MS, _PX).
• MUST: Put small, focused utility functions in utils/ with one utility per file.
• MUST: Use Boolean over !!.
• MUST: No dynamic imports (import()) unless strictly necessary (e.g. code-splitting a large optional dependency, breaking a circular dependency that cannot be refactored). Prefer static import at the top of the file.

V8 Hot-Path Rules

For hot per-frame paths (pointer/scroll handlers, animation ticks, fiber walks):

• MUST: Keep indirect call sites monomorphic. Do not pass different callbacks to a shared recursor/iterator that gets hot - split into one specialized helper per callback, or inline the loop.
• MUST: Mutate object fields in place instead of replacing the field with a fresh object literal. obj.target.x = ... not obj.target = { x, y, ... }. Allocating per-frame literals churns the GC and cycles hidden classes.
• MUST: Keep numeric helpers in a single number-type "lane". A function that early-returns a Smi (return 8) and otherwise returns a double (labelWidth * 0.2) will deopt every consumer with not a Smi. Pick one (e.g. Math.round the double).
• SHOULD: Prefer closed-form arithmetic over loops that subtract/add a constant until a delta is in range (e.g. angle normalization with Math.round(delta / 360), not while delta > 180).