docs: ts conventions to agents.md

1 files changed, 14 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index cd59a85c..d326ac5d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,3 +21,17 @@ Each app is a frontend that calls into Rust. Logic is never duplicated between a
 
 - Read components before using them. They may already apply classes, which affects what you need to pass and how to override them.
 
+### TypeScript
+
+Function signatures should make the call site readable and let the function evolve without breaking callers. Positional parameters fail both: `formatTime(30, 24)` hides which number is which, and adding, removing, or reordering an argument silently breaks every caller whose types happen to still line up. A single destructured object fixes both at once - each argument names itself at the call site, and the shape can grow without churn. So signatures default to one object parameter:
+
+```tsx
+// ❌ meaning depends on order; the shape can't evolve without touching every caller
+function formatTime(seconds: number, fps: number) { ... }
+
+// ✅ each argument names itself; fields can be added, reordered, or made optional freely
+function formatTime({ seconds, fps }: { seconds: number; fps: number }) { ... }
+```
+
+The one real exception is type predicates (`element is VideoElement`) — the language requires a positional subject, so the reasoning above doesn't get to apply.
+