@m4l/testing 0.0.24 → 1.0.1

package/README.md

@@ -0,0 +1,679 @@
+# Testing Libraries
+
+`packages/testing` contains workspace-shared testing helpers that can be consumed from multiple Nx projects without copying the same mock data or helper code into every package.
+
+Treat `packages/testing` as the **default home for any testing helper that can reasonably be reused or that prevents future reimplementation**. If a fixture, installer, override pattern, browser/runtime shim, mock builder, or E2E helper could serve another test area with only minor adaptation, promote it into `packages/testing` even when that extraction is more work than keeping the first implementation local.
+
+This is the publishable `@m4l/testing` package, targeting version `1.0.1`. Its source-first workspace API and published stable API share the same four subpaths. The `0.x` registry line remains unchanged.
+
+Private workspace-only libraries remain under `libs/*`; use their own conventions rather than copying this package's release configuration.
+
+## Build, release and adoption
+
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:typecheck`
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:test`
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:test-coverage`
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:lint`
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:build`
+- `NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false yarn nx run @m4l/testing:verify-package`
+
+`verify-package` packs the build without publishing, installs it in a new OS
+temporary directory outside the checkout, checks strict types with the
+`development` condition enabled, and runs Vitest/RTL and Playwright API smoke
+checks using only the installed tarball. There are no workspace aliases or
+links. This is package-consumption verification, not MF host E2E. A second mocks-only installation verifies that React and test-runner peers are
+not pulled in and that the compiled mocks execute independently. The consumers
+are retained for diagnosis; its path and tarball integrity are written to ignored
+`tmp/poc-mf-versioned-consumers/testing-package-verification.json`.
+
+The output is `dist/packages/@m4l/testing`. Vite builds the ESM entries and bundles
+the private observability implementation needed by Playwright. The build clears its declaration incremental state after Vite cleans the output,
+then TypeScript emits declarations under `types/`; published export maps contain no `development`
+condition. React, Vitest, Playwright and RTL remain consumer-owned peers, marked
+optional so a mocks-only consumer does not need to install unrelated runners.
+Consumers must install the peers required by their chosen subpath. The library declares compatible peer ranges from the tested versions; the
+workspace and versioned MF consumers keep exact install pins. The dist-manifest
+helper opts into preserving these source peer contracts rather than replacing
+them with exact workspace versions, so unrelated consumers can resolve their
+own compatible types and runners.
+
+The root entry provides common React/Vitest/RTL exports and the modern Vitest
+helpers. Version `1.0.1` does not ship the old Cypress `registerCommands` API or
+the old `testColumnConfigs` / `testFilterFields` / `testSortFields` runners from
+`0.0.24`; migrate those usages to the explicit subpaths and `assertColumnConfigs`,
+`assertFilterFields`, `assertSortFields`. Old pinned `0.x` consumers retain their
+published artifacts. Consumers of `latest` or `*` require a compatibility review
+before the registry tag changes.
+
+The package lint policy permits only the catalog import in
+`playwright/src/helpers/realtimePerformanceBrowser.ts` to cross the buildable/private
+boundary, because that implementation is bundled. External-consumer fixtures
+may use public self-imports because they run after copying outside the workspace.
+All other imports retain the normal Nx boundary rules.
+
+The repository release allowlist and publish target opt this package into the
+existing release machinery. The target version `1.0.1` requires an explicit
+bootstrap/version review against current registry state and reachable tags;
+registration alone does not force Nx Release to choose that version. No package
+or dist-tag is published by the local POC. Verify the packed artifact outside the
+workspace before beta/stable release. Non-Golden MFs adopt a stable exact NPM
+version; if they need a testing API change, develop against source as Golden in
+one MR and return to versioned consumption in another MR after stable publication.
+
+### One-time 1.0.1 bootstrap without Nx Release
+
+The initial migration may use direct build/npm/Git commands. This is a one-time
+bootstrap, not a second versioning system. Subsequent versions use the existing
+beta/main Nx Release workflow. Keep the source manifest at `1.0.1` and use the
+configured tag format `release/@m4l/testing/1.0.1`; Nx resolves subsequent versions
+from reachable Git tags, not from an unrelated custom tag.
+
+Before a real publication, commit and push the reviewed changes, use a clean
+checkout, and coordinate the initial `main` pipeline so it does not also publish
+this change. The existing `ENABLE_RELEASE=false` CI variable disables automatic
+release jobs for that pipeline; it is pipeline-wide, so do not use it for a merge
+that also needs other package releases. Do not persist that setting for later
+pipelines. The normal scoped `main` release deliberately publishes a new version
+for qualifying branch changes even if a manual publication already exists.
+
+From the workspace root, build and verify without invoking the Nx CLI or Nx
+Release (the Vite configuration still uses the workspace Nx path plugin):
+
+```bash
+rtk proxy env NX_NO_CLOUD=true NX_CLOUD_DISTRIBUTED_EXECUTION=false NX_DAEMON=false yarn vite build --config packages/testing/vite.config.ts
+rtk proxy yarn exec rimraf out-tsc/packages/testing/build
+rtk proxy yarn exec tsc -p packages/testing/tsconfig.build.json
+rtk proxy node -e "require('node:fs').copyFileSync('packages/testing/README.md', 'dist/packages/@m4l/testing/README.md')"
+rtk proxy node packages/testing/scripts/verify-package.mjs
+rtk proxy npm publish ./tmp/poc-mf-versioned-consumers/m4l-testing-1.0.1.tgz --dry-run --access public --tag latest --ignore-scripts --registry https://registry.npmjs.org
+```
+
+The verification report records the tarball integrity. Check that `1.0.1` is
+unpublished, the local and remote release tag are absent, and the committed
+manifest and tarball both say `1.0.1`. A dry-run does not establish publish or
+Git push permission. After the beta/quality checks and the one-time publication
+coordination are satisfied, the separate write commands are:
+
+```bash
+rtk proxy npm publish ./tmp/poc-mf-versioned-consumers/m4l-testing-1.0.1.tgz --access public --tag latest --ignore-scripts --registry https://registry.npmjs.org
+rtk proxy npm view @m4l/testing@1.0.1 version dist.integrity --json --registry https://registry.npmjs.org
+rtk proxy git tag -a release/@m4l/testing/1.0.1 HEAD -m "chore(release): publish 1.0.1"
+rtk proxy git push origin refs/tags/release/@m4l/testing/1.0.1
+```
+
+Publish the exact verified tarball and compare the registry integrity with the
+report **before** tagging the unchanged build commit. If publication succeeds
+but tagging/pushing fails, recover only the missing tag step; do not republish,
+overwrite a tag, or increment the version as a workaround. This creates a GitLab
+repository tag; it does not create a separate GitLab Release notes page.
+
+Before returning to normal release automation, verify that the tag commit is
+an ancestor of `main` and fetch that tag into future release checkouts. Preserve
+the source manifest/version alignment and the existing beta requirement. The
+next patch from a reachable `1.0.1` baseline is `1.0.2`; feature/breaking commits
+may produce a minor/major version under the normal release rules.
+
+## Terminology
+
+- `M4L` is the broader workspace/runtime namespace used by the monorepo packages and applications.
+- `Patronus` refers only to the visual design-system layer: tokens, theme colors, and styling conventions applied on top of components.
+- `Patronus` does **not** imply business logic, runtime behavior, package ownership, or generic application functionality.
+- In shared testing helpers, prefer `M4L` naming for generic runtime or app-level behavior. Reserve `Patronus` wording for documentation that is specifically about the visual design-system surface.
+
+## Exports
+
+- `@m4l/testing/rtl`
+  Shared React Testing Library helpers for broad app- and MF-level rendering patterns, including reusable DOM runtime mocks such as `ResizeObserver`, `matchMedia`, and browser storage.
+- `@m4l/testing/mocks`
+  Shared deterministic constants and helper factories for common testing data such as environment payloads, dictionary data, formatter values, and neutral host-tools scaffolding.
+- `@m4l/testing/vitest`
+  Shared Vitest-specific installers and module-factory helpers for repeated setup patterns, such as console-error filters plus reusable M4L app, M4L package, and exact-package module mocks.
+- `@m4l/testing/playwright`
+  Shared Playwright E2E helpers for reusable route installers, browser/runtime helpers, deterministic fixture builders, and MF-loading stubs that should not remain owned by a single app E2E project.
+
+Current shared Playwright helpers include:
+
+The authenticated-preview helpers below currently define the reusable
+host-owned baseline only. They cover authenticated shell bootstrap, sidebar
+launch, and the common authenticated module-dictionary seam that shows up
+immediately after the host mounts a real MF preview bundle. They do not own
+app-specific URL assertions about selected modules. Feature-specific post-mount
+mocks and visible MF-owned assertions stay in the owning MF E2E project. That
+ownership split is now exercised by both `operative_my_gps_devices-e2e` and
+`operative_gps_history_list-e2e`, and the API still stays intentionally narrow
+until a third authenticated MF proves another shared seam.
+
+When those helpers touch shell runtime selection or bootstrap overrides, treat
+`apps/gclick/HOST_RUNTIME_STANDARD.md` as the canonical runtime methodology
+guide and update it alongside the helper docs.
+
+- `createHostAuthenticatedMfMenuFixture(...)`
+  Builds the minimal authenticated sidebar menu tree for one MF entry, including the MF `moduleId`, visible title, preview `debugPort`, and optional `dynamicParams` that should reach the opened MF window.
+- `createHostAuthenticatedMfModuleDictionaryFixture(...)`
+  Builds the standard authenticated MF module-dictionary payload used after the host opens a real preview bundle, including the common `module_name` and `module_description` data keys.
+- `createHostMfPreviewDynamicParamsFixture(...)`
+  Builds a typed preview-scenario `dynamicParams` payload for authenticated MF launches. It documents the shared `dummyPresetId` and `testCondition` keys while still allowing MF-specific extension keys when a scenario needs more than the common baseline.
+- `installHostAuthenticatedMfPreviewBootstrap(...)`
+  Composes the authenticated host-shell bootstrap baseline with one deterministic MF sidebar entry. The high-level installer accepts the MF identity fields directly (`moduleId`, `title`, `debugPort`, optional `iconUrl`, and optional `dynamicParams`) instead of exposing the lower-level menu-fixture shape. The shared baseline now also stubs `GET /users/me/preferences`, so authenticated host-preview suites inherit the same preferences bootstrap seam that the host runtime now requires without re-registering that endpoint in every MF-owned E2E project.
+- `installHostAuthenticatedMfModuleDictionaryRoute(...)`
+  Installs the common authenticated MF module-dictionary route used after host-side launch so each MF pilot does not need its own one-line `isAuth: true` wrapper around the lower-level module-dictionary installer.
+- `openHostAuthenticatedMfPreviewModule(...)`
+  Installs the authenticated preview bootstrap, optionally lets the caller install MF-local post-mount route mocks, mirrors `dynamicParams.dummyPresetId` into the shell-bootstrap queries `hostRuntimeMode=dummy` and `hostRuntimeDummyPresetId` when one deterministic host runtime is needed, and navigates through the real host sidebar flow. URL expectations about selected modules stay in the owning app or MF E2E contract.
+  Keep the default debug-port readiness wait for flows that mount a real MF
+  preview bundle. Only set `skipDebugPortReadyWait: true` when the suite
+  replaces that remote bundle with `installMicrofrontendRenderStub(...)` and no
+  preview origin needs to boot at all. When one MF needs the shared host-open
+  flow to prove that its shell-managed window actually emerged before the
+  app-local ready wait begins, pass a caller-owned `waitForModuleOpen(...)`
+  gate and let the shared helper re-attempt the sidebar click once if that
+  gate never materializes.
+- `openHostSidebarModule(...)`
+  Opens one host-shell sidebar module by visible title and expands the sidebar first when the menu item is not yet visible. The helper retries with a non-exact accessible-name match when icon text or other leading accessible content makes the exact `menuitem` name longer than the visible label alone.
+  It can also accept one caller-owned `waitForModuleOpen(...)` gate plus a
+  small `maxClickAttempts` budget so host-owned window emergence is verified
+  immediately after the sidebar click instead of being deferred to a later
+  app-specific ready wait.
+- `installMicrofrontendRenderStub(...)`
+  Installs a deterministic browser-side `render_v2_*` / `unmount_*` MF contract stub that matches the current host runtime shape used by `MFLoader`, so host-shell E2E suites can validate MF opening behavior without downloading a real remote bundle. The stub records render calls immediately, then waits on a deadline for the host-created container before mounting the visible DOM so CI does not depend on one exact animation-frame budget.
+- MF-owned authenticated preview helper files should keep window lookup logic
+  anchored on visible shell semantics, not on dev-only selectors. In practice
+  that means combining user-visible title text, the host `close` action, and
+  one MF-owned control rendered inside the managed window instead of assuming
+  `data-testid` or readable CSS class names survive the compiled preview lane.
+- `attachJson(...)`
+  Attaches one formatted JSON payload to the current Playwright report entry so
+  app E2E projects do not each reinvent the same `testInfo.attach(...)` shape.
+- `formatFailedChecks(...)`
+  Converts failed check arrays into one readable multiline assertion message
+  without forcing each app E2E project to keep its own string formatter.
+- `readRealtimeMarkerInterpolationState(...)`,
+  `hasRealtimeMarkerContexts(...)`, and
+  `isRealtimeDeviceSelectedOrDebugPanelVisible(...)`
+  Browser-executable helpers for the shared
+  `window.__M4L_REALTIME_PERFORMANCE__` marker-interpolation debug state. Use
+  them with `page.evaluate(...)` and `page.waitForFunction(...)` instead of
+  rewriting the same browser-global access in each app E2E project.
+- `tryWaitForBrowserCondition(...)` and `waitForBrowserCondition(...)`
+  Generic Playwright polling helpers that wrap `page.waitForFunction(...)` with
+  a reusable boolean-returning path plus a caller-owned timeout error path.
+
+## Internal structure
+
+- `package.json`
+  Publishable package metadata with source-first development conditions and compiled subpath exports for `./rtl`, `./mocks`, `./vitest`, and `./playwright`.
+- `tsconfig.json`
+  Solution/editor config for the testing package.
+- `tsconfig.rtl.json`
+  Standalone typecheck/declaration project for `rtl`. It stays isolated from the workspace-wide `@m4l/*` alias graph so the focused internal project does not surface editor-only `rootDir` diagnostics from unrelated packages.
+- `tsconfig.mocks.json`
+  Standalone typecheck/declaration project for `mocks`, using the same local-alias isolation as `rtl`.
+- `tsconfig.vitest.json`
+  Standalone typecheck/declaration project for `vitest`. It keeps the Vitest-only runtime surface isolated while still allowing the shared installers to consume `@m4l/testing/mocks`.
+- `tsconfig.playwright.json`
+  Standalone typecheck/declaration project for `playwright`. It reserves a dedicated shared home for reusable E2E helpers without coupling them to any one app E2E project.
+
+The root TypeScript paths resolve all testing subpaths and observability to source.
+The focused configs therefore need no local paths overrides. The aggregate
+`tsconfig.lib.json` checks the runtime helpers; `tsconfig.spec.json` includes tests.
+`tsconfig.build.json` emits build-only declarations with workspace-relative layout
+inside the tarball, including the private observability types required by the
+Playwright helpers. These are compiled declarations, not checkout dependencies.
+
+Inside each public subpath, keep `src/index.ts` as a pure barrel only.
+Do not place implementation logic directly in `index.ts`.
+Split implementation into responsibility files such as:
+
+- `types.ts`
+- `constants.ts`
+- `fixtures.ts`
+- explicit single-purpose files such as `render.ts` when the subpath exposes one clear resource
+- `helpers/`
+  Keep one helper file per helper or helper family, plus a barrel `helpers/index.ts`.
+- `installers/`
+  Keep one installer file per installer or installer family, plus a barrel `installers/index.ts`.
+- `factories/`
+  Keep one factory file per mocked library or module family, plus a barrel `factories/index.ts`.
+  When a factory family has layered composition, prefer explicit subfolders such
+  as `factories/base/`, `factories/packages/`, and `factories/app/`, each with
+  its own barrel so the hierarchy stays visible in the tree.
+
+Avoid catch-all implementation filenames such as `utils.ts`, `helpers.ts`, `factories.ts`, or `installers.ts` once the logic has a clear named responsibility. Reserve those generic names for folders or barrel files only.
+
+Consumer test projects should continue to consume `@m4l/testing/*` from source in their test-facing TypeScript config (`tsconfig.spec.json`, Playwright `tsconfig.json`, or equivalent) by widening `rootDir` and including the shared source globs they need. This keeps test iteration fast and avoids forcing prebuilt declaration output every time a shared testing helper export changes.
+When a shared testing subpath starts shipping `.tsx` implementation files, those source-based consumer includes should cover both `**/*.ts` and `**/*.tsx` for that subpath so renames like `m4lBaseComponents.ts` → `m4lBaseComponents.tsx` do not trigger `TS6307` in downstream composite spec programs.
+If a Playwright E2E project includes `packages/testing/playwright/src/**/*`, it
+must also include `libs/observability/mf/src/**/*` and
+`libs/observability/shared/src/**/*` in the same `tsconfig.json` because the
+shared browser/runtime helpers now depend on the source-owned
+`@m4l/observability/mf` catalog and its neutral
+`@m4l/observability/shared` contracts. Keep those sources together; do not
+switch that consumer seam to project references or `dist` mappings just to
+suppress `TS6307`.
+The internal `packages/testing` `tsconfig.vitest.json` and
+`tsconfig.playwright.json` follow that same rule by widening `rootDir` and
+including `libs/observability/mf/src/**/*` plus
+`libs/observability/shared/src/**/*` directly instead of referencing
+`../observability/tsconfig.mf.json` or relying on `out-tsc`.
+
+Current shared runtime helpers in `@m4l/testing/rtl` include:
+
+- `render(...)`
+  Shared React Testing Library render helper with automatic `cleanup()` and `vi.clearAllMocks()` after each test plus a ready-to-use `userEvent` instance.
+- `installMatchMediaMock(...)`
+  Shared `window.matchMedia` installer for package and app setup files that need a browser-like media-query API without duplicating the same global shim in every project.
+- `installStorageMock(...)`
+  Installs reusable `localStorage` / `sessionStorage` shims plus a shared `Storage` constructor for package and app setup files that need deterministic browser storage without keeping one app-local memory-storage class per project.
+- `installResizeObserverMock(...)`
+  Installs a reusable `ResizeObserver` test double on `globalThis` / `window`, with manual `trigger()` support and optional auto-trigger behavior on `observe(...)`.
+- `createResizeObserverEntry(...)`
+  Builds deterministic `ResizeObserverEntry` payloads for width/height-driven test scenarios.
+
+Current shared data helpers in `@m4l/testing/mocks` include:
+
+- `environmentFixture`, `useEnvironmentValueFixture`, `formattersFixture`, and related `*Fixture` constants
+  Shared deterministic baselines for tests that can reuse the standard data shape without per-test construction.
+- `createEnvironmentFixture(...)`
+  Returns a full `EnvironmentType`-compatible fixture by merging explicit overrides on top of the shared baseline fixture.
+- `createUseEnvironmentValueFixture(...)`
+  Returns a lighter `useEnvironment()`-style fixture for tests that only need the commonly consumed environment fields.
+- `createUseModuleDictionaryValueFixture(...)`
+  Returns a lightweight `useModuleDictionary()` value with predictable `getLabel(...)` and `getModuleLabel()` behavior, plus optional keyed-label overrides for tests that only need stable dictionary resolution without rebuilding inline hook payloads.
+- `createUserPreferencesFixture(...)`, `createUserPreferencesApiDataFixture(...)`, `createUserPreferencesMagnitudePropertyFixture(...)`, and `createUserPreferencesContextValueFixture(...)`
+  Build reusable authenticated user-preferences fixtures for tests that now depend on locale, number delimiters, date/time formats, time zone, or magnitude conversions. `createUserPreferencesContextValueFixture(...)` mirrors the `useUserPreferences()` runtime contract closely enough to exercise `changeUserPreferences(...)`, `formatNumber(...)`, `getMagnitudeProperty(...)`, and `convertMagnitude(...)` without importing the real app context.
+- `createHostToolsFixture(...)`
+  Builds a neutral host-tools fixture with a `BrowserHistory`-compatible in-memory history baseline plus no-op callbacks, and lets each test override only the members it cares about.
+- `createToasterFixture(...)`
+  Builds a deterministic toast stub for tests that only need a valid toaster shape and stable return ids.
+
+Current shared Vitest helpers in `@m4l/testing/vitest` include:
+
+- `installConsoleErrorFilter(...)`
+  Reusable console-error filter for noisy test-runner warnings that should be muted consistently across packages.
+- `installRhfOnSubmitRef(...)`
+  Shared global ref installer for app tests that need a stable `RHFormProvider` submit bridge.
+- `createM4lAppBaseModuleMock(...)`
+- `createM4lPackageBaseModuleMock(...)`
+- `createM4lBaseComponentsModuleMock(...)`
+- `createM4lAppComponentsModuleMock(...)`
+- `createM4lAppFormComponentsModuleOverrides(...)`
+- `createM4lAppFormLayoutsModuleOverrides(...)`
+- `createM4lAppCoreModuleMock(...)`
+- `createM4lPackageGclickModuleMock(...)`
+- `createM4lPackageGclickRealtimeModuleMock(...)`
+- `createM4lAppGraphicsModuleMock(...)`
+- `createM4lAppLayoutsModuleMock(...)`
+- `createM4lPackageComponentsModuleMock(...)`
+- `createM4lPackageCoreModuleMock(...)`
+- `createM4lPackageGraphicsModuleMock(...)`
+- `createM4lPackageLayoutsModuleMock(...)`
+- `createPaperFormComponentMock(...)`
+- `createChildrenContainerComponentMock(...)`
+- `createNamedFieldComponentMock(...)`
+- `createPropertyValueComponentMock(...)`
+- `createIconComponentMock(...)`
+- `createDividerComponentMock(...)`
+- `createNavLinkComponentMock(...)`
+- `createWindowBaseComponentMock(...)`
+- `createHelmetPageComponentMock(...)`
+- `createActionButtonComponentMock(...)`
+- `createSuspenseLoadableComponentMock(...)`
+- `createLeafletModuleMock(...)`
+- `createReactHookFormModuleMock(...)`
+- `createReResizableModuleMock(...)`
+- `createReactLeafletModuleMock(...)`
+  Reusable module factories for M4L component consumers plus app and package `test/setup.ts` files so packages, hosts, and MFs can keep thin local adapters instead of repeating the same large `vi.mock(...)` payloads. When a consumer needs untouched real exports too, pass `baseModule` populated from `importOriginal(...)` and let the shared factory override only the test-facing surface.
+  `createM4lAppFormComponentsModuleOverrides(...)` provides a reusable override payload for app/MF `@m4l/components` setups that need the dynamic-MF parameters store plus neutral form container/action placeholders (`FormContainer`, `ActionsContainer`, `ActionFormCancel`, `ActionFormIntro`, `RHFAutocompleteAsync`, and `RHFRadioGroup`) without copying the same local override object across app test setups.
+  `createM4lAppFormLayoutsModuleOverrides(...)` provides a reusable override payload for app/MF `@m4l/layouts` setups that need neutral paper-form seams (`useDynamicPaperForm`, `useFormAddEdit`) and a configurable `createComponentField(...)` identity baseline without repeating the same setup-local overrides.
+  `createReactHookFormModuleMock(...)` now accepts `useFormContextData` so tests can inject package-local `setValue`, `reset`, `formState`, and related RHF behavior without rebuilding the full `react-hook-form` contract in each file.
+  `createLeafletModuleMock(...)` now covers the repeated partial `leaflet` seams that showed up during the `GpsMap` normalization work: configurable `L.control.scale()` and `L.DomEvent.disableClickPropagation()` / `disableScrollPropagation()` behavior, while still preserving real exports through `baseModule` when the consumer needs the untouched runtime surface.
+  `createReactLeafletModuleMock(...)` now covers neutral `Circle`, `GeoJSON`, `Polygon`, `Polyline`, `LayerGroup`, `Marker`, `Popup`, and configurable `useMap()` behavior. Use `useMapData` when the test can keep one stable map object for the whole file, or `useMapImplementation` when the test needs `useMap()` to read mutable per-test state such as a late-bound fake map ref. When a test still needs real exports such as `MapContainer`, keep the mock partial by passing `baseModule` from `importOriginal(...)` and override only the shape components or `useMap()` contract that belong to the scenario.
+  `createSuspenseLoadableComponentMock(...)` complements that baseline for per-test overrides: use it with `vi.mocked(Loadable).mockImplementation(...)` when a test needs lazy-route rendering through the existing app setup mock instead of re-declaring `@m4l/components` locally.
+  `createM4lAppBaseModuleMock(...)` is the app-level baseline for direct `@m4l/base` consumers in host and MF setups. It shares the same neutral `Icon`, `Tooltip`, and `Typography` placeholder contract as the package-level baseline while giving app `test/setup.ts` files the same naming convention used by `createM4lAppCoreModuleMock(...)` and `createM4lAppComponentsModuleMock(...)`.
+  `createM4lPackageBaseModuleMock(...)` is the dedicated package-level baseline for direct `@m4l/base` consumers. It keeps `Icon`, `Tooltip`, and `Typography` on a neutral primitive placeholder surface while `baseModule` can still preserve the real constants, class keys, and helper exports when the scenario needs them.
+  `createM4lBaseComponentsModuleMock(...)` is the shared base layer for `@m4l/components`: it covers reusable component-system primitives, form placeholders, DataGrid-friendly stubs, and passthrough spies for utility helpers such as validation builders when the real implementation should stay observable by default. When this README mentions the design-system layer behind those primitives, that is the narrow context where the term `Patronus` applies.
+  That same base layer now preserves `className`, `disabled`, and click handling on the shared `IconButton` placeholder so package and app tests can assert stable button-state behavior without rebuilding a local `@m4l/components` partial mock.
+  The shared button-like placeholders (`Button`, `IconButton`, and `Tab`) now
+  use explicit button-prop interfaces instead of `UnknownRecord` plus unsafe
+  handler casts, so the shared mock surface stays closer to the real React
+  button contract and consumer typechecks can catch drift earlier.
+  RHF placeholder components exposed by that base layer use explicit `rhf-*`
+  test ids such as `rhf-field-name`, `rhf-select-countryId`,
+  `rhf-number-timeMinInSeconds`, `rhf-helper-geometry`,
+  `rhf-radio-group-assignmentType`, and `rhf-checkable-list-devices` so tests
+  can distinguish shared React Hook Form placeholders from other mock surfaces.
+  That base layer also exposes typography helpers such as `getTypographyStyles()` so app and package tests can execute style maps without rebuilding another local `@m4l/components` partial mock.
+  The shared M4L app factories now also cover neutral platform-shell and MF-loading collaborators that repeatedly show up in app tests, including provider passthrough components such as `ModuleDictionaryProvider`, `ModuleSkeletonProvider`, `DomainCountryProvider`, `FormatterProvider`, `ModalProvider`, `PopupsProvider`, `AreasProvider`, `FlagsProvider`, `EnvironmentProvider`, `HostToolsProvider`, `NetworkProvider`, `AuthProvider`, `LocalesProvider`, `ThemeSettingsProvider`, `DeviceTypeProvider`, and `HostThemeProvider`, plus shell primitives such as `SideBar`, `AppBar`, `HelmetPage`, `AreasAdmin`, `LanguagePopover`, `AccountPopover`, `MFNoAuthApp`, `MFLoader`, `createDynamicMFStore(...)`, `createToaster(...)`, `getMFLoaderComponentsDictionary()`, `getLoadingErrorComponentsDictionary()`, and locale/domain hooks such as `useLocales()`, `useDomainCountry()`, and `getLocaleFromNetwork()`.
+  The shared base `@m4l/components` layer now also owns reusable view primitives such as `Divider`, `NavLink`, and `WindowBase`, plus focused placeholder helpers such as `createDividerComponentMock(...)`, `createNavLinkComponentMock(...)`, and `createWindowBaseComponentMock(...)` so app tests can stay on top of the setup-owned baseline instead of rebuilding local workspace-library mocks.
+  `createM4lPackageGclickModuleMock(...)` remains intentionally specific to the `@m4l/gclick` package and covers map-store, indicator, and GNSS enum behavior that only makes sense when mocking that exact runtime package.
+  The shared app-components baseline now exposes a minimal but stable
+  `WINDOW_SIZES.square` contract with both `medium` and `large` entries so app
+  tests can open modal windows without each suite rebuilding the same shape
+  locally. Consumers that need additional sizes such as `small`, `vertical`,
+  or `horizontal` can still extend that baseline in their local `test/setup.ts`
+  overrides.
+  `createM4lPackageGclickRealtimeModuleMock(...)` is the matching package-safe baseline for direct `@m4l/gclick-realtime` consumers. Use `surface: 'payload'` when the test only imports `@m4l/gclick-realtime/payload`, `surface: 'contracts'` for `@m4l/gclick-realtime/contracts`, and the default root surface when a direct `@m4l/gclick-realtime` mock should expose both contracts and payload guards.
+  The package-safe M4L factories intentionally stay narrower: they cover direct `@m4l/base` primitive placeholders through `createM4lPackageBaseModuleMock(...)`, compose on top of `createM4lBaseComponentsModuleMock(...)` where appropriate, and add only reusable package-test collaborators such as `useEnvironment()`, `useModuleDictionary()`, `useHostTools()`, `useNetwork()`, `useModuleSkeleton()`, `useLocalStorageWithListener()`, `useWindowToolsMF()`, package-safe popup scaffolding through `PopupsProvider`, popup/modal hooks, lightweight DataGrid helpers, package-safe `@m4l/layouts` contracts such as `DynamicTabs`, `useModule()`, and `useFormAddEdit()`, plus package-safe `@m4l/graphics` contracts such as `usePaginate()`, `useRows()`, and `getContrastTextColor()` without pulling app-shell collaborators into every library test suite.
+  The option exports that do not add extra fields, such as `CreateM4lAppGraphicsModuleMockOptions` and `CreateM4lAppLayoutsModuleMockOptions`, intentionally stay as direct type aliases of `CreateVitestModuleMockOptions` so the public helper API preserves the same call shape without carrying lint-only empty interfaces.
+  Legacy `*Microfrontend*` alias exports were removed from `@m4l/testing/vitest`; use the `*M4lApp*` names for generic app baselines, the `*M4lPackage*` names for generic library-package baselines, and `*Gclick*` only inside names that point to the exact `@m4l/gclick` runtime package.
+  The layered factories now live under `vitest/src/factories/base/`,
+  `vitest/src/factories/packages/`, and `vitest/src/factories/app/`. Treat the
+  folder name as part of the documentation: `base` defines the reusable
+  foundation, `packages` defines package-test composition, and `app` defines
+  app and MF composition.
+  For MF apps, prefer one real local `test/setup.ts` that installs the shared
+  baseline from `@m4l/testing` plus one MF-owned adapter file such as
+  `test/testing.ts` for mutable scenario state. That split keeps the global
+  setup stable while feature tests only override the small seams they truly
+  own, instead of rebuilding full `vi.mock(...)` payloads in every file.
+  Factory implementation files import `vi` explicitly from `vitest` instead of
+  relying on runner globals so the shared helper source stays readable and
+  typecheck-friendly even outside direct test-file context.
+  React-rendering factory implementation files now use `.tsx` plus JSX instead
+  of dense `React.createElement(...)` payloads so the shared mock surface stays
+  easier to read and maintain as it grows.
+  Shared factory families that mock publishable packages should also ship local
+  contract tests next to the factory implementation. In `packages/testing/vitest`,
+  keep those checks as colocated `__tests__/*.contract.test.ts` files plus any
+  matching `*.types.contract.ts` probes that can compile inside the internal
+  library program.
+  When a contract test needs to compare a shared mock against the real package
+  export surface, prefer `await vi.importActual<Record<string, unknown>>()`
+  inside the test file runtime path, such as an `it(...)` block or a shared
+  `beforeAll(...)` preload, instead of a top-level static import. For heavier
+  packages, preload the real module once in `beforeAll(...)` so contract tests
+  stay deterministic under full-suite load. That keeps the runtime drift check
+  real while avoiding `packages/testing` typecheck cycles or source-program
+  expansion into the consumer package.
+  Use runtime contract tests for real package-boundary drift detection
+  (existence and coarse export kind), and keep `*.types.contract.ts` probes
+  focused on the shared mock prop interfaces that belong to `packages/testing`
+  itself. Do not force `packages/testing` TypeScript programs to import full
+  consumer-package source trees just to compare public types.
+
+### Column, filter, and sort assertion helpers
+
+- `assertColumnConfigs(columns, configs)`
+  Verifies a DataGrid column array against a typed config spec and returns
+  `string[]` of violations. Use this when a hook or helper builds DataGrid
+  columns and the test should own the `describe` / `it` structure while still
+  getting readable drift messages for column props, formatter helpers, and
+  supported hook-call metadata.
+- `assertFilterFields(actualFields, expectedFields)`
+  Verifies a DynamicFilter field array and returns `string[]` of violations.
+  It checks the standard field properties plus `selectAsyncOptions` when the
+  field type is `selectAsync`.
+- `assertSortFields(actualFields, expectedFields)`
+  Verifies a DynamicSort field array and returns `string[]` of violations for
+  structural drift such as `name`, `dictionaryId`, `type`, `presence`, and
+  optional `urlIcon`.
+
+Use these helpers instead of manually asserting each field property inline.
+
+### Path for consumers outside this Nx workspace
+
+`@m4l/testing` is still a private internal workspace library. For MF repos or
+other consumers that live outside this Nx monorepo, the migration path is
+explicitly one of these two options:
+
+1. publish `@m4l/testing` (or a narrowed public subpackage) so the external
+   consumer can import `assertColumnConfigs(...)`,
+   `assertFilterFields(...)`, and `assertSortFields(...)` directly
+2. copy the shared helper files into the external consumer's own local testing
+   helpers and treat them as repo-owned utilities there
+
+Do not point non-Nx consumers at `packages/testing/old` anymore. Inside this
+monorepo, `@m4l/testing/vitest` is now the canonical assertion-helper path.
+
+## Nx configuration note
+
+`packages/testing` owns its Vitest contract explicitly:
+
+- `project.json` defines the `test`, `test-ci`, and `test-coverage` targets
+- `vitest.config.ts` stays unconditional because those targets execute it
+  directly
+- the workspace does not register the `@nx/vitest` inference plugin in
+  `nx.json`, so this library does not need extra graph-time exclude wiring
+
+That is the repository-standard **project-owned** Vitest mode for a library
+that already declares explicit test targets.
+
+### Direct validation for `@m4l/testing/vitest`
+
+`packages/testing/vitest` now has its own direct Vitest config and Nx test target.
+Use that direct target whenever you change shared Vitest factories, helpers, or
+installers.
+
+- Main gate:
+
+```sh
+nx test @m4l/testing
+```
+
+  This runs `packages/testing/vitest.config.ts` without coverage so local iteration
+  stays fast and the terminal output stays quieter during normal development.
+
+- CI-equivalent target:
+
+```sh
+nx run @m4l/testing:test-ci
+```
+
+  This runs the same config with coverage enabled and enforces
+  `100/100/100/100` thresholds for statements, branches, functions, and lines.
+  The coverage gate intentionally includes invalid-input guards for helpers
+  such as `assertFilterFields(...)` and `assertSortFields(...)`, plus the
+  exhaustive unsupported-hook fallback path inside `assertColumnConfigs(...)`,
+  so regressions fail at the shared-helper boundary instead of slipping through
+  as "unreachable" branches.
+
+- Explicit local coverage target:
+
+```sh
+nx run @m4l/testing:test-coverage
+```
+
+  Use this when you want the same direct coverage gate locally without using
+  the CI-named target.
+
+- Direct runner command when Nx indirection is not needed:
+
+```sh
+yarn vitest --config packages/testing/vitest.config.ts --run --coverage
+```
+
+Use the direct `@m4l/testing` gate before validating downstream consumers such
+as `@m4l/gclick`, `@m4l/gclick_host`, or `operative_gps_history_list`, because
+shared-helper regressions now fail at the source library boundary instead of
+waiting for a consumer suite to surface them.
+
+## Baseline mock contract
+
+When a package, app, or MF installs a shared module baseline in `test/setup.ts`, treat that baseline as the default testing contract for the suite.
+
+- Use shared factories such as `createM4lPackageComponentsModuleMock(...)`, `createM4lPackageCoreModuleMock(...)`, or the generic app-level variants to install the reusable module baseline once in `test/setup.ts`.
+- Keep those factories narrow and curated: they should override only the reusable test-facing surface, while untouched exports stay real through `baseModule: await importOriginal(...)`.
+- In individual test files, prefer `vi.mocked(...)`, `mockReturnValue(...)`, and `mockImplementation(...)` to adjust the behavior of the already-installed baseline mocks for the scenario under test.
+- Do not re-declare another full `vi.mock('@m4l/components'...)` or `vi.mock('@m4l/core'...)` factory in each test file when the setup baseline already covers that module.
+- `vi.mocked(...)` changes the behavior of the installed mock. It does **not** restore the original implementation of an export that `test/setup.ts` already replaced.
+- If a test truly needs the original implementation of one export that the setup baseline overrides, use a local partial mock with `importOriginal(...)` / `vi.importActual(...)`, or change the shared factory so that export stays as passthrough by default.
+- Keep local `vi.mock(...)` blocks for feature-only collaborators, sibling modules, or external dependencies whose behavior is specific to one subject and does not belong in the shared baseline.
+- When a local `react-leaflet` mock is still needed, it should usually start from `createReactLeafletModuleMock(...)` and keep only the feature-specific pieces local, such as a ref-aware `Marker`, a late-bound `useMapImplementation`, or plugin-specific Leaflet state.
+- When a local `leaflet` mock is still needed, it should usually start from `createLeafletModuleMock(...)` and keep only plugin-specific behavior local, such as `geoJSON()`, Geoman state, icon factories, or feature-only Leaflet helpers that are not yet reused elsewhere.
+- Document the residual local seams after each migration slice. A local mock is acceptable when it encodes feature-only runtime behavior, but the owning package or app README should record why that seam stays local so later cleanups do not re-open the same extraction debate without new evidence.
+
+Current shared Playwright policy in `@m4l/testing/playwright` is:
+
+- treat it as the canonical home for reusable Playwright E2E helpers across apps
+- extract cross-app route installers, auth/bootstrap mocks, MF bundle stubs, popup/window helpers, and deterministic E2E fixture builders there
+- keep the initial scaffold intentionally small until the first app migrations promote their first shared helpers
+- keep Playwright artifact ownership standardized at the workspace root under
+  `out-e2e/{project-name}/`
+- resolve HTML/blob/output report folders from the workspace root inside
+  `playwright.config.ts` itself instead of relying on project-relative report
+  paths that only work from one `cwd`
+- when an app or MF exposes a `show-report` Nx target, point it at the
+  workspace-root `out-e2e/{project-name}/report` path and forward extra args
+  so alternate `--host` / `--port` values remain easy when the default
+  Playwright port is already occupied
+
+### Local-first ownership and promotion timing
+
+Use this rule before extracting another Playwright helper into
+`@m4l/testing/playwright`:
+
+- keep the helper local while it still depends on one app's selectors,
+  thresholds, scenario semantics, or assertion vocabulary
+- keep topology adapters local while they still describe one app's host-vs-
+  standalone browser choreography
+- keep contract-depth concepts such as `minimum` and `deep` local to the owning
+  E2E project; they are test-contract categories, not shared library concerns
+- promote the helper once it already has a second consumer or clearly models a
+  shared shell/runtime seam without carrying app-specific DOM assumptions
+- do not extract a helper early if the only way to share it is to fill the API
+  with app-specific branching such as `if host`, `if standalone`, or
+  per-module selectors
+
+The practical bar is:
+
+- first consumer: local is the default
+- second real consumer or clean shared shell seam: promote to shared
+
+Current shared Playwright helpers in `@m4l/testing/playwright` include:
+
+- `createHostAuthenticatedSessionFixture(...)`
+- `createHostAreaFixture(...)`
+- `createHostCookieFixture(...)`
+- `createHostUiConfigFixture(...)`
+- `createHostLocaleFixture(...)`
+- `createHostGuestSessionFixture(...)`
+- `createHostModuleDictionaryFixture(...)`
+  Deterministic host-bootstrap payload builders that let app E2E projects keep only feature-specific labels or overrides local.
+- `installHostAuthenticatedSessionRoute(...)`
+- `installHostAreasRoute(...)`
+- `installHostCookiesRoute(...)`
+- `installHostMenusRoute(...)`
+- `installHostAuthenticatedBootstrapRoutes(...)`
+- `installHostUiConfigRoute(...)`
+- `installHostUiConfigAssetRoutes(...)`
+- `installHostGuestSessionRoute(...)`
+- `installHostLocaleRoute(...)`
+- `installHostModuleDictionaryRoute(...)`
+- `installHostGuestBootstrapRoutes(...)`
+- `installHostPasswordResetRoute(...)`
+- `installHostPasswordNewRoute(...)`
+  Reusable host guest-bootstrap, authenticated-shell, and password-submit route installers that virtualize shared host contracts without pulling app-specific selectors into the shared library. The password installers intercept the current `POST */api/v1/*/auth/password/reset` and `POST */api/v1/*/auth/password/new` backend contracts; these API paths are intentionally distinct from the canonical `/password/new` host browser route. The new-password fixture mirrors the backend's `201` response with `{ "data": "ok" }`. The retired `/auth/password_new` path follows the host wildcard fallback instead of rendering the password form. `installHostUiConfigRoute(...)` now also supports an explicit `responseGate` promise so E2E suites can keep the guest shell blocked deterministically until `ui-config` resolves instead of depending on fixed timing windows. Prefer that gate-first approach whenever the browser contract is "the shell stays blocked until bootstrap finishes", keep exact transient spinner-node assertions closer to the owning unit or integration tests unless the browser-visible node itself is the contract under test, and pair these installers with single-worker Playwright lanes plus unique per-project ports when multiple E2E apps share one machine.
+- `installMicrofrontendRenderStub(...)`
+  Reusable browser-side MF render/unmount contract stub for host-shell E2E coverage that needs to validate menu-to-window ownership without downloading a real remote bundle. It tracks mount successes/failures in the browser-side stub state for post-failure diagnostics.
+
+## Decision guide
+
+Use this guide before adding a new shared helper or choosing one of the existing subpaths.
+
+### Mandatory reuse policy
+
+- Start by assuming a new testing helper belongs in `packages/testing`.
+- Keep a helper local only when it is tightly coupled to one feature's DOM structure, one component family's business semantics, or one app-specific assertion vocabulary and would add noise to the shared library.
+- "Could another test or app benefit from this without carrying feature-only assumptions?" is the deciding question. If the answer is yes, move it to `packages/testing`.
+- Choose the shared-library path even when the first extraction is harder. The repository standard values future reuse over short-term local convenience.
+
+### Choose the subpath by context
+
+- Need deterministic data, neutral object shapes, or pure fixture builders with no Vitest-only behavior:
+  Use `@m4l/testing/mocks`.
+- Need React Testing Library lifecycle setup or browser-global runtime shims such as `ResizeObserver`:
+  Use `@m4l/testing/rtl`.
+- Need a package-wide `matchMedia` shim in `test/setup.ts`:
+  Start with `installMatchMediaMock(...)` from `@m4l/testing/rtl` instead of defining another local `Object.defineProperty(window, 'matchMedia', ...)` block.
+- Need `vi.fn()`, `vi.mock(...)` payloads, runner-global setup, or app `test/setup.ts` installers:
+  Use `@m4l/testing/vitest`.
+- Need Playwright route interception installers, reusable auth/bootstrap E2E mocks, browser/runtime helpers, or MF-loader stubs that can serve more than one app:
+  Use `@m4l/testing/playwright`.
+- Need something that only makes sense for one package, feature, or component area and would add noise to the shared testing library:
+  Keep it local in `src/test/`, `test/`, or `__testing__/`.
+
+### Choose the helper family by need
+
+- Static `*Fixture` constants:
+  Use them when the shared baseline already matches the scenario and the test does not need custom construction.
+- `create*Fixture(...)` builders:
+  Use them when most of the shape is shared but a few fields change per suite or per test.
+- `install*...(...)` installers:
+  Use them from setup files when a helper must patch `globalThis`, `window`, or another process-wide testing hook.
+- `create*ModuleMock(...)` factories:
+  Use them to build the body of a shared `vi.mock(...)` payload, while keeping the final `vi.mock(...)` registration local to the consumer setup file.
+
+### Common decisions
+
+- Need a full provider-compatible environment object:
+  Start with `environmentFixture` or `createEnvironmentFixture(...)`.
+- Need to mock `useEnvironment()` directly:
+  Start with `useEnvironmentValueFixture` or `createUseEnvironmentValueFixture(...)`.
+- Need to override `useModuleDictionary()` in a focused test without re-declaring `@m4l/core`:
+  Start with `createUseModuleDictionaryValueFixture(...)`, then install it through `vi.mocked(useModuleDictionary).mockReturnValue(...)` on top of the setup-owned baseline.
+- Need neutral host tools or toast methods:
+  Start with `createHostToolsFixture(...)` and `createToasterFixture(...)`.
+- Need a shared M4L app `test/setup.ts` baseline for host or MF:
+  Build the shared module payload with `@m4l/testing/vitest`, keep only app-specific overrides in the local setup file, and use `baseModule` when the setup must preserve untouched real exports from `importOriginal(...)`. Use `createM4lAppBaseModuleMock(...)` for direct `@m4l/base` imports, `createM4lAppCoreModuleMock(...)` for `@m4l/core`, and the matching app-level factory for components, layouts, or graphics.
+- Need a shared M4L package `test/setup.ts` baseline for library component tests:
+  Start with `createM4lPackageCoreModuleMock(...)` and `createM4lPackageComponentsModuleMock(...)`, which already compose the shared `createM4lBaseComponentsModuleMock(...)` layer. Use `createM4lPackageBaseModuleMock(...)` when package tests import `@m4l/base` primitives directly. Keep the local package setup thin, and override per-scenario behavior through `vi.mocked(...)` instead of re-declaring the whole module factory in each test file.
+- Need a reusable local `vi.mock('@m4l/layouts'...)` payload for package tests without adopting the broader app-shell baseline:
+  Start with `createM4lPackageLayoutsModuleMock(...)`, then override only the exact collaborator needed for the scenario through `moduleOverrides`.
+- Need a reusable local `vi.mock('@m4l/graphics'...)` payload for package tests without adopting the broader app-shell baseline:
+  Start with `createM4lPackageGraphicsModuleMock(...)`, then override only the exact collaborator needed for the scenario through `moduleOverrides`.
+- Need a reusable local `vi.mock('react-hook-form'...)` payload with a custom `useFormContext()` shape:
+  Start with `createReactHookFormModuleMock(...)`, then inject the scenario-specific `setValue`, `reset`, `formState`, or other RHF members through `useFormContextData`.
+- Need a reusable local `vi.mock('react-leaflet'...)` payload for package tests:
+  Start with `createReactLeafletModuleMock(...)`. Use `moduleOverrides` for shape placeholders such as `Circle`, `GeoJSON`, `Polygon`, or `Polyline`, and pass `baseModule` from `importOriginal(...)` when the test still needs untouched real exports such as `MapContainer`.
+- Need the real implementation of one export that the shared setup baseline already overrides:
+  Do not expect `vi.mocked(...)` to restore it. Use a local partial mock with `importOriginal(...)` / `vi.importActual(...)`, or keep that export as passthrough in the shared factory by default.
+- Need reusable DOM placeholders for library component tests:
+  Start with `createPaperFormComponentMock(...)`, `createChildrenContainerComponentMock(...)`, `createNamedFieldComponentMock(...)`, `createPropertyValueComponentMock(...)`, `createIconComponentMock(...)`, and `createActionButtonComponentMock(...)` from `@m4l/testing/vitest` before creating another feature-local JSX placeholder helper.
+  When the placeholder represents an RHF-owned control installed through `createM4lBaseComponentsModuleMock(...)`, assert the explicit `rhf-*` test ids emitted by the shared baseline instead of reintroducing legacy ids such as `field-*`, `select-*`, or `checkbox-*`.
+- Need a test-specific override for a library that the app already mocks in `test/setup.ts`:
+  Prefer `vi.mocked(...)` on the existing mock first. If the override shape becomes reusable across files or apps, promote the override helper into `@m4l/testing/vitest` instead of adding another local `vi.mock(...importOriginal)` block.
+- Need to decide whether a remaining local mock should stay local:
+  Ask whether it still encodes feature-specific orchestration or a shared contract gap. Keep it local when it owns mutable plugin/runtime behavior such as Geoman state, `leaflet.geoJSON()`, or a one-off integration seam under active review; otherwise promote the reusable portion into `@m4l/testing`.
+- Need reusable Playwright route mocking for host-style bootstrap, auth, or MF loading:
+  Start in `@m4l/testing/playwright` when the helper can be consumed by more than one app; keep only app-specific selectors and flows local.
+- Need a package-local wrapper, feature-specific provider composition, or assertions tied to one feature and not reusable without carrying that feature's semantics:
+  Do not move it into `packages/testing`.
+
+## Reuse-first expectation
+
+- Before creating any new testing helper, inspect `@m4l/testing/rtl`, `@m4l/testing/mocks`, `@m4l/testing/vitest`, and `@m4l/testing/playwright` first.
+- If the helper can reasonably enrich one of those shared subpaths, add it there instead of creating a new local implementation.
+- During migrations, treat local fixtures, setup wrappers, Vitest module payloads, and assertion helpers as candidates for `packages/testing` first. Keep only feature-specific orchestration local, and promote reusable portions so packages and apps do not rebuild the same testing surface independently.
+- Before creating a new DOM/runtime helper that patches browser globals, check `@m4l/testing/rtl` first.
+- Before creating a new Playwright route installer, auth/bootstrap mock, popup/window helper, or MF bundle stub, check `@m4l/testing/playwright` first.
+- If a test needs `ResizeObserver`, prefer `installResizeObserverMock(...)` and `createResizeObserverEntry(...)` instead of adding a new inline `ResizeObserverMock` class in the test file.
+- If you add a new public helper to `@m4l/testing/*`, document its purpose, intended usage context, and local-vs-shared boundary in the implementation JSDoc and keep this README decision guide aligned.
+- Only keep a local observer mock when the behavior is truly feature-specific and cannot be expressed cleanly with the shared helper API.
+- Keep generated declaration files out of `packages/testing/**/src`. Shared testing helpers are consumed from source in package test configs, so stray `.d.ts` files next to the source only add editor noise.
+
+## Placement rules
+
+- Put cross-package reusable testing data in `@m4l/testing/mocks`.
+- Put cross-package reusable Vitest installers and module-mock factories in `@m4l/testing/vitest`.
+- Put cross-app reusable Playwright route installers, fixtures, and browser/runtime helpers in `@m4l/testing/playwright`.
+- Prefer the shared environment factories in `@m4l/testing/mocks` before creating another inline `mockEnvironmentContext` or `environmentDataForTesting` object in a test file.
+- Keep the final `vi.mock(...)` registration in the consumer `test/setup.ts` file even when the factory body comes from `@m4l/testing/vitest`.
+- Keep app-specific page objects, selectors, and flows local to the owning `apps/*-e2e` project even when shared Playwright helpers exist.
+- Keep feature-specific fixtures, wrappers, and assertions next to the feature in `__testing__/` or the local `src/test/` area only when they are genuinely too feature-bound to enrich `packages/testing`.
+- Keep unit test files co-located with the component, hook, or helper they validate.
+
+## Design guidelines
+
+- Prefer pure factories and deterministic constants over framework-bound mocks.
+- Keep every `packages/testing/*/src/index.ts` file as a barrel-only entrypoint. Put implementation in responsibility files and let `index.ts` re-export that public surface.
+- Use `*Fixture` for static test data, `create*Fixture(...)` for test-data builders, and `create*ModuleMock(...)` for `vi.mock(...)` payload factories.
+- Prefer explicit implementation filenames such as `render.ts`, `consoleError.ts`, or `environment.ts` over catch-all filenames such as `utils.ts`.
+- When a subpath accumulates several helpers, move them under `helpers/` with one file per helper or helper family and keep `helpers/index.ts` as a barrel.
+- When a subpath accumulates several installers, move them under `installers/` with one file per installer or installer family and keep `installers/index.ts` as a barrel.
+- Put reusable DOM observer/runtime helpers that patch browser globals, such as `ResizeObserver`, in `@m4l/testing/rtl` instead of `@m4l/testing/mocks`.
+- Put reusable `vi.fn()`, `vi.mock(...)` factory payloads, and runner-specific setup logic in `@m4l/testing/vitest` instead of `@m4l/testing/mocks`.
+- Inside `@m4l/testing/vitest`, keep repeated module factories under `factories/` with one file per mocked library or module family instead of a single large `factories.ts`.
+- Put reusable Playwright helpers under explicit `fixtures/`, `helpers/`, or `installers/` folders inside `@m4l/testing/playwright` rather than leaving cross-app E2E support in one app project.
+- Type shared fixtures with local contract interfaces inside `packages/testing`, then let each consumer validate compatibility with package-owned types through local `satisfies` adapters. This keeps the shared testing library typed without coupling it back to one runtime package.
+- Keep `@m4l/testing/vitest` free of direct `@m4l/core` runtime type dependencies so packages such as `core` can consume it without creating a circular dependency.
+- Do not move feature-specific wrappers into `packages/testing` just because more than one test file uses them inside the same feature area.
+- When a helper only exists to support one component family, keep it local and document it there.