vue-tui/AGENTS.md

Common Pitfalls & Best Practices

• AGENTS.md is the source of truth. CLAUDE.md is a symlink to it.
• Always use Vue's shallowRef over ref by default. Using ref requires a solid justification and a code comment explaining why deep reactivity is needed.
• Always use defineComponent() to define components. Never use bare { setup() {} } objects — they lack component scope, so inject, watch, and onScopeDispose won't work correctly.
• Vue SFCs must use <script setup> unless there's an explicit reason not to.
• Bug fixes must follow test-first: write a failing test that reproduces the bug, then fix the code and verify the test passes.
• Tests must simulate real user conditions. Non-TTY environments disable chalk colors — use FORCE_COLOR env var so ANSI output is always exercised. A bug invisible in tests but visible in a real terminal is a testing gap, not a minor issue.
• When debugging color/ANSI output in non-TTY environments (e.g. Claude Code shell), use FORCE_COLOR=3 env var to force chalk to output ANSI codes.
• The PTY suite (vitest.pty.config.ts) runs tests concurrently (sequence.concurrent: true). Each test spawns its own isolated subprocess/app, so they don't share state. Never assert on wall-clock-dependent behavior there (e.g. exact render/commit counts that rely on the renderer's ~32ms throttle): trigger the event so it renders synchronously and assert immediately after, or it flakes under CPU contention. it.sequential does NOT fix cross-fork CPU contention — fix the timing dependency instead.
• Two test patterns are incompatible with concurrent execution and must run sequentially (this is why the main vite.config.ts suite is not concurrent):
  • Inline/file snapshots (toMatchInlineSnapshot): the module-level expect loses snapshot test context under concurrency. Fixable — destructure the context-local expect: test.concurrent("name", async ({ expect }) => { expect(x).toMatchInlineSnapshot() }).
  • Fake timers (vi.useFakeTimers / advanceTimersByTime): these mutate the process-global timer functions, so a concurrent test calling useRealTimers() yanks the mocked API out from under another mid-advanceTimersByTime ("timers not mocked"). Not fixable with context — these tests must stay sequential.
• After completing any task, run vp run ready (or vpr ready) to verify: lint, type-check, test all packages, and build.
• Never commit anything under docs/. That directory is for local working notes and specs — it must stay out of git.

Using Vite+, the Unified Toolchain for the Web

This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, and it invokes Vite through vp dev and vp build. Run vp help to print a list of commands and vp <command> --help for information about a specific command.

Docs are local at node_modules/vite-plus/docs or online at https://viteplus.dev/guide/.

Review Checklist

• Run vp install after pulling remote changes and before getting started.
• Run vp check and vp test to format, lint, type check and test changes.
• Check if there are vite.config.ts tasks or package.json scripts necessary for validation, run via vp run <script>.
• If setup, runtime, or package-manager behavior looks wrong, run vp env doctor and include its output when asking for help.