claude-toolkit 0.16.0 → 0.17.0

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

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

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

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

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

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

@@ -1,186 +0,0 @@
-# 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/testing/README.md

@@ -1,84 +0,0 @@
-# Testing Best Practices
-
-> A curated collection of testing best practices for the rendezvous.nz stack, sourced from official documentation, framework maintainers, and the testing community as of 2026.
-
-This project uses a **3-layer testing strategy** that maps to the classic testing pyramid. Each layer targets a different scope, runs in a different environment, and catches a different class of bugs.
-
-```
-          /  E2E  \           Playwright (real browsers)
-         /----------\         Full user flows, cross-browser
-        / Interaction \       Storybook (component sandbox)
-       /----------------\     Component behavior, visual, a11y
-      /      Unit        \    Vitest (Node/JSDOM)
-     /--------------------\   Pure logic, signals, utilities
-```
-
-## The Three Layers
-
-| Layer                                   | Tool             | Scope                                | Environment                            | Speed             |
-| --------------------------------------- | ---------------- | ------------------------------------ | -------------------------------------- | ----------------- |
-| [Unit](vitest-unit.md)                  | Vitest 4.x       | Functions, signals, hooks, utilities | Node / JSDOM                           | ~ms per test      |
-| [Interaction](storybook-interaction.md) | Storybook 10.x   | Component rendering, behavior, a11y  | Real browser (via Vitest addon)        | ~100ms per story  |
-| [E2E](playwright-e2e.md)                | Playwright 1.58+ | Full user flows, API integration     | Real browser (Chromium/Firefox/WebKit) | ~seconds per test |
-
-## When to Use Which Layer
-
-| Question                                                  | Layer                                  |
-| --------------------------------------------------------- | -------------------------------------- |
-| Does this logic need a DOM?                               | **Unit** if no, **Interaction** if yes |
-| Does it involve multiple pages or navigation?             | **E2E**                                |
-| Am I testing a single component's visual states?          | **Interaction**                        |
-| Am I testing a reactive primitive (signal, memo, effect)? | **Unit**                               |
-| Does it require authentication or real network?           | **E2E**                                |
-| Am I testing component accessibility?                     | **Interaction** (axe-core addon)       |
-| Am I testing cross-browser rendering?                     | **E2E** (multi-browser projects)       |
-| Does it need the Cloudflare Worker running?               | **E2E**                                |
-
-## Distribution Guideline
-
-Aim for the pyramid shape -- many fast unit tests at the base, fewer interaction tests in the middle, and a focused set of E2E tests at the top.
-
-| Layer       | Target Ratio | What to Cover                                                                |
-| ----------- | ------------ | ---------------------------------------------------------------------------- |
-| Unit        | ~70%         | Business logic, utilities, data transforms, reactive primitives, error paths |
-| Interaction | ~20%         | Component variants, user interactions, accessibility, visual regression      |
-| E2E         | ~10%         | Critical user journeys, authentication flows, cross-page workflows           |
-
-## Shared Principles Across All Layers
-
-1. **Test behavior, not implementation.** Assert what the user sees or what the API returns, not internal state.
-2. **Prefer role-based queries.** Use `getByRole`, `getByLabel`, `getByText` over test IDs or CSS selectors.
-3. **Never sleep.** Use framework-provided waiting mechanisms (`waitFor`, `findBy*`, web-first assertions).
-4. **One assertion focus per test.** A test should verify one behavior. Multiple assertions are fine if they verify facets of the same behavior.
-5. **Isolate tests.** No test should depend on another test's side effects. Reset state between tests.
-6. **Mock at boundaries.** Mock network calls and external services, not internal modules.
-7. **SolidJS reactivity rules apply in tests.** Never destructure props. Use `renderHook` or `createRoot` for signal testing.
-
-## SolidJS-Specific Considerations
-
-SolidJS components run once -- only reactive expressions re-execute. This affects testing:
-
-- **`render()` takes a callback**: `render(() => <Component />)`, not `render(<Component />)`.
-- **Effects are async**: Use `testEffect` from `@solidjs/testing-library` for effect assertions.
-- **Storybook decorators need `createJSXDecorator`**: Standard decorators cause duplicate DOM elements with SolidJS.
-
-## Technology Versions (as of April 2026)
-
-| Tool                     | Version | Notes                                                |
-| ------------------------ | ------- | ---------------------------------------------------- |
-| Vitest                   | ^4.1.x  | V8 coverage, test tags, builder-pattern fixtures     |
-| @solidjs/testing-library | ^0.8.x  | SolidJS-specific render, renderHook, testEffect      |
-| Storybook                | ^10.3.x | ESM-only, `sb.mock`, testing widget                  |
-| storybook-solidjs-vite   | ^10.0.x | Community-maintained SolidJS renderer                |
-| @storybook/addon-vitest  | ^10.x   | Replaces old test-runner, uses Vitest browser mode   |
-| Playwright               | ^1.58.x | Timeline view, Chrome for Testing, WebSocket mocking |
-| @axe-core/playwright     | ^4.x    | WCAG 2.1 AA automated accessibility checks           |
-| MSW                      | ^2.x    | Network mocking for both Storybook and Vitest        |
-
-## Guides
-
-| Guide                                                     | Summary                                                                      |
-| --------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| [Vitest Unit Testing](vitest-unit.md)                     | AAA pattern, signal testing, mocking, coverage, performance, anti-patterns.  |
-| [Storybook Interaction Testing](storybook-interaction.md) | CSF 3, play functions, a11y, visual regression, MSW, portable stories.       |
-| [Playwright E2E Testing](playwright-e2e.md)               | Page Objects, fixtures, auth, network mocking, CI/CD, flaky test prevention. |