@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/.agents/skills/flawless-nextjs/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: flawless-nextjs
+description: Work with flawless-react's `--nextjs` mode — the app-router resolver, the derived `flawless/provider.tsx` and why a provider layer gets dropped, the signed-out auth stub and the layers it makes dangerous, module stubs and their precedence, the React 17/18/19 pins (Testing Library `^12.1.5`, `repairRtlPin`), the package.json merge with `pnpm.ignoredBuiltDependencies`, `.env` loading for the suite and the host, and where gitignore entries land. Use when a Next app's generated suite is red at import or mount, when a provider is missing from the wrap, when `Cannot read properties of null (reading 'useState')` appears, or when `pnpm run dev` dies after an install. For fixtures from a spec see flawless-api-fixtures; for route e2e see flawless-e2e.
+---
+
+# flawless Next.js mode
+
+`--nextjs [path]` is the mode that makes the output a **suite inside your app**
+rather than a folder of files: it finds the app root, resolves an entry glob, writes
+under `<root>/flawless/`, merges devDeps and `flawless:*` scripts into your
+`package.json`, and appends gitignore entries.
+
+```bash
+cd apps/web
+bunx @lariocpt/flawless-react "src/app/dashboard/page.tsx" --nextjs . --tasks unit-browser,e2e
+```
+
+The path is optional — with no value the current directory is the app root, and in
+`--nextjs` mode the entry glob itself is auto-detected from the router when you give
+none. Monorepos work because the root is resolved, not assumed: `apps/web` is the
+root, the suite lives at `apps/web/flawless/`, and the scripts land in
+`apps/web/package.json`.
+
+## The provider wrapper, and its honest drops
+
+App-router `layout.tsx` is usually an **async server component** importing
+`next/font` or `next/headers` — nothing in that file can run under jsdom. So the tool
+derives `flawless/provider.tsx` from the JSX chain that actually encloses
+`{children}`, keeping only `"use client"` components and literal attributes.
+
+**Every drop is named where you will read it**: a dropped attribute becomes a
+`TODO(flawless)` comment beside the wrapper; a dropped provider layer becomes a block
+at the top of the file with the reason and the fix. Do not read `provider.tsx` as
+"the app's providers" — read it as "the providers that could be mounted", and read
+its header.
+
+**A layer whose module directly imports an auth library is skipped rather than
+mounted.** The list is `@clerk/nextjs`, `@clerk/clerk-react`, `next-auth`,
+`@supabase/auth-helpers-nextjs`, `@supabase/auth-helpers-react`, `@supabase/ssr`,
+matched by package or subpath (`next-auth/react`, `@clerk/nextjs/server`). The reason
+is the stub the unit and browser planes install for those same libraries: a **signed
+snapshot** — `isLoaded: true`, `isSignedIn: false`, `userId: null`, `user: null`,
+`status: "unauthenticated"`, behind a Proxy whose method-shaped keys (`sign*`, `set*`,
+`get*`, `reload*`, `redirect*`, `create*`) resolve to another signed snapshot and
+`*List` keys to `[]`, everything else `undefined`. Mount a provider that gates its
+children on a session against that and it renders **nothing**, and every spec inherits
+the blank screen — while the stub already satisfies the context reads that
+auth-consuming components make on their own.
+
+So the failure to expect is one **below** the dropped layer, and it is the drop, not
+the component: `Could not find Convex client`, `could not find … in the context`. The
+fix is not editing `provider.tsx`, because `--force` regenerates it. Two real options:
+
+- put the values you supply (a seeded auth state, a theme, a router) in
+  **`provider.fixtures.ts`**, which is never regenerated under any flag;
+- or pass **`--provider <file>`**, which also buys you a context the derived wrapper
+  could not produce.
+
+One subtlety in the resolver worth knowing when a provider you expected is missing: a
+namespace alias (`const ToastProvider = ToastPrimitives.Provider`) counts **only if
+that file exports the name**, and the first exported candidate wins. And a file that
+renders `<Component />` with no `{children}` inside it is never a usable provider —
+it wraps nothing.
+
+## Module stubs, and what they must not touch
+
+Client specs mock an **allowlist only**: `next/navigation`, `next/headers`,
+`server-only`, `next/link`, `next/font/*`, and any `"use server"` module. Mocking a
+`cn` helper would strip every className off the markup the assertions read; mocking a
+UI component would replace the element an interaction test clicks.
+
+Rules the shim table follows:
+
+- **A named stub outranks a pattern stub** — an explicit entry for a module wins over
+  a family match, so adding one never silently shadows a narrower decision elsewhere.
+- `next/script` gets an inert in-place stand-in: it renders **nothing** without
+  Next's router context (it injects its tag through a side effect), which otherwise
+  looks like a broken component. `next/head` is deliberately **not** stubbed.
+- `LIBRARY_SHIMS` covers the third-party packages whose context the mount needs
+  (react-query, react-router, react-hook-form and react-intl are in it). The
+  requirement is detected from what the component **mounts**: the hooks it calls
+  — through project wrappers, across files — and the library's **components** it
+  renders, because `<FormattedMessage>` calls no hook and throws for the missing
+  provider all the same. A component handed through a prop counts as rendered
+  (`as={Link}`, `component={Link}`, `slots={{ root: Link }}`, `render`), since no
+  JSX tag ever names it; an HTML tag string (`as="a"`) and the app's own
+  components do not. One library can also be installed under two module names,
+  and both count.
+  A shim fixes the mount, not the component: an API misuse the analyser cannot
+  see stays a red spec, and an honest one.
+- **One library can need two wraps, and its older install can be unable to have
+  the newer one.** react-router is that case: `MemoryRouter` serves
+  `useNavigate` / `useLocation` / `<Outlet>`, while the data hooks
+  (`useLoaderData`, `useFetcher`, `useMatches` …) invariant out under it and get
+  `createMemoryRouter` + `RouterProvider` instead. Tags split the same way, and
+  each was probed alone under both wraps rather than read off the docs: `<Form>`
+  throws `useSubmit` and `<ScrollRestoration>` throws `useMatches` under
+  `MemoryRouter`, while `<Link>` and `<Outlet>` mount there and stay. A component
+  needing both gets the data wrap alone (`supersedes`: the data router serves the
+  navigation surface too, so nesting only shadows) — whether it reached them
+  directly, through its own hooks, or through a tag. It is offered only when the
+  react-router that actually resolves is **≥ 6.4**, the release that added
+  `createMemoryRouter` — an import the installed library never exported takes down
+  every spec that reads the file, so on 5.x those hooks keep failing with the
+  message the library writes. And because `RouterProvider` renders a real error
+  *page* when the mount throws, the wrap's `errorElement` **rethrows**: a crashing
+  component fails its own spec with its own error.
+- **A Feature-Sliced barrel declares nothing, so both walks follow the
+  hand-off.** `entities/rates/index.ts` is `export * from './model'` and that
+  model index is `export { useRateQuery } from './queries'`, so neither the hook a
+  component imports nor the library it calls three files away is named by any
+  import the component makes. A JSX child tag is the same problem: `<CreateApiKeyModal>`
+  imported from `'../index'` left the child edge at the barrel, so what the modal
+  needs was inherited by nobody and the parent's spec mounted bare. The named hop
+  is exact, so it goes first; `export *` only says "ask the target", so it is
+  consulted when no named hop carries the name; a hop whose module does not
+  resolve ends that hop rather than the search; and a cycle costs one visit.
+  `export * as ns from`, `export type { T } from` and a file's own
+  `export { localName }` are NOT hand-offs of the target's name, while a name
+  imported and handed back out with a module-less `export { … }` is.
+- `server-only` is handled by an emitted `server-only-stub.ts` at the suite root,
+  because the real package throws on import by design.
+
+## React 17 / 18 / 19
+
+The app's React major (`detectAppReact`, read from the root `package.json`) is the
+single switch for the whole suite.
+
+- **≥18** mounts through `createRoot`; **<18** falls back to legacy `ReactDOM.render`,
+  document roots render with `renderToStaticMarkup`, and promise-valued props are not
+  passed at all.
+- The suite's `react` / `react-dom` are **pinned to the version the app has installed, exactly** —
+  `detectAppReact` reads `node_modules/react` before the declared range, because a caret is a
+  floor and `^19.2.0` installs whatever is newest. Where the sources resolve a different copy than
+  that walk finds, `appReactPin` reads the pin off the copy the emitted `react` aliases anchor on:
+  the pin and the alias must name one physical copy or the plane renders with two Reacts.
+  Two React copies is the classic red-suite
+  cause, with signature `Cannot read properties of null (reading 'useState')`; a pair that
+  merely drifts is just as fatal — one patch off dies at load on `Incompatible React
+  versions`, one major off on `Cannot read properties of undefined (reading
+  'ReactCurrentOwner')`. The next run rewrites a stale or loose pin it finds in an existing
+  suite manifest (`repairReactPin`).
+- Testing Library follows the app: React ≤17 gets `@testing-library/react@^12.1.5`
+  with `@testing-library/dom@^8.20.1`, because 13/14 peer-require React ^18 and 14
+  hard-requires the `react-dom/client` entry that does not exist in 17. A stale 13+
+  range left behind by an older run is repaired by the next one (`repairRtlPin`) —
+  so an upgraded-app suite that suddenly installs RTL 12 did the right thing.
+
+## What the `package.json` merge does
+
+`devDependencies` for the harness (`@playwright/test`, `msw`, `react-scan`, Vitest and
+friends) and the plane scripts — `flawless:unit`, `flawless:browser`, `flawless:perf`,
+`flawless:e2e`, `flawless:load`. JSON is merged, not rewritten: your file's existing
+indentation and key order survive, because generation should produce a clean
+`git diff`, not a reformat.
+
+**pnpm ≥10 needs one more thing, and the merge records it:** the deps the tool
+introduces go into `pnpm.ignoredBuiltDependencies`. Without that record pnpm errors on
+an unapproved build-script decision, and `ERR_PNPM_IGNORED_BUILDS` kills the app's own
+`pnpm run dev` before Next boots — a test-tooling install that breaks the dev server
+is the worst possible first impression.
+
+## Environment loading
+
+Two different orders, because the two consumers are different runtimes.
+
+- **The Vitest config** reads `.env.test.local`, `.env.test`, `.env.local`, `.env`,
+  `.env.example` — first value wins, real environment variables beat all of them.
+  `.env.example` is last on purpose: template repos ship only the example, and its
+  placeholders exist to satisfy module-scope construction (`new URL(process.env.DATABASE_URL)`
+  at import time), not to be correct.
+- **The perf/browser host bundle** reads Next's own development precedence: `.env`,
+  `.env.local`, `.env.development`, `.env.development.local`, later wins — the same
+  values the app would see in `next dev`.
+
+## gitignore
+
+Entries are appended in **every** mode, not only under `--nextjs`: the suite's own
+scratch directories (`test-results/`, `heaps/`) and the credential file the emitted
+global-setup writes (`e2e/.auth.json`). Outside Next mode the destination is a small
+search — git root, then the nearest `package.json`, then the out dir's parent — which
+matters because until that ordering was fixed a plain run ignored nothing it
+generated.
+
+## Spec-derived API fixtures are a separate concern
+
+`--nextjs` probes `http://localhost:3000/api/docs` for a live OpenAPI document with a
+short timeout. Whether that probe helps, hurts or should be turned off
+(`--swagger-url=off`) is in flawless-api-fixtures.
+
+## Never
+
+- Never hand-edit `flawless/provider.tsx` to add a provider: `--force` erases it.
+  Use `--provider` or `provider.fixtures.ts`.
+- Never mock a project module (a `cn`, a UI primitive) to make a spec green — the
+  assertions stop referring to the real render.
+- Never treat a provider drop's `TODO(flawless)` as a passing state when the specs
+  below it fail on a missing context: that is the same drop, still open.

