agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/frontend-developer/references/react-rules/server-hoist-static-io.md

@@ -0,0 +1,142 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+  
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Alternative: synchronous file reads with Node.js fs**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**General Node.js example: loading config or templates**
+
+```typescript
+// Incorrect: reads config on every call
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+  
+  return render(template, data, config)
+}
+
+// Correct: loads once at module level
+const configPromise = fs.readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise
+  ])
+  
+  return render(template, data, config)
+}
+```
+
+**When to use this pattern:**
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+**When NOT to use this pattern:**
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** Module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+**In traditional serverless:** Each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

package/template/agent/skills/frontend-developer/references/react-rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/template/agent/skills/frontend-developer/references/react-rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/template/agent/skills/frontend-developer/references/svelte-sveltekit.md

@@ -0,0 +1,220 @@
+# Svelte + SvelteKit Reference
+
+> **Philosophy:** Write less code. No virtual DOM. Compiled framework.
+> Reactivity is built into the language, not bolted on.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `svelte.config.js`, `package.json` with `svelte` or `@sveltejs/kit` dependency.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `svelte.config.js` | SvelteKit configuration (adapter, preprocess) |
+| `vite.config.ts` | Vite bundler configuration |
+| `tsconfig.json` | TypeScript configuration |
+| `.env` | Environment variables (prefixed `PUBLIC_` for client) |
+
+**Recommended project structure (SvelteKit):**
+
+```
+src/
+  routes/
+    +layout.svelte              # Root layout
+    +page.svelte                # Home page
+    +error.svelte               # Error page
+    about/
+      +page.svelte              # /about
+    users/
+      [id]/
+        +page.svelte            # /users/:id
+        +page.server.ts         # Server load function
+    api/
+      posts/
+        +server.ts              # API endpoint
+  lib/
+    components/                 # Reusable components
+    stores/                     # Svelte stores
+    server/                     # Server-only code ($lib/server/)
+    utils.ts                    # Shared utilities
+  app.html                      # HTML template
+  app.css                       # Global styles
+static/                         # Static assets
+```
+
+---
+
+## Architecture Patterns
+
+### Svelte 5 Runes (Default)
+
+```svelte
+<script lang="ts">
+  let count = $state(0)
+  let doubled = $derived(count * 2)
+
+  function increment() {
+    count++
+  }
+</script>
+
+<button onclick={increment}>{count} ({doubled})</button>
+```
+
+| Rune | Purpose |
+|------|---------|
+| `$state` | Reactive state declaration |
+| `$derived` | Computed value (replaces `$:` reactive statements) |
+| `$effect` | Side effect (replaces `$:` for effects) |
+| `$props` | Component props |
+| `$bindable` | Two-way binding capability |
+
+### Data Loading (SvelteKit)
+
+| Pattern | Use When |
+|---------|----------|
+| **`+page.server.ts` `load()`** | SSR data — runs on server only |
+| **`+page.ts` `load()`** | Universal — runs on server AND client |
+| **`+server.ts`** | API endpoints |
+| **Form actions** | Mutations (POST/PUT/DELETE) |
+
+```ts
+// src/routes/posts/+page.server.ts
+export async function load({ fetch }) {
+  const posts = await fetch('/api/posts').then(r => r.json())
+  return { posts }
+}
+
+// src/routes/posts/+page.svelte
+<script>
+  let { data } = $props()
+</script>
+
+{#each data.posts as post}
+  <article>{post.title}</article>
+{/each}
+```
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **`$state` (rune)** | Component-local state |
+| **Svelte stores (`writable`)** | Shared state across components |
+| **`$page.url.searchParams`** | URL state (filters, pagination) |
+| **Context API** | Scoped dependency injection |
+
+---
+
+## Performance Optimization
+
+### Why Svelte is Fast by Default
+
+- **No virtual DOM** — compiles to direct DOM manipulation
+- **No runtime framework** — smaller bundle (Svelte ~2KB vs React ~40KB)
+- **Granular reactivity** — only updates exactly what changed
+- **Automatic code splitting** — SvelteKit splits by route
+
+### Key Optimizations
+
+1. **`{#key}`** — force re-create a component when key changes.
+
+2. **`{#await}`** — built-in async rendering.
+
+```svelte
+{#await fetchData()}
+  <Spinner />
+{:then data}
+  <DataView {data} />
+{:catch error}
+  <ErrorMessage {error} />
+{/await}
+```
+
+3. **Enhanced image** — `@sveltejs/enhanced-img` for automatic optimization.
+
+4. **Streaming** — SvelteKit supports streaming SSR with nested `load` functions.
+
+5. **Preloading** — `data-sveltekit-preload-data="hover"` preloads links on hover.
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **UI** | `shadcn-svelte` | `skeleton`, `melt-ui` |
+| **Styling** | `tailwindcss` | `unocss` |
+| **Forms** | `superforms` + `zod` | `felte` |
+| **Auth** | `lucia` | `authjs-sveltekit` |
+| **Database** | `prisma` / `drizzle` | `kysely` |
+| **Testing** | `vitest` + `@testing-library/svelte` | — |
+| **E2E** | `playwright` | `cypress` |
+| **Icons** | `lucide-svelte` | `svelte-icons` |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| Svelte 4 `$:` reactive statements | Legacy (Svelte 5 uses runes) | `$derived`, `$effect` |
+| `onMount` for data fetching | Runs only on client, no SSR | `load()` in `+page.server.ts` |
+| Mutating `$state` arrays without reassignment | May not trigger reactivity | Push then reassign: `items = [...items, newItem]` |
+| `$effect` for derived state | Extra update cycle | Use `$derived` |
+| `PUBLIC_` prefix missing for client env | Variable not available in client | Prefix with `PUBLIC_` |
+| Importing `$lib/server` in client code | Server secrets leak to bundle | Use `$lib/server/` only in `.server.ts` |
+| Missing form `use:enhance` | Full page reload on submit | Add `use:enhance` for progressive enhancement |
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | Vitest + `@testing-library/svelte` | Components, stores |
+| **E2E** | Playwright | Full user flows |
+
+```ts
+import { render, screen } from '@testing-library/svelte'
+import Counter from '$lib/components/Counter.svelte'
+
+test('increments count', async () => {
+  render(Counter)
+  const button = screen.getByRole('button')
+  await button.click()
+  expect(button.textContent).toBe('1')
+})
+```
+
+---
+
+## Deployment & Distribution
+
+### Adapters
+
+SvelteKit uses adapters for different deployment targets:
+
+```bash
+npm run build
+```
+
+| Adapter | Platform |
+|---------|----------|
+| `@sveltejs/adapter-auto` | Auto-detect (Vercel, Netlify, Cloudflare) |
+| `@sveltejs/adapter-vercel` | Vercel |
+| `@sveltejs/adapter-node` | Node.js server |
+| `@sveltejs/adapter-static` | Static site (SSG) |
+| `@sveltejs/adapter-cloudflare` | Cloudflare Pages/Workers |
+
+```js
+// svelte.config.js
+import adapter from '@sveltejs/adapter-auto'
+
+export default {
+  kit: { adapter: adapter() }
+}
+```