chore: add claude code configuration

Shared plugin settings and path-scoped convention rules for
JavaScript, TypeScript, React, and React testing. Per-user
settings.local.json stays untracked via .gitignore.

Author: xobotyi

.claude/rules/javascript.md

@@ -0,0 +1,105 @@
+---
+paths:
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.mts"
+  - "**/*.cts"
+---
+
+# JavaScript Conventions
+
+Clarity is the highest virtue — if control flow needs a comment, rewrite it. Prefer boring patterns over clever
+tricks. If existing code contradicts a rule below, follow the code and flag the divergence. For TypeScript files these
+rules are the base layer; [typescript.md](typescript.md) stacks on top.
+
+## Declarations & Naming
+
+- `const` by default, `let` only when reassigned, never `var`. One declaration per line; `const` group before `let`.
+  `const` prevents reassignment, not mutation.
+- camelCase for variables/functions, PascalCase for classes, `#private` class fields (not `_` convention),
+  `is`/`has`/`can`/`should` prefixes for booleans, kebab-case file names.
+- SCREAMING_SNAKE_CASE only for true compile-time constants — a variable holding a computed value is camelCase.
+- Descriptive names; short names (`i`, `x`) only in tiny scopes. Accepted abbreviations: `url`, `id`, `err`, `ctx`,
+  `req`, `res` — avoid others. No redundant context (`car.make`, not `car.carMake`). Same word for the same concept
+  across the codebase.
+
+## Equality & Safety
+
+- Always `===`/`!==`; the only valid `==` is `value == null` (catches both `null` and `undefined`).
+- `??` over `||` for defaults — `||` swallows `0`, `""`, `false`.
+- `?.` sparingly: data you expect to exist should throw, not silently yield `undefined`.
+- Falsy values: `false`, `0`, `-0`, `0n`, `""`, `null`, `undefined`, `NaN` — everything else is truthy, including
+  `[]`, `{}`, `"0"`.
+- Ternaries: one-liner or one-branch-per-line only; anything else becomes `if`/`else` or early return. Nested
+  ternaries are banned — no exceptions.
+
+## Syntax
+
+- Template literals only when interpolating; plain quotes otherwise.
+- Spread for copies (`{ ...obj }`, `[...arr]`), never `Object.assign`. Shorthand properties, grouped at the top of
+  the literal. Computed keys `{ [key]: value }`. Logical assignment: `opts.timeout ??= 5000`.
+
+## Functions
+
+- Arrows for callbacks/anonymous functions; function declarations when hoisting or `this` binding is needed.
+  Parentheses around single arrow params. Never arrows as object methods or on prototypes (lexical `this`).
+- Destructured options object for 3+ parameters. Default parameters over `||`/manual checks. Rest params over
+  `arguments`.
+- Early return, guard clauses first, happy path flat. One function, one job — a name containing "and" means split.
+  Keep under ~30 lines; extract helpers.
+- Prefer pure functions; isolate side effects (DOM, network, logging) — don't hide them inside data transformations.
+- Closures retain references, not copies — beware large objects captured unintentionally.
+
+## Async
+
+- `async`/`await` over `.then()` chains. Always `await` promises — a floating promise is a silent failure.
+  Fire-and-forget must attach `.catch(reportError)`.
+- `return await` only inside `try` where you catch the error; otherwise return the promise directly.
+- Parallel independent work: `Promise.all`; all results regardless of failure: `Promise.allSettled`; timeout:
+  `Promise.race`; fallback: `Promise.any`. No sequential awaits in loops — `Promise.all(items.map(...))`, or a
+  concurrency limiter (`p-map`) for large arrays.
+- Throw `Error` objects, never strings. Custom error classes (extend `Error`, set `name`, add context) when callers
+  must distinguish.
+- Never swallow errors — every `catch` handles, rethrows, or reports; `console.log(err)` is not handling. Let errors
+  propagate to a top-level handler; don't wrap every `await` in `try`/`catch`.
+- `new Promise()` only to wrap callback APIs. `AbortController`/`{ signal }` for cancellation. `for await...of` for
+  async iterables.
+
+## Modules
+
+- ES modules only; CommonJS is legacy. Named exports over default (exceptions: framework-required conventions).
+  Never export mutable `let` — export accessor functions.
+- Imports at top, grouped with blank lines: built-in (`node:fs`), external, internal. Merge imports from the same
+  module. Namespace import (`import * as x`) at 5+ items, named below that.
+- Include file extensions in relative import paths (`"./user.js"`); no directory imports resolving to `index.js`.
+- No barrel files in subdirectories — acceptable only as a package entry point enforced via `package.json` `exports`.
+  No wildcard re-exports. No circular dependencies — extract a third module or inject.
+- Dynamic `import()` for code splitting: routes, large conditional deps, feature flags. One concern per module.
+  Side-effect imports are rare and documented.
+
+## Objects, Arrays, Classes
+
+- Literals (`{}`, `[]`), never constructors. Method shorthand. Dot notation for static keys, brackets for dynamic.
+  `Object.hasOwn(obj, key)` over `hasOwnProperty`.
+- Functional methods (`map`/`filter`/`find`/`some`/`every`/`flatMap`/`reduce`) for transforms — always return in the
+  callback; `for...of` for side-effect loops; never `for...in` on arrays.
+- Don't mutate inputs — return new objects/arrays: add `[...arr, item]`, remove `arr.filter`, update `arr.map`.
+  Return objects (not arrays) for multiple values. `Array.from(arrayLike)`; `Array.from(iterable, mapFn)` over
+  `[...iterable].map()`.
+- `Map` when keys aren't strings or are user-provided (prototype pollution); `Set` for dedup; generators for lazy
+  sequences. Never extend built-in prototypes.
+- ES `class` only; `#private` fields; composition over inheritance (`extends` only for true is-a); no empty
+  constructors; `static` for state-free operations. Don't force classes — one method with state is a closure, one
+  method without is a function.
+
+## Docs & JSDoc
+
+- Doc comments (`/** */`) are API documentation — the "no comments" default does not apply. Every exported function,
+  class, and module-level constant gets one; `@param`/`@returns`/`@throws` for non-trivial signatures. Behavior and
+  intent, not implementation. Update the doc in the same edit that changes behavior.
+- Pure-JS (non-TS) code: type via JSDoc with `// @ts-check`; annotate exported boundaries, `@typedef` for shared
+  shapes, skip the obvious.

