claude-toolkit 0.16.0 → 0.17.0

package/docs/best-practices/solidjs/context-and-global-state.md

@@ -1,131 +0,0 @@
-# Context & Global State
-
-> Sources: [Context](https://docs.solidjs.com/concepts/context), [Complex State Management](https://docs.solidjs.com/guides/complex-state-management) — SolidJS Docs
-
-## When to Use Context
-
-Context solves **prop drilling** — passing state through many component layers that don't use it themselves. Use it for:
-
-- Theme / appearance settings
-- Authentication state
-- Feature flags
-- Any state needed by many descendants
-
-**When NOT to use context:**
-- If only a few components need the data, pass props directly
-- If you can restructure the component tree to avoid drilling
-- For truly global singletons, a module-level signal may be simpler
-
-## Basic Context Pattern
-
-```typescript
-import { createContext, useContext } from "solid-js";
-import { createStore } from "solid-js/store";
-
-// 1. Create context
-const CounterContext = createContext<{
-  count: number;
-  increment: () => void;
-}>();
-
-// 2. Create provider component
-function CounterProvider(props: ParentProps) {
-  const [state, setState] = createStore({ count: 0 });
-  const value = {
-    get count() { return state.count; },
-    increment() { setState("count", c => c + 1); },
-  };
-
-  return (
-    <CounterContext.Provider value={value}>
-      {props.children}
-    </CounterContext.Provider>
-  );
-}
-
-// 3. Consume with useContext
-function Counter() {
-  const ctx = useContext(CounterContext);
-  return <button onClick={ctx.increment}>{ctx.count}</button>;
-}
-```
-
-## Safe useContext with Error Throwing
-
-`useContext` returns `undefined` when no provider exists above. Create a custom hook that throws a helpful error:
-
-```typescript
-function useCounter() {
-  const ctx = useContext(CounterContext);
-  if (!ctx) {
-    throw new Error("useCounter must be used within a CounterProvider");
-  }
-  return ctx;
-}
-```
-
-This also **narrows the TypeScript type** — no more `| undefined`.
-
-## Context + Store Pattern (Recommended)
-
-Combine `createStore` with context for scalable state. Stores give you fine-grained reactivity; context distributes it without prop drilling.
-
-```typescript
-function createTaskStore() {
-  const [state, setState] = createStore({
-    tasks: [] as Task[],
-    filter: "all" as "all" | "active" | "completed",
-  });
-
-  return {
-    get tasks() { return state.tasks; },
-    get filter() { return state.filter; },
-    addTask(text: string) {
-      setState("tasks", state.tasks.length, {
-        id: crypto.randomUUID(),
-        text,
-        completed: false,
-      });
-    },
-    toggleTask(id: string) {
-      setState("tasks", t => t.id === id, "completed", c => !c);
-    },
-    setFilter(filter: "all" | "active" | "completed") {
-      setState("filter", filter);
-    },
-  };
-}
-
-const TaskContext = createContext<ReturnType<typeof createTaskStore>>();
-
-function TaskProvider(props: ParentProps) {
-  return (
-    <TaskContext.Provider value={createTaskStore()}>
-      {props.children}
-    </TaskContext.Provider>
-  );
-}
-```
-
-**Why this works well in Solid:** Updating a signal at the top of the tree does NOT cause children to re-render. Only the specific reactive expressions that read the changed property update. There is no performance penalty for high-level state.
-
-## HMR Consideration
-
-To avoid recreating context during Hot Module Replacement, define `createContext` in its **own module** (separate file), not inline in a component file.
-
-## Module-Level Signals vs Context
-
-For truly global, app-wide singletons (e.g., a theme toggle), a module-level signal is simpler:
-
-```typescript
-// theme.ts
-export const [theme, setTheme] = createSignal<"light" | "dark">("light");
-
-// Any component can import directly
-import { theme, setTheme } from "./theme";
-```
-
-Use context instead when:
-- Different subtrees need different values (e.g., per-user state)
-- You need testability (mock providers in tests)
-- The state has complex dependencies

package/docs/best-practices/solidjs/control-flow.md

@@ -1,124 +0,0 @@
-# Control Flow
-
-> Sources: [Show](https://docs.solidjs.com/reference/components/show), [For](https://docs.solidjs.com/reference/components/for), [SolidJS Tutorials](https://www.solidjs.com/tutorial) — SolidJS Docs
-
-## Why Control Flow Components?
-
-In Solid, **avoid JavaScript-native conditionals and `.map()` in JSX**. Solid's control flow components provide explicit boundaries that the compiler can optimize — they track dependencies and minimize DOM operations.
-
-## `<Show>` — Conditional Rendering
-
-Renders children when `when` is truthy. Optionally provides a `fallback`.
-
-```typescript
-<Show when={user()} fallback={<LoginPrompt />}>
-  <Dashboard />
-</Show>
-```
-
-### Callback Form for Type Narrowing
-
-The callback form provides a non-null accessor — essential for TypeScript:
-
-```typescript
-<Show when={user()}>
-  {(nonNullUser) => <span>{nonNullUser().name}</span>}
-</Show>
-```
-
-TypeScript cannot narrow accessor types through control flow, so the callback form is the idiomatic way to access narrowed values.
-
-## `<For>` — List Rendering
-
-Renders a list, keyed by **reference** (not index). Only re-renders items that actually change.
-
-```typescript
-<For each={items()}>
-  {(item, index) => (
-    <li>{index()}: {item.name}</li>
-  )}
-</For>
-```
-
-- `item` is the value (not reactive for primitives)
-- `index()` is a signal — call it as a function
-- Items are tracked by reference — avoid recreating objects
-
-### `<Index>` — Keyed by Index
-
-For primitive arrays where values change but positions are stable:
-
-```typescript
-<Index each={names()}>
-  {(name, i) => <li>{i}: {name()}</li>}
-</Index>
-```
-
-- `name` is a signal (reactive)
-- `i` is a plain number (not reactive)
-
-**Rule of thumb:** Use `<For>` for arrays of objects, `<Index>` for arrays of primitives.
-
-## `<Switch>` / `<Match>` — Multi-Branch Conditional
-
-```typescript
-<Switch fallback={<p>Unknown state</p>}>
-  <Match when={state() === "loading"}>
-    <Spinner />
-  </Match>
-  <Match when={state() === "error"}>
-    <ErrorDisplay />
-  </Match>
-  <Match when={state() === "ready"}>
-    <Content />
-  </Match>
-</Switch>
-```
-
-First matching `<Match>` wins. Use `fallback` on `<Switch>` for the default case.
-
-## `<ErrorBoundary>` — Error Catching
-
-Catches errors thrown in child components and renders a fallback:
-
-```typescript
-<ErrorBoundary fallback={(err, reset) => (
-  <div>
-    <p>Error: {err.message}</p>
-    <button onClick={reset}>Retry</button>
-  </div>
-)}>
-  <RiskyComponent />
-</ErrorBoundary>
-```
-
-The `reset` function re-renders the children, giving the component a fresh chance.
-
-## `<Suspense>` — Async Loading States
-
-Displays a fallback while waiting for async resources to resolve:
-
-```typescript
-<Suspense fallback={<Skeleton />}>
-  <UserProfile />  {/* Uses createResource internally */}
-</Suspense>
-```
-
-Suspense detects any `createResource` read within its boundary and holds rendering until all resolve. Nested Suspense boundaries allow granular loading states.
-
-## `<Dynamic>` — Dynamic Component
-
-Render a component determined at runtime:
-
-```typescript
-<Dynamic component={isAdmin() ? AdminPanel : UserPanel} user={user()} />
-```
-
-## Don't Use
-
-| Instead of | Use |
-|---|---|
-| `{condition && <Component />}` | `<Show when={condition}>` |
-| `{condition ? <A /> : <B />}` | `<Show when={condition} fallback={<B />}>` |
-| `{items.map(i => ...)}` | `<For each={items()}>` |
-| Nested ternaries | `<Switch>` / `<Match>` |

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

@@ -1,205 +0,0 @@
-# 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

@@ -1,113 +0,0 @@
-# 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

@@ -1,100 +0,0 @@
-# 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