@hitch42/applet 0.1.1-beta.1 → 0.1.1-beta.11

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.

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

@@ -0,0 +1,38 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, react-lazy
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `lazy` and `Suspense` to load large components only when React renders them.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from "./monaco-editor";
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />;
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import { lazy, Suspense } from "react";
+
+const MonacoEditor = lazy(() =>
+  import("./monaco-editor").then((module) => ({ default: module.MonacoEditor })),
+);
+
+function CodePanel({ code }: { code: string }) {
+  return (
+    <Suspense fallback={<EditorSkeleton />}>
+      <MonacoEditor value={code} />
+    </Suspense>
+  );
+}
+```

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

@@ -0,0 +1,40 @@
+---
+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 = () => {
+    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) {
+      void import("./monaco-editor").then((mod) => mod.init());
+    }
+  }, [flags.editorEnabled]);
+
+  return <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>;
+}
+```

package/scaffold/.agents/skills/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/scaffold/.agents/skills/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/scaffold/.agents/skills/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/scaffold/.agents/skills/react-best-practices/rules/js-batch-dom-css.md

@@ -0,0 +1,110 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+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.
+
+**This is OK (browser batches style changes):**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = "100px";
+  element.style.height = "200px";
+  element.style.backgroundColor = "blue";
+  element.style.border = "1px solid black";
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+
+```typescript
+function layoutThrashing(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();
+}
+```
+
+**Correct (batch reads, then writes):**
+
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect();
+  const offsetWidth = element.offsetWidth;
+  const offsetHeight = element.offsetHeight;
+
+  // Write phase - all style changes after
+  element.style.width = "100px";
+  element.style.height = "200px";
+}
+```
+
+**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();
+}
+```
+
+**React example:**
+
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = "100px";
+      const width = ref.current.offsetWidth; // Forces layout
+      ref.current.style.height = "200px";
+    }
+  }, [isHighlighted]);
+
+  return <div ref={ref}>Content</div>;
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return <div className={isHighlighted ? "highlighted-box" : ""}>Content</div>;
+}
+```
+
+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.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.

package/scaffold/.agents/skills/react-best-practices/rules/js-cache-function-results.md

@@ -0,0 +1,58 @@
+---
+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>
+  )
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.

package/scaffold/.agents/skills/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);
+}
+```