design-api

# API design and DX Inspect the current call sites, types, tests, exports, and relevant design records before applying general guidance. Existing local contracts beat generic patterns. ## Default priorities 1. Correct observable behavior 2. Type safety and useful inference 3. A small, coherent concept set 4. Consistency with adjacent Video.js APIs 5. Composable escape hatches and tree-shakable output Prefer config objects once positional arguments become ambiguous, explicit contracts over hidden coupling, and inference over required annotations. Avoid adding a plugin system when ordinary composition or a narrow extension point solves the problem. ## Load references conditionally - General API tradeoffs: `references/principles.md` - Type inference or public type shape: `references/typescript.md` - Store, signal, or state architecture: `references/state.md` - Middleware, builders, adapters, or lifecycles: `references/extensibility.md` - Suspected design smell: `references/anti-patterns.md` - Prior-art comparison: `references/libraries.md` and, only if useful, `references/voices.md` Do not load every reference by default. ## Example Input: “Design a typed selector API for the store.” Output: A concrete public shape with inference behavior, compatibility tradeoffs, extension points, and tests to prove the contract.