@hitch42/applet 0.1.1-beta.7 → 0.1.1-beta.9

package/scaffold/.agents/skills/react-best-practices/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: react-best-practices
+description: Client React performance guidelines. Use when writing, reviewing, or refactoring React components, client data fetching, bundles, rendering, or browser performance.
+license: MIT
+metadata:
+  version: "1.0.0"
+---
+
+# React Best Practices
+
+Performance guidance for client React applications. The rules focus on browser behavior, client data fetching, bundles, rendering, and re-renders.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing new React components
+- Implementing client data fetching
+- Reviewing code for performance issues
+- Refactoring existing React 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        | Client-Side Data Fetching | MEDIUM-HIGH | `client-`    |
+| 4        | Re-render Optimization    | MEDIUM      | `rerender-`  |
+| 5        | Rendering Performance     | MEDIUM      | `rendering-` |
+| 6        | JavaScript Performance    | LOW-MEDIUM  | `js-`        |
+| 7        | Advanced Patterns         | LOW         | `advanced-`  |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `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
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable imports
+- `bundle-dynamic-imports` - Use React.lazy for heavy components
+- `bundle-defer-third-party` - Split non-critical libraries from the initial bundle
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 4. 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-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 5. 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-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Track async action pending state with useTransition
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 6. 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
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 7. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `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

package/scaffold/.agents/skills/react-best-practices/rules/advanced-effect-event-deps.md

@@ -0,0 +1,50 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from "react";
+
+function ChatRoom({ roomId, onConnected }: { roomId: string; onConnected: () => void }) {
+  const handleConnected = useEffectEvent(onConnected);
+
+  useEffect(() => {
+    const connection = createConnection(roomId);
+    connection.on("connected", handleConnected);
+    connection.connect();
+
+    return () => connection.disconnect();
+  }, [roomId, handleConnected]);
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from "react";
+
+function ChatRoom({ roomId, onConnected }: { roomId: string; onConnected: () => void }) {
+  const handleConnected = useEffectEvent(onConnected);
+
+  useEffect(() => {
+    const connection = createConnection(roomId);
+    connection.on("connected", handleConnected);
+    connection.connect();
+
+    return () => connection.disconnect();
+  }, [roomId]);
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)

package/scaffold/.agents/skills/react-best-practices/rules/advanced-event-handler-refs.md

@@ -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` reads the latest handler without re-subscribing. The Effect Event function does not have a stable identity.

package/scaffold/.agents/skills/react-best-practices/rules/advanced-init-once.md

@@ -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/scaffold/.agents/skills/react-best-practices/rules/advanced-use-latest.md

@@ -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/scaffold/.agents/skills/react-best-practices/rules/async-cheap-condition-before-await.md

@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag();
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag();
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.

package/scaffold/.agents/skills/react-best-practices/rules/async-defer-await.md

@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId);
+
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true };
+  }
+
+  // Only this branch uses userData
+  return processUserData(userData);
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true };
+  }
+
+  // Fetch only when needed
+  const userData = await fetchUserData(userId);
+  return processUserData(userData);
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId);
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId);
+
+  if (!resource) {
+    return { error: "Not found" };
+  }
+
+  const permissions = await fetchPermissions(userId);
+
+  if (!permissions.canEdit) {
+    return { error: "Forbidden" };
+  }
+
+  return await updateResourceData(resource, permissions);
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).

package/scaffold/.agents/skills/react-best-practices/rules/async-dependencies.md

@@ -0,0 +1,48 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
+const profile = await fetchProfile(user.id);
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+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);
+  },
+});
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser();
+const profilePromise = userPromise.then((user) => fetchProfile(user.id));
+
+const [user, config, profile] = await Promise.all([userPromise, fetchConfig(), profilePromise]);
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

package/scaffold/.agents/skills/react-best-practices/rules/async-parallel.md

@@ -0,0 +1,24 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser();
+const posts = await fetchPosts();
+const comments = await fetchComments();
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([fetchUser(), fetchPosts(), fetchComments()]);
+```

package/scaffold/.agents/skills/react-best-practices/rules/bundle-analyzable-paths.md

@@ -0,0 +1,42 @@
+---
+title: Prefer Statically Analyzable Imports
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, vite, webpack, rollup, esbuild, imports
+---
+
+## Prefer Statically Analyzable Imports
+
+Build tools work best when import paths are obvious at build time. If you hide the real path inside a variable, the tool can include too many files or fail to split the bundle correctly.
+
+Prefer explicit maps or literal paths so the set of reachable modules stays narrow and predictable.
+
+When analysis becomes too broad, the cost is real:
+
+- Larger browser bundles
+- Slower builds
+- More memory use
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: "./pages/home",
+  settings: "./pages/settings",
+} as const;
+
+const Page = await import(PAGE_MODULES[pageName]);
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import("./pages/home"),
+  settings: () => import("./pages/settings"),
+} as const;
+
+const Page = await PAGE_MODULES[pageName]();
+```
+
+Reference: [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)

package/scaffold/.agents/skills/react-best-practices/rules/bundle-barrel-imports.md

@@ -0,0 +1,39 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from "lucide-react";
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from "@mui/material";
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (direct imports):**
+
+```tsx
+import Button from "@mui/material/Button";
+import TextField from "@mui/material/TextField";
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries do not publish types for deep import paths. Verify that the package exports types for each subpath.
+
+These imports reduce the modules that the browser and build tool must process.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.

package/scaffold/.agents/skills/react-best-practices/rules/bundle-conditional.md

@@ -0,0 +1,35 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({
+  enabled,
+  setEnabled,
+}: {
+  enabled: boolean;
+  setEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+}) {
+  const [frames, setFrames] = useState<Frame[] | null>(null);
+
+  useEffect(() => {
+    if (enabled && !frames) {
+      import("./animation-frames.js")
+        .then((mod) => setFrames(mod.frames))
+        .catch(() => setEnabled(false));
+    }
+  }, [enabled, frames, setEnabled]);
+
+  if (!frames) return <Skeleton />;
+  return <Canvas frames={frames} />;
+}
+```

package/scaffold/.agents/skills/react-best-practices/rules/bundle-defer-third-party.md

@@ -0,0 +1,46 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: reduces the initial bundle
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Some analytics and logging components do not need to be in the initial bundle. Load them in a separate chunk.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import Analytics from "./analytics";
+
+export default function App() {
+  return (
+    <>
+      <AppRoutes />
+      <Analytics />
+    </>
+  );
+}
+```
+
+**Correct (loads from a separate chunk):**
+
+```tsx
+import { lazy, Suspense } from "react";
+
+const Analytics = lazy(() => import("./analytics"));
+
+export default function App() {
+  return (
+    <>
+      <AppRoutes />
+      <Suspense fallback={null}>
+        <Analytics />
+      </Suspense>
+    </>
+  );
+}
+```
+
+`React.lazy` loads this chunk when React first renders `<Analytics>`. This example renders it on startup, so it does not wait for idle time.