claude-toolkit 0.1.9

package/docs/best-practices/solidjs/data-fetching.md

@@ -0,0 +1,205 @@
+# Data Fetching
+
+> Sources: [Fetching Data](https://docs.solidjs.com/guides/fetching-data), [createResource](https://docs.solidjs.com/reference/basic-reactivity/create-resource) — SolidJS Docs
+
+## createResource
+
+The primary tool for async data in SolidJS. Wraps an async operation into a reactive signal with built-in loading, error, and state tracking.
+
+```typescript
+const [user, { mutate, refetch }] = createResource(userId, async (id) => {
+  const res = await fetch(`/api/users/${id}`);
+  return res.json();
+});
+```
+
+- `userId` is the **source signal** — when it changes, the fetcher re-runs
+- The fetcher receives the source value as its first argument
+- Returns a resource signal with reactive properties
+
+### Resource Properties
+
+```typescript
+user()          // The resolved data (or undefined)
+user.loading    // Boolean — is a fetch in progress?
+user.error      // Error object if the fetch failed
+user.state      // "unresolved" | "pending" | "ready" | "refreshing" | "errored"
+user.latest     // Most recent successful data (persists during refetch)
+```
+
+## Handling States in JSX
+
+### With Control Flow
+
+```typescript
+<Show when={!user.loading} fallback={<Spinner />}>
+  <Show when={!user.error} fallback={<Error message={user.error.message} />}>
+    <UserCard user={user()} />
+  </Show>
+</Show>
+```
+
+### With Suspense + ErrorBoundary (recommended)
+
+```typescript
+<ErrorBoundary fallback={(err, reset) => (
+  <div>
+    <p>Failed: {err.message}</p>
+    <button onClick={reset}>Retry</button>
+  </div>
+)}>
+  <Suspense fallback={<Skeleton />}>
+    <UserCard />  {/* reads createResource internally */}
+  </Suspense>
+</ErrorBoundary>
+```
+
+Suspense detects resource reads within its boundary and shows the fallback until all resolve. This is the idiomatic pattern.
+
+## Optimistic Updates with `mutate`
+
+Update the UI immediately, then let the server catch up:
+
+```typescript
+const [tasks, { mutate, refetch }] = createResource(fetchTasks);
+
+function addTask(text: string) {
+  // Optimistic: update UI immediately
+  mutate(prev => [...(prev ?? []), { id: "temp", text, completed: false }]);
+  
+  // Then sync with server
+  postTask(text).then(() => refetch());
+}
+```
+
+`mutate` overwrites the resource value without calling the fetcher.
+
+## Refetching
+
+Force a refetch independent of the source signal:
+
+```typescript
+const [prices, { refetch }] = createResource(fetchPrices);
+
+// Poll every 10 seconds
+const interval = setInterval(refetch, 10_000);
+onCleanup(() => clearInterval(interval));
+```
+
+## createAsync (SolidStart / Solid Router)
+
+For SolidStart apps, `createAsync` is the recommended async primitive. It's a thin wrapper over `createResource` designed for router-integrated data loading:
+
+```typescript
+import { createAsync } from "@solidjs/router";
+
+const user = createAsync(() => getUser());
+```
+
+`createAsync` is intended to become the standard async primitive in Solid 2.0.
+
+## Runtime Validation with Zod / Valibot
+
+Data entering your app from APIs, forms, or `localStorage` should be validated at runtime — TypeScript types don't exist at runtime. See [TypeScript Runtime Validation](../typescript/runtime-validation.md) for when to validate.
+
+### Validating API Responses in `createResource`
+
+Parse and type-narrow data inside the fetcher so the resource signal is guaranteed to hold valid data:
+
+```typescript
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+const [user] = createResource(userId, async (id): Promise<User> => {
+  const res = await fetch(`/api/users/${id}`);
+  const json = await res.json();
+  return UserSchema.parse(json); // Throws on invalid shape
+});
+```
+
+`z.infer<typeof Schema>` keeps your TypeScript types and runtime validation in sync — no duplication.
+
+### A Reusable Typed Fetch Helper
+
+```typescript
+const fetchTyped = async <T extends z.ZodSchema>(
+  url: string,
+  schema: T,
+): Promise<z.infer<T>> => {
+  const res = await fetch(url);
+  return schema.parse(await res.json());
+};
+
+// Usage with createResource
+const [user] = createResource(userId, (id) =>
+  fetchTyped(`/api/users/${id}`, UserSchema)
+);
+```
+
+### Form Validation
+
+[@modular-forms/solid](https://modularforms.dev/solid/guides/validate-your-fields) has built-in Zod integration via the `zodForm` adapter:
+
+```typescript
+import { createForm } from "@modular-forms/solid";
+import { zodForm } from "@modular-forms/solid";
+
+const LoginSchema = z.object({
+  email: z.string().min(1, "Required").email("Invalid email"),
+  password: z.string().min(8, "Min 8 characters"),
+});
+
+type LoginForm = z.infer<typeof LoginSchema>;
+
+const [form, { Form, Field }] = createForm<LoginForm>({
+  validate: zodForm(LoginSchema),
+});
+```
+
+### Valibot as a Lighter Alternative
+
+[Valibot](https://valibot.dev/) provides the same validation patterns with a tree-shakeable design — ~1.4kb vs Zod's ~13kb for a typical form schema. Ryan Carniato (SolidJS creator) has endorsed it, and `@modular-forms/solid` supports it natively via `valiForm`.
+
+```typescript
+import * as v from "valibot";
+
+const UserSchema = v.object({
+  id: v.string(),
+  name: v.pipe(v.string(), v.nonEmpty()),
+  email: v.pipe(v.string(), v.email()),
+});
+
+type User = v.InferInput<typeof UserSchema>;
+```
+
+**Choose based on your constraints:**
+
+| Criteria        | Zod       | Valibot    |
+| --------------- | --------- | ---------- |
+| Bundle size     | ~13kb     | ~1.4kb     |
+| Tree-shakeable  | No        | Yes        |
+| Ecosystem       | Larger    | Growing    |
+| API style       | Chaining  | Functional |
+| Runtime speed   | Baseline  | ~2x faster |
+
+## Don't Fetch in Effects
+
+```typescript
+// WRONG — no loading state, no error handling, race conditions
+createEffect(async () => {
+  const data = await fetch(`/api/${id()}`);
+  setResult(await data.json());
+});
+
+// RIGHT — built-in state management, cancellation, reactivity
+const [result] = createResource(id, fetchData);
+```
+
+Effects run after render, causing a flash of empty state. Resources integrate with Suspense and provide proper loading/error states.

package/docs/best-practices/solidjs/effects-and-lifecycle.md

@@ -0,0 +1,113 @@
+# Effects & Lifecycle
+
+> Sources: [Effects](https://docs.solidjs.com/concepts/effects), [onMount](https://docs.solidjs.com/reference/lifecycle/on-mount), [onCleanup](https://docs.solidjs.com/reference/lifecycle/on-cleanup) — SolidJS Docs
+
+## createEffect
+
+Runs a side effect whenever its tracked dependencies change. Dependencies are automatically detected.
+
+```typescript
+createEffect(() => {
+  document.title = `${count()} items`;
+});
+```
+
+### When to Use Effects
+
+Effects are for **interacting with the outside world** — the DOM, third-party libraries, logging, WebSockets.
+
+**Use effects for:**
+- DOM manipulation not covered by JSX
+- Third-party library integration
+- WebSocket connections
+- Logging / analytics
+
+**Don't use effects for:**
+- Derived values → use `createMemo` or inline derivation
+- State synchronization → derive instead of sync
+- Data fetching → use `createResource`
+
+### The #1 Anti-Pattern: Syncing State
+
+```typescript
+// WRONG — creates glitchy intermediate states
+createEffect(() => {
+  setDoubled(count() * 2);
+});
+
+// RIGHT — derive the value
+const doubled = createMemo(() => count() * 2);
+```
+
+When you use effects to sync state, the reactive graph must choose an execution order, which can produce inconsistent intermediate states that flash in the UI.
+
+## `on` — Explicit Dependencies
+
+When you need to control which signals trigger an effect:
+
+```typescript
+import { on } from "solid-js";
+
+createEffect(on(userId, (id) => {
+  // Only runs when userId changes, not when other signals read inside change
+  fetchUserData(id);
+}));
+```
+
+`on` also provides the previous value:
+
+```typescript
+createEffect(on(count, (current, previous) => {
+  console.log(`Changed from ${previous} to ${current}`);
+}));
+```
+
+## onMount
+
+Runs once after the component's initial render, when DOM elements are available. Non-reactive — it doesn't track signals.
+
+```typescript
+onMount(() => {
+  // DOM is ready, refs are populated
+  inputRef?.focus();
+  
+  // Good for one-time setup
+  const chart = new Chart(canvasRef);
+});
+```
+
+**Use for:** ref access, one-time DOM setup, measurements, API calls that should only happen once.
+
+## onCleanup
+
+Runs when the enclosing reactive scope is disposed or re-executed. Essential for preventing memory leaks.
+
+```typescript
+// In a component — runs when component unmounts
+onCleanup(() => {
+  chart.destroy();
+});
+
+// In an effect — runs before each re-execution and on dispose
+createEffect(() => {
+  const id = setInterval(() => tick(), props.interval);
+  onCleanup(() => clearInterval(id));
+});
+```
+
+**Always clean up:**
+- Event listeners
+- Timers (`setInterval`, `setTimeout`)
+- WebSocket connections
+- Third-party library instances
+- Subscriptions
+
+## Lifecycle Order
+
+1. Component function runs (synchronous)
+2. Reactive expressions are set up (signals, memos, effects registered)
+3. DOM is created and mounted
+4. `onMount` callbacks fire
+5. Effects run (in dependency order)
+6. On signal change: effects re-run, `onCleanup` fires before each re-run
+7. On unmount: all `onCleanup` callbacks fire

package/docs/best-practices/solidjs/performance.md

@@ -0,0 +1,100 @@
+# Performance
+
+> Sources: [lazy](https://docs.solidjs.com/reference/component-apis/lazy), [batch](https://docs.solidjs.com/reference/reactive-utilities/batch), [untrack](https://docs.solidjs.com/reference/reactive-utilities/untrack) — SolidJS Docs
+
+## What Solid Optimizes For You
+
+Before reaching for performance tools, understand what Solid already does:
+
+- **No virtual DOM diffing** — updates go directly to the specific DOM nodes
+- **Components run once** — no re-renders, no stale closures
+- **Automatic batching in stores** — multiple `setState` calls in the same synchronous block are batched
+- **Conditional dependency tracking** — branches not taken don't create subscriptions
+- **Equality checks on signals** — redundant updates are ignored
+
+Most performance problems in Solid come from **fighting the reactive model**, not from the framework itself.
+
+## `batch` — Group Signal Updates
+
+When updating multiple independent signals in one synchronous operation, `batch` prevents intermediate re-renders:
+
+```typescript
+import { batch } from "solid-js";
+
+batch(() => {
+  setFirstName("John");
+  setLastName("Doe");
+  setAge(30);
+});
+// All effects that depend on these signals run once, not three times
+```
+
+Without `batch`, each setter triggers its dependents immediately. With `batch`, all updates are applied, then dependents run once with the final state.
+
+**Note:** Store `setState` calls are already batched automatically. `batch` is primarily useful for multiple `createSignal` setters.
+
+## `untrack` — Read Without Subscribing
+
+Read a reactive value without creating a dependency:
+
+```typescript
+import { untrack } from "solid-js";
+
+createEffect(() => {
+  // This effect re-runs when query() changes
+  // But does NOT re-run when options() changes
+  fetchData(query(), untrack(() => options()));
+});
+```
+
+**Use for:**
+- Static configuration that shouldn't trigger re-runs
+- Initial values you read once
+- Avoiding circular dependencies
+
+## `lazy` — Code Splitting
+
+Lazy-load components to reduce initial bundle size:
+
+```typescript
+import { lazy } from "solid-js";
+
+const AdminPanel = lazy(() => import("./AdminPanel"));
+
+// Renders like a normal component
+// Loads the code on first render, triggers Suspense boundaries
+<Suspense fallback={<Spinner />}>
+  <AdminPanel />
+</Suspense>
+```
+
+The component loads on first render, not on import. Combine with `<Suspense>` for loading states.
+
+## `<Dynamic>` — Avoid Mounting All Variants
+
+Instead of conditionally showing/hiding multiple heavy components, use `<Dynamic>` to mount only the active one:
+
+```typescript
+const panels = { settings: Settings, profile: Profile, billing: Billing };
+
+<Dynamic component={panels[activePanel()]} />
+```
+
+## Performance Anti-Patterns
+
+| Anti-Pattern | Why It's Slow | Fix |
+|---|---|---|
+| Recreating objects in signals | Triggers all subscribers on every set | Use stores for nested data |
+| Using `.map()` instead of `<For>` | Recreates all DOM nodes on any change | Use `<For>` or `<Index>` |
+| Effects that sync state | Creates cascading updates | Derive with `createMemo` |
+| Reading signals at component top level | Captures once, never updates | Read in JSX or effects |
+| Wrapping everything in effects | Unnecessary tracking overhead | Only for external side effects |
+
+## When to Actually Worry
+
+Solid's reactivity is already very fast. Optimize only when you observe actual performance issues:
+
+1. **Lists with 1000+ items** — ensure you're using `<For>` not `.map()`
+2. **Rapid signal updates** (e.g., mouse move) — consider `batch` or throttling
+3. **Large initial bundle** — use `lazy` for routes and heavy components
+4. **Deep store trees** — use path syntax updates, not object replacement

package/docs/best-practices/solidjs/props-patterns.md

@@ -0,0 +1,100 @@
+# Props Patterns
+
+> Sources: [Props](https://docs.solidjs.com/concepts/components/props), [Props Tutorials](https://www.solidjs.com/tutorial/props_defaults) — SolidJS Docs
+
+## The Cardinal Rule: Never Destructure Props
+
+Props use **getters** internally for reactive tracking. Destructuring extracts the value once, severing the reactive connection permanently.
+
+```typescript
+// WRONG — breaks reactivity
+const MyComponent = ({ name, count }) => {
+  return <div>{name}: {count}</div>; // Never updates
+};
+
+// WRONG — same problem
+const MyComponent = (props) => {
+  const { name } = props; // Captured once, never reactive
+  return <div>{name}</div>;
+};
+
+// CORRECT — preserves reactivity
+const MyComponent = (props) => {
+  return <div>{props.name}: {props.count}</div>;
+};
+```
+
+## `mergeProps` for Defaults
+
+Set default prop values without breaking reactivity:
+
+```typescript
+import { mergeProps } from "solid-js";
+
+const Button = (props) => {
+  const merged = mergeProps({ variant: "primary", size: "md" }, props);
+  return <button class={`btn-${merged.variant} btn-${merged.size}`}>
+    {merged.children}
+  </button>;
+};
+```
+
+`mergeProps` resolves properties in reverse order — later objects override earlier ones while preserving reactive tracking.
+
+## `splitProps` for Prop Forwarding
+
+Safely separate local props from props to forward to children:
+
+```typescript
+import { splitProps } from "solid-js";
+
+const Input = (props) => {
+  const [local, inputProps] = splitProps(props, ["label", "error"]);
+  
+  return (
+    <div>
+      <label>{local.label}</label>
+      <input {...inputProps} />
+      <Show when={local.error}>
+        <span class="error">{local.error}</span>
+      </Show>
+    </div>
+  );
+};
+```
+
+You can split into multiple groups:
+
+```typescript
+const [style, events, rest] = splitProps(props, ["class", "style"], ["onClick", "onInput"]);
+```
+
+## `children` Helper
+
+Accessing `props.children` multiple times can create duplicate elements. Use the `children` helper to resolve children once:
+
+```typescript
+import { children } from "solid-js";
+
+const ColoredList = (props) => {
+  const resolved = children(() => props.children);
+  
+  return <div class="colored">{resolved()}</div>;
+};
+```
+
+The helper resolves any dynamic children into a flat array, memoized for safe repeated access.
+
+## Call Signals Before Passing as Props
+
+When passing a signal value to a child component, call the getter. Components shouldn't need to know whether a prop came from a signal or a static value.
+
+```typescript
+// CORRECT — child receives a plain value
+<UserCard name={userName()} age={userAge()} />
+
+// Also valid — passing a reactive getter for the child to track
+<UserCard name={userName} />  // child would read props.name()
+```
+
+The first pattern is simpler and recommended for most cases. The second is useful when you want the child to participate in fine-grained tracking.

package/docs/best-practices/solidjs/reactivity-model.md

@@ -0,0 +1,104 @@
+# Reactivity Model
+
+> Sources: [Fine-Grained Reactivity](https://docs.solidjs.com/advanced-concepts/fine-grained-reactivity), [Intro to Reactivity](https://docs.solidjs.com/concepts/intro-to-reactivity) — SolidJS Docs
+
+## The Core Difference
+
+SolidJS uses **fine-grained reactivity**. Updates target specific DOM elements that depend on changed data — not entire component trees. Components run **once**; only the reactive expressions inside them re-execute.
+
+This means:
+- No virtual DOM diffing
+- No component re-renders
+- No stale closure bugs
+- Updates are surgical and automatic
+
+## How It Works
+
+### Signals, Effects, and the Subscription Model
+
+The reactive system has two key elements: **signals** (data sources) and **observers** (effects, memos, JSX expressions).
+
+1. A global `currentSubscriber` variable tracks the active observer
+2. When an observer runs, it sets itself as the current subscriber
+3. Any signal read during that execution registers the subscriber
+4. When a signal's value changes, all registered subscribers re-execute
+5. The subscriber reference is cleared after execution
+
+```typescript
+const [count, setCount] = createSignal(0);
+
+// This effect becomes a subscriber of `count`
+createEffect(() => {
+  console.log(count()); // Reading count() registers the dependency
+});
+
+setCount(1); // Notifies the effect, which re-runs
+```
+
+### Equality Checks
+
+Signals only notify subscribers when the value **actually changes**. Redundant updates (setting the same value) are ignored.
+
+```typescript
+setCount(0); // If count is already 0, no effects fire
+```
+
+## The Synchronous Contract
+
+Reactivity in Solid is **synchronous**. The system registers a subscriber, runs the function, and unregisters — all in one synchronous pass.
+
+This means **async operations break tracking**:
+
+```typescript
+// BROKEN — fetch happens after tracking ends
+createEffect(async () => {
+  const data = await fetch(url());  // url() is tracked
+  setResult(data);                   // but this runs after tracking ends
+});
+
+// CORRECT — use createResource for async
+const [data] = createResource(url, fetchData);
+```
+
+## Dependency Tracking is Automatic
+
+You don't declare dependencies. Solid tracks them by observing which signals are read during execution:
+
+```typescript
+createEffect(() => {
+  // Solid automatically knows this depends on firstName() and lastName()
+  console.log(`${firstName()} ${lastName()}`);
+});
+```
+
+### Conditional Tracking
+
+If a branch isn't taken, signals in that branch aren't tracked:
+
+```typescript
+const display = createMemo(() => {
+  if (!showDetails()) return "Hidden";
+  // name() and age() are only tracked when showDetails() is true
+  return `${name()}, age ${age()}`;
+});
+```
+
+## Derive, Don't Sync
+
+The golden rule of Solid reactivity:
+
+**If a value can be computed from other reactive values, derive it — don't synchronize it with an effect.**
+
+```typescript
+// WRONG — synchronizing state
+createEffect(() => {
+  setDoubled(count() * 2);
+});
+
+// RIGHT — deriving state
+const doubled = createMemo(() => count() * 2);
+// or simply:
+const doubled = () => count() * 2;
+```
+
+Derived values integrate naturally with the reactive graph. Effects that synchronize state create ordering problems and glitchy intermediate states.

package/docs/best-practices/solidjs/signals-and-state.md

@@ -0,0 +1,78 @@
+# Signals & State
+
+> Sources: [Signals](https://docs.solidjs.com/concepts/signals), [Derived Signals](https://docs.solidjs.com/concepts/derived-values/derived-signals) — SolidJS Docs
+
+## createSignal
+
+The primary state primitive. Returns a getter function and a setter function.
+
+```typescript
+const [count, setCount] = createSignal(0);
+
+// Read: always call as a function
+console.log(count()); // 0
+
+// Write: direct value or updater function
+setCount(5);
+setCount(prev => prev + 1);
+```
+
+**Key mental model:** The getter is a function, not a value. You must call `count()` to read it. Forgetting the parentheses is the most common Solid mistake.
+
+## Derived Values
+
+### Inline Derivations
+
+For simple computations, a plain function is sufficient:
+
+```typescript
+const doubled = () => count() * 2;
+```
+
+This re-evaluates every time it's called in a reactive context. No caching.
+
+### createMemo
+
+For expensive computations or values read in multiple places, use `createMemo` to cache the result:
+
+```typescript
+const sorted = createMemo(() => {
+  console.log("Sorting..."); // Only runs when items() changes
+  return items().slice().sort((a, b) => a.localeCompare(b));
+});
+```
+
+**When to use `createMemo` vs inline derivation:**
+
+| Scenario | Use |
+|---|---|
+| Simple, cheap computation | Inline function `() => ...` |
+| Expensive computation (sort, filter, map) | `createMemo` |
+| Value read in multiple reactive contexts | `createMemo` |
+| Value used once in JSX | Inline function |
+
+## Signals for Functions
+
+If you need to store a function as a signal value, use the callback form of the setter to avoid Solid treating it as an updater:
+
+```typescript
+const [handler, setHandler] = createSignal<() => void>(() => {});
+
+// WRONG — Solid calls this as an updater
+setHandler(myFunction);
+
+// RIGHT — wrap in callback
+setHandler(() => myFunction);
+```
+
+## When to Use Signals vs Stores
+
+| Data shape | Use |
+|---|---|
+| Single primitive value | `createSignal` |
+| Simple object (few properties, flat) | `createSignal` |
+| Complex nested object | `createStore` |
+| Array of objects with updates | `createStore` |
+| Shared state across components | `createStore` + context |
+
+See [Stores & Nested State](stores-and-nested-state.md) for store patterns.