devstack 0.1.0

package/vendor/skills/skills/vercel-react-best-practices/rules/bundle-preload.md

@@ -0,0 +1,44 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== "undefined") {
+      void import("./monaco-editor");
+    }
+  };
+
+  return (
+    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+      Open Editor
+    </button>
+  );
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== "undefined") {
+      void import("./monaco-editor").then(mod => mod.init());
+    }
+  }, [flags.editorEnabled]);
+
+  return <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>;
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

package/vendor/skills/skills/vercel-react-best-practices/rules/client-event-listeners.md

@@ -0,0 +1,78 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback();
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [key, callback]);
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from "swr/subscription";
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>();
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set());
+    }
+    keyCallbacks.get(key)!.add(callback);
+
+    return () => {
+      const set = keyCallbacks.get(key);
+      if (set) {
+        set.delete(callback);
+        if (set.size === 0) {
+          keyCallbacks.delete(key);
+        }
+      }
+    };
+  }, [key, callback]);
+
+  useSWRSubscription("global-keydown", () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb());
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  });
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut("p", () => {
+    /* ... */
+  });
+  useKeyboardShortcut("k", () => {
+    /* ... */
+  });
+  // ...
+}
+```

package/vendor/skills/skills/vercel-react-best-practices/rules/client-localstorage-schema.md

@@ -0,0 +1,74 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem("userConfig", JSON.stringify(fullUserObject));
+const data = localStorage.getItem("userConfig");
+```
+
+**Correct:**
+
+```typescript
+const VERSION = "v2";
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config));
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`);
+    return data ? JSON.parse(data) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem("userConfig:v1");
+    if (v1) {
+      const old = JSON.parse(v1);
+      saveConfig({ theme: old.darkMode ? "dark" : "light", language: old.lang });
+      localStorage.removeItem("userConfig:v1");
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem(
+      "prefs:v1",
+      JSON.stringify({
+        theme: user.preferences.theme,
+        notifications: user.preferences.notifications,
+      })
+    );
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.

package/vendor/skills/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md

@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX);
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY);
+
+  document.addEventListener("touchstart", handleTouch);
+  document.addEventListener("wheel", handleWheel);
+
+  return () => {
+    document.removeEventListener("touchstart", handleTouch);
+    document.removeEventListener("wheel", handleWheel);
+  };
+}, []);
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX);
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY);
+
+  document.addEventListener("touchstart", handleTouch, { passive: true });
+  document.addEventListener("wheel", handleWheel, { passive: true });
+
+  return () => {
+    document.removeEventListener("touchstart", handleTouch);
+    document.removeEventListener("wheel", handleWheel);
+  };
+}, []);
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.

package/vendor/skills/skills/vercel-react-best-practices/rules/client-swr-dedup.md

@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch("/api/users")
+      .then(r => r.json())
+      .then(setUsers);
+  }, []);
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from "swr";
+
+function UserList() {
+  const { data: users } = useSWR("/api/users", fetcher);
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from "@/lib/swr";
+
+function StaticContent() {
+  const { data } = useImmutableSWR("/api/config", fetcher);
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from "swr/mutation";
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation("/api/user", updateUser);
+  return <button onClick={() => trigger()}>Update</button>;
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)

package/vendor/skills/skills/vercel-react-best-practices/rules/js-batch-dom-css.md

@@ -0,0 +1,57 @@
+---
+title: Batch DOM CSS Changes
+impact: MEDIUM
+impactDescription: reduces reflows/repaints
+tags: javascript, dom, css, performance, reflow
+---
+
+## Batch DOM CSS Changes
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**Incorrect (interleaved reads and writes force reflows):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.style.width = "100px";
+  const width = element.offsetWidth; // Forces reflow
+  element.style.height = "200px";
+  const height = element.offsetHeight; // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = "100px";
+  element.style.height = "200px";
+  element.style.backgroundColor = "blue";
+  element.style.border = "1px solid black";
+
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect();
+}
+```
+
+**Better: use CSS classes**
+
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add("highlighted-box");
+
+  const { width, height } = element.getBoundingClientRect();
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.

package/vendor/skills/skills/vercel-react-best-practices/rules/js-cache-function-results.md

@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+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 => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null;
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache;
+  }
+
+  isLoggedInCache = document.cookie.includes("auth=");
+  return isLoggedInCache;
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null;
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

package/vendor/skills/skills/vercel-react-best-practices/rules/js-cache-property-access.md

@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value);
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value;
+const len = arr.length;
+for (let i = 0; i < len; i++) {
+  process(value);
+}
+```

package/vendor/skills/skills/vercel-react-best-practices/rules/js-cache-storage.md

@@ -0,0 +1,68 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem("theme") ?? "light";
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+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); // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null;
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(document.cookie.split("; ").map(c => c.split("=")));
+  }
+  return cookieCache[name];
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener("storage", e => {
+  if (e.key) storageCache.delete(e.key);
+});
+
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "visible") {
+    storageCache.clear();
+  }
+});
+```

package/vendor/skills/skills/vercel-react-best-practices/rules/js-combine-iterations.md

@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin);
+const testers = users.filter(u => u.isTester);
+const inactive = users.filter(u => !u.isActive);
+```
+
+**Correct (1 iteration):**
+
+```typescript
+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);
+}
+```

package/vendor/skills/skills/vercel-react-best-practices/rules/js-early-exit.md

@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false;
+  let errorMessage = "";
+
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true;
+      errorMessage = "Email required";
+    }
+    if (!user.name) {
+      hasError = true;
+      errorMessage = "Name required";
+    }
+    // Continues checking all users even after error found
+  }
+
+  return hasError ? { valid: false, error: errorMessage } : { valid: true };
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: "Email required" };
+    }
+    if (!user.name) {
+      return { valid: false, error: "Name required" };
+    }
+  }
+
+  return { valid: true };
+}
+```

package/vendor/skills/skills/vercel-react-best-practices/rules/js-hoist-regexp.md

@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g;
+regex.test("foo"); // true, lastIndex = 3
+regex.test("foo"); // false, lastIndex = 0
+```