i-want-to-heal/AGENTS.md

Project Notes

Target Hardware: AYN Thor

• AYN Thor main display: 6-inch AMOLED, 1920 x 1080, 120Hz.
• AYN Thor secondary display: 3.92-inch AMOLED, 1240 x 1080, 60Hz.
• AYN Thor UI sizing must be designed against Android CSS/layout viewport, not physical framebuffer pixels.
• Approximate Thor CSS viewports: main display 960 x 540, secondary display 620 x 540.
• Test top-screen UI only against the main display viewport, and bottom-screen UI only against the secondary display viewport.

Input Requirements

• Every game screen, menu, dialog, overlay, and gameplay interaction must be fully navigable by controller at all times.
• Any time a screen, menu, dialog, overlay, or gameplay interaction is added or changed, verify controller navigation still works for that surface before considering the work complete.
• Controller navigation must not depend on touch, mouse, keyboard, or hidden developer-only shortcuts.
• Focus state must always be visible and predictable when controller navigation is active.
• Avoid interaction patterns that trap focus, lose focus, or require precise pointer input.

Architecture Requirements

• Keep systems modular and scoped by responsibility.
• Prefer small reusable modules/components over large files with mixed concerns.
• Keep shared game logic independent from platform-specific web or mobile wrappers whenever practical.
• Apply game changes to both web version and mobile app version.

I Want To Heal 1 vs I Want To Heal 2

• I Want To Heal 1 is the existing healer-first menu/combat game. Preserve its current progression, saves, inventories, collection logs, combat screens, and content unless the user explicitly asks to change IWT1.
• I Want To Heal 2 is the new 2D boss-arena version. Keep IWT2 code, content, save data, inventories, character levels, and collection logs separate from IWT1 so the two modes are not confused.
• The app should offer a game-select screen before the main menu: I Want To Heal 1 launches the old version, and I Want To Heal 2 launches the new 2D version.
• Both games must remain usable from the same Android APK and from iwanttoheal.phenomrom.com.
• Prefer an explicit folder split for IWT2, such as src/modes/iwt2/, with subfolders for screens, simulation, rendering, content, and save/repository code.
• Keep IWT2 simulation state independent from rendering. Arena movement, AI, boss attacks, collisions, damage, stun/knockdown, progression, inventory, and collection logs should live in pure TypeScript modules where practical.
• IWT2 rendering can use a 2D canvas/game runtime, but renderer objects must not become the source of truth for saveable gameplay state.
• IWT2 needs continuous movement input: left analog stick on AYN Thor and WASD on keyboard. Do not rely only on existing menu-style navigation actions for arena movement.
• IWT2 menus, dialogs, inventory, collection log, pause overlays, and game-select screen must still follow controller navigation requirements.
• First IWT2 boss conversion target: Bulldrome. Bulldrome should have normal melee tank damage, a charge across the arena that damages and knocks down/stuns hit players for 0.75 seconds, and every 3rd charge should be followed by an AoE ground slam around the boss that also damages and knocks down/stuns hit players for 0.75 seconds.
• IWT2 starter party fantasy: player-controlled healer plus visible party members moving in the arena. Paladin tank holds aggro; ranger fires arrows; mage fires fireballs; rogue flanks; warrior fights in melee. Each class should have a distinct icon and color scheme.

Performance Requirements

• Treat CPU, GPU, memory, battery, and startup cost as first-class constraints.
• Avoid unnecessary per-frame allocations, polling, timers, layout work, and re-renders.
• Keep assets sized appropriately for Thor displays; do not ship oversized textures, images, audio, or data blobs without need.
• Prefer event-driven updates and cached calculations for UI and game systems.
• Profile or measure when changing hot paths, rendering, animation, input handling, asset loading, or persistent state.

Build Requirements

• User rebuilds app; do not rebuild APK unless explicitly requested.