@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/content/guidance/storefront-next/sfnext-project-setup/references/SCRIPTS.md

@@ -0,0 +1,47 @@
+# Project Scripts
+
+Scripts in a Storefront Next project's `package.json`. Run with `pnpm <name>`; extra flags after the name are forwarded (`pnpm test --coverage`). If a script here is missing in your project, `grep -A60 '"scripts"' package.json` -- your project is the source of truth.
+
+## Develop and run
+
+| Script | Does |
+| --- | --- |
+| `dev` | Aggregates extension locales and config, then starts `sfnext dev` (Vite SSR, HMR) on http://localhost:5173. Runs with the `dev-data-store` Node condition |
+| `dev:debug` | Same with `--inspect` for a Node debugger |
+| `dev:log` | Dev with `SFCC_LOG_LEVEL=debug` |
+| `build` | `locales:aggregate-extensions`, `config:aggregate-extensions`, `cartridge:generate`, then `react-router build` -> `build/` |
+| `start` / `preview` | `sfnext preview`: serves the production build on http://localhost:3000 (builds if needed; `SFNEXT_DATA_STORE_UNAVAILABLE_MODE=fallback`) |
+
+## Deploy and operate
+
+| Script | Does |
+| --- | --- |
+| `push` | `sfnext push --project-directory .` -- uploads `build/` to Managed Runtime. Build first. Pass flags after it: `pnpm push -- --wait -e staging` |
+| `cartridge:generate` | `sfnext generate-cartridge` -- Page Designer metadata from decorators |
+| `cartridge:validate` | `sfnext validate-cartridge` -- validate metadata JSON against schemas |
+| `cartridge:deploy` | `sfnext deploy-cartridge` -- upload cartridges to the B2C instance (`-- --delete` wipes old files first) |
+| `config:inspect` | `sfnext config inspect` -- show which `config.server.ts` values are overridden by `.env` or MRT |
+| `config:push-env` | `b2c mrt env var push` -- sync `.env` variables to an MRT environment |
+| `config:aggregate-extensions`, `locales:aggregate-extensions` | Merge per-extension config / translations; run automatically by `dev`, `build`, `typecheck` |
+| `b2c` | Run the b2c CLI from the project (`pnpm b2c --help`) |
+
+## Quality
+
+| Script | Does |
+| --- | --- |
+| `typecheck` | Aggregate extension config, `react-router typegen`, then `tsc --noEmit` |
+| `lint` / `lint:fix` | OxLint (type-aware, zero warnings) plus Biome format check / fix |
+| `format` / `format:check` | Biome |
+| `lint:a11y`, `lint:css`, `a11y:scan-coverage` | Static accessibility lint, CSS/token lint, a11y scan coverage report |
+| `test` / `test:watch` | Vitest (`pnpm test src/components/foo` for one path) |
+| `storybook` | Storybook on http://localhost:6006 |
+| `storybook:build` | Static Storybook build |
+| `storybook:test` | Story tests: `--type=snapshot \| interaction \| a11y`, `--static`, `--update` |
+| `bundlesize` | Build with `BUNDLES_SIZE_CHECK=true` to enforce bundle limits |
+| `bundlesize:compare` | Compare bundle sizes between builds |
+| `lighthouse:ci` | Lighthouse CI run |
+| `extensions:list` | List extension points |
+| `e2e`, `e2e:turnstile`, `a11y` | Playwright suites in `e2e/` |
+| `chromatic:core` | Chromatic visual-test helper |
+
+Bundle treemap: `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` (writes `build/client-bundle-size.html`).

package/content/guidance/storefront-next/sfnext-project-setup/references/SFNEXT-CLI.md

