@tinkcarlos/skillora 0.2.0

package/.claude/skills/react-best-practices/references/eliminating-waterfalls.md

@@ -0,0 +1,169 @@
+# Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+---
+
+## 1. Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used.
+
+```typescript
+// ❌ Incorrect: blocks both branches
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+
+  if (skipProcessing) {
+    return { skipped: true }
+  }
+
+  return processUserData(userData)
+}
+
+// ✅ Correct: only blocks when needed
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    return { skipped: true }
+  }
+
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+---
+
+## 2. Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+Use `better-all` to maximize parallelism for operations with partial dependencies.
+
+```typescript
+// ❌ Incorrect: profile waits for config unnecessarily
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+
+// ✅ Correct: config and profile run in parallel
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+Reference: https://github.com/shuding/better-all
+
+---
+
+## 3. Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+Start independent operations immediately, even if you don't await them yet.
+
+```typescript
+// ❌ Incorrect: config waits for auth, data waits for both
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+
+// ✅ Correct: auth and config start immediately
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+---
+
+## 4. Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+```typescript
+// ❌ Incorrect: sequential execution, 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// ✅ Correct: parallel execution, 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+---
+
+## 5. Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Use Suspense boundaries to show wrapper UI faster while data loads.
+
+```tsx
+// ❌ Incorrect: wrapper blocked by data fetching
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+// ✅ Correct: wrapper shows immediately, data streams in
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+**When NOT to use:**
+- Critical data needed for layout decisions
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift

package/.claude/skills/react-best-practices/references/javascript-performance.md

@@ -0,0 +1,256 @@
+# JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+---
+
+## 1. Batch DOM CSS Changes
+
+**Impact: MEDIUM (reduces reflows/repaints)**
+
+```typescript
+// ❌ Incorrect: multiple reflows
+function updateElementStyles(element: HTMLElement) {
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+
+// ✅ Correct: add class - single reflow
+// CSS: .highlighted-box { width: 100px; height: 200px; ... }
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+}
+
+// ✅ Correct: change cssText - single reflow
+function updateElementStyles(element: HTMLElement) {
+  element.style.cssText = `
+    width: 100px;
+    height: 200px;
+    background-color: blue;
+    border: 1px solid black;
+  `
+}
+```
+
+---
+
+## 2. Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+```typescript
+// ❌ Incorrect (O(n) per lookup)
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+
+// ✅ Correct (O(1) per lookup)
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+---
+
+## 3. Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+```typescript
+// ❌ Incorrect: 3 lookups × N iterations
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+
+// ✅ Correct: 1 lookup total
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+---
+
+## 4. Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+```typescript
+// ❌ Incorrect: redundant computation
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        const slug = slugify(project.name) // Called 100+ times
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+
+// ✅ Correct: cached results
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        const slug = cachedSlugify(project.name)
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+---
+
+## 5. Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+```typescript
+// ❌ Incorrect: reads storage on every call
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+
+// ✅ Correct: Map cache
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)
+}
+```
+
+---
+
+## 6. Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+```typescript
+// ❌ Incorrect: 3 iterations
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+
+// ✅ Correct: 1 iteration
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+---
+
+## 7. Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH**
+
+```typescript
+// ❌ Incorrect: always runs expensive comparison
+function hasChanges(current: string[], original: string[]) {
+  return current.sort().join() !== original.sort().join()
+}
+
+// ✅ Correct: O(1) length check first
+function hasChanges(current: string[], original: string[]) {
+  if (current.length !== original.length) {
+    return true
+  }
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+---
+
+## 8. Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+```typescript
+// ❌ Incorrect (O(n) per check)
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+
+// ✅ Correct (O(1) per check)
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+---
+
+## 9. Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs)**
+
+```typescript
+// ❌ Incorrect: mutates original array
+function UserList({ users }: { users: User[] }) {
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+
+// ✅ Correct: creates new array
+function UserList({ users }: { users: User[] }) {
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Other immutable array methods:**
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement

package/.claude/skills/react-best-practices/references/rendering-performance.md

@@ -0,0 +1,230 @@
+# Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+---
+
+## 1. Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements.
+
+```tsx
+// ❌ Incorrect: animating SVG directly - no hardware acceleration
+function LoadingSpinner() {
+  return (
+    <svg
+      className="animate-spin"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+
+// ✅ Correct: animating wrapper div - hardware accelerated
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+---
+
+## 2. CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+```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).
+
+---
+
+## 3. Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+```tsx
+// ❌ Incorrect: recreates element every render
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+
+// ✅ Correct: reuses same element
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+**Note:** If React Compiler is enabled, this is automatic.
+
+---
+
+## 4. Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+```svg
+<!-- ❌ Incorrect: excessive precision -->
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+
+<!-- ✅ Correct: 1 decimal place -->
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+---
+
+## 5. Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+```tsx
+// ❌ Incorrect: breaks SSR
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const theme = localStorage.getItem('theme') || 'light'
+  return <div className={theme}>{children}</div>
+}
+
+// ❌ Incorrect: visual flickering
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+
+  useEffect(() => {
+    const stored = localStorage.getItem('theme')
+    if (stored) setTheme(stored)
+  }, [])
+
+  return <div className={theme}>{children}</div>
+}
+
+// ✅ Correct: no flicker, no hydration mismatch
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+---
+
+## 6. Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+---
+
+## 7. Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+```tsx
+// ❌ Incorrect: renders "0" when count is 0
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+// When count = 0, renders: <div>0</div>
+
+// ✅ Correct: renders nothing when count is 0
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+// When count = 0, renders: <div></div>
+```