.claude/rules/react-testing.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.test.jsx"
+  - "**/*.test.tsx"
+  - "**/*.spec.jsx"
+  - "**/*.spec.tsx"
+---
+
+# React Testing (Testing Library)
+
+Tests resemble how users interact with the app: query by what users see (roles, labels, text), never by
+implementation details (class names, internals, test IDs).
+
+## Setup & Interactions
+
+- Always query via `screen` — never destructure from `render()`. `userEvent.setup()` before rendering.
+- `userEvent` over `fireEvent` — it simulates real behavior (focus, blur, full key event sequences).
+- Don't call `cleanup` manually — it's automatic. Don't wrap in `act` — `render()` and interactions already do; an
+  `act` warning means a real bug (state update after the test finished), fix the cause.
+
+## Queries
+
+- Priority: `getByRole` > `getByLabelText` > `getByText` > `getByTestId` (last resort). If you can't query by role,
+  the element is probably inaccessible to screen readers — fix the markup, not the test.
+- Variants: `getBy` for elements that must be present, `queryBy` only for asserting absence, `findBy` for async
+  appearance.
+- Don't add `role` attributes to native elements (`<button>` already has `role="button"`). Inputs get `type` and a
+  `<label>` — that's what makes them queryable by role.
+
+## Async
+
+- Prefer `findBy` over `waitFor` + `getBy`.
+- `waitFor`: one assertion per callback (faster failure diagnosis); no side effects inside (the callback retries);
+  never an empty callback.
+
+## Assertions
+
+- Use `@testing-library/jest-dom` matchers: `toBeInTheDocument()`, `toBeVisible()`, `toBeDisabled()`,
+  `toHaveTextContent()`, `toHaveAttribute()`, `toHaveValue()` — not raw attribute/DOM poking.
+- Forms with `useFormStatus`: the component under test must render inside a `<form>` with an `action`.