@@ -0,0 +1,63 @@
+# `sfnext` CLI
+
+The `sfnext` binary comes from `@salesforce/storefront-next-dev`. Ways to run it:
+
+- `pnpm sfnext <command>` or a project script (`pnpm dev`, `pnpm push`, ...) inside the project
+- `b2c sfnext <command>` -- the b2c CLI installs the plugin on first use and, when run inside a project, prefers the project's local copy
+- `pnpm dlx @salesforce/storefront-next-dev <command>` for commands that run before a project exists (`create-storefront`)
+
+Most commands take `-d, --project-directory` (default: current directory). `.env` in the project directory is loaded automatically (not `.env.default`).
+
+## Project lifecycle
+
+| Command | Purpose |
+| --- | --- |
+| `create-storefront` | Create a project from a starter theme. Flags: `-n` name, `-V` starter theme (`fashion`, `cosmetic`, `foundations`, `footwear`, `furniture`, `luxury`), `-t` template URL/path, `-b` branch/tag, `-d` defaults, `-o` output dir |
+| `dev` | Vite dev server with SSR. `-p, --port` (default 5173) |
+| `preview` | Serve the production build, building if needed. `-p, --port` (default 3000) |
+| `create-bundle` | Create an MRT bundle in `.bundle/` without pushing. `-b` build dir, `-o` output dir, `-m` message, `-s` project slug |
+| `push` | Upload the build to Managed Runtime. See below |
+
+## Managed Runtime push
+
+```bash
+pnpm build && pnpm push -- -m "Release notes" -e staging --wait
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `-m, --message` | Bundle message (default: git branch:commit) |
+| `-w, --wait` | Wait for the deployment to finish; requires a target environment |
+| `-b, --build-directory` | Build dir (default: auto-detected `build/`) |
+| `-p, --project` | MRT project slug (env `MRT_PROJECT`, then `SFCC_MRT_PROJECT`, then dw.json `mrtProject`) |
+| `-e, --environment` | Target environment (env `MRT_TARGET`). Without one the bundle is uploaded but not deployed |
+| `--api-key`, `--credentials-file`, `--cloud-origin` | MRT credentials (env `MRT_API_KEY`, `MRT_CREDENTIALS_FILE`, `MRT_CLOUD_ORIGIN`; or `~/.mobify`) |
+
+`push` does not build; it fails if the build directory is missing.
+
+## Cartridges (Page Designer metadata)
+
+| Command | Purpose |
+| --- | --- |
+| `generate-cartridge` | Generate component metadata from decorators into `cartridges/app_storefrontnext_base` |
+| `validate-cartridge` | Validate the generated JSON |
+| `deploy-cartridge` | Upload cartridges to a B2C instance. Instance settings come from flags, env, or `dw.json`. Flags: `-s, --server`, `-v, --code-version`, `-r, --reload` (re-activate), `--delete` (remove old files first), `-c` include / `-x` exclude cartridges |
+| `setup-base-cartridge` | Register the SLAS scopes the base cartridge needs: `--slas-client-id <id>` (needs short code and tenant ID from flags/env/dw.json) |
+
+Deploying cartridges needs WebDAV credentials; without `--code-version` it also needs OAuth credentials to discover the active code version.
+
+## Configuration and extensions
+
+| Command | Purpose |
+| --- | --- |
+| `config inspect` | Show which `config.server.ts` values are overridden by `.env` or MRT (`--project`, `--environment` to include MRT values) |
+| `config aggregate-extensions`, `locales aggregate-extensions` | Merge extension config / translations (run by `dev`, `build`, `typecheck`) |
+| `extensions list` | List installed extensions |
+| `extensions install -e <SFDC_EXT_...>` | Install an extension |
+| `extensions remove -e <A,B>` | Remove extensions (`--yes` to also remove dependents) |
+| `extensions create -n "<Name>" -d "<desc>"` | Scaffold a new extension (`-p` target project dir) |
+| `create-instructions` | Generate install/uninstall instruction files for an extension you author |
+
+## SCAPI clients
+
+`sfnext scapi available | add | list | remove` manage typed SCAPI clients, including custom APIs. See `storefront-next:sfnext-scapi`.

package/content/guidance/storefront-next/sfnext-quality-gates/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sfnext-quality-gates
+description: >-
+  Run and fix the Storefront Next quality gates before a PR or deploy: OxLint (type-aware, --max-warnings 0) plus Biome formatting, lint:a11y, lint:css, typecheck, the TypeScript-only check, bundle-size budgets, Lighthouse CI, and the pre-PR checklist. Use when pnpm lint, pnpm format:check, pnpm typecheck, pnpm bundlesize or pnpm lighthouse:ci fails, for custom/color-linter or custom/header-format errors, "unused Tailwind class" findings, oxlint-disable comments, "what should I run before opening a PR", or CI red on lint. Do not use for writing tests (use `storefront-next:sfnext-testing`), accessibility fixes themselves (use `storefront-next:sfnext-accessibility`), or runtime performance tuning (use `storefront-next:sfnext-performance`).
+---
+
+# Storefront Next Quality Gates
+
+Your project enforces style, types, size and accessibility with a few commands. CI runs the same ones, and lint is strict: any warning fails.
+
+## Pre-PR checklist
+
+```bash
+pnpm lint            # OxLint (type-aware, --max-warnings 0) then Biome format check
+pnpm typecheck       # route typegen + tsc --noEmit
+pnpm test            # unit tests
+pnpm storybook:test --type=snapshot   # if you touched components or stories
+pnpm bundlesize      # if you added dependencies or large components
+```
+
+If you changed UI, also run `pnpm storybook:test --type=interaction` and `--type=a11y` (needs `pnpm exec playwright install chromium`). Fix formatting and auto-fixable lint in one go with `pnpm lint:fix`.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `pnpm lint` | `oxlint --type-aware --report-unused-disable-directives --max-warnings 0` (e2e excluded) then `biome format` check, then the e2e package's own lint |
+| `pnpm lint:fix` | `oxlint --fix` then `biome format --write` |
+| `pnpm format` / `pnpm format:check` | Biome formatting only (4-space indent, 120 columns, single quotes in JS, double in JSX) |
+| `pnpm lint:a11y` | Reports only `jsx-a11y/*` findings; exit 1 if any (see `storefront-next:sfnext-accessibility`) |
+| `pnpm lint:css` | After a build, checks the built app stylesheet for Tailwind candidates that only come from stories, tests or docs (dead or story-only classes). Run `pnpm build` first |
+| `pnpm typecheck` | `react-router typegen` then `tsc --noEmit` (uses extra heap) |
+| `node scripts/check-typescript-only.js` | Fails if `.js/.jsx/.mjs/.cjs` exist under `src/` |
+| `pnpm bundlesize` | Builds with `BUNDLES_SIZE_CHECK=true`; fails if chunks exceed limits in `package.json#bundlesize` (`client` and `server` lists) |
+| `pnpm bundlesize:compare` | Compares two bundle metadata files: `node scripts/compare-bundlesize.mjs --baseline <path> --candidate <path> [--tolerance <pct>]` |
+| `pnpm lighthouse:ci` | `lhci autorun` using `lighthouserc.cjs` (build first; it starts the preview server itself) |
+| `pnpm config:inspect` | Prints the resolved config to debug env overrides |
+
+ESLint and Prettier are not used. OxLint owns all linting (including type-aware rules and custom plugin rules); Biome owns only formatting.
+
+## Custom rules you will hit
+
+- `custom/color-linter`: use design tokens (`bg-primary`, `text-muted-foreground`), not hard-coded colors. See `storefront-next:sfnext-theming`.
+- `custom/header-format`: every TS/JS file needs the Apache 2.0 license header. Copy it from any existing source file.
+- `jsx-a11y/*` recommended set at error, plus `no-aria-hidden-on-focusable`, `anchor-ambiguous-text`, `no-redundant-roles` (allows `role="list"` on `ul`) and `alt-text` extended to `DynamicImage` and `ProductImage`.
+- `no-restricted-imports`: browser-only `@salesforce/storefront-next-runtime/i18n/client` is blocked from server modules.
+- TypeScript only in `src/`.
+
+Fix the code rather than disabling. If a suppression is truly needed, use a scoped `// oxlint-disable-next-line <rule> -- reason`. `--report-unused-disable-directives` fails stale ones. Generated and vendored trees (SCAPI generated clients, `src/components/ui/**`, build output) are skipped by lint and format.
+
+More: [references/lint-and-budgets.md](references/lint-and-budgets.md) and `docs/README-LINTING.md` (skip the sections about repository internals that do not apply to your project).
+
+## Typical failures
+
+| Symptom | Fix |
+|---------|-----|
+| `pnpm lint` fails only at the end on formatting | `pnpm format` |
+| Warning count > 0 | Warnings are errors here; fix or justify with a scoped disable |
+| `jsx-a11y/...` error | Fix markup; run `pnpm lint:a11y` while iterating |
+| Type errors about `+types/...` routes | Run `pnpm typecheck` (it regenerates route types) |
+| `pnpm lint:css` cannot find stylesheet | Run `pnpm build` first |
+| Lighthouse/bundle budget exceeded after adding a feature | See the budget notes in the reference; look for eager imports before raising a limit |
+
+## Related Skills
+
+- `storefront-next:sfnext-testing` - unit, story and e2e tests (the test half of the checklist)
+- `storefront-next:sfnext-accessibility` - fixing a11y lint and scan findings
+- `storefront-next:sfnext-performance` - reducing bundle and page weight
+- `storefront-next:sfnext-theming` - design tokens behind `color-linter`
+- `storefront-next:sfnext-deployment` - build and push after the gates pass

package/content/guidance/storefront-next/sfnext-quality-gates/references/lint-and-budgets.md

@@ -0,0 +1,39 @@
+# Lint configuration and performance budgets
+
+## Configuration files in your project
+
+| File | Role |
+|------|------|
+| `.oxlintrc.json` | All lint rules, custom JS-plugin rules (`custom/*`), overrides for tests/stories, `ignorePatterns` |
+| `biome.json` | Formatter only (linter and assists disabled) |
+| `lint-plugins/` | Source of the `custom/color-linter` and `custom/header-format` rules |
+| `e2e/biome.json` and e2e scripts | The e2e package lints and formats itself; it is not type-aware linted |
+
+OxLint's JS-plugin loader needs Node >= 22.6; the project requires Node 24.
+
+Test files relax some rules (fixtures use ad-hoc roles and handlers); story and test overrides are in `.oxlintrc.json`.
+
+## Editor integration
+
+Install the Oxc VS Code extension for inline diagnostics and the Biome extension (set as default formatter) for format on save.
+
+## Bundle size
+
+- Limits: `package.json#bundlesize` with `client` and `server` arrays of `{ name: <glob>, limit: '<size>' }`. Defaults are generous if absent.
+- `pnpm bundlesize` writes `build/<env>-bundlemeta.json` per environment.
+- Visualize: `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` opens `build/client-bundle-size.html` and `build/ssr-bundle-size.html` (`docs/README-PERFORMANCE.md`).
+- Before adding a large dependency, check its impact with the visualizer, lazy-load it (`React.lazy` or dynamic `import()`), and prefer server-only code for heavy logic.
+
+## Lighthouse CI
+
+- `lighthouserc.cjs` defines the URLs (home, a PDP, cart), number of runs, category score minimums (performance, accessibility, SEO, best-practices) and ceilings for `resource-summary:script:size` and `resource-summary:document:size` per route.
+- The shipped numbers are tuned to the starter theme. Your customizations (new scripts, bigger documents, different sites or product ids in the URL list) will move them. Update URLs to pages that exist in your catalog, then measure and set ceilings deliberately, with headroom, rather than deleting assertions.
+- Run `pnpm build` first; the config starts the preview server on port 3001 itself.
+- Also run `pnpm bundlesize` in CI or locally so regressions show up per chunk, not just in page totals.
+
+## When a budget fails
+
+1. Identify what grew: compare bundle metadata (`pnpm bundlesize:compare`) or the visualizer.
+2. Look for eager imports of heavy modules in root, layouts or shared components; convert to lazy loads.
+3. Check that new third-party scripts are deferred (see `storefront-next:sfnext-performance`).
+4. Only then raise a limit, in the smallest increment, and note why in the commit message.

package/content/guidance/storefront-next/sfnext-revalidation/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: sfnext-revalidation
+description: >-
+  Control which Storefront Next loaders re-run after an action or navigation: shouldRevalidate exports, the policy modules in src/lib/revalidation/routes (root, cart, product, category, checkout, home, wishlist, api-client, shared), getActionPath and isAmbientMutation, and the tag primitives in src/lib/revalidation/tags (withRevalidateTags, shouldRevalidateForTags, tagGroup, tagImplications). Use for "page re-fetches after add to cart", "loader runs too often", "stale data after a mutation", "flash of skeleton after changing a swatch", "add shouldRevalidate", or when a new action or route changes which loaders fire. Do not use for writing loaders or actions (use `storefront-next:sfnext-data-fetching`), Suspense and LCP tuning (use `storefront-next:sfnext-performance`), or client-side state (use `storefront-next:sfnext-state-management`).
+---
+
+# Storefront Next Revalidation
+
+React Router re-runs loaders after every action submission. A storefront has deep route trees, persistent fetchers (mini-cart) and lazy modals (quick view), so one add-to-cart can re-run many loaders that never read the basket, each with its own SCAPI fan-out. This skill is how to keep only the re-runs that are needed. The authoritative guide is `docs/README-REVALIDATION.md` in your project; read it before changing policy.
+
+## What revalidates
+
+An action submission (`<Form>`, `useSubmit`, `fetcher.submit`) re-runs the whole active set:
+
+1. the matched route chain (root, layouts, leaf),
+2. mounted resource fetchers (`fetcher.load()` of a resource route whose component is still mounted),
+3. fetchers inside open modals, drawers and sheets.
+
+A raw `fetch()`, a SCAPI client call, or `fetcher.load()` is not a submission and triggers nothing. A route that only exports an `action` fires revalidation but has no loader to re-run.
+
+## When a re-run is justified
+
+For each pair (action, active loader) it is justified only if both are true:
+
+- **Overlap**: the action result changes something the loader reads.
+- **Value not already available**: the new value does not already reach the UI another way (for example the basket provider is updated from the action result, so a cart action does not need the PDP loader to re-run).
+
+Two waste types: no overlap, or overlap with the value already available. Do not gate a re-run that is itself the sync mechanism (a provider that refills from loader output).
+
+## Where the policy lives
+
+Each route re-exports a shared policy rather than inlining logic:
+
+```ts
+// src/routes/_app.cart.tsx
+export { shouldRevalidate } from '@/lib/revalidation/routes/cart';
+```
+
+| Module (`src/lib/revalidation/routes/`) | Used by |
+|---|---|
+| `root.ts` | `src/root.tsx` (`export { shouldRevalidate } from ...`); denylist of irrelevant mutations, safe default is revalidate |
+| `cart.ts`, `checkout.ts`, `home.ts`, `wishlist.ts` | the matching route files |
+| `product.ts` | `_app.p.$.tsx`: relevant mutations force true; navigation re-runs only on different path or `pid` |
+| `category.ts` | `_app.c.$.tsx` and `_app.search.tsx`: skips client-only param changes and non-ambient mutations |
+| `api-client.ts` | `resource.api.client.$resource.ts` |
+| `shared.ts` | helpers: `getActionPath`, `isContextMutation`, `isIdentityMutation`, `isAmbientMutation` |
+
+`_app.tsx` exports `shouldRevalidate() { return false }` (navigation data that no shopper action changes). `resource.basket-products.ts` opts in only when `actionResult.basket.basketId` exists.
+
+"Ambient" mutations (site/currency, shopper context, login/signup/logout) change request-wide inputs and legitimately re-run most loaders.
+
+## Add a policy for a new route
+
+Prefer suppress-by-default allowlists for expensive loaders, and defer to the default for cheap ones:
+
+```ts
+// src/lib/revalidation/routes/store-events.ts
+import type { ShouldRevalidateFunctionArgs } from 'react-router';
+import { resourceRoutes } from '@/route-paths';
+import { getActionPath, isAmbientMutation } from './shared';
+
+const RELEVANT = [resourceRoutes.setSelectedStore] as readonly string[];
+
+export function shouldRevalidate({ currentUrl, nextUrl, formMethod, formAction, defaultShouldRevalidate }: ShouldRevalidateFunctionArgs) {
+    if (formMethod && formMethod !== 'GET') {
+        const path = getActionPath(formAction, currentUrl.origin);
+        return Boolean(path && (isAmbientMutation(path) || RELEVANT.includes(path)));
+    }
+    if (currentUrl.pathname !== nextUrl.pathname) return true;
+    return defaultShouldRevalidate; // explicit revalidate() still works; client-only params stay skipped
+}
+```
+
+Steps:
+
+1. List what the loader reads (fetched fields, URL params, cookies, context such as currency or selected store).
+2. List the actions reachable while this route is active (page, shell, open modals and drawers). Mark overlap and availability per action.
+3. Export the policy. Admit only mutations with overlap and no other delivery path. Document each admit in a comment.
+4. If a URL-filtered loader (search params) re-runs on navigation anyway, skip revalidating when only those params change.
+5. Add a test next to the policy (`*.test.ts`), covering an admitted mutation, a skipped mutation and a navigation.
+6. Verify manually: open DevTools Network, perform the gesture, and count loader (`.data`) requests.
+
+Gate adequacy matters: a policy that only checks `formAction` is set still re-runs on every action. Inspect the action path or `actionResult`.
+
+## Tags for cross-route contracts
+
+When several routes depend on the same data, use the tag primitives in `@/lib/revalidation/tags` (the framework ships primitives only; you own the catalogs):
+
+```ts
+// src/lib/revalidation/tags/cart.ts  (yours)
+export const cartTags = { all: 'cart.*', lineItem: (id: string) => `cart.lineItems:${id}` as const } as const;
+
+// action: emit
+import { withRevalidateTags } from '@/lib/revalidation/tags';
+return withRevalidateTags({ basket }, [cartTags.lineItem(itemId)]);
+
+// route: subscribe
+import { shouldRevalidateForTags } from '@/lib/revalidation/tags';
+export const shouldRevalidate = shouldRevalidateForTags([cartTags.all]);
+```
+
+Spell tags only through catalog builders (a typo silently matches nothing). Syntax: dot-separated segments, optional `:id`, `.*` wildcard is subscriber-only. Helpers: `tagGroup`, `tagImplications`, `matchesTag`, `normalizeTags`, `resolveTags`; `shouldRevalidateForTags(spec, { ambient, expand })`. An untagged action falls back to default behavior. See `src/lib/revalidation/tags/index.example.test.ts` and details in [POLICIES-AND-TAGS.md](references/POLICIES-AND-TAGS.md).
+
+## Related levers
+
+- Add-to-cart, promo and quantity changes update the basket through `updateBasketResource` and `BasketProvider` (`src/providers/basket.tsx`), so pages rarely need loader re-runs to show the new basket.
+- `useRevalidateOnReturn` (`@/hooks/use-revalidate-on-return`) refreshes stale data when the shopper returns to the tab or page.
+- Modals and drawers mount lazily; a quick-view that both loads product data and submits add-to-cart widens the active set and triggers it. Keep its fetcher unmounted until open and consider moving the submit elsewhere.
+- Leave `shouldRevalidate` gates on root-level session, site and config loaders conservative: the root policy defaults to revalidate.
+
+## Finding more
+
+`docs/README-REVALIDATION.md`, `docs/README-DATA.md`, `docs/README-STATE.md` and `AGENTS.md` in your project. `b2c docs search "revalidation"` or the `docs_search` MCP tool for product docs.
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - loaders, actions, fetchers
+- `storefront-next:sfnext-performance` - review checklist (revalidation scope section)
+- `storefront-next:sfnext-state-management` - providers that make a re-run unnecessary
+- `storefront-next:sfnext-routing` - route files that export policies
+- `storefront-next:sfnext-testing` - tests for policies

package/content/guidance/storefront-next/sfnext-revalidation/references/POLICIES-AND-TAGS.md

@@ -0,0 +1,55 @@
+# Policies and tags reference
+
+## Policy inputs
+
+`shouldRevalidate` receives `currentUrl`, `nextUrl`, `formMethod`, `formAction`, `actionStatus`, `actionResult` and `defaultShouldRevalidate`.
+
+- Action submissions have `formMethod` other than GET. Resolve the target with `getActionPath(formAction, currentUrl.origin)` from `@/lib/revalidation/routes/shared`, then compare to `resourceRoutes` values.
+- A navigation has no non-GET `formMethod`. Compare pathname and the search params the loader consumes.
+- `useRevalidator().revalidate()` arrives with `defaultShouldRevalidate` true and no `formMethod`; return `defaultShouldRevalidate` for that case so explicit refreshes work.
+- Treat any 2xx `actionStatus` as success, not only 200.
+
+## Decision table
+
+| Situation | Policy |
+|---|---|
+| Loader reads only data no action changes (navigation menu) | `return false` |
+| Loader reads URL filters | skip when only those params change; the navigation re-runs it with new params |
+| Expensive loader, few relevant writes | allowlist (suppress by default), as in `product.ts` |
+| Cheap loader, few irrelevant writes | denylist, as in `root.ts` |
+| Resource fetcher backing a provider | opt in when `actionResult` carries its payload (`basket.basketId`) |
+| Many routes depend on one data domain | tags |
+
+## Modals and drawers
+
+Lazy modals and drawers join the active set only after opening. List each modal as potential target (loads a resource fetcher on open) and trigger (submits an action). Fix by gating the fetcher-owning route, or by not mounting the loading component until needed.
+
+## Tags
+
+Primitives (`src/lib/revalidation/tags/index.ts`):
+
+| Export | Role |
+|---|---|
+| `withRevalidateTags(result, tags)` | action: attach `revalidateTags` to the result |
+| `shouldRevalidateForTags(spec, { ambient, expand })` | route: build a `shouldRevalidate`; `spec` is a tag array or `({ params }) => tags` |
+| `tagGroup(tag, deps)` | subscriber: a tag plus the tags it depends on |
+| `tagImplications(map)` | emitter side: expand an emitted tag into implied concrete tags |
+| `matchesTag(pattern, emitted)` | the matcher |
+| `normalizeTags`, `resolveTags` | utilities |
+
+Matching rules: the subscriber's pattern is compared to each emitted tag segment by segment. A trailing `.*` in the pattern matches any deeper tags. A pattern that omits `:id` matches all instances; if both pin an id they must equal. An emitted `*` is a literal segment.
+
+Ambient tags (cross-cutting dimensions such as currency) are appended to every subscription unless you pass `{ ambient: false }`. The default vocabulary is empty; define it per app with `tagImplications` if you need it.
+
+Compose with an extra guard when needed:
+
+```ts
+const byTags = shouldRevalidateForTags(['cart.*']);
+export const shouldRevalidate = (args) => byTags(args) && args.nextUrl.searchParams.get('drawer') === 'open';
+```
+
+Keep tag catalogs small and per domain in `src/lib/revalidation/tags/<domain>.ts`. Test them with the pattern in `index.example.test.ts`.
+
+## Root policy
+
+The root policy (`routes/root.ts`) defaults to revalidate, so avoid adding expensive work to the root loader; put it in a leaf route or stream it. Request-wide state is produced by the middleware chain in `src/root.tsx`.