api(docs): simplifying after OpaqueRef annotations are no longer necessary on .map (commontoolsinc#1939)

docs: simplify OpaqueRef instructions after type inference improvements

Update pattern/recipe documentation to reflect that OpaqueRef type
annotations are no longer necessary in .map() callbacks. TypeScript now
automatically infers the correct types.

Changes:
- Remove explicit OpaqueRef<T> annotations from all code examples
- Update messaging from "must annotate" to "automatically inferred"
- Note that explicit annotations still work if preferred
- Celebrate the improvement as "good news" throughout

Files updated:
- docs/common/PATTERNS.md
- docs/common/HANDLERS.md
- docs/common/COMPONENTS.md
- .claude/skills/recipe-dev/SKILL.md
- .claude/skills/recipe-dev/references/workflow-guide.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: seefeldb

.claude/skills/recipe-dev/SKILL.md

@@ -51,7 +51,7 @@ Begin with minimal viable recipe:
 
 ```typescript
 /// <cts-enable />
-import { Default, NAME, OpaqueRef, recipe, UI } from "commontools";
+import { Default, NAME, recipe, UI } from "commontools";
 
 interface Item {
   title: string;
@@ -67,7 +67,7 @@ export default recipe<Input, Input>("My Recipe", ({ items }) => {
     [NAME]: "My Recipe",
     [UI]: (
       <div>
-        {items.map((item: OpaqueRef<Item>) => (
+        {items.map((item) => (
           <div>{item.title}</div>
         ))}
       </div>
@@ -82,7 +82,7 @@ export default recipe<Input, Input>("My Recipe", ({ items }) => {
 Add bidirectional binding for simple updates:
 
 ```typescript
-{items.map((item: OpaqueRef<Item>) => (
+{items.map((item) => (
   <ct-checkbox $checked={item.done}>
     {item.title}
   </ct-checkbox>
@@ -137,7 +137,6 @@ See "Deployment Workflow" section below.
 ### Common Error Categories
 
 **Type Errors** (see `HANDLERS.md` for details):
-- Missing `OpaqueRef<T>` annotation in `.map()`
 - Wrong style syntax (object vs string, see `COMPONENTS.md`)
 - Using `Cell<OpaqueRef<T>[]>` instead of `Cell<T[]>` in handlers
 - Forgetting `Cell<>` wrapper in handler state types
@@ -167,7 +166,6 @@ See "Deployment Workflow" section below.
 
 | Error Message | Check |
 |---------------|-------|
-| "Property X does not exist on type 'OpaqueRef<unknown>'" | Missing `OpaqueRef<T>` in `.map()` - See `HANDLERS.md` |
 | "Type 'string' is not assignable to type 'CSSProperties'" | Using string style on HTML element - See `COMPONENTS.md` |
 | Handler type mismatch | Check `Cell<T[]>` vs `Cell<Array<Cell<T>>>` - See `HANDLERS.md` |
 | Data not updating | Missing `$` prefix or wrong event name - See `COMPONENTS.md` |
@@ -256,20 +254,6 @@ const grouped = groupByCategory(items);
 
 See `RECIPES.md` for reactive programming details.
 
-### Type Annotations
-
-**Always annotate `.map()` parameters:**
-
-```typescript
-{items.map((item: OpaqueRef<Item>) => (
-  <ct-checkbox $checked={item.done} />
-))}
-```
-
-**Why:** TypeScript can't infer types for bidirectional binding without annotation.
-
-See `PATTERNS.md` for common patterns.
-
 ## Multi-File Recipes
 
 When building complex recipes across multiple files:
@@ -306,8 +290,6 @@ See `PATTERNS.md` Level 3-4 for linking and composition patterns.
 - Test syntax before deploying (unless deployment fails)
 - Add multiple features before testing
 - Use handlers for simple value updates
-- Forget `OpaqueRef<T>` annotations in `.map()`
-- Duplicate content from `docs/common/` - reference it instead
 
 ## Documentation Map
 

.claude/skills/recipe-dev/references/workflow-guide.md

@@ -111,7 +111,6 @@ echo '{"title": "Test Item"}' | ./dist/ct charm set --identity claude.key --api-
 ### Common Error Patterns
 
 **Type Errors:**
-- Missing `OpaqueRef<T>` in `.map()` - See `HANDLERS.md`
 - Wrong style syntax (object vs string) - See `COMPONENTS.md`
 - Using `Cell<OpaqueRef<T>[]>` in handlers instead of `Cell<T[]>` - See `HANDLERS.md`
 

docs/common/COMPONENTS.md

@@ -56,7 +56,7 @@ interface ShoppingItem {
 }
 
 // In your recipe
-{items.map((item: OpaqueRef<ShoppingItem>) => (
+{items.map((item) => (
   <div>
     <ct-checkbox $checked={item.done}>
       <span>{item.title}</span>
@@ -66,8 +66,6 @@ interface ShoppingItem {
 ))}
 ```
 
-**Important:** Notice the `OpaqueRef<ShoppingItem>` type annotation. This is required when using `.map()` with bidirectional binding to ensure proper type checking.
-
 ## When to Use Handlers vs Bidirectional Binding
 
 ### Decision Matrix
@@ -406,7 +404,7 @@ interface ShoppingItem {
 }
 
 // ✅ CORRECT - Manual rendering for custom fields
-{items.map((item: OpaqueRef<ShoppingItem>) => (
+{items.map((item) => (
   <div>
     <ct-checkbox $checked={item.done}>
       {item.title}

docs/common/HANDLERS.md

@@ -173,8 +173,8 @@ export default recipe<Input, Input>(
     return {
       [UI]: (
         <div>
-          {/* Context 4: In JSX .map() - OpaqueRef<ShoppingItem> */}
-          {items.map((item: OpaqueRef<ShoppingItem>) => (
+          {/* Context 4: In .map() - item is OpaqueRef<ShoppingItem> */}
+          {items.map((item) => (
             <ct-checkbox $checked={item.done}>{item.title}</ct-checkbox>
           ))}
           <ct-button onClick={addItem({ items })}>Add</ct-button>
@@ -192,9 +192,9 @@ Think of types this way:
 
 | Type | Mental Model | Where Used | Example |
 |------|--------------|------------|---------|
-| `Cell<T[]>` | A **box** containing an array | Handler params, recipe params, returns | `items: Cell<ShoppingItem[]>` |
+| `Cell<T[]>` | A **box** containing an array | Handler params, sometimes lift params, returns | `items: Cell<ShoppingItem[]>` |
 | `T[]` | The **plain array** inside the box | Result of `.get()` | `const arr = items.get()` returns `ShoppingItem[]` |
-| `OpaqueRef<T>` | A **cell-like reference** to each item | In JSX `.map()` | `items.map((item: OpaqueRef<ShoppingItem>) => ...)` |
+| `OpaqueRef<T>` | A **cell-like reference** to each item | Recipe params, in `.map()` | `items.map((item) => ...)` |
 | `T` | A **plain object** | Inside plain arrays | `{ title: "Milk", done: false }` |
 
 ### How They Transform
@@ -205,11 +205,9 @@ const items: Cell<ShoppingItem[]>  // Handler receives this
 // Open the box with .get()
 const plainArray: ShoppingItem[] = items.get();
 
-// In JSX, .map() wraps each item
-{items.map((item: OpaqueRef<ShoppingItem>) => (
-  // item is NOT a plain ShoppingItem
-  // item is NOT a Cell<ShoppingItem>
-  // item IS an OpaqueRef<ShoppingItem>
+// In recipe, arguments, cells and map parameters are OpaqueRef<>
+{items.map((item) => (
+  // item's type is automatically inferred as OpaqueRef<ShoppingItem>
   <ct-checkbox $checked={item.done} />
 ))}
 ```
@@ -219,7 +217,7 @@ const plainArray: ShoppingItem[] = items.get();
 **Different contexts require different types:**
 
 1. **Handler parameters need `Cell<T[]>`** - so you can call `.get()` and `.set()`
-2. **JSX .map() needs `OpaqueRef<T>`** - for bidirectional binding to work
+2. **JSX .map() has `OpaqueRef<T>`** - for bidirectional binding to work (automatically inferred!)
 3. **Recipe schemas use plain `T[]`** - to define the data structure
 
 **Common mistake:**
@@ -281,8 +279,8 @@ export default recipe<Input, Input>("Shopping List", ({ items }) => {
   return {
     [UI]: (
       <div>
-        {/* In .map(): OpaqueRef<ShoppingItem> */}
-        {items.map((item: OpaqueRef<ShoppingItem>) => (
+        {/* Also in .map(), inferred as OpaqueRef<ShoppingItem> */}
+        {items.map((item) => (
           <div>
             <ct-checkbox $checked={item.done}>
               {item.title}