AGENTS.md

1<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:_sections:start -->
2# Sections
3 
4This file defines all sections, their ordering, impact levels, and descriptions.
5The section ID (in parentheses) is the filename prefix used to group rules.
6 
7---
8 
9## 1. Component Architecture (architecture)
10 
11**Impact:** HIGH  
12**Description:** Fundamental patterns for structuring components to avoid prop
13proliferation and enable flexible composition.
14 
15## 2. State Management (state)
16 
17**Impact:** MEDIUM  
18**Description:** Patterns for lifting state and managing shared context across
19composed components.
20 
21## 3. Implementation Patterns (patterns)
22 
23**Impact:** MEDIUM  
24**Description:** Specific techniques for implementing compound components and
25context providers.
26 
27## 4. React 19 APIs (react19)
28 
29**Impact:** MEDIUM  
30**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
31<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:_sections:end -->
32 
33<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:_template:start -->
34## Rule Title Here
35 
36Brief explanation of the rule and why it matters.
37 
38**Incorrect:**
39 
40```tsx
41// Bad code example
42```
43 
44**Correct:**
45 
46```tsx
47// Good code example
48```
49 
50Reference: [Link](https://example.com)
51<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:_template:end -->
52 
53<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:architecture-avoid-boolean-props:start -->
54## Avoid Boolean Prop Proliferation
55 
56Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
57component behavior. Each boolean doubles possible states and creates
58unmaintainable conditional logic. Use composition instead.
59 
60**Incorrect (boolean props create exponential complexity):**
61 
62```tsx
63function Composer({
64  onSubmit,
65  isThread,
66  channelId,
67  isDMThread,
68  dmId,
69  isEditing,
70  isForwarding,
71}: Props) {
72  return (
73    <form>
74      <Header />
75      <Input />
76      {isDMThread ? (
77        <AlsoSendToDMField id={dmId} />
78      ) : isThread ? (
79        <AlsoSendToChannelField id={channelId} />
80      ) : null}
81      {isEditing ? (
82        <EditActions />
83      ) : isForwarding ? (
84        <ForwardActions />
85      ) : (
86        <DefaultActions />
87      )}
88      <Footer onSubmit={onSubmit} />
89    </form>
90  )
91}
92```
93 
94**Correct (composition eliminates conditionals):**
95 
96```tsx
97// Channel composer
98function ChannelComposer() {
99  return (
100    <Composer.Frame>
101      <Composer.Header />
102      <Composer.Input />
103      <Composer.Footer>
104        <Composer.Attachments />
105        <Composer.Formatting />
106        <Composer.Emojis />
107        <Composer.Submit />
108      </Composer.Footer>
109    </Composer.Frame>
110  )
111}
112 
113// Thread composer - adds "also send to channel" field
114function ThreadComposer({ channelId }: { channelId: string }) {
115  return (
116    <Composer.Frame>
117      <Composer.Header />
118      <Composer.Input />
119      <AlsoSendToChannelField id={channelId} />
120      <Composer.Footer>
121        <Composer.Formatting />
122        <Composer.Emojis />
123        <Composer.Submit />
124      </Composer.Footer>
125    </Composer.Frame>
126  )
127}
128 
129// Edit composer - different footer actions
130function EditComposer() {
131  return (
132    <Composer.Frame>
133      <Composer.Input />
134      <Composer.Footer>
135        <Composer.Formatting />
136        <Composer.Emojis />
137        <Composer.CancelEdit />
138        <Composer.SaveEdit />
139      </Composer.Footer>
140    </Composer.Frame>
141  )
142}
143```
144 
145Each variant is explicit about what it renders. We can share internals without
146sharing a single monolithic parent.
147<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:architecture-avoid-boolean-props:end -->
148 
149<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:architecture-compound-components:start -->
150## Use Compound Components
151 
152Structure complex components as compound components with a shared context. Each
153subcomponent accesses shared state via context, not props. Consumers compose the
154pieces they need.
155 
156**Incorrect (monolithic component with render props):**
157 
158```tsx
159function Composer({
160  renderHeader,
161  renderFooter,
162  renderActions,
163  showAttachments,
164  showFormatting,
165  showEmojis,
166}: Props) {
167  return (
168    <form>
169      {renderHeader?.()}
170      <Input />
171      {showAttachments && <Attachments />}
172      {renderFooter ? (
173        renderFooter()
174      ) : (
175        <Footer>
176          {showFormatting && <Formatting />}
177          {showEmojis && <Emojis />}
178          {renderActions?.()}
179        </Footer>
180      )}
181    </form>
182  )
183}
184```
185 
186**Correct (compound components with shared context):**
187 
188```tsx
189const ComposerContext = createContext<ComposerContextValue | null>(null)
190 
191function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
192  return (
193    <ComposerContext value={{ state, actions, meta }}>
194      {children}
195    </ComposerContext>
196  )
197}
198 
199function ComposerFrame({ children }: { children: React.ReactNode }) {
200  return <form>{children}</form>
201}
202 
203function ComposerInput() {
204  const {
205    state,
206    actions: { update },
207    meta: { inputRef },
208  } = use(ComposerContext)
209  return (
210    <TextInput
211      ref={inputRef}
212      value={state.input}
213      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
214    />
215  )
216}
217 
218function ComposerSubmit() {
219  const {
220    actions: { submit },
221  } = use(ComposerContext)
222  return <Button onPress={submit}>Send</Button>
223}
224 
225// Export as compound component
226const Composer = {
227  Provider: ComposerProvider,
228  Frame: ComposerFrame,
229  Input: ComposerInput,
230  Submit: ComposerSubmit,
231  Header: ComposerHeader,
232  Footer: ComposerFooter,
233  Attachments: ComposerAttachments,
234  Formatting: ComposerFormatting,
235  Emojis: ComposerEmojis,
236}
237```
238 
239**Usage:**
240 
241```tsx
242<Composer.Provider state={state} actions={actions} meta={meta}>
243  <Composer.Frame>
244    <Composer.Header />
245    <Composer.Input />
246    <Composer.Footer>
247      <Composer.Formatting />
248      <Composer.Submit />
249    </Composer.Footer>
250  </Composer.Frame>
251</Composer.Provider>
252```
253 
254Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
255<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:architecture-compound-components:end -->
256 
257<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:patterns-children-over-render-props:start -->
258## Prefer Children Over Render Props
259 
260Use `children` for composition instead of `renderX` props. Children are more
261readable, compose naturally, and don't require understanding callback
262signatures.
263 
264**Incorrect (render props):**
265 
266```tsx
267function Composer({
268  renderHeader,
269  renderFooter,
270  renderActions,
271}: {
272  renderHeader?: () => React.ReactNode
273  renderFooter?: () => React.ReactNode
274  renderActions?: () => React.ReactNode
275}) {
276  return (
277    <form>
278      {renderHeader?.()}
279      <Input />
280      {renderFooter ? renderFooter() : <DefaultFooter />}
281      {renderActions?.()}
282    </form>
283  )
284}
285 
286// Usage is awkward and inflexible
287return (
288  <Composer
289    renderHeader={() => <CustomHeader />}
290    renderFooter={() => (
291      <>
292        <Formatting />
293        <Emojis />
294      </>
295    )}
296    renderActions={() => <SubmitButton />}
297  />
298)
299```
300 
301**Correct (compound components with children):**
302 
303```tsx
304function ComposerFrame({ children }: { children: React.ReactNode }) {
305  return <form>{children}</form>
306}
307 
308function ComposerFooter({ children }: { children: React.ReactNode }) {
309  return <footer className='flex'>{children}</footer>
310}
311 
312// Usage is flexible
313return (
314  <Composer.Frame>
315    <CustomHeader />
316    <Composer.Input />
317    <Composer.Footer>
318      <Composer.Formatting />
319      <Composer.Emojis />
320      <SubmitButton />
321    </Composer.Footer>
322  </Composer.Frame>
323)
324```
325 
326**When render props are appropriate:**
327 
328```tsx
329// Render props work well when you need to pass data back
330<List
331  data={items}
332  renderItem={({ item, index }) => <Item item={item} index={index} />}
333/>
334```
335 
336Use render props when the parent needs to provide data or state to the child.
337Use children when composing static structure.
338<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:patterns-children-over-render-props:end -->
339 
340<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:patterns-explicit-variants:start -->
341## Create Explicit Component Variants
342 
343Instead of one component with many boolean props, create explicit variant
344components. Each variant composes the pieces it needs. The code documents
345itself.
346 
347**Incorrect (one component, many modes):**
348 
349```tsx
350// What does this component actually render?
351<Composer
352  isThread
353  isEditing={false}
354  channelId='abc'
355  showAttachments
356  showFormatting={false}
357/>
358```
359 
360**Correct (explicit variants):**
361 
362```tsx
363// Immediately clear what this renders
364<ThreadComposer channelId="abc" />
365 
366// Or
367<EditMessageComposer messageId="xyz" />
368 
369// Or
370<ForwardMessageComposer messageId="123" />
371```
372 
373Each implementation is unique, explicit and self-contained. Yet they can each
374use shared parts.
375 
376**Implementation:**
377 
378```tsx
379function ThreadComposer({ channelId }: { channelId: string }) {
380  return (
381    <ThreadProvider channelId={channelId}>
382      <Composer.Frame>
383        <Composer.Input />
384        <AlsoSendToChannelField channelId={channelId} />
385        <Composer.Footer>
386          <Composer.Formatting />
387          <Composer.Emojis />
388          <Composer.Submit />
389        </Composer.Footer>
390      </Composer.Frame>
391    </ThreadProvider>
392  )
393}
394 
395function EditMessageComposer({ messageId }: { messageId: string }) {
396  return (
397    <EditMessageProvider messageId={messageId}>
398      <Composer.Frame>
399        <Composer.Input />
400        <Composer.Footer>
401          <Composer.Formatting />
402          <Composer.Emojis />
403          <Composer.CancelEdit />
404          <Composer.SaveEdit />
405        </Composer.Footer>
406      </Composer.Frame>
407    </EditMessageProvider>
408  )
409}
410 
411function ForwardMessageComposer({ messageId }: { messageId: string }) {
412  return (
413    <ForwardMessageProvider messageId={messageId}>
414      <Composer.Frame>
415        <Composer.Input placeholder="Add a message, if you'd like." />
416        <Composer.Footer>
417          <Composer.Formatting />
418          <Composer.Emojis />
419          <Composer.Mentions />
420        </Composer.Footer>
421      </Composer.Frame>
422    </ForwardMessageProvider>
423  )
424}
425```
426 
427Each variant is explicit about:
428 
429- What provider/state it uses
430- What UI elements it includes
431- What actions are available
432 
433No boolean prop combinations to reason about. No impossible states.
434<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:patterns-explicit-variants:end -->
435 
436<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:react19-no-forwardref:start -->
437## React 19 API Changes
438 
439> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
440 
441In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
442 
443**Incorrect (forwardRef in React 19):**
444 
445```tsx
446const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
447  return <TextInput ref={ref} {...props} />
448})
449```
450 
451**Correct (ref as a regular prop):**
452 
453```tsx
454function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
455  return <TextInput ref={ref} {...props} />
456}
457```
458 
459**Incorrect (useContext in React 19):**
460 
461```tsx
462const value = useContext(MyContext)
463```
464 
465**Correct (use instead of useContext):**
466 
467```tsx
468const value = use(MyContext)
469```
470 
471`use()` can also be called conditionally, unlike `useContext()`.
472<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:react19-no-forwardref:end -->
473 
474<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-context-interface:start -->
475## Define Generic Context Interfaces for Dependency Injection
476 
477Define a **generic interface** for your component context with three parts:
478`state`, `actions`, and `meta`. This interface is a contract that any provider
479can implement—enabling the same UI components to work with completely different
480state implementations.
481 
482**Core principle:** Lift state, compose internals, make state
483dependency-injectable.
484 
485**Incorrect (UI coupled to specific state implementation):**
486 
487```tsx
488function ComposerInput() {
489  // Tightly coupled to a specific hook
490  const { input, setInput } = useChannelComposerState()
491  return <TextInput value={input} onChangeText={setInput} />
492}
493```
494 
495**Correct (generic interface enables dependency injection):**
496 
497```tsx
498// Define a GENERIC interface that any provider can implement
499interface ComposerState {
500  input: string
501  attachments: Attachment[]
502  isSubmitting: boolean
503}
504 
505interface ComposerActions {
506  update: (updater: (state: ComposerState) => ComposerState) => void
507  submit: () => void
508}
509 
510interface ComposerMeta {
511  inputRef: React.RefObject<TextInput>
512}
513 
514interface ComposerContextValue {
515  state: ComposerState
516  actions: ComposerActions
517  meta: ComposerMeta
518}
519 
520const ComposerContext = createContext<ComposerContextValue | null>(null)
521```
522 
523**UI components consume the interface, not the implementation:**
524 
525```tsx
526function ComposerInput() {
527  const {
528    state,
529    actions: { update },
530    meta,
531  } = use(ComposerContext)
532 
533  // This component works with ANY provider that implements the interface
534  return (
535    <TextInput
536      ref={meta.inputRef}
537      value={state.input}
538      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
539    />
540  )
541}
542```
543 
544**Different providers implement the same interface:**
545 
546```tsx
547// Provider A: Local state for ephemeral forms
548function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
549  const [state, setState] = useState(initialState)
550  const inputRef = useRef(null)
551  const submit = useForwardMessage()
552 
553  return (
554    <ComposerContext
555      value={{
556        state,
557        actions: { update: setState, submit },
558        meta: { inputRef },
559      }}
560    >
561      {children}
562    </ComposerContext>
563  )
564}
565 
566// Provider B: Global synced state for channels
567function ChannelProvider({ channelId, children }: Props) {
568  const { state, update, submit } = useGlobalChannel(channelId)
569  const inputRef = useRef(null)
570 
571  return (
572    <ComposerContext
573      value={{
574        state,
575        actions: { update, submit },
576        meta: { inputRef },
577      }}
578    >
579      {children}
580    </ComposerContext>
581  )
582}
583```
584 
585**The same composed UI works with both:**
586 
587```tsx
588// Works with ForwardMessageProvider (local state)
589<ForwardMessageProvider>
590  <Composer.Frame>
591    <Composer.Input />
592    <Composer.Submit />
593  </Composer.Frame>
594</ForwardMessageProvider>
595 
596// Works with ChannelProvider (global synced state)
597<ChannelProvider channelId="abc">
598  <Composer.Frame>
599    <Composer.Input />
600    <Composer.Submit />
601  </Composer.Frame>
602</ChannelProvider>
603```
604 
605**Custom UI outside the component can access state and actions:**
606 
607The provider boundary is what matters—not the visual nesting. Components that
608need shared state don't have to be inside the `Composer.Frame`. They just need
609to be within the provider.
610 
611```tsx
612function ForwardMessageDialog() {
613  return (
614    <ForwardMessageProvider>
615      <Dialog>
616        {/* The composer UI */}
617        <Composer.Frame>
618          <Composer.Input placeholder="Add a message, if you'd like." />
619          <Composer.Footer>
620            <Composer.Formatting />
621            <Composer.Emojis />
622          </Composer.Footer>
623        </Composer.Frame>
624 
625        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
626        <MessagePreview />
627 
628        {/* Actions at the bottom of the dialog */}
629        <DialogActions>
630          <CancelButton />
631          <ForwardButton />
632        </DialogActions>
633      </Dialog>
634    </ForwardMessageProvider>
635  )
636}
637 
638// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
639function ForwardButton() {
640  const {
641    actions: { submit },
642  } = use(ComposerContext)
643  return <Button onPress={submit}>Forward</Button>
644}
645 
646// This preview lives OUTSIDE Composer.Frame but can read composer's state!
647function MessagePreview() {
648  const { state } = use(ComposerContext)
649  return <Preview message={state.input} attachments={state.attachments} />
650}
651```
652 
653The `ForwardButton` and `MessagePreview` are not visually inside the composer
654box, but they can still access its state and actions. This is the power of
655lifting state into providers.
656 
657The UI is reusable bits you compose together. The state is dependency-injected
658by the provider. Swap the provider, keep the UI.
659<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-context-interface:end -->
660 
661<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-decouple-implementation:start -->
662## Decouple State Management from UI
663 
664The provider component should be the only place that knows how state is managed.
665UI components consume the context interface—they don't know if state comes from
666useState, Zustand, or a server sync.
667 
668**Incorrect (UI coupled to state implementation):**
669 
670```tsx
671function ChannelComposer({ channelId }: { channelId: string }) {
672  // UI component knows about global state implementation
673  const state = useGlobalChannelState(channelId)
674  const { submit, updateInput } = useChannelSync(channelId)
675 
676  return (
677    <Composer.Frame>
678      <Composer.Input
679        value={state.input}
680        onChange={(text) => sync.updateInput(text)}
681      />
682      <Composer.Submit onPress={() => sync.submit()} />
683    </Composer.Frame>
684  )
685}
686```
687 
688**Correct (state management isolated in provider):**
689 
690```tsx
691// Provider handles all state management details
692function ChannelProvider({
693  channelId,
694  children,
695}: {
696  channelId: string
697  children: React.ReactNode
698}) {
699  const { state, update, submit } = useGlobalChannel(channelId)
700  const inputRef = useRef(null)
701 
702  return (
703    <Composer.Provider
704      state={state}
705      actions={{ update, submit }}
706      meta={{ inputRef }}
707    >
708      {children}
709    </Composer.Provider>
710  )
711}
712 
713// UI component only knows about the context interface
714function ChannelComposer() {
715  return (
716    <Composer.Frame>
717      <Composer.Header />
718      <Composer.Input />
719      <Composer.Footer>
720        <Composer.Submit />
721      </Composer.Footer>
722    </Composer.Frame>
723  )
724}
725 
726// Usage
727function Channel({ channelId }: { channelId: string }) {
728  return (
729    <ChannelProvider channelId={channelId}>
730      <ChannelComposer />
731    </ChannelProvider>
732  )
733}
734```
735 
736**Different providers, same UI:**
737 
738```tsx
739// Local state for ephemeral forms
740function ForwardMessageProvider({ children }) {
741  const [state, setState] = useState(initialState)
742  const forwardMessage = useForwardMessage()
743 
744  return (
745    <Composer.Provider
746      state={state}
747      actions={{ update: setState, submit: forwardMessage }}
748    >
749      {children}
750    </Composer.Provider>
751  )
752}
753 
754// Global synced state for channels
755function ChannelProvider({ channelId, children }) {
756  const { state, update, submit } = useGlobalChannel(channelId)
757 
758  return (
759    <Composer.Provider state={state} actions={{ update, submit }}>
760      {children}
761    </Composer.Provider>
762  )
763}
764```
765 
766The same `Composer.Input` component works with both providers because it only
767depends on the context interface, not the implementation.
768<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-decouple-implementation:end -->
769 
770<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-lift-state:start -->
771## Lift State into Provider Components
772 
773Move state management into dedicated provider components. This allows sibling
774components outside the main UI to access and modify state without prop drilling
775or awkward refs.
776 
777**Incorrect (state trapped inside component):**
778 
779```tsx
780function ForwardMessageComposer() {
781  const [state, setState] = useState(initialState)
782  const forwardMessage = useForwardMessage()
783 
784  return (
785    <Composer.Frame>
786      <Composer.Input />
787      <Composer.Footer />
788    </Composer.Frame>
789  )
790}
791 
792// Problem: How does this button access composer state?
793function ForwardMessageDialog() {
794  return (
795    <Dialog>
796      <ForwardMessageComposer />
797      <MessagePreview /> {/* Needs composer state */}
798      <DialogActions>
799        <CancelButton />
800        <ForwardButton /> {/* Needs to call submit */}
801      </DialogActions>
802    </Dialog>
803  )
804}
805```
806 
807**Incorrect (useEffect to sync state up):**
808 
809```tsx
810function ForwardMessageDialog() {
811  const [input, setInput] = useState('')
812  return (
813    <Dialog>
814      <ForwardMessageComposer onInputChange={setInput} />
815      <MessagePreview input={input} />
816    </Dialog>
817  )
818}
819 
820function ForwardMessageComposer({ onInputChange }) {
821  const [state, setState] = useState(initialState)
822  useEffect(() => {
823    onInputChange(state.input) // Sync on every change 😬
824  }, [state.input])
825}
826```
827 
828**Incorrect (reading state from ref on submit):**
829 
830```tsx
831function ForwardMessageDialog() {
832  const stateRef = useRef(null)
833  return (
834    <Dialog>
835      <ForwardMessageComposer stateRef={stateRef} />
836      <ForwardButton onPress={() => submit(stateRef.current)} />
837    </Dialog>
838  )
839}
840```
841 
842**Correct (state lifted to provider):**
843 
844```tsx
845function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
846  const [state, setState] = useState(initialState)
847  const forwardMessage = useForwardMessage()
848  const inputRef = useRef(null)
849 
850  return (
851    <Composer.Provider
852      state={state}
853      actions={{ update: setState, submit: forwardMessage }}
854      meta={{ inputRef }}
855    >
856      {children}
857    </Composer.Provider>
858  )
859}
860 
861function ForwardMessageDialog() {
862  return (
863    <ForwardMessageProvider>
864      <Dialog>
865        <ForwardMessageComposer />
866        <MessagePreview /> {/* Custom components can access state and actions */}
867        <DialogActions>
868          <CancelButton />
869          <ForwardButton /> {/* Custom components can access state and actions */}
870        </DialogActions>
871      </Dialog>
872    </ForwardMessageProvider>
873  )
874}
875 
876function ForwardButton() {
877  const { actions } = use(Composer.Context)
878  return <Button onPress={actions.submit}>Forward</Button>
879}
880```
881 
882The ForwardButton lives outside the Composer.Frame but still has access to the
883submit action because it's within the provider. Even though it's a one-off
884component, it can still access the composer's state and actions from outside the
885UI itself.
886 
887**Key insight:** Components that need shared state don't have to be visually
888nested inside each other—they just need to be within the same provider.
889<!-- forgecat:@forgecat/vercel-labs_agent-skills_composition-patterns:state-lift-state:end -->
890