claude-toolkit 0.1.9

package/docs/best-practices/solidjs/stores-and-nested-state.md

@@ -0,0 +1,111 @@
+# Stores & Nested State
+
+> Sources: [Stores](https://docs.solidjs.com/concepts/stores), [Complex State Management](https://docs.solidjs.com/guides/complex-state-management) — SolidJS Docs
+
+## When to Use Stores
+
+Use `createStore` when your state is a **complex, nested object** or an **array of objects** that receives granular updates. Stores provide fine-grained reactivity at the **property level** — updating a nested property only re-renders the parts of UI that depend on that specific property.
+
+```typescript
+import { createStore } from "solid-js/store";
+
+const [state, setState] = createStore({
+  user: { name: "Alice", settings: { theme: "dark" } },
+  tasks: [
+    { id: 1, text: "Learn Solid", completed: false },
+  ],
+});
+```
+
+**Reading:** Access properties directly (no function call needed):
+
+```typescript
+<span>{state.user.name}</span>
+<span>{state.user.settings.theme}</span>
+```
+
+## Path Syntax Updates
+
+Stores use a **path syntax** for targeted, efficient updates:
+
+```typescript
+// Update a nested property
+setState("user", "settings", "theme", "light");
+
+// Update a specific array item
+setState("tasks", 0, "completed", true);
+
+// Update with a function
+setState("tasks", 0, "completed", prev => !prev);
+```
+
+### Array Operations
+
+```typescript
+// Append to array (targeted — doesn't recreate the array)
+setState("tasks", state.tasks.length, {
+  id: 2, text: "Ship it", completed: false,
+});
+
+// Update multiple indices
+setState("tasks", [0, 2], "completed", true);
+
+// Update by range
+setState("tasks", { from: 0, to: 3 }, "completed", false);
+
+// Update by predicate
+setState("tasks", task => task.completed, "archived", true);
+```
+
+## `produce` for Imperative Updates
+
+When you need to modify multiple properties at once, `produce` provides an imperative API:
+
+```typescript
+import { produce } from "solid-js/store";
+
+setState("tasks", 0, produce(task => {
+  task.completed = true;
+  task.completedAt = Date.now();
+}));
+
+// Also works at the store root
+setState(produce(state => {
+  state.tasks.push({ id: 3, text: "New task", completed: false });
+  state.user.name = "Bob";
+}));
+```
+
+`produce` creates a draft, applies your mutations, then produces an immutable update. Only use it with objects and arrays (not Sets or Maps).
+
+## `reconcile` for External Data
+
+When you receive a whole new object (e.g., from an API response), `reconcile` diffs the old and new data, only triggering updates for properties that actually changed:
+
+```typescript
+import { reconcile } from "solid-js/store";
+
+const newData = await fetchTasks();
+setState("tasks", reconcile(newData));
+```
+
+This avoids re-rendering everything when most of the data hasn't changed.
+
+## `unwrap` for Snapshots
+
+Extract a plain JavaScript object from a store (strips the reactive proxy):
+
+```typescript
+import { unwrap } from "solid-js/store";
+
+const snapshot = unwrap(state);
+// Use snapshot for third-party libraries, logging, or serialization
+```
+
+## Best Practices
+
+- **Use path syntax** for targeted updates — it's more efficient than replacing objects
+- **Use `produce`** when modifying multiple properties in one operation
+- **Use `reconcile`** when integrating API responses to avoid unnecessary updates
+- **Don't mutate store properties directly** — always go through `setState`
+- **Stores are batched automatically** — multiple `setState` calls in the same synchronous block are batched into one update

package/docs/best-practices/solidjs/typescript-integration.md

@@ -0,0 +1,186 @@
+# TypeScript Integration
+
+> Source: [TypeScript](https://docs.solidjs.com/configuration/typescript) — SolidJS Docs
+
+## TSConfig for SolidJS
+
+Required settings for Solid's JSX transformation:
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true
+  }
+}
+```
+
+`"jsx": "preserve"` is required — Solid's JSX transformation is incompatible with TypeScript's built-in JSX handling.
+
+## Typing Signals
+
+```typescript
+// Type is inferred from the initial value
+const [count, setCount] = createSignal(0); // Signal<number>
+
+// Explicit type when initial value doesn't capture the full type
+const [user, setUser] = createSignal<User | null>(null);
+
+// Without a default, type includes undefined
+const [data, setData] = createSignal<string>(); // Accessor<string | undefined>
+```
+
+## Typing Stores
+
+```typescript
+type AppState = {
+  user: User;
+  tasks: Task[];
+  settings: { theme: "light" | "dark" };
+};
+
+const [state, setState] = createStore<AppState>({
+  user: { id: "1", name: "Alice" },
+  tasks: [],
+  settings: { theme: "dark" },
+});
+```
+
+## Typing Context
+
+Provide a type parameter to `createContext`:
+
+```typescript
+type AuthContext = {
+  user: User | null;
+  login: (credentials: Credentials) => Promise<void>;
+  logout: () => void;
+};
+
+const AuthContext = createContext<AuthContext>();
+```
+
+**Factory pattern** — derive the type from the factory function:
+
+```typescript
+function createAuthStore() { /* ... */ }
+
+const AuthContext = createContext<ReturnType<typeof createAuthStore>>();
+```
+
+## Component Types
+
+```typescript
+import type { Component, ParentComponent, VoidComponent, FlowComponent } from "solid-js";
+
+// Standard component
+const App: Component = () => <div>Hello</div>;
+
+// Accepts children
+const Card: ParentComponent<{ title: string }> = (props) => (
+  <div>
+    <h2>{props.title}</h2>
+    {props.children}
+  </div>
+);
+
+// No children allowed
+const Icon: VoidComponent<{ name: string }> = (props) => (
+  <svg class={`icon-${props.name}`} />
+);
+```
+
+### Generic Components
+
+`Component` types don't support generics. Use function declarations:
+
+```typescript
+function Select<T>(props: {
+  options: T[];
+  value: T;
+  onChange: (value: T) => void;
+  label: (item: T) => string;
+}): JSX.Element {
+  return (
+    <For each={props.options}>
+      {(option) => (
+        <button
+          classList={{ active: option === props.value }}
+          onClick={() => props.onChange(option)}
+        >
+          {props.label(option)}
+        </button>
+      )}
+    </For>
+  );
+}
+```
+
+## Event Handlers
+
+Inline handlers are auto-typed. For extracted handlers:
+
+```typescript
+const handleInput: JSX.EventHandler<HTMLInputElement, InputEvent> = (e) => {
+  // e.currentTarget is typed as HTMLInputElement
+  setValue(e.currentTarget.value);
+};
+```
+
+## Control Flow Type Narrowing
+
+TypeScript can't narrow types through accessors. Use the callback form of `<Show>`:
+
+```typescript
+// WRONG — TypeScript doesn't know user() is non-null inside Show
+<Show when={user()}>
+  <span>{user()!.name}</span>  {/* Forced to use ! */}
+</Show>
+
+// RIGHT — callback provides narrowed accessor
+<Show when={user()}>
+  {(u) => <span>{u().name}</span>}
+</Show>
+```
+
+## Extending JSX Types
+
+### Custom Events
+
+```typescript
+declare module "solid-js" {
+  namespace JSX {
+    interface CustomEvents {
+      myEvent: CustomEvent<{ detail: string }>;
+    }
+  }
+}
+```
+
+### Custom Directives
+
+```typescript
+declare module "solid-js" {
+  namespace JSX {
+    interface Directives {
+      tooltip: string;
+      clickOutside: () => void;
+    }
+  }
+}
+```
+
+### Explicit Properties/Attributes
+
+```typescript
+declare module "solid-js" {
+  namespace JSX {
+    interface ExplicitProperties { /* prop:___ */ }
+    interface ExplicitAttributes { /* attr:___ */ }
+    interface ExplicitBoolAttributes { /* bool:___ */ }
+  }
+}
+```

package/docs/best-practices/typescript/README.md

@@ -0,0 +1,45 @@
+# Matt Pocock's TypeScript Best Practices
+
+> A curated collection of TypeScript best practices, opinions, and patterns from [Matt Pocock](https://www.mattpocock.com/) and [Total TypeScript](https://www.totaltypescript.com/).
+
+Matt Pocock is one of the most influential TypeScript educators. These documents capture his opinionated, production-tested guidance — not generic advice, but specific stances backed by reasoning.
+
+## Core Choices
+
+Foundational decisions that shape every TypeScript project.
+
+| Guide | Summary |
+|---|---|
+| [Type vs Interface](type-vs-interface.md) | Default to `type`. Use `interface` only for `extends`. |
+| [Enums & Alternatives](enums-alternatives.md) | Avoid enums. Use `as const` objects with derived unions. |
+| [any & unknown](any-and-unknown.md) | Ban `any` by default. Know the two legitimate exceptions. |
+| [TSConfig Cheat Sheet](tsconfig-cheat-sheet.md) | Recommended compiler options for every project shape. |
+
+## Patterns
+
+Type-level patterns that make code safer and more expressive.
+
+| Guide | Summary |
+|---|---|
+| [Discriminated Unions](discriminated-unions.md) | Model states as unions — make illegal states unrepresentable. |
+| [Generics Patterns](generics-patterns.md) | Three patterns: types-to-types, types-to-functions, inference. |
+| [The `satisfies` Operator](satisfies-operator.md) | Five practical uses for type validation without losing inference. |
+| [Essential Patterns](essential-patterns.md) | Branded types, globals, assertion functions, classes. |
+
+## Architecture
+
+How to organize and connect types across a codebase.
+
+| Guide | Summary |
+|---|---|
+| [Type Organization](type-organization.md) | Colocate, share at folder level, or extract to a package. |
+| [Deriving vs Decoupling](deriving-vs-decoupling.md) | Derive when tightly coupled. Decouple across concerns. |
+| [Runtime Validation](runtime-validation.md) | Use Zod at trust boundaries. Skip it for controlled inputs. |
+
+## Micro-Opinions
+
+Small but specific stances on everyday TypeScript choices.
+
+| Guide | Summary |
+|---|---|
+| [Micro-Opinions](micro-opinions.md) | Return types, `const` vs `let`, `T[]` vs `Array<T>`, method shorthand, `Function` type. |

package/docs/best-practices/typescript/any-and-unknown.md

@@ -0,0 +1,73 @@
+# `any` & `unknown`
+
+> Source: [any Considered Harmful, Except For These Cases](https://www.totaltypescript.com/any-considered-harmful) — Matt Pocock
+
+## The Rule
+
+**Ban `any` from your codebase.** Enable the ESLint rule that prevents its use and avoid it wherever possible.
+
+`any` disables TypeScript's core value proposition: type checking, autocomplete, and safety guarantees. It's a contagion — once `any` enters an expression, it spreads through assignments and return values.
+
+## What to Use Instead
+
+| Situation | Use |
+|---|---|
+| Type is genuinely unknown | `unknown` (then narrow before use) |
+| Type varies but has a consistent shape | Generics with constraints |
+| You know the data shape | The specific type |
+
+```typescript
+// Instead of any
+function parse(input: unknown): User {
+  if (typeof input === "object" && input !== null && "name" in input) {
+    return input as User;
+  }
+  throw new Error("Invalid input");
+}
+```
+
+## The Two Legitimate Exceptions
+
+Matt identifies two advanced scenarios where `any` is the right choice.
+
+### Exception 1: Type Argument Constraints in Generics
+
+When building generic utility types, `unknown` in constraints can be too restrictive:
+
+```typescript
+// This is too restrictive — only works with specific function shapes
+type ReturnType<T extends (...args: unknown[]) => unknown> = ...
+
+// any[] constraint is correct — "we don't care what the function accepts"
+type ReturnType<T extends (...args: any[]) => any> = ...
+```
+
+Using `any[]` here is intentional: you're declaring that the constraint should accept **any function**, not that you're bypassing safety.
+
+### Exception 2: Conditional Types in Generic Functions
+
+TypeScript's type narrowing sometimes can't verify that conditional type logic matches runtime behavior:
+
+```typescript
+function processValue<T extends string | number>(
+  value: T
+): T extends string ? string[] : number {
+  if (typeof value === "string") {
+    return value.split("") as any; // TypeScript can't narrow conditional return types
+  }
+  return (value as number) * 2 as any;
+}
+```
+
+In these cases, Matt recommends using `as any` **and adding a unit test** to validate the function's behavior at runtime.
+
+## The Pragmatic Approach
+
+When you genuinely need `any`, use an `eslint-disable` comment to make it explicit and reviewable:
+
+```typescript
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Callback = (...args: any[]) => void;
+```
+
+This creates a searchable record of every `any` in your codebase, making them easy to audit and justify in code review.

package/docs/best-practices/typescript/deriving-vs-decoupling.md

@@ -0,0 +1,83 @@
+# Deriving vs Decoupling
+
+> Source: [Deriving vs Decoupling: When NOT To Be A TypeScript Wizard](https://www.totaltypescript.com/deriving-vs-decoupling) — Matt Pocock
+
+## The Distinction
+
+- **Deriving** = creating a type that depends on another type's structure (`Pick`, `Omit`, `typeof`, mapped types)
+- **Decoupling** = creating independent types with no dependency between them
+
+The temptation to derive comes from TypeScript's powerful type manipulation. But cleverness isn't always correctness.
+
+## When to Decouple
+
+Decouple when types serve **different concerns** — different responsibilities with different reasons to change.
+
+```typescript
+// Database layer
+type User = {
+  id: string;
+  name: string;
+  email: string;
+  imageUrl: string;
+  passwordHash: string;
+};
+
+// UI layer — DON'T derive from User
+type AvatarProps = {
+  imageUrl: string;
+  name: string;
+};
+```
+
+Why not `Pick<User, "imageUrl" | "name">`? Because:
+- `User` lives in database code; `AvatarProps` is UI logic
+- They have different reasons to change
+- If `User.imageUrl` is renamed to `User.avatarUrl`, should every UI component break? Probably not.
+- The component should remain portable even if the data model moves
+
+As Matt puts it: "It's smarter to do the simple thing."
+
+## When to Derive
+
+Derive when types share a **common concern** and are tightly coupled by design.
+
+### From `as const` objects
+
+```typescript
+const albumTypes = {
+  CD: "cd",
+  VINYL: "vinyl",
+  DIGITAL: "digital",
+} as const;
+
+type AlbumType = (typeof albumTypes)[keyof typeof albumTypes];
+// "cd" | "vinyl" | "digital"
+```
+
+Maintaining a separate union and object would mean updating two places for every change — pure busywork.
+
+### Related variants
+
+```typescript
+type User = {
+  id: string;
+  name: string;
+  email: string;
+};
+
+type UserWithoutId = Omit<User, "id">;
+```
+
+These are directly related — a `UserWithoutId` is meaningless outside the context of `User`.
+
+## Decision Framework
+
+> "The decision to derive or decouple is all about reducing your future workload."
+
+| Signal | Action |
+|---|---|
+| Changing one type should always change the other | **Derive** |
+| Types serve different layers or concerns | **Decouple** |
+| Derivation adds complexity for marginal DRY benefit | **Decouple** |
+| Types share the same source of truth | **Derive** |

package/docs/best-practices/typescript/discriminated-unions.md

@@ -0,0 +1,75 @@
+# Discriminated Unions
+
+> Source: [TypeScript Discriminated Unions for Frontend Developers](https://www.totaltypescript.com/discriminated-unions-are-a-devs-best-friend) — Matt Pocock
+
+## The Problem: Bag of Optionals
+
+The naive approach to modeling state uses optional properties in a single type:
+
+```typescript
+// Don't do this
+type State = {
+  status: "loading" | "success" | "error";
+  data?: { id: string };
+  error?: Error;
+};
+```
+
+This allows **impossible states**: you can have `status: "success"` with no `data`, or `status: "loading"` with an `error`. TypeScript can't help you because every property is independently optional.
+
+## The Solution: Discriminated Unions
+
+Model each state as a distinct member of a union, with only the properties relevant to that state:
+
+```typescript
+type State =
+  | { status: "loading" }
+  | { status: "success"; data: { id: string } }
+  | { status: "error"; error: Error };
+```
+
+Now `data` only exists when `status` is `"success"`, and `error` only exists when `status` is `"error"`. Impossible states are unrepresentable.
+
+## Type Narrowing
+
+You must check the discriminator before accessing state-specific properties. This strictness is a feature:
+
+```typescript
+function handleState(state: State) {
+  if (state.status === "success") {
+    // TypeScript knows state.data exists here
+    console.log(state.data.id);
+  }
+
+  if (state.status === "error") {
+    // TypeScript knows state.error exists here
+    console.log(state.error.message);
+  }
+}
+```
+
+## Component Props Pattern
+
+Apply discriminated unions to component APIs with conditional properties:
+
+```typescript
+type ModalProps =
+  | {
+      variant: "with-description";
+      title: string;
+      description: string;
+      buttonText: string;
+    }
+  | {
+      variant: "base";
+      title: string;
+    };
+```
+
+This prevents consumers from passing `description` without `buttonText`, or using the wrong combination of props.
+
+## Why This Matters
+
+As Matt puts it: "Instead of a big optional bag of data, you'll start understanding the connections between data and UI."
+
+Discriminated unions force you to think about which data belongs together in which state — and the compiler enforces those relationships for you.

package/docs/best-practices/typescript/enums-alternatives.md

@@ -0,0 +1,72 @@
+# Enums & Alternatives
+
+> Source: [Why I Don't Like Enums](https://www.totaltypescript.com/why-i-dont-like-typescript-enums) — Matt Pocock
+
+## The Verdict
+
+**Avoid enums. Use `as const` objects with derived union types instead.**
+
+## Why Enums Are Problematic
+
+### 1. Numeric Enums Accept Raw Numbers
+
+Numeric enums allow passing any raw number where an enum value is expected — completely defeating the purpose of type safety.
+
+```typescript
+enum Direction {
+  Up,    // 0
+  Down,  // 1
+  Left,  // 2
+  Right, // 3
+}
+
+function move(dir: Direction) {}
+
+move(99); // No error! TypeScript allows this.
+```
+
+### 2. Inconsistent Behavior
+
+Numeric and string enums behave differently:
+- Numeric enums generate **bidirectional** mappings (value-to-key and key-to-value), doubling the runtime keys
+- String enums enforce stricter type-checking but don't generate reverse mappings
+- You can mix numeric and string values in a single enum (don't)
+
+### 3. Nominal Typing
+
+Enums use nominal typing — two enums with identical values are not interchangeable. This breaks from JavaScript's structural approach and creates surprising incompatibilities.
+
+### 4. Implementation Bugs
+
+The TypeScript repository has 71 open enum-related bug issues. The TS team has indicated many are architecturally unfixable.
+
+## The Alternative: `as const` Objects
+
+```typescript
+const Direction = {
+  Up: "up",
+  Down: "down",
+  Left: "left",
+  Right: "right",
+} as const;
+
+type Direction = (typeof Direction)[keyof typeof Direction];
+// "up" | "down" | "left" | "right"
+```
+
+This gives you:
+- A runtime object for lookups (`Direction.Up`)
+- A union type for type safety (`Direction`)
+- No surprising behavior
+- Standard JavaScript semantics
+
+## If You Must Use Enums
+
+Use **string enums only**. They behave more predictably, resemble the transpiled output more closely, and don't allow raw value assignment.
+
+```typescript
+enum Status {
+  Active = "active",
+  Inactive = "inactive",
+}
+```