writing-typescript

# TypeScript Development ## Scope - Use for `.ts` and `.tsx`, Node.js services, React apps, typed APIs, and TypeScript design advice. - Do not use for Go, Python, plain HTML/CSS/JS, or server-rendered templates. - Follow the repository's TypeScript version, tsconfig, package manager, framework, test runner, and lint rules. - Do not add dependencies or switch frameworks unless the project already uses them or the user approves. ## Reference Reads - Read only the references needed for the task. - Read `references/principles.md` for non-trivial TypeScript changes or reviews. - Read `references/patterns.md` for data models, validation, async flow, or module boundaries. - Read `references/react.md` for `.tsx`, hooks, component state, forms, performance, or React tests. - Read `references/testing.md` before adding or changing TypeScript tests. ## Defaults - Preserve strict typing; do not weaken compiler options to pass checks. - Use `unknown` for untrusted input. Avoid `any`; isolate it only for unavoidable interop. - Validate API, JSON, env, storage, and form data at the boundary before typed use. - Use discriminated unions for variants, async state, and domain states. - Use guard clauses and focused helpers. Avoid deep nesting, global state, and mixed concerns. - Use the project's error conventions; prefer unions or `Result` for recoverable failures. - Pass dependencies explicitly; avoid inheritance, singletons, and hidden module state. - Avoid unsafe casts, non-null assert...