{"id":"d3896099-5422-4329-8f0e-dc39a48a0403","entityType":"agent","slug":"clawhub-iliaal-compound-eng-react-frontend","name":"ia-react-frontend","canonicalUrl":"https://www.xpersona.co/agent/clawhub-iliaal-compound-eng-react-frontend","canonicalPath":"/agent/clawhub-iliaal-compound-eng-react-frontend","generatedAt":"2026-10-09T15:16:07.370Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T12:23:05.550Z","emptyReason":null},"description":"React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when working with React component structure, state management, Next.js routing, Vitest, React Testing Library, reviewing React code, or synchronizing JSON locales and reviewing translations in a React or frontend interface. For visual design and aesthetic direction, use frontend-design instead. Skill: ia-react-frontend Owner: iliaal Summary: React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when working with React component structure, state management, Next.js routing, Vitest, React Testing Library, reviewing React code, or synchronizing JSON locales and reviewing translations in a React or frontend interface. For visual design and aesthetic direction, use frontend-design instead. Ta","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.7K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17bcar8wq0xhegs0ny6f57ypd8484bw:compound-eng-react-frontend","sourceUrl":"https://clawhub.ai/iliaal/compound-eng-react-frontend","homepage":"https://clawhub.ai/iliaal/skills/compound-eng-react-frontend","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/iliaal/compound-eng-react-frontend","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/iliaal/skills/compound-eng-react-frontend","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":46,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when working with React component structure, state management, Next.js routing, Vitest"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:23:05.550Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:23:05.550Z","emptyReason":null},"stars":null,"forks":null,"downloads":2661,"packageName":null,"latestVersion":"5.0.1","tractionLabel":"2.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T12:23:05.549Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T12:23:05.550Z","lastCrawledAt":"2026-10-09T12:23:05.549Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T12:23:05.549Z","lastVerifiedAt":null,"highlights":[{"version":"5.0.1","createdAt":"2026-10-03T17:07:02.338Z","changelog":"v5.0.1","fileCount":16,"zipByteSize":34912},{"version":"5.0.0","createdAt":"2026-09-26T23:19:48.089Z","changelog":"v5.0.0","fileCount":15,"zipByteSize":32128},{"version":"4.5.2","createdAt":"2026-09-08T01:49:01.814Z","changelog":"v4.5.2","fileCount":9,"zipByteSize":20452},{"version":"4.5.0","createdAt":"2026-08-29T22:22:10.718Z","changelog":"v4.5.0","fileCount":6,"zipByteSize":16946},{"version":"4.4.3","createdAt":"2026-08-29T12:33:05.422Z","changelog":"v4.4.3","fileCount":6,"zipByteSize":13462},{"version":"4.4.1","createdAt":"2026-08-10T19:39:29.452Z","changelog":"v4.4.1","fileCount":6,"zipByteSize":13443},{"version":"4.2.1","createdAt":"2026-07-11T11:15:24.505Z","changelog":"v4.2.1","fileCount":6,"zipByteSize":12746},{"version":"4.2.0","createdAt":"2026-07-07T18:39:13.514Z","changelog":"v4.2.0","fileCount":6,"zipByteSize":12634}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17bcar8wq0xhegs0ny6f57ypd8484bw:compound-eng-react-frontend","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T15:16:07.365Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-iliaal-compound-eng-react-frontend/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T12:23:05.550Z","emptyReason":null},"readme":"Skill: ia-react-frontend\n\nOwner: iliaal\n\nSummary: React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when working with React component structure, state management, Next.js routing, Vitest, React Testing Library, reviewing React code, or synchronizing JSON locales and reviewing translations in a React or frontend interface. For visual design and aesthetic direction, use frontend-design instead.\n\nTags: latest:5.0.1\n\nVersion history:\n\nv5.0.1 | 2026-10-03T17:07:02.338Z | user\n\nv5.0.1\n\nv5.0.0 | 2026-09-26T23:19:48.089Z | user\n\nv5.0.0\n\nv4.5.2 | 2026-09-08T01:49:01.814Z | user\n\nv4.5.2\n\nv4.5.0 | 2026-08-29T22:22:10.718Z | user\n\nv4.5.0\n\nv4.4.3 | 2026-08-29T12:33:05.422Z | user\n\nv4.4.3\n\nv4.4.1 | 2026-08-10T19:39:29.452Z | user\n\nv4.4.1\n\nv4.2.1 | 2026-07-11T11:15:24.505Z | user\n\nv4.2.1\n\nv4.2.0 | 2026-07-07T18:39:13.514Z | user\n\nv4.2.0\n\nv4.1.0 | 2026-06-01T16:01:17.068Z | user\n\nv4.1.0\n\nv3.0.5 | 2026-04-30T00:03:32.781Z | user\n\nv3.0.5\n\nv3.0.4 | 2026-04-27T14:39:28.668Z | user\n\nv3.0.4\n\nv3.0.3 | 2026-04-24T12:35:02.978Z | user\n\nv3.0.3\n\nv3.0.2 | 2026-04-24T11:50:25.488Z | user\n\nv3.0.2\n\nv3.0.1 | 2026-04-24T11:31:07.875Z | user\n\nv3.0.1\n\nv3.0.0 | 2026-04-23T19:28:24.001Z | user\n\nv3.0.0\n\nv2.56.1 | 2026-04-18T13:30:22.887Z | user\n\nv2.56.1\n\nv2.56.0 | 2026-04-14T12:40:30.585Z | user\n\nv2.56.0\n\nv2.55.1 | 2026-04-12T14:30:44.420Z | user\n\nv2.55.1\n\nv2.55.0 | 2026-04-11T01:01:25.140Z | user\n\nv2.55.0\n\nv2.53.2 | 2026-04-08T14:21:14.907Z | user\n\nv2.53.2\n\nv2.53.0 | 2026-04-06T02:57:43.378Z | user\n\nv2.53.0\n\nArchive index:\n\nArchive v5.0.1: 16 files, 34912 bytes\n\nFiles: references/components-and-state.md (9513b), references/e2e-testing.md (6946b), references/locale-synchronization.md (2013b), references/rendering-and-frameworks.md (6401b), references/tailwind-class-composition.md (3559b), references/tailwind-component-patterns.md (3851b), references/tailwind-configuration.md (6164b), references/tailwind-layout-patterns.md (3770b), references/tailwind-v3-to-v4.md (1732b), references/tailwind.md (3955b), references/test-selection.md (1547b), references/testing.md (8245b), skill-card.md (2109b), SKILL.md (4740b), SPEC.md (4506b), _meta.json (146b)\n\nFile v5.0.1:SKILL.md\n\n---\nname: ia-react-frontend\nclass: language\ndescription: >-\n React architecture patterns, TypeScript, Next.js, hooks, and testing. Use when\n working with React component structure, state management, Next.js routing,\n Vitest, React Testing Library, reviewing React code, or synchronizing JSON\n locales and reviewing translations in a React or frontend interface. For\n visual design and aesthetic direction, use frontend-design instead.\npaths: \"**/*.tsx,**/*.jsx,**/*.ts,**/*.css,**/tailwind.config.*,**/*.html,**/*.vue,**/*.blade.php\"\n---\n\n# React Frontend\n\n**Verify before implementing**: For App Router patterns, React 19 APIs, or version-specific behavior, look up current docs (Context7 `query-docs` if available, else the framework's official docs via web search) before writing code. Training data may lag current releases.\n\n## Working rules\n\n- Keep derived state in render and user actions in event handlers; use effects for external synchronization.\n- Give async work a lifecycle and cancellation policy; represent failure separately from pending and empty data.\n- Preserve focus when hiding interactive regions and exercise keyboard navigation in a real browser.\n- Validate and authorize every public server action; send only needed fields across server/client boundaries.\n- Measure performance changes and test user-visible behavior, not type-checking alone.\n\n## Effects Decision Tree\n\nEffects are escape hatches; most logic should NOT use effects.\n\n| Need | Solution |\n|------|----------|\n| Derived value from props/state | Calculate during render (useMemo if expensive) |\n| Reset state on prop change | `key` prop on component |\n| Respond to user event | Event handler |\n| Notify parent of state change | Call onChange in event handler, or fully controlled component |\n| Chain of state updates | Calculate all next state in one event handler |\n| Sync with external system | Effect with cleanup |\n\n**Effect rules:**\n- Never suppress the linter; fix the code instead\n- Use updater functions (`setItems(prev => [...prev, item])`) to remove state dependencies\n- Move objects/functions inside effects to stabilize dependencies\n- `useEffectEvent` for non-reactive values (e.g., theme in a connection effect)\n- Always return cleanup for subscriptions, connections, listeners\n- Data fetching cancellation (pick by situation): `AbortController` for fetch; `ignore` flag for non-cancellable promises. With React Query, pass the query function's signal to the transport, such as `queryFn: ({ signal }) => fetch(url, { signal })`. Without consuming that signal, an unused query can finish and populate the cache; do not describe that behavior as transport cancellation.\n\n\n## Discipline\n\n- Simplicity first: every change as simple as possible, impact minimal code\n- Only touch what's necessary; avoid introducing unrelated changes\n- No hacky workarounds: if a fix feels wrong, step back and implement the clean solution\n- Before adding a new abstraction, verify it appears in 3+ places\n\n\n## References\n\n- [testing.md](./references/testing.md): Component, hook, and mocking test examples\n- [e2e-testing.md](./references/e2e-testing.md): Playwright E2E patterns\n\n\n## Verify\n\n- TypeScript compiles with zero errors\n- No suppressed lint rules (`eslint-disable`, `@ts-ignore`) in new code\n- `useEffect` dependency arrays not manually overridden\n- No `forwardRef` usage in React 19+ projects (use `ref` prop directly)\n\n## Task-specific references\n\nRead the relevant reference before implementing or reviewing the matching behavior:\n\n- For component types, state ownership, async races, focus, or cached query behavior: [components-and-state.md](./references/components-and-state.md).\n- For performance, React APIs, Next.js boundaries, or caching: [rendering-and-frameworks.md](./references/rendering-and-frameworks.md).\n- For Tailwind CSS: utilities, `@theme` tokens, CVA/tailwind-variants, dark mode, v3-to-v4 migration, or overflow and `hidden` pitfalls: [tailwind.md](./references/tailwind.md).\n- For component, hook, browser, or integration test changes: [test-selection.md](./references/test-selection.md).\n- For synchronizing JSON locale files or reviewing translations: [locale-synchronization.md](./references/locale-synchronization.md).\n\nExisting specialized references, when the corresponding topic applies:\n\n- Tailwind details behind [tailwind.md](./references/tailwind.md): [tailwind-configuration.md](./references/tailwind-configuration.md), [tailwind-v3-to-v4.md](./references/tailwind-v3-to-v4.md), [tailwind-class-composition.md](./references/tailwind-class-composition.md), [tailwind-component-patterns.md](./references/tailwind-component-patterns.md), [tailwind-layout-patterns.md](./references/tailwind-layout-patterns.md).\n\nFile v5.0.1:_meta.json\n\n{\n \"ownerId\": \"kn715jrbbh71q9zncr0bqdkr8n848q1a\",\n \"slug\": \"compound-eng-react-frontend\",\n \"version\": \"5.0.1\",\n \"publishedAt\": 1791047222338\n}\n\nFile v5.0.1:references/components-and-state.md\n\n# Components, state, and interaction\n\n## Component TypeScript\n\n- Extend native elements with `ComponentPropsWithoutRef<'button'>`, add custom props via intersection\n- Use `React.ReactNode` for children, `React.ReactElement` for single element, render prop `(data: T) => ReactNode`\n- Discriminated unions for variant props; TypeScript narrows automatically in branches\n- Generic components: `` with `keyof T` for column keys, `T extends { id: string }` for constraints\n- Event types: `React.MouseEvent`, `FormEvent`, `ChangeEvent`\n- `as const` for custom hook tuple returns\n- `useRef(null)` for DOM (use `?.`), `useRef(0)` for mutable values\n- Explicit `useState(null)` for unions/null\n- Pass optional handlers through unwrapped: `onX={(a) => handler?.(a)}` is always truthy, so a child that renders a control only when `onX` is provided always renders it, and the click silently does nothing. Pass `handler` (or `undefined`) and gate the control on the real handler's presence.\n- useReducer actions as discriminated unions: `{ type: 'set'; payload: number } | { type: 'reset' }`\n- useContext null guard: throw in custom `useX()` hook if context is null\n- **A parameter type whose properties are all optional is a weak type, and a mismatched argument fails to compile rather than passing `undefined`.** TypeScript requires the argument to share at least one property with a weak type, so `(record: { newField?: boolean })` rejects a generated type that does not yet carry `newField` with `TS2559: Type 'X' has no properties in common with type 'Y'`. Intersect with the base type instead (`T & { newField?: boolean }`); the shim then deletes cleanly once the field lands upstream\n\n\n## Concurrency & Race Classes\n\nFive race classes survive type-checking and unit tests; hunt each one during review (cleanup/cancellation mechanics: Effect rules above):\n\n| Class | Production signal | Fix |\n|-------|-------------------|-----|\n| Lifecycle cleanup gap | \"state update on unmounted component\" warnings, leaks under rapid navigation | Return cleanup from every effect that registers a listener/timer/observer |\n| Remount-timing mistake | Async callback mutates state/DOM after route change/unmount (`fetch().then(setData)` resolves post-navigation) | Cancel per the cancellation hierarchy |\n| Boolean-as-state for non-binary UI | Contradictory combos (`isLoading: true, error: Error`) | State constant (`'idle' \\| 'loading' \\| 'success' \\| 'error'`) + transition function; invalid states unreachable |\n| Stale promise/timer, no cancel path | Promise chain or `setTimeout` holds `setState` after the component moved on | Bind every async op to a cancel mechanism; test the cleanup path |\n| Per-element handlers on large lists | N closures/subscriptions per row, stale-closure bugs on rapid re-renders | Delegate: one parent handler + `event.target.closest(...)` when >~50 items or frequent updates |\n| Gate keyed on a child's success-only callback | Parent's submit stays locked behind \"still loading, try again in a moment\" copy that never resolves; only a page reload escapes | Report failures up (`onLoadError`) as well as successes, and split the flag into loading / loaded / failed; a boolean cannot carry a terminal state. Keep the action blocked in both if proceeding on unknown data is unsafe; the fix is honest copy plus a real in-place retry, not unblocking |\n| `inert` toggled from a blur-managed flag | First `Tab` *inside* the subtree sends focus to ``; the next `Tab` restarts at the top of the document and skips the (now inert) subtree entirely | React maps `onBlur` to native `focusout`, which fires on intra-subtree moves, and `focusin`/`focusout` are `DiscreteEventPriority`, so React commits `inert` synchronously *between* the two events, landing it on the already-focused incoming control. Stand down only when focus truly leaves: `if (e.currentTarget.contains(e.relatedTarget)) return;` |\n\n**Focus-ownership rules:**\n- Never toggle `inert` on a subtree that currently holds focus. The blunt version has no guard at all: a scroll-driven `inert={!isVisible}` on a sticky bar, drawer, or collapsing panel strands the user on a control that is invisible, inert, and unactivatable. Hand focus to the equivalent visible control before hiding, and pass `focus({ preventScroll: true })` when the handoff fires from a scroll handler, or `focus()` scrolls its target into view and fights the scroll the user is performing. If the handoff target carries the same focus listeners that feed the guard, `focus()` arms the flag as a side effect of doing its job and the subtree never goes inert again; make the handoff symmetric (two effects guarding opposite values of one flag) rather than adding an exception to the guard. `aria-hidden` without `inert` fixes double announcement but leaves the duplicate tab stops. Assert on what the user can *do* (does the handler fire, where does `Tab` go), not on `document.activeElement`; Chromium resolves the unfocusing steps lazily and it reads back inconsistently\n- A blur-managed \"focus is inside\" flag cannot be cleared by a blur that never fires. Headless popover primitives restore focus to the element that *opened* the content on close; when the popover is anchored to an input with no trigger element, that restore no-ops, the library preventDefaults the focus-scope restore, and focus lands on `document.body`. The input never receives another `blur`, so the flag sticks `true` for the component's lifetime and anything gated on it (a \"re-seed local text from `props.value`\" effect, for instance) is silently dead. Clear it explicitly in the select handler and on close when `document.activeElement` is not the input. The same design usually adds `onOpenAutoFocus={e => e.preventDefault()}` to avoid stealing typing focus, which leaves the content pointer-only: no trigger to Tab to and no auto-focus in. Add an explicit affordance plus `aria-haspopup`/`aria-expanded`. Browser-dependent: Chromium and Firefox blur the input on `mousedown`, Safari does not, so \"works on my machine\" from Safari proves nothing\n\n\n## State Management\n\n```\nLocal UI state → useState, useReducer\nShared client state → Zustand (simple) | Redux Toolkit (complex)\nAtomic/granular → Jotai\nServer/remote data → React Query (TanStack Query)\nURL state → nuqs, router search params\nForm state → React Hook Form\n```\n\n**Key patterns:**\n- Zustand: `create()(devtools(persist((set) => ({...}))))`; use slices for scale, selective subscriptions to prevent re-renders\n- React Query: query keys factory (`['users', 'detail', id] as const`), `staleTime`/`gcTime`, optimistic updates with `onMutate`/`onError` rollback\n- React Query `isError` means *a fetch failed*, not *there is no data*: a failed refetch sets `status: 'error'` while retaining the last successful payload, so the usual `isLoading ? spinner : isError ? errorPanel : content` ladder routes a working, fully cached list into the error panel. The defaults compose into it: `refetchOnMount: true` + `staleTime: 0` refetch on every mount, `retry: false` makes one blip terminal, and `gcTime: 5min` keeps the cache alive across a modal's unmount/remount. Gate the branch on data-absence: `isLoadingError` (`isError && !hasData`), or `isError && derived.length === 0` when the suite mocks the hook and leaves `isLoadingError` undefined. Audit the side effects with it: `useEffect(() => { if (isError) toast(...) }, [isError])` fires over the live list too\n- The mirror case has the same tell: under `retry: false` a first load that fails leaves `data` `undefined` forever, so a branch gated on `data !== undefined` folds *failed* into *pending* and renders \"Loading…\" permanently. Whether it is recoverable is decided by mount topology, not by open/closed state: a component rendered unconditionally inside a ref-driven popup is mounted for the life of the page, so `refetchOnMount` never fires again. Any remedy that adds a branch on `isError` must itself be gated on data-absence, or it re-introduces the previous bullet. Enumerate all four states before writing either gate (`isLoading` for first load with no data yet, `isFetching` for any fetch in flight including a background refetch over a warm cache, `isError` for last fetch failed with cache possibly still present, and loaded-and-genuinely-empty) and state the action in each: `!isFetching` misses the error state, `!isFetching && !isError` mishandles a background refetch of a legitimately empty result. The write path has the same shape, inverted: a fail-closed save gate keyed on `isError` blocks a valid submit whenever cached data is present\n- A mutate-scoped `onSuccess` requires a mounted observer when success dispatches. A synchronous hook-level callback can finish before deferred query notifications unmount the row, but that ordering is not a general lifetime guarantee. If hook-level `onSuccess` removes the row and then awaits a refresh, the row can unmount before success dispatches and the mutate-scoped toast can be dropped. Put side effects that must survive unmount in the mutation's hook-level callbacks. Read the installed scheduler and awaited callback chain, and run a known-bad control that removes the observer before dispatch before accepting or dismissing a lifetime finding.\n- Never duplicate server data (React Query) in a client store (Zustand)\n- Colocate state close to where it's used\n\nFile v5.0.1:references/e2e-testing.md\n\n# E2E Testing with Playwright\n\n> When to read: when authoring Playwright end-to-end tests: directory layout, fixtures, page objects, network mocking, CI integration.\n\n## Directory Structure\n\n```\nproject-root/\n├── playwright.config.ts\n└── e2e/\n ├── fixtures/\n │ ├── auth.fixture.ts\n │ └── test-data.fixture.ts\n ├── pages/\n │ ├── base.page.ts\n │ └── .page.ts\n ├── tests/\n │ ├── auth/\n │ │ └── login.spec.ts\n │ └── smoke/\n │ └── critical-paths.spec.ts\n └── utils/\n └── api-helpers.ts\n```\n\nNaming: tests `.spec.ts`, page objects `.page.ts`, fixtures `.fixture.ts`.\n\n## Configuration\n\nKeep this config at the project root and run the CLI from that root. Playwright resolves `testDir` relative to the config file. For a nested config, adjust its relative directories and pass `--config ` explicitly.\n\n```typescript\nimport { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n testDir: './e2e/tests',\n fullyParallel: true,\n forbidOnly: !!process.env.CI,\n retries: process.env.CI ? 2 : 0,\n workers: process.env.CI ? 1 : undefined,\n reporter: 'html',\n expect: {\n toHaveScreenshot: { animations: 'disabled' },\n },\n use: {\n baseURL: 'http://localhost:5173',\n trace: 'on-first-retry',\n screenshot: 'only-on-failure',\n },\n projects: [\n { name: 'setup', testDir: './e2e/fixtures', testMatch: 'auth.fixture.ts' },\n {\n name: 'chromium',\n use: { ...devices['Desktop Chrome'], storageState: 'e2e/.auth/user.json' },\n dependencies: ['setup'],\n },\n ],\n webServer: {\n command: 'npm run dev',\n url: 'http://localhost:5173',\n reuseExistingServer: !process.env.CI,\n },\n});\n```\n\n## Page Object Model\n\nTests never use selectors directly; page objects encapsulate all locators and actions.\n\n```typescript\n// e2e/pages/base.page.ts\nimport { type Page, type Locator } from '@playwright/test';\n\nexport abstract class BasePage {\n constructor(protected readonly page: Page) {}\n abstract goto(): Promise;\n abstract readonly ready: Locator;\n async waitForLoad() { await this.ready.waitFor(); }\n get toast(): Locator { return this.page.getByRole('alert'); }\n}\n\n// e2e/pages/users.page.ts\nexport class UsersPage extends BasePage {\n readonly ready: Locator;\n readonly createButton: Locator;\n readonly searchInput: Locator;\n\n constructor(page: Page) {\n super(page);\n this.ready = page.getByRole('heading', { name: /users/i });\n this.createButton = page.getByRole('button', { name: /create/i });\n this.searchInput = page.getByRole('searchbox', { name: /search/i });\n }\n\n async goto() {\n await this.page.goto('/users');\n await this.waitForLoad();\n }\n\n async searchFor(query: string) {\n const resp = this.page.waitForResponse('**/api/users?*');\n await this.searchInput.fill(query);\n await resp;\n }\n}\n```\n\nRules: locators as public readonly properties, actions as async methods with internal waits, no assertions in page objects, one PO per page.\n\n## Selector Priority\n\n| Priority | Method | Use when |\n|----------|--------|----------|\n| 1 | `getByRole` | Buttons, links, headings, inputs |\n| 2 | `getByLabel` | Form inputs with labels |\n| 3 | `getByPlaceholder` | Search inputs |\n| 4 | `getByText` | Static text content |\n| 5 | `getByTestId` | No accessible selector available |\n\nNever use CSS selectors, XPath, or DOM structure selectors. When adding `data-testid`, use `--` pattern: `create-user-btn`.\n\n## Filling Inputs\n\nPrefer `locator.fill(value)` to `page.keyboard.type()`. Synthesised keystrokes drop characters intermittently under a browser-attached session (CDP against an already-running browser), and the driver reports the full string as typed while the DOM holds a short value, so the assertion that would catch it is the one nobody writes. Rich-text editors whose state lives outside the element's `value` (ProseMirror, Slate, TipTap) ignore programmatic writes and still need `type()`; there, assert `input_value()` (or the editor's own serialized content) after typing and retry on a short read.\n\n## Wait Strategies\n\nNever use `waitForTimeout` or `setTimeout`. Do not use `waitForLoadState('networkidle')` as a readiness signal; Playwright's API docs mark it discouraged for testing and point to web assertions instead. Start a `waitForResponse` before the action that triggers the request, or a fast response is missed. Use explicit conditions:\n\n```typescript\nawait page.getByRole('heading', { name: 'Dashboard' }).waitFor();\nawait page.waitForURL('/dashboard');\nconst resp = page.waitForResponse(\n (r) => r.url().includes('/api/users') && r.status() === 200,\n);\nawait page.getByRole('button', { name: /load/i }).click();\nawait resp;\nawait page.getByTestId('spinner').waitFor({ state: 'hidden' });\n```\n\n## Auth State Reuse\n\nSave auth state once, reuse across all tests:\n\n```typescript\n// e2e/fixtures/auth.fixture.ts\nimport { test as setup } from '@playwright/test';\n\nsetup('authenticate', async ({ page }) => {\n await page.goto('/login');\n await page.getByLabel('Email').fill('testuser@example.com');\n await page.getByLabel('Password').fill('TestPassword123!');\n await page.getByRole('button', { name: /sign in/i }).click();\n await page.waitForURL('/dashboard');\n await page.context().storageState({ path: 'e2e/.auth/user.json' });\n});\n```\n\nTests receive auth state via `storageState` in config projects.\n\n## Test Data & Network\n\n- Tests create own data via API helpers (faster than UI), clean up in `finally` blocks\n- Mock responses with `page.route('**/api/path', route => route.fulfill({ ... }))`\n- Simulate errors with `route.abort('failed')`\n\n## Flaky Test Fixes\n\n| Cause | Fix |\n|-------|-----|\n| Hardcoded waits | Explicit wait conditions |\n| Shared test data | Each test creates its own |\n| Animations | Wait for the actual interaction result; for screenshot assertions, use `expect.toHaveScreenshot.animations: 'disabled'` as configured above |\n| Race conditions | Wait for API responses before assertions |\n\nThe screenshot animation option affects screenshot assertions. It does not disable application animations during interaction tests.\n\n**Quarantine workflow**: confirm flakiness before quarantining:\n```bash\nnpx playwright test --repeat-each=10 path/to/test.spec.ts # Confirm flakiness\nnpx playwright test --retries=3 path/to/test.spec.ts # Check if retries help\n```\n\nMark confirmed flaky tests with an issue reference:\n```typescript\ntest.fixme(true, 'Flaky - Issue #123'); // Always skip\ntest.skip(!!process.env.CI, 'Flaky in CI only - Issue #123'); // Skip in CI only\n```\n\n```bash\nnpx playwright test --headed --debug # Debug mode\nnpx playwright show-trace trace.zip # Trace viewer\nnpx playwright test --ui # Interactive UI\n```\n\nFile v5.0.1:references/locale-synchronization.md\n\n# JSON locale synchronization\n\nSynchronize the requested messages with the application's installed message formatter and usage context. Produce a focused locale diff and report structural checks separately from language review.\n\n1. Read the locale configuration and source messages. Trace each changed key to its component or call site. Identify the message's meaning, UI role, interpolation values, and space constraints; a key name alone does not establish translation context.\n2. Compare source history to identify added, changed, and removed messages. If history is unavailable, report translation staleness as unknown. Key parity alone cannot show whether an existing translation still matches a changed source message.\n3. Update only the authorized keys and locales. Preserve unrelated translations, non-string values, and array structure. Confirm usage before removing a message; absence from one source file does not prove the application no longer uses the key.\n4. Preserve required placeholder names and formatter tokens exactly. Validate plural and select grammar with the installed formatter. Use the categories required by the target locale rather than copying the source locale's categories. Preserve interpolation bindings and the markup expected by the renderer; translated text may reorder placeholders or tags where the formatter permits it.\n5. Parse the edited JSON and run the repository's locale or message validation. Check key coverage against the configured fallback policy. Verify placeholder compatibility, plural branches, markup structure, and unchanged non-string values. Reject a structurally valid message that loses a required substitution or branch.\n6. Exercise changed messages in the UI, including representative plural values, long text, and right-to-left layout when applicable. Report linguistic accuracy or visual fit as unverified when no fluent review or browser check occurred. A parser or placeholder check establishes structural compatibility, not translation quality.\n\nFile v5.0.1:references/rendering-and-frameworks.md\n\n# Rendering and framework patterns\n\n## Performance\n\n**Critical: eliminate waterfalls:**\n- `Promise.all()` for independent async operations\n- Move `await` into branches where actually needed\n- Suspense boundaries to stream slow content\n\n**Critical: bundle size:**\n- Import directly from modules, avoid barrel files (`index.ts` re-exports)\n- `next/dynamic` or `React.lazy()` for heavy components\n- Defer third-party scripts (analytics, logging) until after hydration\n- Preload on hover/focus for perceived speed\n- `content-visibility: auto` + `contain-intrinsic-size` on long lists skips off-screen layout/paint\n\n**Re-render optimization:**\n- Never define a component inside another component. Each parent render creates a new function identity, and React compares element *types* to decide whether to update or replace: a new type means the whole subtree unmounts and remounts, so local state is lost, effects re-run, and DOM nodes are recreated. Symptoms are behavioral, not slow: an input loses focus on every keystroke, animations restart, scroll position resets. Hoist the component to module scope and pass what it needed via props. The React Compiler does not save this one; the type identity changes before memoization applies\n- Derive state during render, not in effects\n- Subscribe to derived booleans, not raw objects (`state.items.length > 0` not `state.items`)\n- Functional setState for stable callbacks: `setCount(c => c + 1)`\n- Lazy state init: `useState(() => expensiveComputation())`\n- `useTransition` for non-urgent updates (search filtering)\n- `useDeferredValue` for expensive derived UI\n- Don't subscribe to searchParams/state read only in callbacks; read on demand\n- Use ternary (`condition ? : `), not `&&` for conditionals\n- `React.memo` only for expensive subtrees with stable props\n- Hoist static JSX outside components\n\n**React Compiler** (React 19): auto-memoizes, so write idiomatic React without adding unnecessary manual memoization. Keep existing `useMemo`/`useCallback`/`memo` until identity-sensitive effects and measured performance verify that removal preserves behavior. Enable via `reactCompiler: true` in next.config (non-framework: `babel-plugin-react-compiler`). Keep components pure.\n\n\n## React 19\n\n- **ref as prop**: `forwardRef` deprecated. Accept `ref?: React.Ref` as regular prop\n- **useActionState**: replaces `useFormState`: `const [state, formAction, isPending] = useActionState(action, initialState)`\n- **use()**: unwrap Promise or Context during render (not in callbacks/effects). Enables conditional context reads\n- **useOptimistic**: `const [optimistic, addOptimistic] = useOptimistic(state, mergeFn)` for instant UI feedback\n- **useFormStatus**: `const { pending } = useFormStatus()` in child of `
`\n- **Server Components**: default in App Router. Async, access DB/secrets directly. No hooks, no event handlers\n- **Server Actions**: `'use server'` directive. Validate inputs (Zod), `revalidateTag`/`revalidatePath` after mutations. **Server Actions are public endpoints**; always verify auth/authz inside each action, not just in middleware or layout guards\n- **``** preserves state/DOM for toggled components (experimental)\n\n\n## Next.js App Router\n\n**File conventions:** `page.tsx` (route UI), `layout.tsx` (shared wrapper), `template.tsx` (re-mounted on navigation, unlike layout), `loading.tsx` (Suspense), `error.tsx` (error boundary), `not-found.tsx` (404), `default.tsx` (parallel route fallback), `route.ts` (API endpoint)\n\n**Rendering modes:** Server Components (default) | Client (`'use client'`) | Static (build) | Dynamic (request) | Streaming (progressive)\n\n**Decision:** Server Component unless it needs hooks, event handlers, or browser APIs. Split: server parent + client child. Isolate interactive components as `'use client'` leaf components; keep server components static with no global state or event handlers.\n\n**Server → client boundary:** pass only the fields a client component actually uses, not whole ORM rows or fetch objects. Every prop crossing the `'use client'` boundary is serialized into the payload, so a 50-field `user` object read for one field still ships all 50.\n\n**Client-only state that drives first paint** (theme, locale, feature flag, auth hint): reading `localStorage` during render breaks SSR, and reading it in `useEffect` paints the default first, so the correct value arrives one frame later as a visible flash. Set the value on the document with a small synchronous inline script that runs before hydration, typically writing a `class` or `data-` attribute on `` that CSS already keys on. The script is developer-authored and must never interpolate user, request, or database data; it is the one place `dangerouslySetInnerHTML` is warranted, and only for a literal string.\n\n**Routing patterns:**\n- Route groups `(name)`: organize without affecting URL\n- Parallel routes `@slot`: independent loading states in same layout\n- Intercepting routes `(.)`: modal overlays with full-page fallback\n\n**Caching:**\n- `fetch(url, { cache: 'force-cache' })`: static\n- `fetch(url, { next: { revalidate: 60 } })`: ISR\n- `fetch(url, { cache: 'no-store' })`: dynamic\n- Tag-based: `fetch(url, { next: { tags: ['products'] } })` then `revalidateTag('products')`\n\n**Data fetching:**\n- Fetch in Server Components where data is used\n- Use Suspense boundaries for slow queries\n- `React.cache()` for per-request dedup\n- `generateStaticParams` for static generation\n- `generateMetadata` for dynamic SEO\n- Static metadata with `title: { default: 'App', template: '%s | App' }` for cascading page titles\n- `after()` for non-blocking side effects (logging, analytics); runs after response is sent\n- Hoist static I/O (fonts, config) to module level; runs once, not per request\n- Never hold request-scoped or user data in module-level mutable state: server renders run concurrently in one process, so shared module state leaks across requests (one user's data surfacing in another's response). Hoist only immutable static I/O; keep request data local to the render tree (pass as props)\n\n\n## Tailwind Integration\n\nFor Tailwind v4 configuration, utility patterns, dark mode, and component variants, see [tailwind.md](./tailwind.md).\n\n**Class sorting in JSX**: keep Tailwind classes in canonical order (enforce via `eslint-plugin-better-tailwindcss`).\n\nFile v5.0.1:references/tailwind-class-composition.md\n\n# Class generation and composition\n\n## ESLint Integration\n\nUse `eslint-plugin-better-tailwindcss` for automated class validation:\n- `no-conflicting-classes`: catches `text-red-500 text-blue-500`\n- `no-unknown-classes`: flags typos\n- `enforce-canonical-classes`: normalizes shorthand\n- `no-duplicate-classes`: removes redundant entries\n- `no-deprecated-classes`: catches v3 classes removed in v4\n- `useSortedClasses`: enforces canonical class order; configure `attributes: [\"classList\"]` and `functions: [\"clsx\", \"cva\", \"cn\", \"tv\", \"tw\"]` to cover JSX utility functions\n\n\n## Class Merging\n\nUse `cn()` combining `clsx` + `tailwind-merge` for conditional/dynamic classes. Use plain strings for static `className` attributes.\n\n```typescript\nimport { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\nexport function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }\n```\n\n```typescript\n// Static: plain string\n