.claude/rules/react.md

@@ -0,0 +1,105 @@
+---
+paths:
+  - "**/*.jsx"
+  - "**/*.tsx"
+---
+
+# React Conventions
+
+Components are pure functions. State is minimal. Effects are escape hatches — before reaching for `useEffect`, verify
+you actually need it. Rules target React 19. Testing conventions in [react-testing.md](react-testing.md) (loads for
+`*.test.tsx`/`*.spec.tsx`).
+
+## Component Design
+
+- Break UI into a hierarchy where each component does one thing; build static (props-only) first; then find minimal
+  state — if it's passed from a parent, never changes, or can be computed, it is not state; put state in the closest
+  common parent of everything that renders from it; children update it through callbacks.
+- Purity: same props + state = same JSX. Never mutate props, state, or anything declared before the render. Local
+  mutation within a render is fine; event handlers don't need to be pure.
+- One component per file; co-located small helpers acceptable until reused. Function declarations for components.
+  Never `React.FC` — implicit `children`, breaks generics; use `function Button(props: ButtonProps)`.
+- Every component with props gets a dedicated named type (`ButtonProps`) — never inline prop types in the signature.
+  Type events explicitly when needed (`React.ChangeEvent<HTMLInputElement>`).
+
+## Component Body Organization
+
+Logic in the body, declarative JSX in the return.
+
+- Group all event handlers in a single `handle` object (`handle.submit()`, `onChange={handle.inputChange}`). Never
+  inline handler logic in JSX.
+- Compute derived JSX and element arrays in the body; `.map()` inside the return statement is discouraged —
+  build the array first, reference it in JSX.
+- Inline conditionals (`{isVisible && <X />}`) only when simple; multi-branch or complex conditions are computed in
+  the body.
+
+## JSX
+
+- Self-closing tags without children; boolean attributes bare (`disabled`, not `disabled={true}`); fragments over
+  wrapper divs.
+- `count && <List />` renders `0` — use `count > 0 &&` or a ternary.
+- `key` on every list item: stable unique IDs, never array index when items can reorder. `key` also resets component
+  state when the entity changes (`<Profile key={userId} />`) — cleaner than an Effect.
+- Spread props sparingly — explicit props over `{...props}`. No side effects during render.
+
+## Composition
+
+- Props down, events up. Composition over configuration — pass JSX as `children`/render props instead of stacking
+  boolean flags. A stateful wrapper's unchanged `children` skip re-rendering.
+- Compound components (shared context between sub-components) for tabs, menus, accordions. Controlled when a parent
+  coordinates siblings; uncontrolled for isolated UI.
+- Refs: `ref` is a regular prop — never `forwardRef` (deprecated). Ref callbacks may return a cleanup; use block
+  bodies, not implicit returns.
+
+## Hooks
+
+- Top level only — never in conditions, loops, or nested functions. Exception: `use()` may be called conditionally —
+  prefer `use(Ctx)` over `useContext(Ctx)`.
+- Exhaustive deps always — the linter is right; if a dependency causes unwanted re-runs, restructure, don't suppress.
+- One Effect per concern; separate Effects for separate external systems.
+- Custom hooks share stateful logic, not state — each call is independent. `use` prefix only for functions that call
+  hooks. Name by use case (`useOnlineStatus`), not lifecycle (`useMount`). Don't wrap a lone `useState` in a hook.
+  Return: single value directly; value+setter as `[value, setValue] as const`; several related values as an object.
+- External stores: `useSyncExternalStore` over manual Effect + state.
+
+## Effects Are Escape Hatches
+
+Effects synchronize with external systems only — browser events, WebSockets, third-party widgets, non-React DOM,
+prop/state-dependent fetching (with cleanup).
+
+You do NOT need an Effect to: transform data for rendering (compute in render), handle user events (event handler),
+reset or adjust state on prop change (`key` or compute), notify the parent (call the callback in the handler), share
+logic between handlers (extract a function), or chain state updates (compute everything in one handler).
+
+Every subscribing Effect returns a cleanup. Fetching in an Effect uses an `ignore` flag against races — but prefer
+react-query (already used in this repo's frontends) over raw fetch Effects.
+
+## State Management
+
+- Placement chain: local `useState` → lift to common parent → composition (restructure to pass `children`) → Context
+  → external library. Context is not the first fix for prop drilling.
+- Server cache (API data) is not UI state: react-query/SWR — never hand-rolled `useState` + `useEffect` caching. UI
+  state (modal open, form input, selected tab) stays in `useState`/`useReducer`/Context.
+- `useState`: don't store what you can compute; colocate; updater function when next depends on previous
+  (`setCount(c => c + 1)`); lazy init for expensive values (`useState(() => build())`).
+- `useReducer` when many handlers touch the same state or transitions are non-trivial. Reducers are pure; actions
+  describe what happened (`'added_task'`, not `'set_tasks'`), one action per user interaction; `default` case throws;
+  `as const` on action types.
+- Context: consumption always wrapped in a custom hook that throws outside the provider. Keep providers close to
+  usage; split logically (data vs dispatch contexts so dispatch-only consumers don't re-render). `<Context value>`
+  directly, not `<Context.Provider value>`.
+- Actions: `useActionState` for form submissions/mutations (pending, errors, queuing built in); return
+  error states instead of throwing; `useOptimistic` for instant feedback; `useFormStatus` only from a component
+  rendered inside the `<form>`.
+
+## Performance
+
+- Decision tree: no perceptible lag → don't optimize. Slow render → profile and fix the computation. Unnecessary
+  re-renders → restructure first (push state down, lift content up). Only then memoize. Fix the slow render before
+  the re-render.
+- `memo` when a component re-renders often with identical props and that's expensive; `useMemo` for genuinely
+  expensive computation or reference stability into memoized children; `useCallback` for callbacks into memoized
+  children, custom hook returns, and Effect deps. If a project enables React Compiler, stop memoizing manually but
+  leave existing memoization in place.
+- Import from concrete files, not barrels. `lazy(() => import('./Chart'))` + `<Suspense>` for heavy components.
+  Independent fetches through `Promise.all`, never sequential awaits.

.claude/rules/typescript.md

@@ -0,0 +1,86 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.mts"
+  - "**/*.cts"
+---
+
+# TypeScript Conventions
+
+Extends [javascript.md](javascript.md). Types encode intent — let the compiler prove the rest. If you need `as` or
+`any`, the types are wrong; fix the types, don't fight the checker.
+
+## Type Safety
+
+- `strict: true` always; also `noUncheckedIndexedAccess` and `noImplicitOverride`.
+- `unknown` over `any`: external values (API responses, `JSON.parse`, user input) and pass-through parameters are
+  `unknown`, narrowed with guards. `any` only for incremental JS migration or test mocks that deliberately bypass
+  checking — with a comment saying why.
+- No non-null assertions (`!`) without a comment explaining why the value cannot be null — prefer narrowing.
+- No `as` on object literals — annotate (`: Foo`); assertions hide missing/extra property errors. `as` is justified
+  only when you genuinely know more than the compiler (DOM APIs returning wide types, trusted external data). Always
+  `as` syntax, never angle brackets. Double assertion goes through `unknown`, never `any`.
+- Never `@ts-ignore` or `@ts-nocheck`. `@ts-expect-error` in tests only, with a comment.
+- `{}` means "any non-nullish value" — almost never what you want. Opaque value: `unknown`; dict-like:
+  `Record<string, unknown>`; any non-primitive: `object`.
+
+## Annotations & Shapes
+
+- Omit trivially inferred types (`const x = 5`). Annotate exported function signatures (params and return) and
+  complex return types where inference goes opaque or wide. Annotate at declaration so errors surface where the bug
+  is, not at distant call sites.
+- `import type` / `export type` for type-only imports and re-exports (`verbatimModuleSyntax`).
+- `interface` for object shapes; `type` for everything else (unions, intersections, tuples, functions,
+  mapped/conditional). Stay consistent within a project.
+- No empty interfaces, no `namespace`, no wrapper types (`String`, `Number`). Data shapes are interfaces, not
+  classes.
+- Nullability: optional `?` over `| undefined`; keep `| null` at the use site (`getUser(): User | null`), not baked
+  into type aliases. `!= null` checks both null and undefined.
+
+## Generics
+
+- Constrain with `extends`, and keep constraints tight. `T` is fine for one parameter; `TKey`/`TValue`/`TItem` for
+  several. Every type parameter must appear in the signature — no unused ones, no return-type-only generics (they
+  can't be inferred).
+- Let inference work: don't pass type arguments the compiler can infer. `NoInfer<T>` when a parameter should be
+  constrained by others rather than drive inference. Defaults: `interface Container<T, U = T[]>`.
+- Built-in utility types over hand-rolled equivalents: `Partial`, `Pick`, `Omit`, `Record`, `Exclude`, `Extract`,
+  `ReturnType`, `Parameters`, `Awaited`. An explicit interface when the type is a distinct domain concept.
+- Complexity budget: unions/interfaces always; utility types for well-known transformations; conditional/mapped/
+  template-literal types for library code only; recursive `infer` chains last resort. If you can't explain a type in
+  one sentence, split or simplify it.
+
+## Narrowing
+
+- Discriminated unions (`kind`/`type` literal field) for variants. Exhaustive switch with
+  `default: { const _exhaustive: never = value; ... }` to catch new variants at compile time.
+- Type predicates (`pet is Fish`) for reusable guards; assertion functions (`asserts value is Error`) for boundary
+  validation. `typeof`/`instanceof`/`in` narrow natively.
+- Pitfalls: `typeof null === "object"` — check null first; truthiness narrowing fails on `""`, `0`, `NaN`, `false` —
+  explicit null checks when those are valid values.
+
+## Enums
+
+- Union of string literals over enum (`type Status = "active" | "inactive"`). If an enum is warranted (runtime
+  object, iteration, namespace for constants), use a string enum; never numeric with implicit values, never mixed
+  members, never coerced to boolean (`level !== Level.NONE`, not `!!level`).
+
+## Functions & Classes
+
+- Union types or optional parameters over overloads; when overloads are unavoidable, specific signatures before
+  general.
+- Callbacks: `void` return when the result is ignored; no optional parameters in callback types — callers may ignore
+  extra args.
+- Classes: omit `public` (default); `readonly` on never-reassigned properties; constructor parameter properties
+  (`constructor(private readonly db: Database)`); initialize fields at declaration; `override` keyword on overrides.
+- Branded types for nominal safety where structural typing is too permissive (domain IDs, validated strings):
+  `type UserId = string & { readonly __brand: unique symbol }` — keep the mechanism consistent project-wide.
+- Array syntax: `T[]` for simple element types, `Array<T>` for complex ones (`Array<string | number>`).
+- Doc comments describe behavior and semantics, not types already visible in the signature.
+
+## tsconfig
+
+- `module: "NodeNext"` when transpiling with tsc; `module: "preserve"` with bundlers (Vite, esbuild);
+  `verbatimModuleSyntax: true` in both. Target `ESNext`; `lib` includes `dom` for browser projects.
+- Keep configs minimal: `extends` for sharing; separate `tsconfig.build.json` excluding tests/scripts.