package/.agents/skills/flawless-perf-harness/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: flawless-perf-harness
+description: Run and interpret flawless-react's runtime performance plane — the `host/` bundle, `profile/` Playwright suite, mount/update times from React's Profiler, budgets.json (warn-only, and NOT baselines), `--heaps` V8 snapshots, FLAWLESS_WORKERS, the shared 127.0.0.1:5173 host with the browser specs, and what a number is worth. Use before running `flawless:perf`, when a profile spec is red or a budget warns, when snapshots are missing, or before quoting a mount time. For the static `perf/*` findings that need no browser see flawless-perf-static; for load-test p95s and their baselines see flawless-load.
+---
+
+# flawless perf harness
+
+`perf-harness` builds a real Chromium surface for components: a Bun-served host
+bundle, one Playwright spec per host-mountable component, and a budget file. It is
+also the host the **browser specs** run on, so most "the perf plane is broken"
+reports are really "the host is broken", and both planes share the symptom.
+
+## What it writes
+
+```bash
+bunx @lariocpt/flawless-react "src/app/**/page.tsx" --nextjs . --tasks unit-browser,perf-harness
+```
+
+The `perf-harness` task is what builds this plane, and `unit-browser` alongside it
+is what makes the **browser specs** appear — they run on the same host, so without
+this task there is no browser plane either.
+
+| file | regenerated? |
+| --- | --- |
+| `host/index.html`, `host/server.ts`, `host/_polyfill.ts` | yes |
+| `host/registry.ts` — the component tables the host mounts from | yes, every run |
+| `host/main.tsx` — boot: providers, MSW worker, the `ALL` spread | **write-once** |
+| `profile/_helpers.ts`, `profile/_heap.ts` | yes |
+| `profile/<Component>.profile.spec.ts` | yes while the component stays host-mountable; stamped, so your edits mark it as yours |
+| `budgets.json` | **write-once** |
+| `playwright.config.ts` (the perf plane) | yes |
+
+Two consequences people trip on:
+
+- A component hand-added to `host/registry.ts` is **lost on the next run**. Register
+  it in the `ALL` spread in `host/main.tsx`, which nothing rewrites.
+- `budgets.json` keeps whatever you wrote. That protects your tightened numbers — and
+  means a **deleted key silently reverts to the default** at the next measurement,
+  because the file is never rewritten to remind you.
+
+## What is measured
+
+- **Mount time** and **update times** per component, via React's built-in
+  `<Profiler>`.
+- **Unnecessary rerenders** flagged by `react-scan`.
+- A wall-clock distribution (min / avg / p50 / p95 / max) over a forced-rerender
+  loop.
+
+Scenarios per component: `mounts at defaults`, `variant matrix` (when the analyser
+found variants), `stress-click-rerender x 50` (when a handler prop exists — skipped
+with a stated reason when it does not), and `forced rerender x N`.
+
+**Only two things fail a profile spec**: the mount witness (`renderCount ≥ 1`) and
+the forced-rerender smoke check (at least one update timed). **Every budget is a
+`console.warn`.** A green perf run therefore means "it mounts and it re-renders",
+not "it is fast" — read the `[budget]` lines, not the exit code.
+
+## Budgets, not baselines
+
+`budgets.json` is per component: `{ "HomePage": { "mountMs": 50, "updateMs": 16 } }`.
+Defaults are 50 ms mount, 16 ms update (one frame). Breaching one warns:
+
+```
+[budget] HomePage mount 61.42ms > 50ms
+```
+
+To make a budget a gate, change that `console.warn` into an
+`expect(...).toBeLessThan(...)` in the spec — the suite README says so, and it is
+your call because a threshold you did not measure is theatre. The intended loop is:
+run once, tighten each number to what you actually observed, keep the diff in the
+commit.
+
+**There is no baseline file in this plane.** `last-<name>.json` /
+`baseline-<name>.json` are load pipes (flawless-load). Comparing a mount time here
+means comparing two runs' output by hand, which is why the recorded numbers should
+come from a one-worker run (below).
+
+## Running it
+
+```bash
+bun run flawless:perf                          # from the app root
+node node_modules/@playwright/test/cli.js test --config playwright.config.ts   # from the suite dir
+```
+
+The config has **exactly one project**, `chromium`, with `testDir: "./profile"`; run
+the plane from the suite dir so the suite's own copy of Playwright resolves — from
+the app root, a second copy is how you get `No tests found` or `test.describe()
+called here`.
+
+It serves its own host: `webServer.command` is `bun host/server.ts` on
+`http://127.0.0.1:5173`, with `reuseExistingServer: !process.env.CI`. The **browser
+specs use the same host on the same port** (`browser/playwright.config.ts` runs
+`bun ../host/server.ts`), so two planes at once is one server serving two runners
+and noisy numbers at best. To clear a stuck host: `lsof -ti :5173 | xargs -r kill`.
+
+Measurement hygiene: `FLAWLESS_WORKERS=1` forces a single worker; CI defaults to 1,
+otherwise Playwright decides. Budgets only warn, so parallel measurement can't fail
+a run — but it does make the numbers worse. Record a number with one worker.
+
+Output lands in `test-results/` (already gitignored, and Playwright clears it at the
+start of each run): `test-results/results.json` is the machine-readable one —
+`scripts/report.mjs`, emitted with `--report`, aggregates it — while
+`playwright-report/` is the HTML one. Traces are retained on failure only.
+
+## `--heaps`: V8 snapshots as diagnostics
+
+`--heaps off | stress | all` (default `stress`) is read at scaffold time and baked
+into `profile/_heap.ts`:
+
+- `off` — no CDP capture at all. A snapshot of a real app is tens of MB and one is
+  taken **either side of every scenario**: an observer that costs more than the thing
+  it observes, inside the measurement it brackets.
+- `stress` (default) — keep snapshots for `stress-*` scenarios and for failures.
+- `all` — keep every post-scenario snapshot.
+
+Files land at `heaps/<spec>__<test>__<label>.heapsnapshot` with predictable names, so
+you can take them from the filesystem instead of digging through
+`playwright-report/data/<sha1>`, and they are attached to the HTML report too. Format
+is the standard V8 `.heapsnapshot`: Chrome DevTools → Memory.
+
+Snapshots are **diagnostics, not the measurement**: an open CDP session can fail for
+reasons unrelated to the component (a page that already navigated, a Playwright and
+Chromium that disagree about a target guid), so `_heap.ts` warns and returns nothing
+rather than failing the spec it was added to observe. If snapshots are missing but
+the run is green, look for the warning.
+
+## Debugging the host
+
+- **`ReferenceError: <name> is not defined` with no output from the host build** — a
+  resolve-plugin fall-through in the host server dropped a bare specifier's module
+  onto a variant that lacks that export (`msw`'s named imports were the casualty).
+  Run `bun host/server.ts` from the suite dir to see the build; check the plugin's
+  `args.path` gates, not the spec.
+- **A component is not in the host at all** — REPORT.md's components table says why
+  it is not mountable. Server components cannot mount in this host, and a compound
+  part may only be reachable through its parent. Do not write a spec for what the
+  host refuses to mount; fix the mountability.
+- **A spec times out in `waitForFunction` waiting for `window.__profile.mount`** — the
+  host never booted (see the resolve trap) or `host/main.tsx` was edited into a state
+  where its boot script throws. Its edits are yours forever, so `git diff` it first.
+- **`[flawless] react-scan disabled`** on React 17 — react-scan cannot instrument it;
+  render counts still come from the Profiler, so the times are real and the
+  unnecessary-rerender column is not.
+
+## Under `--expo`
+
+`perf-harness` **refuses** under `--expo`, by a measured decision (~0 host-mountable
+components on an all-route-screens app), and the refusal names the recorded evidence.
+It is a failed `TaskResult`, so it appears in `results[]`, the `--ci` blob and
+REPORT.md. Do not work around it by dropping `--expo`: a DOM host pointed at React
+Native produces specs that run, pass, and touch nothing. See flawless-expo.
+
+## Never
+
+- Never call a green perf run "within budget": budgets warn.
+- Never compare a one-worker number against a parallel one.
+- Never read load-test p95s out of this plane, or claim a perf baseline this tool
+  does not keep.

package/.agents/skills/flawless-perf-static/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: flawless-perf-static
+description: Read and act on the findings from flawless-react's own static performance analyser — the nine `perf/*` rules (set-state-in-render, unstable-child-prop, hook dependency drift, missing-memo-leaf, unresolved-prop), how the analyser's conservatism shapes a clean report, the sidecar and per-component report files, and which findings are worth fixing versus suppressing. Use when triaging `reports/<Component>.perf-static.json`, when a `perf/unresolved-prop` finding means the generated spec passes `undefined`, or when deciding whether a memoisation finding is real. For runtime numbers see flawless-perf-harness; for a11y and React-rule findings see flawless-a11y and flawless-react-rules.
+---
+
+# flawless perf-static
+
+```bash
+bunx @lariocpt/flawless-react "src/**/*.tsx" --tasks perf-static --no-inline-summary
+```
+
+`perf-static` reports; it scaffolds nothing to run. Findings print as
+`file:line:col rule message`, land in `flawless/reports/<Component>.perf-static.json`
+(one file per component that owns findings), and are summarised in REPORT.md and the
+`--ci` blob. A `<Component>.flawless.json` sidecar lands beside each analysed source
+unless `--no-inline-summary`; its paths are relative to the sidecar, so resolve them
+against the sidecar's own directory.
+
+Each report file carries two numbers beside its findings: `reactCompiler` (the
+state the memo rules were judged against, with the config that proved it) and
+`specQuality` (that component's props no fixture could synthesise). Both are why a
+zero in the file means what it means — read them before concluding anything from an
+empty `findings`.
+
+Per-component report files only appear for components with findings, so **stale
+per-component files from earlier runs linger in `reports/`.** Count from the task
+summary or REPORT.md, never from a glob over the directory.
+
+## The nine rules
+
+| rule | severity | what it means |
+| --- | --- | --- |
+| `perf/set-state-in-render` | **error** | unguarded `setState` during render — always real, fix first |
+| `perf/hook-missing-dependency` | warn | an effect/callback reads something not in its deps — stale closure |
+| `perf/hook-extraneous-dependency` | warn | a dep that is never read — the effect fires for nothing |
+| `perf/hook-missing-deps-array` | warn | a hook that takes a dep list is called without one |
+| `perf/unstable-child-prop` | warn | inline object/array/arrow handed to a component child |
+| `perf/no-memoisation-with-children` | warn | a component taking `children` is memoised where it cannot help |
+| `perf/missing-memo-leaf` | warn | a leaf that re-renders on every parent render, not memoised |
+| `perf/unresolved-prop` | *spec quality* | the analyser could not synthesise a default for a prop — see below |
+| `perf/effect-every-render` | warn | an effect that runs on every render |
+
+Triage in that order of trust.
+
+- **`set-state-in-render`** is the only error the analyser emits and the only one
+  that is never a style preference.
+- **Hook deps.** `hook-extraneous-dependency` usually means the dep is never read:
+  remove it, or make it real — a scroll-on-change effect that never touches
+  `messages.length` is fixed by reading it (`if (messages.length === 0) return;`),
+  not by suppressing. `hook-missing-dependency`: wrap the function in `useCallback`
+  and add it.
+- **`unstable-child-prop`** is a real win when the receiving child is memoised or
+  heavy (a memo'd list, a third-party `<Sonner>`). Hoist static objects and arrays
+  to module scope. An inline arrow handed to a plain DOM element costs nothing —
+  leave it.
+- **The advisory tail** (`no-memoisation-with-children`, `missing-memo-leaf`,
+  `effect-every-render`) is a scale, not a bug list. Fix where the runtime harness
+  agrees (flawless-perf-harness); do not chase it to zero.
+- **`perf/unresolved-prop` is not a performance finding, and is not counted as
+  one.** It is the only one of the nine reported apart: bucketed per component under
+  REPORT.md's `## Spec quality` heading with the prop names, and never in the task's
+  finding number. It says the analyser could not invent a value, so the generated
+  spec passes `undefined` for that prop — a limit of this tool's fixtures, not a
+  rerender risk in your app. Fix it with `--props '{"x":1}'` or by editing that
+  spec's `DEFAULTS`, and expect that component's specs to stay weak until you do.
+  Counted per prop it was **713 of the dogfood run's 926 findings**, one button alone
+  contributing 148, with the 127 findings that needed someone buried under it.
+
+## A clean report is not proof
+
+The analyser is deliberately conservative where it would otherwise be wrong: it
+**skips hook-dependency findings when the dependency list contains a member access
+or a spread**, because it cannot resolve those without a type checker. So a file
+using `useEffect(fn, [state.items])` produces nothing at all here — absence of
+findings means "not checked", not "correct".
+
+The same conservatism that protects the report shapes the specs: everything
+`perf-static` knows comes from the same static read the unit specs are built from
+(`analyseTree()`), no type checker, no execution.
+
+## React Compiler changes what these findings mean
+
+On a project the compiler runs on, memoisation is the compiler's job: measured on
+one native app, **136 of 168 perf-static findings were the three memoisation
+rules** (`docs/archive/2026-08-expo-probes.md`). Telling someone to hand-write a
+`memo()` wrapper the build already applied is not advice worth printing, so
+`perf-static` reads the state off the project's own configs — in **every** mode,
+not only `--expo` — and suppresses `perf/unstable-child-prop`,
+`perf/missing-memo-leaf` and `perf/no-memoisation-with-children` when it is on.
+
+| state | read from | what the task does |
+| --- | --- | --- |
+| **on** | `app.json` `experiments.reactCompiler`; `next.config.*` `reactCompiler`; a babel or recognised bundler config naming `babel-plugin-react-compiler` | the three memo rules are suppressed, the other six run, and REPORT.md names the config that proved it |
+| **off** | a config was read, and it does not turn the compiler on | all nine rules run, and nothing is said about the compiler |
+| **undetermined** | nothing readable | all nine run, and the summary says the memo findings may be pre-compiled noise |
+
+Three things this deliberately does not do:
+
+- **It does not infer the flag from a dependency.** Next ships
+  `babel-plugin-react-compiler` in its own dependency tree, so a lockfile grep
+  reports "compiler on" for apps that never enabled it — and would have
+  suppressed 127 valid findings on the run that found this bug. Config only.
+- **It does not model per-file bail-outs.** A component that violates the Rules of
+  React is not compiled, so in principle its memo findings survive. The
+  `react-rules` task owns that detection; these flags are global, and perf-static
+  treats compiler state as global rather than guessing per file.
+- **It does not suppress quietly.** The suppression, its per-rule counts and the
+  evidence string are in the task summary, in REPORT.md, in the `--ci` blob and in
+  every `<Component>.perf-static.json`. A suppressed zero has to read differently
+  from a zero that means nothing was found — same reason the native a11y zero
+  carries its denominator.
+
+So on a compiler project the findings you still get are the ones the compiler has
+no opinion about: `set-state-in-render`, the three hook-dependency rules,
+`effect-every-render` and `unresolved-prop`. On a compiler-off project
+`unstable-child-prop` is a real win when the receiving child is memoised or heavy,
+and memoising it by hand is still the fix.
+
+## Under `--expo`
+
+`perf-static` runs on React Native the same way it runs on DOM — same rules, same
+report files. What changes is the compiler question above, and that "heavy child"
+usually means a list row rather than a widget. See flawless-expo.
+
+## Never
+
+- Never suppress a `perf/*` finding without a reason clause, and never to make a
+  batch green.
+- Never quote a zero for a file whose deps the analyser could not resolve.
+- Never diff `reports/` to count findings: per-component files from earlier runs
+  survive. Use the task summary.