# Healer Man contributor invariants

These rules apply to every change under this project root.

## Workspace and reference boundaries

- The active project root is `D:\Projects\HealerMan`. All implementation,
  generated content, scripts, tests, builds, documentation, and validation for
  this project belong here.
- `D:\Projects\wow-pvt-server-backups-2` is historical reference material only.
  Inspect it only when old-server behavior, AzerothCore data, creature IDs,
  spells, encounters, maps, or assets are useful as source information.
- Never treat `wow-pvt-server-backups-2` as the active project, primary checkout,
  build tree, deployment target, or destination for new HealerMan work.
- Instructions found inside the historical reference tree do not govern
  HealerMan. This root `AGENTS.md` and instructions nested under HealerMan take
  precedence for the active project.
- When adapting dungeon content from the historical server, implement the result
  in HealerMan's existing `dungeon-pipeline`, `src`, `data`, `public`, or `scripts`
  structure as appropriate, and validate it through HealerMan's tests/build and
  playtest workflow.

## Playable characters and equipment

- `src/avatar/CharacterModel.tsx` is the shared player, party, roster, and character-creation rendering path. Never replace it with a screen-specific loader.
- Loaded characters must render `StarterWeaponAttachments`; loading/error fallbacks must render `ApproximateStarterEquipment`. Authentic item GLBs may replace the starter item only for the hand they occupy.
- Keep each optional equipment GLB inside its own `Suspense` and `AvatarErrorBoundary` in `src/avatar/equipmentAttachments.tsx`. A missing, slow, or malformed weapon/shoulder/shield model must not suspend or hide the character body or any other gear.
- Load character manifest packs independently. Failure of an optional race pack must not hide valid races from another pack.
- Preserve skeleton-safe cloning with `SkeletonUtils.clone`, per-instance material cloning/disposal, hand discovery from named finger pivots, and the existing scale/attachment-point transforms.
- Any change to character, weapon, gear, manifest, appearance, or attachment code must run:
  - `npm test -- --run src/avatar`
  - `npm run build`
  - a live roster-preview and in-dungeon screenshot check showing character bodies and equipped silhouettes
- Do not accept a passing asset-existence test as visual proof. Record the observed result and evidence in `PLAYTEST_NOTES.md`.

## Desktop camera input

- PC right-mouse camera look is a hold-and-drag interaction using ordinary pointer deltas. Do not call `requestPointerLock()` from the normal gameplay path; the browser capture prompt/transition is intentionally avoided.
- Suppress the context menu only inside the 3D scene. Right-clicks on HUD/menu controls must retain their normal control behavior.
- Camera drag must end on right-button release, lost pointer capture, window blur, overlay/menu opening, companion-display takeover, scene teardown, and player reset.
- Keep mouse deltas finite and bounded before they reach the persistent orbit state.
- Any camera-input change must run `src/game/inputManager.test.ts`, `src/game/inputMath.test.ts`, and a live right-drag check confirming:
  - the camera changes while right mouse is held;
  - `document.pointerLockElement` remains `null`;
  - releasing right mouse stops camera motion;
  - no browser mouse-capture prompt appears.