npm - gsd-pi - Versions diffs - 2.28.0 → 2.29.0-dev.23d50d0 - Mend

gsd-pi 2.28.0 → 2.29.0-dev.23d50d0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1321) hide show

package/dist/resources/skills/make-interfaces-feel-better/typography.md ADDED Viewed

@@ -0,0 +1,123 @@
+# Typography
+Typography rendering details that make interfaces feel better.
+## Text Wrapping
+### text-wrap: balance
+Distributes text evenly across lines, preventing orphaned words on headings and short text blocks. **Only works on blocks of 6 lines or fewer** (Chromium) or 10 lines or fewer (Firefox) — the balancing algorithm is computationally expensive, so browsers limit it to short text.
+```css
+/* Good — even line lengths on short text */
+h1, h2, h3 {
+  text-wrap: balance;
+}
+```
+```css
+/* Bad — default wrapping leaves orphans */
+h1 {
+  /* no text-wrap rule → "Read our
+     blog" instead of balanced lines */
+}
+```
+```css
+/* Bad — balance on long paragraphs (silently ignored, wastes intent) */
+.article-body p {
+  text-wrap: balance;
+}
+```
+**Tailwind:** `text-balance`
+### text-wrap: pretty
+Optimizes the last line to avoid orphans using a slower algorithm that favors better typography over performance. Unlike `balance`, it works on longer text — use this for body copy where you want to minimize orphans without the 6-line limit.
+```css
+p {
+  text-wrap: pretty;
+}
+```
+### When to Use Which
+| Scenario | Use |
+| --- | --- |
+| Headings, titles, short text (≤6 lines) | `text-wrap: balance` |
+| Body paragraphs, descriptions | `text-wrap: pretty` |
+| Code blocks, pre-formatted text | Neither — leave default |
+## Font Smoothing (macOS)
+On macOS, text renders heavier than intended by default. Apply antialiased smoothing to the root layout so all text renders crisper and thinner.
+```css
+/* CSS */
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+```tsx
+// Tailwind — apply to root layout
+<html className="antialiased">
+```
+### Good vs. Bad
+```css
+/* Good — applied once at the root */
+html {
+  -webkit-font-smoothing: antialiased;
+}
+/* Bad — applied per-element, inconsistent */
+.heading {
+  -webkit-font-smoothing: antialiased;
+}
+.body {
+  /* no smoothing → heavier than heading */
+}
+```
+**Note:** This only affects macOS rendering. Other platforms ignore these properties, so it's safe to apply universally.
+## Tabular Numbers
+When numbers update dynamically (counters, prices, timers, table columns), use tabular-nums to make all digits equal width. This prevents layout shift as values change.
+```css
+/* CSS */
+.counter {
+  font-variant-numeric: tabular-nums;
+}
+```
+```tsx
+// Tailwind
+<span className="tabular-nums">{count}</span>
+```
+### When to Use
+| Use tabular-nums | Don't use tabular-nums |
+| --- | --- |
+| Counters and timers | Static display numbers |
+| Prices that update | Decorative large numbers |
+| Table columns with numbers | Phone numbers, zip codes |
+| Animated number transitions | Version numbers (v2.1.0) |
+| Scoreboards, dashboards | |
+### Caveat
+Some fonts (like Inter) change the visual appearance of numerals with this property — specifically, the digit `1` becomes wider and centered. This is expected behavior and usually desirable for alignment, but verify it looks right in your specific font.
+```css
+/* With Inter font:
+   Default:  1234  → proportional, "1" is narrow
+   Tabular:  1234  → all digits equal width, "1" centered */
+```

package/dist/resources/skills/react-best-practices/README.md ADDED Viewed

@@ -0,0 +1,123 @@
+# React Best Practices
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+## Structure
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+## Getting Started
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+2. Build AGENTS.md from rules:
+   ```bash
+   pnpm build
+   ```
+3. Validate rule files:
+   ```bash
+   pnpm validate
+   ```
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+## Creating a New Rule
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `async-` for Eliminating Waterfalls (Section 1)
+   - `bundle-` for Bundle Size Optimization (Section 2)
+   - `server-` for Server-Side Performance (Section 3)
+   - `client-` for Client-Side Data Fetching (Section 4)
+   - `rerender-` for Re-render Optimization (Section 5)
+   - `rendering-` for Rendering Performance (Section 6)
+   - `js-` for JavaScript Performance (Section 7)
+   - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+## Rule File Structure
+Each rule file should follow this structure:
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+## Rule Title Here
+Brief explanation of the rule and why it matters.
+**Incorrect (description of what's wrong):**
+```typescript
+// Bad code example
+```
+**Correct (description of what's right):**
+```typescript
+// Good code example
+```
+Optional explanatory text after examples.
+Reference: [Link](https://example.com)
+## File Naming Convention
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+## Impact Levels
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+## Scripts
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+## Contributing
+When adding or modifying rules:
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+## Acknowledgments
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).

package/dist/resources/skills/react-best-practices/SKILL.md ADDED Viewed

@@ -0,0 +1,136 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+# Vercel React Best Practices
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+## When to Apply
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+## Rule Categories by Priority
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+## Quick Reference
+### 1. Eliminating Waterfalls (CRITICAL)
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+### 2. Bundle Size Optimization (CRITICAL)
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+### 3. Server-Side Performance (HIGH)
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+### 5. Re-render Optimization (MEDIUM)
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+### 6. Rendering Performance (MEDIUM)
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+### 7. JavaScript Performance (LOW-MEDIUM)
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+### 8. Advanced Patterns (LOW)
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+## How to Use
+Read individual rule files for detailed explanations and code examples:
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+## Full Compiled Document
+For the complete guide with all rules expanded: `AGENTS.md`

package/dist/resources/skills/react-best-practices/metadata.json ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}

package/dist/resources/skills/react-best-practices/rules/_sections.md ADDED Viewed

@@ -0,0 +1,46 @@
+# Sections
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+---
+## 1. Eliminating Waterfalls (async)
+**Impact:** CRITICAL
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+## 2. Bundle Size Optimization (bundle)
+**Impact:** CRITICAL
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+## 3. Server-Side Performance (server)
+**Impact:** HIGH
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+## 4. Client-Side Data Fetching (client)
+**Impact:** MEDIUM-HIGH
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+## 5. Re-render Optimization (rerender)
+**Impact:** MEDIUM
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+## 6. Rendering Performance (rendering)
+**Impact:** MEDIUM
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+## 7. JavaScript Performance (js)
+**Impact:** LOW-MEDIUM
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+## 8. Advanced Patterns (advanced)
+**Impact:** LOW
+**Description:** Advanced patterns for specific cases that require careful implementation.

package/dist/resources/skills/react-best-practices/rules/_template.md ADDED Viewed

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+## Rule Title Here
+**Impact: MEDIUM (optional impact description)**
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+**Incorrect (description of what's wrong):**
+```typescript
+// Bad code example here
+const bad = example()
+```
+**Correct (description of what's right):**
+```typescript
+// Good code example here
+const good = example()
+```
+Reference: [Link to documentation or resource](https://example.com)

package/dist/resources/skills/react-best-practices/rules/advanced-event-handler-refs.md ADDED Viewed

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+## Store Event Handlers in Refs
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+**Incorrect (re-subscribes on every render):**
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+**Correct (stable subscription):**
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+**Alternative: use `useEffectEvent` if you're on latest React:**
+```tsx
+import { useEffectEvent } from 'react'
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

package/dist/resources/skills/react-best-practices/rules/advanced-init-once.md ADDED Viewed

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+## Initialize App Once, Not Per Mount
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+**Incorrect (runs twice in dev, re-runs on remount):**
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+  // ...
+}
+```
+**Correct (once per app load):**
+```tsx
+let didInit = false
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+  // ...
+}
+```
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

package/dist/resources/skills/react-best-practices/rules/advanced-use-latest.md ADDED Viewed

@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+## useEffectEvent for Stable Callback Refs
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+**Incorrect (effect re-runs on every callback change):**
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+**Correct (using React's useEffectEvent):**
+```tsx
+import { useEffectEvent } from 'react';
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```

package/dist/resources/skills/react-best-practices/rules/async-api-routes.md ADDED Viewed

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+## Prevent Waterfall Chains in API Routes
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+**Incorrect (config waits for auth, data waits for both):**
+```typescript
+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):**
+```typescript
+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 })
+}
+```
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).