Imported from azayrahmad/ms-agent-js (AGENTS.md). Install upstream with npx skills add azayrahmad/ms-agent-js. Copyright stays with the author.

MSAgentJS AI Agent Onboarding

Welcome, AI Agent! This document contains "Recipes" and "Tips" specifically designed to help you navigate and modify this codebase efficiently.

👨‍💻 Operational Recipes

Follow these common patterns when tasked with extending the library:

Recipe: Adding a New Manager

1. Define the manager class in src/.
2. Initialize it in the Agent constructor.
3. If it needs to be updated every frame, call its update(deltaTime) method inside Agent.startLoop.

Recipe: Debugging the Frame Loop

• The AnimationManager handles frame durations in units of 10ms (matching the original MS Agent spec).
• If animations are too fast/slow, check the speed multiplier in Agent or the duration values in the AgentCharacterDefinition.

Recipe: Modifying Balloon Styles

• The Balloon uses Shadow DOM. Styles are defined in src/ui/Balloon.ts using a <style> tag.
• Visual changes to the bubble shape should be made in the SVG path generation logic in Balloon._drawBalloon.

💡 Tips for AI Agents

• Awaiting Requests: API methods return AgentRequest objects which are "thenable". You can await agent.play(...) directly.
• JSDoc: The codebase is heavily documented. Use the read_file tool on src/core/base/types.ts to understand the primary data structures.
• Architecture: For a visual overview of how the managers interact, see docs/internals.md.
• Testing: We use Vitest. Run npm test after changes. For visual changes, manual verification via npm run dev is recommended.

🔍 Further Reading

• docs/api-reference.md: User-facing API details.
• CONTRIBUTING.md: Contribution guidelines and environment setup.

🛡️ AI Agent Standards & Quality Control

As an AI agent (like Jules), you MUST adhere to the following standards to ensure high-quality contributions:

1. Commit & Process Standards

• Conventional Commits: Use the format type(scope): description.
  • Allowed Scopes: core, ui, balloon, audio, sprite, anim, state, parser, demo, docs, scripts, deps.
  • Examples: feat(balloon): add support for RTL text, fix(demo): resolve layout shift on mobile.
• Pre-Commit Verification: Always run npm run test:coverage, npx playwright test, and npm run build before submitting. Verify the build by running npm run preview and checking the output.
• Documentation Index: Before finishing any task, evaluate all relevant documentation files and update them to reflect your changes.

2. Code Quality Standards

• Complete JSDoc: Follow the standard in src/Agent.ts. Every public method and property MUST have JSDoc including @param, @returns, and a clear description.
• Strict TypeScript: Avoid any. Use interfaces and types defined in src/core/base/types.ts.
• Shadow DOM Isolation: All UI components (like Balloon.ts) must use Shadow DOM to prevent style leakage.
• Resource Cleanup: If you introduce timers, listeners, or DOM elements, ensure they are properly disposed of in the Agent.destroy() method.

3. Project-Specific Rules

• Meta-Adherence: Always read this AGENTS.md at the start of every task and consult your "Memory" context for historical patterns.
• Test Coverage: Maintain or improve the project's line coverage (~90%). New features MUST have corresponding tests in tests/.
• Asset Integrity: Ensure character loading logic remains compatible with both legacy .acd and optimized .json formats.
• No Magic Strings: Avoid hardcoding animation names or states; use constants or values from character definitions.
• Mobile First: Implement fallbacks for mobile-specific limitations (e.g., TTS word tracking in Balloon.ts).