@brookmind/ai-toolkit 1.0.5 → 1.1.2

package/skills/react-best-practices/rules/rendering-conditional-render.md

@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```

package/skills/react-best-practices/rules/rendering-content-visibility.md

@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).

package/skills/react-best-practices/rules/rendering-hoist-jsx.md

@@ -0,0 +1,65 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, react-compiler, optimization
+---
+
+## Hoist Static JSX Elements
+
+With React 19 Compiler, static JSX is automatically hoisted. Without the Compiler, manually extract static JSX outside components to avoid re-creation.
+
+**With React 19 Compiler (Recommended):**
+
+The React Compiler automatically detects and hoists static JSX. Just write normal components:
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />;
+}
+
+function Container({ loading }: { loading: boolean }) {
+  return <div>{loading && <LoadingSkeleton />}</div>;
+}
+// Compiler automatically optimizes this!
+```
+
+**Without React Compiler (Manual Optimization):**
+
+If you're not using the Compiler, manually hoist static elements:
+
+**Before (recreates element every render):**
+
+```tsx
+function Container({ loading }: { loading: boolean }) {
+  // This JSX is recreated on every render
+  const skeleton = <div className="animate-pulse h-20 bg-gray-200" />;
+
+  return <div>{loading && skeleton}</div>;
+}
+```
+
+**After (reuses same element):**
+
+```tsx
+// Hoisted to module scope - created once
+const loadingSkeleton = <div className="animate-pulse h-20 bg-gray-200" />;
+
+function Container({ loading }: { loading: boolean }) {
+  return <div>{loading && loadingSkeleton}</div>;
+}
+```
+
+**Best use cases for manual hoisting:**
+
+- Large static SVG icons (expensive to recreate)
+- Complex static layouts that never change
+- Decorative elements with no dynamic props
+
+**When NOT to hoist:**
+
+- Elements with dynamic props or children
+- Elements that need access to component scope (hooks, state)
+- Small simple elements (overhead not worth it)
+
+Reference: [React Compiler](https://react.dev/learn/react-compiler)

package/skills/react-best-practices/rules/rendering-svg-precision.md

@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```

package/skills/react-best-practices/rules/rerender-defer-reads.md

@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```

package/skills/react-best-practices/rules/rerender-dependencies.md

@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```

package/skills/react-best-practices/rules/rerender-derived-state.md

@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'}>
+}
+```

package/skills/react-best-practices/rules/rerender-functional-setstate.md

@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.

package/skills/react-best-practices/rules/rerender-lazy-state-init.md

@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

package/skills/react-best-practices/rules/rerender-memo.md

@@ -0,0 +1,85 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns and skips computation
+tags: rerender, memo, useMemo, react-compiler, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into separate components to enable early returns before computation. With React 19 Compiler, this happens automatically.
+
+**With React 19 Compiler (Recommended):**
+
+If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, you don't need manual memoization. The compiler automatically:
+
+- Memoizes component renders
+- Caches expensive computations
+- Optimizes re-renders
+
+Just write clean code without `memo()` or `useMemo()`:
+
+```tsx
+function UserAvatar({ user }: { user: User }) {
+  const id = computeAvatarId(user); // Compiler auto-memoizes
+  return <Avatar id={id} />;
+}
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />;
+  return (
+    <div>
+      <UserAvatar user={user} /> {/* Compiler auto-memoizes */}
+    </div>
+  );
+}
+```
+
+**Without React Compiler (Manual Optimization):**
+
+If you're not using the React Compiler, use `memo()` and `useMemo()` manually:
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  // This runs on every render, even when loading=true
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user);
+    return <Avatar id={id} />;
+  }, [user]);
+
+  if (loading) return <Skeleton />;
+  return <div>{avatar}</div>;
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user]);
+  return <Avatar id={id} />;
+});
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />;
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  );
+}
+```
+
+**Key insight:** Early returns before component JSX skip that component's computation entirely. Extract expensive work into child components that appear after conditionals.
+
+**When to still use memo() with Compiler:**
+
+Even with the Compiler, `memo()` can be useful for:
+
+- Components receiving frequently-changing callback props
+- Components in lists with stable item identity
+- Performance-critical components where you want explicit control
+
+Reference: [React Compiler](https://react.dev/learn/react-compiler)

package/skills/react-best-practices/rules/rerender-transitions.md

@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```

package/themes/README.md

@@ -0,0 +1,68 @@
+# Claude Vivid Theme
+
+A vibrant, high-contrast theme for OpenCode inspired by Claude Code's aesthetic.
+
+## Features
+
+- **Pure black background** (#000000) for maximum contrast
+- **Vivid syntax highlighting** with bright, saturated colors
+- **Neutral menu interactions** - Gray selection highlights instead of orange
+- **Optimized for dark mode** terminal usage
+
+## Color Palette
+
+### Primary Colors
+- Orange: `#FF6B35` - Headings, variables
+- Purple: `#A855F7` - Keywords  
+- Cyan: `#22D3EE` - Functions, links
+- Green: `#4ADE80` - Strings, success states
+- Yellow: `#FACC15` - Types, warnings
+- Pink: `#EC4899` - Numbers
+- Red: `#EF4444` - Errors
+
+### UI Colors
+- Background: `#000000` (pure black)
+- Panel: `#0a0a0a` (almost black)
+- Elements: `#1a1a1a` (very dark gray)
+- Borders: `#2a2a2a` (dark gray)
+- Selection: `#E5E5E5` (light gray - neutral)
+
+## Installation
+
+This theme is automatically installed when you run the AI Toolkit installer. It will be copied to `~/.config/opencode/themes/claude-vivid.json` and configured in your `opencode.json`.
+
+## Manual Installation
+
+If you want to install it manually:
+
+1. Create the themes directory:
+```bash
+mkdir -p ~/.config/opencode/themes
+```
+
+2. Copy the theme file:
+```bash
+cp themes/claude-vivid.json ~/.config/opencode/themes/
+```
+
+3. Update your `~/.config/opencode/opencode.json`:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "theme": "claude-vivid"
+}
+```
+
+4. Restart OpenCode or run `/theme claude-vivid`
+
+## Customization
+
+You can modify the theme by editing `~/.config/opencode/themes/claude-vivid.json`. All colors use the OpenCode theme schema with support for:
+
+- Hex colors: `"#ffffff"`
+- Color references: `"orange"` (defined in `defs`)
+- Dark/light variants: `{"dark": "#000", "light": "#fff"}`
+
+## Credits
+
+Created for the OpenCode AI Toolkit by @davidcastillog