oxlint-plugin-react-doctor 0.4.2-dev.772385f → 0.4.2-dev.773e235

package/dist/index.js

@@ -719,7 +719,7 @@ const activityWrapsEffectHeavySubtree = defineRule({
 				if (totalEffects === 0) return;
 				context.report({
 					node: openingElement,
-					message: `Every hide & show rebuilds ${effectfulChildren.join(", ")} from scratch because <Activity> wraps them & they use ${totalEffects} effect hook${totalEffects === 1 ? "" : "s"}.`
+					message: `Every hide and show rebuilds ${effectfulChildren.join(", ")} from scratch because <Activity> wraps components with ${totalEffects} effect hook${totalEffects === 1 ? "" : "s"}.`
 				});
 			}
 		};
@@ -1127,10 +1127,55 @@ const flattenJsxName$1 = (node) => {
 //#region src/plugin/utils/is-member-property.ts
 const isMemberProperty = (node, propertyName) => Boolean(node && isNodeOfType(node, "MemberExpression") && isNodeOfType(node.property, "Identifier") && node.property.name === propertyName);
 //#endregion
+//#region src/plugin/constants/nextjs.ts
+const NEXTJS_SOURCE_FILE_EXTENSION_GROUP = "(?:tsx?|jsx?|mts|mjs)";
+const PAGE_FILE_PATTERN = new RegExp(`/page\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+const PAGE_OR_LAYOUT_FILE_PATTERN = new RegExp(`/(page|layout)\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+const INTERNAL_PAGE_PATH_PATTERN = /\/(?:(?:\((?:dashboard|admin|settings|account|internal|manage|console|portal|auth|onboarding|app|ee|protected)\))|(?:dashboard|admin|settings|account|internal|manage|console|portal))\//i;
+const PAGES_DIRECTORY_PATTERN = /\/pages\//;
+const NEXTJS_NAVIGATION_FUNCTIONS = new Set([
+	"redirect",
+	"permanentRedirect",
+	"notFound",
+	"forbidden",
+	"unauthorized"
+]);
+const GOOGLE_FONTS_PATTERN = /fonts\.googleapis\.com/;
+const POLYFILL_SCRIPT_PATTERN = /polyfill\.io|polyfill\.min\.js|cdn\.polyfill/;
+const APP_DIRECTORY_PATTERN = /\/app\//;
+const ROUTE_HANDLER_FILE_PATTERN = new RegExp(`/route\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+const CRON_ROUTE_PATTERN = /\/(?:cron|jobs\/cron)(?:\/|$)/i;
+const MUTATING_ROUTE_SEGMENTS = new Set([
+	"logout",
+	"log-out",
+	"signout",
+	"sign-out",
+	"unsubscribe",
+	"delete",
+	"remove",
+	"revoke",
+	"cancel",
+	"deactivate"
+]);
+const ERROR_BOUNDARY_FILE_PATTERN = new RegExp(`/(error|global-error)\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+const GLOBAL_ERROR_FILE_PATTERN = new RegExp(`/global-error\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+const ROUTE_HANDLER_HTTP_METHODS = new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS",
+	"HEAD"
+]);
+const GOOGLE_ANALYTICS_SCRIPT_PATTERN = /google-analytics\.com|googletagmanager\.com\/gtag/;
+const OG_IMAGE_FILE_PATTERN = new RegExp(`/(opengraph-image|twitter-image)\\d*\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
+//#endregion
 //#region src/plugin/utils/is-nextjs-metadata-image-route-filename.ts
+const METADATA_IMAGE_ROUTE_FILE_PATTERN = new RegExp(`^(opengraph-image|twitter-image|icon|apple-icon)\\d*\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
 const isNextjsMetadataImageRouteFilename = (rawFilename) => {
 	if (!rawFilename) return false;
-	return /^(opengraph-image|twitter-image|icon|apple-icon)\d*\.(jsx?|tsx?)$/.test(path.basename(rawFilename));
+	return METADATA_IMAGE_ROUTE_FILE_PATTERN.test(path.basename(rawFilename));
 };
 //#endregion
 //#region src/plugin/utils/normalize-filename.ts
@@ -1369,12 +1414,12 @@ const objectHasAccessibleChild = (jsxElement, settings) => {
 };
 //#endregion
 //#region src/plugin/rules/a11y/alt-text.ts
-const MISSING_ALT_PROP = "Blind users can't use this image because screen readers skip it without `alt`, so add `alt=\"...\"` (or `alt=\"\"` if decorative).";
-const MISSING_ALT_VALUE = "Blind users can't use this image because its `alt` is empty or invalid, so add a short description (or `alt=\"\"` if decorative).";
-const ARIA_LABEL_VALUE = "Blind users hear nothing here because `aria-label` has no value, so give it a short description.";
-const ARIA_LABELLEDBY_VALUE = "Blind users hear nothing here because `aria-labelledby` has no value, so point it at the id of the text that labels this.";
+const MISSING_ALT_PROP = "Screen reader users cannot access this image without `alt`. Add `alt=\"image_description\"`, or `alt=\"\"` if it is decorative.";
+const MISSING_ALT_VALUE = "Screen reader users cannot access this image because its `alt` is empty or invalid. Add a short description, or `alt=\"\"` if it is decorative.";
+const ARIA_LABEL_VALUE = "Screen reader users hear nothing here because `aria-label` has no value, so give it a short description.";
+const ARIA_LABELLEDBY_VALUE = "Screen reader users hear nothing here because `aria-labelledby` has no value, so point it at the id of the text that labels this.";
 const PREFER_ALT = "Screen readers skip a decorative image more reliably with `alt=\"\"` than `role=\"presentation\"`, so use `alt=\"\"` instead.";
-const MESSAGE_OBJECT = "Blind users can't use this `<object>` because screen readers can't describe it, so add `alt`, `aria-label`, `aria-labelledby`, `title`, or inner fallback text.";
+const MESSAGE_OBJECT = "Screen reader users cannot use this `<object>` because assistive tech cannot describe it, so add `alt`, `aria-label`, `aria-labelledby`, `title`, or inner fallback text.";
 const MESSAGE_AREA = "Blind users can't use this `<area>` of the image map because screen readers can't describe it, so add `alt`, `aria-label`, or `aria-labelledby`.";
 const MESSAGE_INPUT_IMAGE = "Blind users can't use this image button because screen readers can't describe it, so add `alt`, `aria-label`, or `aria-labelledby`.";
 const resolveSettings$52 = (settings) => {
@@ -2703,7 +2748,7 @@ const ABSTRACT_ROLES = new Set([
 const PRESENTATION_ROLES$2 = new Set(["presentation", "none"]);
 //#endregion
 //#region src/plugin/rules/a11y/aria-role.ts
-const buildBaseMessage = (suffix) => `Screen reader users get no help from this \`role\` because it isn't a valid ARIA role, so use a real, non-abstract role.${suffix}`;
+const buildBaseMessage = (suffix) => `This \`role\` is not a valid ARIA role, so assistive tech cannot expose it correctly. Use a real, non-abstract role.${suffix}`;
 const resolveSettings$49 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.ariaRole ?? {} : {};
@@ -2717,7 +2762,7 @@ const ariaRole = defineRule({
 	title: "Invalid ARIA role",
 	tags: ["react-jsx-only"],
 	severity: "error",
-	recommendation: "Use a real, non-abstract ARIA role.",
+	recommendation: "Use a real, non-abstract ARIA role so assistive tech can expose the element correctly.",
 	category: "Accessibility",
 	create: (context) => {
 		const settings = resolveSettings$49(context.settings);
@@ -3512,7 +3557,7 @@ const asyncDeferAwait = defineRule({
 	title: "await before an early-return guard",
 	severity: "warn",
 	tags: ["test-noise"],
-	recommendation: "Move the `await` below the early-return guard so the skip path stays fast",
+	recommendation: "Move the `await` below the early-return guard so the skip path stays fast and avoids unnecessary async work.",
 	create: (context) => {
 		const inspectStatements = (statements) => {
 			for (let statementIndex = 0; statementIndex < statements.length - 1; statementIndex++) {
@@ -3755,7 +3800,7 @@ const autocompleteValid = defineRule({
 	title: "Invalid autocomplete value",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Use a valid autofill token in `autoComplete`.",
+	recommendation: "Use a valid autofill token in `autoComplete` so browsers can fill the right field reliably.",
 	category: "Accessibility",
 	create: (context) => {
 		const settings = resolveSettings$48(context.settings);
@@ -3810,7 +3855,7 @@ const isCreateElementCall = (node) => {
 //#endregion
 //#region src/plugin/rules/react-builtins/button-has-type.ts
 const MISSING_MESSAGE$2 = "Your users can submit the form by accident because a `<button>` with no `type` defaults to submit.";
-const INVALID_MESSAGE = "This button's `type` is invalid.";
+const INVALID_MESSAGE = "This button has an invalid `type`, so the browser may treat it like a submit button.";
 const resolveSettings$47 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.buttonHasType ?? {} : {};
@@ -3851,7 +3896,7 @@ const buttonHasType = defineRule({
 	id: "button-has-type",
 	title: "Button missing explicit type",
 	severity: "warn",
-	recommendation: "Always set a `type` on a `<button>`: `type=\"button\"`, `\"submit\"`, or `\"reset\"`.",
+	recommendation: "Set an explicit button `type` so plain buttons do not submit forms by accident: `type=\"button\"`, `\"submit\"`, or `\"reset\"`.",
 	create: (context) => {
 		const settings = resolveSettings$47(context.settings);
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -3921,7 +3966,7 @@ const buttonHasType = defineRule({
 //#endregion
 //#region src/plugin/rules/react-builtins/checked-requires-onchange-or-readonly.ts
 const MISSING_MESSAGE$1 = "Your users can't toggle this input because `checked` has no `onChange`.";
-const EXCLUSIVE_MESSAGE = "This input behaves unpredictably with both `checked` & `defaultChecked` set.";
+const EXCLUSIVE_MESSAGE = "This input mixes `checked` with `defaultChecked`, so React can't tell whether it is controlled or uncontrolled.";
 const resolveSettings$46 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.checkedRequiresOnchangeOrReadonly ?? {} : {};
@@ -3972,7 +4017,7 @@ const checkedRequiresOnchangeOrReadonly = defineRule({
 	id: "checked-requires-onchange-or-readonly",
 	title: "Checked input without onChange",
 	severity: "warn",
-	recommendation: "Add `onChange` (controlled) or `readOnly` (display-only), or use `defaultChecked` for an uncontrolled checkbox.",
+	recommendation: "Add `onChange`, `readOnly`, or `defaultChecked` so React knows whether the checkbox is editable, display-only, or uncontrolled.",
 	category: "Correctness",
 	create: (context) => {
 		const settings = resolveSettings$46(context.settings);
@@ -4466,7 +4511,7 @@ const noRedundantPaddingAxes = defineRule({
 	severity: "warn",
 	defaultEnabled: false,
 	category: "Architecture",
-	recommendation: "Collapse `px-N py-N` to `p-N` when both sides match. Keep them split only when one side changes at a breakpoint (`py-2 md:py-3`).",
+	recommendation: "Collapse matching padding axes to `p-N` so duplicated classes do not make spacing harder to scan; keep split axes only when breakpoints differ.",
 	create: (context) => ({ JSXAttribute(jsxAttribute) {
 		if (!isNodeOfType(jsxAttribute.name, "JSXIdentifier") || jsxAttribute.name.name !== "className") return;
 		const classNameLiteral = getClassNameLiteral(jsxAttribute);
@@ -4476,7 +4521,7 @@ const noRedundantPaddingAxes = defineRule({
 		if (matchedPairs.length === 0) return;
 		for (const matchedPair of matchedPairs) context.report({
 			node: jsxAttribute,
-			message: `px-${matchedPair.value} & py-${matchedPair.value} are the same.`
+			message: `px-${matchedPair.value} and py-${matchedPair.value} duplicate p-${matchedPair.value}, so the class list is noisier without changing spacing.`
 		});
 	} })
 });
@@ -4490,7 +4535,7 @@ const noRedundantSizeAxes = defineRule({
 	severity: "warn",
 	defaultEnabled: false,
 	category: "Architecture",
-	recommendation: "Collapse `w-N h-N` to `size-N` (Tailwind v3.4+) when both sides match.",
+	recommendation: "Collapse matching width and height to `size-N` so duplicated classes do not make layout harder to scan.",
 	create: (context) => ({ JSXAttribute(jsxAttribute) {
 		if (!isNodeOfType(jsxAttribute.name, "JSXIdentifier") || jsxAttribute.name.name !== "className") return;
 		const classNameLiteral = getClassNameLiteral(jsxAttribute);
@@ -4500,7 +4545,7 @@ const noRedundantSizeAxes = defineRule({
 		if (matchedPairs.length === 0) return;
 		for (const matchedPair of matchedPairs) context.report({
 			node: jsxAttribute,
-			message: `w-${matchedPair.value} & h-${matchedPair.value} are the same.`
+			message: `w-${matchedPair.value} and h-${matchedPair.value} duplicate size-${matchedPair.value}, so the class list is noisier without changing layout.`
 		});
 	} })
 });
@@ -4535,7 +4580,7 @@ const noSpaceOnFlexChildren = defineRule({
 		const spaceValue = spaceMatch[2];
 		context.report({
 			node: jsxAttribute,
-			message: `space-${spaceAxis}-${spaceValue} on a flex or grid parent breaks spacing for your users.`
+			message: `space-${spaceAxis}-${spaceValue} on a flex or grid parent can leave uneven gaps when children hide, wrap, or render in RTL layouts.`
 		});
 	} })
 });
@@ -4548,14 +4593,14 @@ const noThreePeriodEllipsis = defineRule({
 	severity: "warn",
 	defaultEnabled: false,
 	category: "Architecture",
-	recommendation: "Use the real ellipsis \"…\" (or `&hellip;`) instead of three dots. Good for labels like \"Rename…\" and \"Loading…\".",
+	recommendation: "Use the real ellipsis character (\"…\") so UI labels look polished and consistent instead of like three separate periods.",
 	create: (context) => ({ JSXText(jsxTextNode) {
 		const textValue = typeof jsxTextNode.value === "string" ? jsxTextNode.value : "";
 		if (!TRAILING_THREE_PERIOD_ELLIPSIS_PATTERN.test(textValue)) return;
 		if (isInsideExcludedTypographyAncestor(jsxTextNode)) return;
 		context.report({
 			node: jsxTextNode,
-			message: "Three dots (\"...\") look unpolished to your users."
+			message: "Use the real ellipsis character (\"…\") instead of three period characters."
 		});
 	} })
 });
@@ -4617,7 +4662,7 @@ const noVagueButtonLabel = defineRule({
 		if (!VAGUE_BUTTON_LABELS.has(normalizedLabel)) return;
 		context.report({
 			node: jsxElementNode.openingElement ?? jsxElementNode,
-			message: `Screen reader & unsure users can't tell what "${labelText}" does.`
+			message: `Screen reader users may not know what "${labelText}" does. Use a specific action label.`
 		});
 	} })
 });
@@ -5203,10 +5248,10 @@ const effectNeedsCleanup = defineRule({
 		if (usages.length === 0) return;
 		if (effectHasCleanupReturn(callback, usages)) return;
 		const firstUsage = usages[0];
-		const verb = firstUsage.kind === "timer" ? "schedules" : "subscribes via";
+		const resourceKind = firstUsage.kind === "timer" ? "timer" : "subscription";
 		context.report({
 			node,
-			message: `\`${firstUsage.resourceName}(...)\` leaks memory because useEffect ${verb} it but never cleans it up.`
+			message: `\`${firstUsage.resourceName}\` creates a ${resourceKind} in useEffect without returning cleanup. Return a cleanup function so it does not leak after unmount.`
 		});
 	} })
 });
@@ -5854,21 +5899,21 @@ const isOutsideAllFunctions = (symbol) => {
 //#region src/plugin/rules/react-builtins/exhaustive-deps-messages.ts
 const buildMissingDepMessage = (hookName, depName) => `\`${hookName}\` can run with a stale \`${depName}\` & show your users old data.`;
 const buildUnnecessaryDepMessage = (hookName, depName) => `\`${hookName}\` re-runs whenever \`${depName}\` changes even though it never uses it.`;
-const buildDuplicateDepMessage = (hookName, depName) => `\`${hookName}\` lists \`${depName}\` twice in its dependency array.`;
-const buildLiteralDepMessage = (hookName) => `A literal in \`${hookName}\`'s dependency array never changes & does nothing.`;
+const buildDuplicateDepMessage = (hookName, depName) => `\`${hookName}\` lists \`${depName}\` twice, adding dependency-array noise without changing when it runs.`;
+const buildLiteralDepMessage = (hookName) => `A literal in \`${hookName}\`'s dependency array never changes, so it adds noise without protecting against stale values.`;
 const buildRefCurrentDepMessage = (hookName, depName) => `\`${hookName}\` won't re-run when \`${depName}\` changes, since a ref never triggers a redraw.`;
-const buildNonArrayDepsMessage = (hookName) => `\`${hookName}\`'s dependencies can't be checked because its second argument isn't an inline array.`;
+const buildNonArrayDepsMessage = (hookName) => `\`${hookName}\`'s dependencies can't be checked because its second argument isn't an inline array, so stale values can slip through.`;
 const buildMissingDepArrayMessage = (hookName) => `\`${hookName}\` re-runs on every render with no dependency array.`;
 const buildMissingCallbackMessage = (hookName) => `\`${hookName}\` crashes without a function as its first argument.`;
-const buildEffectEventDepMessage = () => `A function from \`useEffectEvent\` is stable & shouldn't sit in the dependency array.`;
-const buildSpreadDepMessage = (hookName) => `\`${hookName}\`'s dependencies can't be checked because of a spread in the array.`;
-const buildComplexDepMessage = (hookName) => `\`${hookName}\`'s dependencies can't be checked because of a complex expression in the array.`;
+const buildEffectEventDepMessage = () => `A function from \`useEffectEvent\` is stable, so listing it adds noise and defeats the event/dependency split.`;
+const buildSpreadDepMessage = (hookName) => `A spread in \`${hookName}\`'s dependency array hides the actual deps, so stale values can slip through.`;
+const buildComplexDepMessage = (hookName) => `A complex expression in \`${hookName}\`'s dependency array hides the real value, so stale values can slip through.`;
 const buildAsyncEffectMessage = (hookName) => `\`${hookName}\` was given an async function, so its cleanup breaks.`;
-const buildUnknownCallbackMessage = (hookName) => `\`${hookName}\`'s dependencies can't be checked because its function is defined elsewhere.`;
+const buildUnknownCallbackMessage = (hookName) => `\`${hookName}\`'s callback is defined elsewhere, so dependencies can't be checked and stale values can slip through.`;
 const buildUnstableDepMessage = (hookName, depName) => `\`${depName}\` is rebuilt every render, so \`${hookName}\` runs every time.`;
 const buildSetStateWithoutDepsMessage = (hookName, setterName) => `\`${hookName}\` calls \`${setterName}\` with no dependency array, so it can loop forever & freeze the component.`;
 const buildRefCleanupMessage = (depName) => `Your cleanup may read the wrong node since the ref \`${depName}\` can change before it runs.`;
-const buildAssignmentMessage = (name) => `Assigning to \`${name}\` inside a hook is thrown away after each render.`;
+const buildAssignmentMessage = (name) => `Assigning to \`${name}\` inside a hook is thrown away after each render, so the next render reads the old value.`;
 //#endregion
 //#region src/plugin/rules/react-builtins/exhaustive-deps-settings.ts
 const resolveExhaustiveDepsSettings = (settings) => {
@@ -6771,13 +6816,13 @@ const flattenJsxName = (name) => {
 	return "";
 };
 const isSupportedJsxName = (name) => isNodeOfType(name, "JSXIdentifier") || isNodeOfType(name, "JSXMemberExpression");
-const buildMessage$24 = (propName, message) => message ?? `Your project blocks the \`${propName}\` prop on this component.`;
+const buildMessage$24 = (propName, message) => message ?? `Your project blocks the \`${propName}\` prop on this component, so this bypasses the component API contract.`;
 const forbidComponentProps = defineRule({
 	id: "forbid-component-props",
-	title: "Forbidden prop on component",
+	title: "Blocked component prop bypasses API contract",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "List the props you want to block per component in the `forbidComponentProps.forbid` setting.",
+	recommendation: "Configure blocked component props so callers cannot bypass the component API contract.",
 	category: "Architecture",
 	create: (context) => {
 		const entries = resolveSettings$43(context.settings).forbid.map(normalizeEntry);
@@ -6808,7 +6853,7 @@ const forbidComponentProps = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/forbid-dom-props.ts
-const buildMessage$23 = (propName, customMessage) => customMessage ?? `Your project blocks the \`${propName}\` prop on plain HTML tags.`;
+const buildMessage$23 = (propName, customMessage) => customMessage ?? `Your project blocks the \`${propName}\` prop on plain HTML tags, so this bypasses the agreed DOM API contract.`;
 const resolveSettings$42 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.forbidDomProps ?? {} : {};
@@ -6826,9 +6871,9 @@ const resolveSettings$42 = (settings) => {
 };
 const forbidDomProps = defineRule({
 	id: "forbid-dom-props",
-	title: "Forbidden DOM prop used",
+	title: "Blocked DOM prop bypasses project contract",
 	severity: "warn",
-	recommendation: "List the HTML props you want to block in the `forbidDomProps.forbid` setting.",
+	recommendation: "Configure blocked DOM props so plain HTML tags stay on the agreed DOM API surface.",
 	category: "Architecture",
 	create: (context) => {
 		const forbidMap = resolveSettings$42(context.settings);
@@ -6889,7 +6934,7 @@ const isReactFunctionCall = (node, expectedCall) => {
 };
 //#endregion
 //#region src/plugin/rules/react-builtins/forbid-elements.ts
-const buildMessage$22 = (element, customHelp) => customHelp ? `Your project blocks \`<${element}>\` here. ${customHelp}` : `Your project blocks \`<${element}>\` here.`;
+const buildMessage$22 = (element, customHelp) => customHelp ? `Your project blocks \`<${element}>\` here. ${customHelp}` : `Your project blocks \`<${element}>\` here, so code stays on the approved UI surface.`;
 const resolveSettings$41 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.forbidElements ?? {} : {};
@@ -6901,9 +6946,9 @@ const resolveSettings$41 = (settings) => {
 const flattenMemberName$1 = flattenCalleeName;
 const forbidElements = defineRule({
 	id: "forbid-elements",
-	title: "Forbidden element used",
+	title: "Blocked element bypasses approved UI primitives",
 	severity: "warn",
-	recommendation: "List the element names you want to block in the `forbidElements.forbid` setting.",
+	recommendation: "Configure blocked elements so code stays on the approved UI primitives.",
 	category: "Architecture",
 	create: (context) => {
 		const forbidMap = resolveSettings$41(context.settings);
@@ -6947,7 +6992,7 @@ const forwardRefUsesRef = defineRule({
 	id: "forward-ref-uses-ref",
 	title: "forwardRef without ref parameter",
 	severity: "warn",
-	recommendation: "Either accept a `ref` parameter, or drop the `forwardRef` wrapper.",
+	recommendation: "Accept the `ref` parameter or drop `forwardRef` so parents are not promised a ref that never reaches the node.",
 	category: "Architecture",
 	create: (context) => ({ CallExpression(node) {
 		if (getCalleeName$1(node) !== "forwardRef") return;
@@ -7008,8 +7053,8 @@ const headingHasContent = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/hook-use-state.ts
-const REQUIRE_DESTRUCTURE_MESSAGE = "This `useState` result is hard to follow.";
-const NAMING_CONVENTION_MESSAGE = "The setter here is hard to spot.";
+const REQUIRE_DESTRUCTURE_MESSAGE = "`useState` should be destructured as `[value, setValue]` so readers can see the state value and setter together.";
+const NAMING_CONVENTION_MESSAGE = "This `useState` setter does not match its value name, so updates are harder to trace.";
 const resolveSettings$39 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { allowDestructuredState: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.hookUseState ?? {} : {}).allowDestructuredState ?? false };
@@ -7034,7 +7079,7 @@ const hookUseState = defineRule({
 	title: "useState not destructured",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Destructure useState as `const [thing, setThing] = useState(…)`.",
+	recommendation: "Destructure `useState` as `const [thing, setThing] = useState(…)` so state reads and writes stay visible together.",
 	category: "Architecture",
 	create: (context) => {
 		const { allowDestructuredState } = resolveSettings$39(context.settings);
@@ -7112,7 +7157,7 @@ const HOOKS_WITH_DEP_ARRAY = new Set([
 	"useMemo",
 	"useImperativeHandle"
 ]);
-const NAN_MESSAGE = "`NaN` in a dependency array silently breaks your hook, since React never sees it change.";
+const NAN_MESSAGE = "`NaN` in a dependency array never compares as changed with `Object.is`, so normalize the value before passing it as a dependency.";
 const isNanLiteral = (node) => {
 	if (isNodeOfType(node, "Identifier") && node.name === "NaN") return true;
 	if (isNodeOfType(node, "MemberExpression") && !node.computed && isNodeOfType(node.object, "Identifier") && node.object.name === "Number" && isNodeOfType(node.property, "Identifier") && node.property.name === "NaN") return true;
@@ -7415,7 +7460,7 @@ const htmlNoNestedInteractive = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/a11y/iframe-has-title.ts
-const MESSAGE$43 = "Blind users can't tell what this `<iframe>` holds because screen readers have no title to read, so add a `title` describing its content.";
+const MESSAGE$43 = "Screen reader users cannot identify this `<iframe>` because it has no title. Add a `title` that describes its content.";
 const evaluateTitleValue = (value) => {
 	if (!value) return "missing";
 	if (isNodeOfType(value, "Literal")) {
@@ -7445,7 +7490,7 @@ const iframeHasTitle = defineRule({
 	title: "iframe missing title",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Add a descriptive `title` to every `<iframe>`.",
+	recommendation: "Add a descriptive `title` so screen reader users know what the embedded frame contains.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const tag = getElementType(node, context.settings);
@@ -7513,7 +7558,7 @@ const iframeMissingSandbox = defineRule({
 	id: "iframe-missing-sandbox",
 	title: "iframe missing sandbox attribute",
 	severity: "warn",
-	recommendation: "Add `sandbox=\"\"` (or a curated value) to your iframe.",
+	recommendation: "Add `sandbox=\"\"` or a curated value so embedded pages cannot get full access to your site by default.",
 	category: "Security",
 	create: (context) => ({
 		JSXOpeningElement(node) {
@@ -7721,7 +7766,7 @@ const interactiveSupportsFocus = defineRule({
 	title: "Interactive element not focusable",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Add `tabIndex` to elements with interactive roles and handlers.",
+	recommendation: "Add keyboard focus support so users can reach interactive elements without a pointer.",
 	category: "Accessibility",
 	create: (context) => {
 		const settings = resolveSettings$36(context.settings);
@@ -8539,7 +8584,7 @@ const jsHoistRegexp = defineRule({
 	create: (context) => createLoopAwareVisitors({ NewExpression(node) {
 		if (isNodeOfType(node.callee, "Identifier") && node.callee.name === "RegExp") context.report({
 			node,
-			message: "This slows the loop because new RegExp() rebuilds the pattern every pass, so move it to a constant outside the loop"
+			message: "`new RegExp()` rebuilds the pattern on every loop pass. Move it to a constant outside the loop."
 		});
 	} })
 });
@@ -8913,7 +8958,7 @@ const jsSetMapLookups = defineRule({
 		if (isIndexedArrayElementWithStringArgument(node.callee.object, node.arguments?.[0])) return;
 		context.report({
 			node,
-			message: `This gets slow because array.${methodName}() inside a loop scans the whole list every time, so use a Set for instant lookups`
+			message: `This scales poorly because \`array.${methodName}()\` inside a loop scans the whole list every time. Use a Set for constant-time lookups.`
 		});
 	} })
 });
@@ -8937,9 +8982,9 @@ const jsTosortedImmutable = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/jsx-boolean-value.ts
-const NEVER_MESSAGE$2 = () => `This prop is written inconsistently.`;
-const ALWAYS_MESSAGE$2 = () => `This prop is written inconsistently.`;
-const FALSE_OMITTED_MESSAGE = (attributeName) => `\`${attributeName}={false}\` does nothing.`;
+const NEVER_MESSAGE$2 = () => "This boolean prop style disagrees with the project setting, so equivalent true props are harder to scan consistently.";
+const ALWAYS_MESSAGE$2 = () => "This boolean prop style disagrees with the project setting, so equivalent true props are harder to scan consistently.";
+const FALSE_OMITTED_MESSAGE = (attributeName) => `\`${attributeName}={false}\` does nothing, so the explicit false value adds noise without changing output.`;
 const resolveSettings$35 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.jsxBooleanValue ?? {} : {};
@@ -8955,7 +9000,7 @@ const jsxBooleanValue = defineRule({
 	title: "Inconsistent boolean prop notation",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pick a single boolean-attribute style across the codebase (default: omit `={true}`).",
+	recommendation: "Use one boolean-attribute style so equivalent true props scan the same across the codebase.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$35(context.settings);
@@ -9009,8 +9054,8 @@ const jsxBooleanValue = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/jsx-curly-brace-presence.ts
-const UNNECESSARY_BRACES_MESSAGE = "These curly braces do nothing here.";
-const REQUIRED_BRACES_MESSAGE = "This value needs curly braces `{ }` to read as an expression.";
+const UNNECESSARY_BRACES_MESSAGE = "These curly braces wrap a literal value, so they add JSX noise without changing output.";
+const REQUIRED_BRACES_MESSAGE = "This JSX value needs `{ }` so React reads it as an expression instead of text.";
 const isAllowedMode = (value) => value === "always" || value === "never" || value === "ignore";
 const resolveSettings$34 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
@@ -9105,7 +9150,7 @@ const jsxCurlyBracePresence = defineRule({
 	title: "Unnecessary curly braces in JSX",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pick a consistent quoting style for JSX literal values.",
+	recommendation: "Use one JSX literal style so equivalent markup scans the same without extra JSX noise.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$34(context.settings);
@@ -9189,8 +9234,8 @@ const containsJsxElement = (root) => {
 };
 //#endregion
 //#region src/plugin/rules/react-builtins/jsx-filename-extension.ts
-const JSX_NOT_ALLOWED = (extension) => `This file has JSX but a \`${extension}\` name.`;
-const EXTENSION_ONLY_FOR_JSX = (extension) => `\`${extension}\` files are meant for JSX, but this one has none.`;
+const JSX_NOT_ALLOWED = (extension) => `This file contains JSX but uses a \`${extension}\` name, so the filename no longer signals JSX to readers or tooling conventions.`;
+const EXTENSION_ONLY_FOR_JSX = (extension) => `\`${extension}\` files are reserved for JSX here, so using that extension without JSX makes file-type conventions less useful.`;
 const resolveSettings$33 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.jsxFilenameExtension ?? {} : {};
@@ -9210,7 +9255,7 @@ const jsxFilenameExtension = defineRule({
 	title: "JSX in disallowed file extension",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Name files with JSX `.jsx` or `.tsx`, or whatever extension your project uses.",
+	recommendation: "Name JSX files with the configured extension so file names accurately signal which files contain JSX.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$33(context.settings);
@@ -9265,8 +9310,8 @@ const isJsxFragmentElement = (node) => {
 };
 //#endregion
 //#region src/plugin/rules/react-builtins/jsx-fragments.ts
-const SYNTAX_MESSAGE = "This fragment is written inconsistently.";
-const ELEMENT_MESSAGE = "This fragment is written inconsistently.";
+const SYNTAX_MESSAGE = "`<React.Fragment>` is used where shorthand fragments are configured, so similar wrappers look different across the codebase.";
+const ELEMENT_MESSAGE = "Fragment shorthand is used where explicit fragments are configured, so similar wrappers look different across the codebase.";
 const resolveSettings$32 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { mode: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.jsxFragments ?? {} : {}).mode ?? "syntax" };
@@ -9276,7 +9321,7 @@ const jsxFragments = defineRule({
 	title: "Inconsistent fragment syntax",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pick one fragment style across the codebase.",
+	recommendation: "Use one fragment style so identical wrappers do not look different across files.",
 	category: "Architecture",
 	create: (context) => {
 		const { mode } = resolveSettings$32(context.settings);
@@ -9304,8 +9349,8 @@ const jsxFragments = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/jsx-handler-names.ts
-const buildHandlerNameMessage = (handlerName, propKey) => `The handler "${handlerName}" for "${propKey}" is hard to recognize.`;
-const buildHandlerPropMessage = (propKey, propValue) => `The prop "${propKey}" passes a handler "${propValue}".`;
+const buildHandlerNameMessage = (handlerName, propKey) => `The handler "${handlerName}" does not match the "${propKey}" event prop convention, so readers cannot trace event flow quickly.`;
+const buildHandlerPropMessage = (propKey, propValue) => `The prop "${propKey}" passes handler "${propValue}" but is not named like an event prop, so callers cannot tell it fires an event.`;
 const DEFAULT_HANDLER_PREFIX = "handle";
 const DEFAULT_HANDLER_PROP_PREFIX = "on";
 const splitPrefixes = (prefixes) => prefixes.split("|").map((token) => token.trim()).filter((token) => token.length > 0);
@@ -9396,7 +9441,7 @@ const jsxHandlerNames = defineRule({
 	title: "Inconsistent event handler names",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Use the `on…` prefix for event-handler props and `handle…` for handlers.",
+	recommendation: "Use the `on…` prefix for event-handler props and `handle…` for handlers so readers can trace event flow.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$31(context.settings);
@@ -9630,7 +9675,7 @@ const jsxKey = defineRule({
 	id: "jsx-key",
 	title: "Missing key in list",
 	severity: "error",
-	recommendation: "Add a `key={...}` prop to each element produced inside `.map` / array literal.",
+	recommendation: "Add a stable `key` prop so React can keep list items matched to the right data when the list changes.",
 	create: (context) => {
 		const settings = resolveSettings$30(context.settings);
 		return {
@@ -9796,7 +9841,7 @@ const jsxNoCommentTextnodes = defineRule({
 	id: "jsx-no-comment-textnodes",
 	title: "Comment rendered as JSX text",
 	severity: "warn",
-	recommendation: "Wrap JSX comments in `{/* … */}` so they're parsed as comments, not children.",
+	recommendation: "Wrap JSX comments in `{/* … */}` so users do not see comment text rendered as children.",
 	create: (context) => ({ JSXText(node) {
 		if (!hasCommentLikePattern(node.value)) return;
 		if (isInsideLiteralTextTag(node)) return;
@@ -9903,7 +9948,7 @@ const jsxNoConstructedContextValues = defineRule({
 	tags: ["react-jsx-only"],
 	severity: "warn",
 	disabledBy: ["react-compiler"],
-	recommendation: "Wrap the context value in `useMemo`, or move it outside the component.",
+	recommendation: "Wrap the context value in `useMemo` or move it outside the component so consumers do not redraw every render.",
 	category: "Performance",
 	create: (context) => {
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -9944,7 +9989,7 @@ const jsxNoDuplicateProps = defineRule({
 	id: "jsx-no-duplicate-props",
 	title: "Duplicate props on element",
 	severity: "error",
-	recommendation: "Remove or rename one of the duplicate props.",
+	recommendation: "Remove or rename one of the duplicate props so the later value does not silently override the earlier one.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const seenPropNames = /* @__PURE__ */ new Set();
 		for (const attribute of node.attributes) {
@@ -10261,7 +10306,7 @@ const jsxNoJsxAsProp = defineRule({
 	tags: ["react-jsx-only"],
 	severity: "warn",
 	disabledBy: ["react-compiler"],
-	recommendation: "Move the JSX outside the component, or wrap it in `useMemo`.",
+	recommendation: "Move the JSX outside the component or wrap it in `useMemo` so memoized children do not redraw every render.",
 	category: "Performance",
 	create: (context) => {
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -10633,7 +10678,7 @@ const jsxNoNewArrayAsProp = defineRule({
 	tags: ["react-jsx-only"],
 	severity: "warn",
 	disabledBy: ["react-compiler"],
-	recommendation: "Wrap the array in `useMemo`, or move it outside the component.",
+	recommendation: "Wrap the array in `useMemo` or move it outside the component so memoized children do not redraw every render.",
 	category: "Performance",
 	create: (context) => {
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -11096,7 +11141,7 @@ const jsxNoNewFunctionAsProp = defineRule({
 	tags: ["react-jsx-only"],
 	severity: "warn",
 	disabledBy: ["react-compiler"],
-	recommendation: "Wrap the callback in `useCallback`, or move it outside the component.",
+	recommendation: "Wrap the callback in `useCallback` or move it outside the component so memoized children do not redraw every render.",
 	category: "Performance",
 	create: (context) => {
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -11403,7 +11448,7 @@ const jsxNoNewObjectAsProp = defineRule({
 	tags: ["react-jsx-only"],
 	severity: "warn",
 	disabledBy: ["react-compiler"],
-	recommendation: "Wrap the object in `useMemo`, or move it outside the component.",
+	recommendation: "Wrap the object in `useMemo` or move it outside the component so memoized children do not redraw every render.",
 	category: "Performance",
 	create: (context) => {
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -11463,7 +11508,7 @@ const jsxNoScriptUrl = defineRule({
 	id: "jsx-no-script-url",
 	title: "javascript: URL in JSX",
 	severity: "error",
-	recommendation: "Replace `javascript:` URLs with `onClick` or `onSubmit` handlers. React 19 blocks them anyway.",
+	recommendation: "Use real event handlers instead of `javascript:` URLs so injected URL text cannot execute as code.",
 	category: "Security",
 	create: (context) => {
 		const options = resolveSettings$28(context.settings);
@@ -11514,7 +11559,7 @@ const jsxNoUndef = defineRule({
 	id: "jsx-no-undef",
 	title: "Undefined JSX component",
 	severity: "error",
-	recommendation: "Import the component or check for typos.",
+	recommendation: "Import the component or fix the typo so React can resolve the JSX identifier at runtime.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const rootIdentifier = getRootIdentifier(node.name);
 		if (!rootIdentifier) return;
@@ -11706,7 +11751,7 @@ const jsxPascalCase = defineRule({
 	severity: "warn",
 	defaultEnabled: false,
 	tags: ["test-noise"],
-	recommendation: "Rename custom JSX components to PascalCase.",
+	recommendation: "Rename custom JSX components to PascalCase so React treats them as components, not intrinsic DOM tags.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$26(context.settings);
@@ -11770,7 +11815,7 @@ const jsxPropsNoSpreadMulti = defineRule({
 	id: "jsx-props-no-spread-multi",
 	title: "Same prop spread multiple times",
 	severity: "warn",
-	recommendation: "Spread the same value at most once per element.",
+	recommendation: "Spread each value at most once so later props cannot silently override earlier props from the same object.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const seenNames = /* @__PURE__ */ new Map();
 		const reportedNames = /* @__PURE__ */ new Set();
@@ -11810,7 +11855,7 @@ const jsxPropsNoSpreading = defineRule({
 	title: "Props spread onto element",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "List each prop explicitly so consumers can see what's being passed.",
+	recommendation: "List each prop explicitly so consumers can see the component API instead of receiving hidden spread props.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$25(context.settings);
@@ -12191,7 +12236,7 @@ const lang = defineRule({
 	title: "Invalid lang attribute value",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Use a valid language code, like `en` or `en-US`.",
+	recommendation: "Use a valid language code like `en` or `en-US` so screen readers choose the right pronunciation rules.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (getElementType(node, context.settings) !== "html") return;
@@ -12218,7 +12263,7 @@ const lang = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/a11y/media-has-caption.ts
-const MESSAGE$32 = "Deaf & hard-of-hearing users miss this media without captions, so add a `<track kind=\"captions\">` inside the `<audio>` or `<video>`.";
+const MESSAGE$32 = "Deaf and hard-of-hearing users need captions for this media. Add a `<track kind=\"captions\">` inside the `<audio>` or `<video>`.";
 const DEFAULT_AUDIO = ["audio"];
 const DEFAULT_VIDEO = ["video"];
 const DEFAULT_TRACK = ["track"];
@@ -12401,49 +12446,6 @@ const nextjsAsyncClientComponent = defineRule({
 	}
 });
 //#endregion
-//#region src/plugin/constants/nextjs.ts
-const PAGE_FILE_PATTERN = /\/page\.(tsx?|jsx?)$/;
-const PAGE_OR_LAYOUT_FILE_PATTERN = /\/(page|layout)\.(tsx?|jsx?)$/;
-const INTERNAL_PAGE_PATH_PATTERN = /\/(?:(?:\((?:dashboard|admin|settings|account|internal|manage|console|portal|auth|onboarding|app|ee|protected)\))|(?:dashboard|admin|settings|account|internal|manage|console|portal))\//i;
-const PAGES_DIRECTORY_PATTERN = /\/pages\//;
-const NEXTJS_NAVIGATION_FUNCTIONS = new Set([
-	"redirect",
-	"permanentRedirect",
-	"notFound",
-	"forbidden",
-	"unauthorized"
-]);
-const GOOGLE_FONTS_PATTERN = /fonts\.googleapis\.com/;
-const POLYFILL_SCRIPT_PATTERN = /polyfill\.io|polyfill\.min\.js|cdn\.polyfill/;
-const APP_DIRECTORY_PATTERN = /\/app\//;
-const ROUTE_HANDLER_FILE_PATTERN = /\/route\.(tsx?|jsx?)$/;
-const CRON_ROUTE_PATTERN = /\/(?:cron|jobs\/cron)(?:\/|$)/i;
-const MUTATING_ROUTE_SEGMENTS = new Set([
-	"logout",
-	"log-out",
-	"signout",
-	"sign-out",
-	"unsubscribe",
-	"delete",
-	"remove",
-	"revoke",
-	"cancel",
-	"deactivate"
-]);
-const ERROR_BOUNDARY_FILE_PATTERN = /\/(error|global-error)\.(tsx?|jsx?)$/;
-const GLOBAL_ERROR_FILE_PATTERN = /\/global-error\.(tsx?|jsx?)$/;
-const ROUTE_HANDLER_HTTP_METHODS = new Set([
-	"GET",
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE",
-	"OPTIONS",
-	"HEAD"
-]);
-const GOOGLE_ANALYTICS_SCRIPT_PATTERN = /google-analytics\.com|googletagmanager\.com\/gtag/;
-const OG_IMAGE_FILE_PATTERN = /\/(opengraph-image|twitter-image)\d*\.(tsx?|jsx?)$/;
-//#endregion
 //#region src/plugin/rules/nextjs/nextjs-error-boundary-missing-use-client.ts
 const nextjsErrorBoundaryMissingUseClient = defineRule({
 	id: "nextjs-error-boundary-missing-use-client",
@@ -12503,11 +12505,11 @@ const hasJsxAttribute = (attributes, attributeName) => Boolean(findJsxAttribute(
 //#region src/plugin/rules/nextjs/nextjs-image-missing-sizes.ts
 const nextjsImageMissingSizes = defineRule({
 	id: "nextjs-image-missing-sizes",
-	title: "Image fill missing sizes",
+	title: "next/image fill image is missing sizes",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Add sizes for responsive behavior: `sizes=\"(max-width: 768px) 100vw, 50vw\"` matching your layout breakpoints",
+	recommendation: "Add `sizes` matching your layout so `next/image` does not assume the largest candidate and make users download oversized images.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier") || node.name.name !== "Image") return;
 		const attributes = node.attributes ?? [];
@@ -12543,11 +12545,11 @@ const nextjsInlineScriptMissingId = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-missing-metadata.ts
 const nextjsMissingMetadata = defineRule({
 	id: "nextjs-missing-metadata",
-	title: "Page missing metadata",
+	title: "Page missing metadata for search previews",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Add `export const metadata = { title: '...', description: '...' }` or `export async function generateMetadata()`",
+	recommendation: "Add metadata or `generateMetadata()` so search engines and social previews get a title and description.",
 	create: (context) => ({ Program(programNode) {
 		const filename = normalizeFilename$1(context.filename ?? "");
 		if (!PAGE_FILE_PATTERN.test(filename)) return;
@@ -12560,7 +12562,7 @@ const nextjsMissingMetadata = defineRule({
 			return false;
 		})) context.report({
 			node: programNode,
-			message: "This page has no metadata, so search engines & social previews get no title or description."
+			message: "This page has no metadata, so search engines and social previews get no title or description."
 		});
 	} })
 });
@@ -12568,7 +12570,7 @@ const nextjsMissingMetadata = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-no-a-element.ts
 const nextjsNoAElement = defineRule({
 	id: "nextjs-no-a-element",
-	title: "Plain anchor for internal link",
+	title: "Plain anchor reloads internal Next.js links",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
@@ -12582,7 +12584,7 @@ const nextjsNoAElement = defineRule({
 		else if (isNodeOfType(hrefAttribute.value, "JSXExpressionContainer") && isNodeOfType(hrefAttribute.value.expression, "Literal")) hrefValue = hrefAttribute.value.expression.value;
 		if (typeof hrefValue === "string" && hrefValue.startsWith("/")) context.report({
 			node,
-			message: "Plain <a> reloads the whole page on internal links."
+			message: "Plain <a> reloads the whole page for internal links, so Next.js loses client-side navigation and prefetching."
 		});
 	} })
 });
@@ -12667,11 +12669,11 @@ const nextjsNoClientSideRedirect = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-no-css-link.ts
 const nextjsNoCssLink = defineRule({
 	id: "nextjs-no-css-link",
-	title: "Stylesheet loaded via link",
+	title: "Linked stylesheet bypasses Next.js CSS optimization",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Import CSS directly: `import './styles.css'` or use CSS Modules: `import styles from './Button.module.css'`",
+	recommendation: "Import CSS directly or use CSS Modules so Next.js can bundle, order, and optimize the stylesheet.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier") || node.name.name !== "link") return;
 		const attributes = node.attributes ?? [];
@@ -12684,7 +12686,7 @@ const nextjsNoCssLink = defineRule({
 		if (typeof hrefValue === "string" && GOOGLE_FONTS_PATTERN.test(hrefValue)) return;
 		context.report({
 			node,
-			message: "This <link rel=\"stylesheet\"> loads unbundled, unoptimized CSS."
+			message: "This <link rel=\"stylesheet\"> bypasses Next.js CSS handling, so the CSS loads unbundled and unoptimized."
 		});
 	} })
 });
@@ -12708,7 +12710,7 @@ const nextjsNoDefaultExportInRouteHandler = defineRule({
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "error",
-	recommendation: "Replace `export default` with named HTTP method exports: `export async function GET(request) { … }`",
+	recommendation: "Replace `export default` with named HTTP method exports because Next.js ignores default exports in `route.ts`.",
 	create: (context) => {
 		let isAppRouteHandler = false;
 		let programNode = null;
@@ -12795,11 +12797,11 @@ const nextjsNoFontLink = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-no-google-analytics-script.ts
 const nextjsNoGoogleAnalyticsScript = defineRule({
 	id: "nextjs-no-google-analytics-script",
-	title: "Manual Google Analytics script",
+	title: "Manual Google Analytics script blocks optimized loading",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Use `import { GoogleAnalytics } from '@next/third-parties/google'` for automatic optimization & smaller bundles",
+	recommendation: "Use `import { GoogleAnalytics } from '@next/third-parties/google'` for automatic optimization and smaller bundles.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier")) return;
 		if (node.name.name !== "script" && node.name.name !== "Script") return;
@@ -12808,7 +12810,7 @@ const nextjsNoGoogleAnalyticsScript = defineRule({
 		const srcValue = isNodeOfType(srcAttribute.value, "Literal") ? srcAttribute.value.value : null;
 		if (typeof srcValue === "string" && GOOGLE_ANALYTICS_SCRIPT_PATTERN.test(srcValue)) context.report({
 			node,
-			message: "Manual Google Analytics script blocks rendering. Use @next/third-parties for optimal loading strategy."
+			message: "Manual Google Analytics scripts block rendering without Next.js' optimized loading strategy."
 		});
 	} })
 });
@@ -12820,7 +12822,7 @@ const nextjsNoHeadImport = defineRule({
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "error",
-	recommendation: "Use the Metadata API instead. Add `export const metadata = { title: '...' }` or `export async function generateMetadata()`",
+	recommendation: "Use the Metadata API because `next/head` is ignored in the App Router and meta tags will not render.",
 	create: (context) => ({ ImportDeclaration(node) {
 		if (node.source?.value !== "next/head") return;
 		const filename = normalizeFilename$1(context.filename ?? "");
@@ -12835,18 +12837,18 @@ const nextjsNoHeadImport = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-no-img-element.ts
 const nextjsNoImgElement = defineRule({
 	id: "nextjs-no-img-element",
-	title: "Plain img element",
+	title: "Plain img ships unoptimized images",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "`import Image from 'next/image'` for automatic WebP/AVIF, lazy loading, and responsive srcset",
+	recommendation: "Use `next/image` so users get optimized formats, responsive srcsets, and lazy loading instead of oversized image downloads.",
 	create: (context) => {
 		if (isGeneratedImageRenderContext(context)) return {};
 		return { JSXOpeningElement(node) {
 			if (isGeneratedImageRenderContext(context, node)) return;
 			if (isNodeOfType(node.name, "JSXIdentifier") && node.name.name === "img") context.report({
 				node,
-				message: "Plain <img> ships unoptimized, oversized images to your users."
+				message: "Plain <img> ships unoptimized, oversized images."
 			});
 		} };
 	}
@@ -12855,11 +12857,11 @@ const nextjsNoImgElement = defineRule({
 //#region src/plugin/rules/nextjs/nextjs-no-native-script.ts
 const nextjsNoNativeScript = defineRule({
 	id: "nextjs-no-native-script",
-	title: "Plain script tag",
+	title: "Plain script can block Next.js rendering",
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "`import Script from \"next/script\"`. Use `strategy=\"afterInteractive\"` for analytics or `\"lazyOnload\"` for widgets",
+	recommendation: "Use `next/script` with `strategy=\"afterInteractive\"` or `\"lazyOnload\"` so third-party scripts do not block rendering.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier") || node.name.name !== "script") return;
 		const typeAttribute = findJsxAttribute(node.attributes ?? [], "type");
@@ -12867,7 +12869,7 @@ const nextjsNoNativeScript = defineRule({
 		if (typeof typeValue === "string" && !EXECUTABLE_SCRIPT_TYPES.has(typeValue)) return;
 		context.report({
 			node,
-			message: "Plain <script> blocks rendering with no loading strategy."
+			message: "Plain <script> has no Next.js loading strategy, so it can block rendering."
 		});
 	} })
 });
@@ -12900,7 +12902,7 @@ const nextjsNoRedirectInTryCatch = defineRule({
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Move the redirect/notFound call outside the try block, or add `unstable_rethrow(error)` in the catch",
+	recommendation: "Move `redirect()` or `notFound()` outside the try block, or rethrow in `catch`, because these APIs throw control-flow errors that catch blocks swallow.",
 	create: (context) => {
 		let tryCatchDepth = 0;
 		return {
@@ -14051,7 +14053,7 @@ const nextjsNoUseSearchParamsWithoutSuspense = defineRule({
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Wrap the component using useSearchParams: `<Suspense fallback={<Skeleton />}><SearchComponent /></Suspense>`",
+	recommendation: "Wrap the component using `useSearchParams` in `<Suspense>` so the rest of the page can stay statically rendered.",
 	create: (context) => {
 		let isPageOrLayoutFile = false;
 		let hasAncestorLayoutSuspense = false;
@@ -14089,7 +14091,7 @@ const nextjsNoUseSearchParamsWithoutSuspense = defineRule({
 				if (!componentBody || !astContainsUseSearchParams(componentBody)) return;
 				context.report({
 					node,
-					message: `<${node.name.name}> uses useSearchParams() but is not wrapped in a <Suspense> boundary.`
+					message: `<${node.name.name}> uses useSearchParams() outside <Suspense>, so this page falls back to client-side rendering.`
 				});
 			}
 		};
@@ -14103,7 +14105,7 @@ const nextjsNoVercelOgImport = defineRule({
 	tags: ["test-noise"],
 	requires: ["nextjs"],
 	severity: "warn",
-	recommendation: "Use `import { ImageResponse } from \"next/og\"`. The `@vercel/og` package is built into Next.js and should not be imported directly",
+	recommendation: "Use `import { ImageResponse } from \"next/og\"`; do not import `@vercel/og` directly because Next.js already bundles it.",
 	create: (context) => ({ ImportDeclaration(node) {
 		if (node.source?.value !== "@vercel/og") return;
 		context.report({
@@ -14617,7 +14619,7 @@ const noAdjustStateOnPropChange = defineRule({
 			if (getArgsUpstreamRefs(analysis, ref).some((argRef) => isProp(analysis, argRef))) continue;
 			context.report({
 				node: callExpr,
-				message: "Your users briefly see the wrong value when the prop changes."
+				message: "This effect adjusts state after a prop changes, so users briefly see the stale value."
 			});
 		}
 	} })
@@ -14630,7 +14632,7 @@ const noAriaHiddenOnFocusable = defineRule({
 	title: "aria-hidden on focusable element",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Remove `aria-hidden` from focusable elements, or stop them being focusable.",
+	recommendation: "Remove `aria-hidden` from focusable elements, or stop them being focusable, so keyboard users do not land on content screen readers hide.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const ariaHidden = hasJsxPropIgnoreCase(node.attributes, "aria-hidden");
@@ -15174,7 +15176,7 @@ const noArrayIndexKey = defineRule({
 	title: "Array index used as a key",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Use a stable `key` from your data instead of the array index.",
+	recommendation: "Use a stable `key` from your data so reordered items keep the right state and DOM.",
 	category: "Performance",
 	create: (context) => ({
 		JSXOpeningElement(node) {
@@ -15251,7 +15253,7 @@ const noArrayIndexKey = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/a11y/no-autofocus.ts
-const MESSAGE$28 = "Screen reader & keyboard users get disoriented because `autoFocus` jumps focus on load, so remove it and let people choose where to focus.";
+const MESSAGE$28 = "`autoFocus` moves focus on load, which can disrupt screen reader and keyboard users. Remove it and let users choose where to focus.";
 const resolveSettings$21 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { ignoreNonDOM: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.noAutofocus ?? {} : {}).ignoreNonDOM ?? true };
@@ -15485,7 +15487,7 @@ const noCascadingSetState = defineRule({
 	title: "Multiple setState calls in one effect",
 	severity: "warn",
 	tags: ["test-noise"],
-	recommendation: "Combine into useReducer: `const [state, dispatch] = useReducer(reducer, initialState)`",
+	recommendation: "Combine related updates in `useReducer` so one effect does not redraw the screen once per `setState` call.",
 	create: (context) => ({ CallExpression(node) {
 		if (!isHookCall$1(node, EFFECT_HOOK_NAMES$1)) return;
 		if (isInitOnlyEffect(node)) return;
@@ -15531,12 +15533,12 @@ const noChainStateUpdates = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/no-children-prop.ts
-const MESSAGE$27 = "Your component can render the wrong children when you pass them through a `children` prop.";
+const MESSAGE$27 = "A `children` prop can override or hide nested children, so the component may render different content than the JSX shows.";
 const noChildrenProp = defineRule({
 	id: "no-children-prop",
 	title: "Children passed as a prop",
 	severity: "warn",
-	recommendation: "Nest children between the tags instead of passing a `children` prop.",
+	recommendation: "Nest children between the tags so the rendered content is visible in JSX and cannot be hidden inside a props object.",
 	create: (context) => ({
 		JSXAttribute(node) {
 			if (!isNodeOfType(node.name, "JSXIdentifier")) return;
@@ -15564,13 +15566,13 @@ const noChildrenProp = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/no-clone-element.ts
-const MESSAGE$26 = "`React.cloneElement` breaks easily when the cloned element's props change.";
+const MESSAGE$26 = "`React.cloneElement` couples the parent to the child's prop shape, so child prop changes can silently break injected behavior.";
 const noCloneElement = defineRule({
 	id: "no-clone-element",
-	title: "Use of cloneElement",
+	title: "cloneElement makes child props fragile",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pass children, render props, or use `Children.map` instead of cloning elements.",
+	recommendation: "Pass children or render props instead so parent code does not depend on fragile cloned child props.",
 	category: "Architecture",
 	create: (context) => ({ CallExpression(node) {
 		const callee = stripParenExpression(node.callee);
@@ -15802,7 +15804,7 @@ const noCreateStoreInRender = defineRule({
 	title: "Store created during render",
 	severity: "error",
 	category: "Correctness",
-	recommendation: "Create the store, atom, or observable at the top level of the file, not inside a component or hook.",
+	recommendation: "Create stores at module scope so subscribers are not cut off and saved state does not reset every render.",
 	create: (context) => ({ CallExpression(node) {
 		const factory = resolveStoreFactoryForCallee(node.callee);
 		if (!factory) return;
@@ -15818,10 +15820,10 @@ const noCreateStoreInRender = defineRule({
 const MESSAGE$24 = "`dangerouslySetInnerHTML` is an XSS hole that runs attacker-controlled HTML in your users' browsers.";
 const noDanger = defineRule({
 	id: "no-danger",
-	title: "Use of dangerouslySetInnerHTML",
+	title: "Raw HTML injection can run unsafe markup",
 	severity: "warn",
 	category: "Security",
-	recommendation: "Render trusted content as React children rather than injecting raw HTML.",
+	recommendation: "Render trusted content as React children so attacker-controlled HTML cannot run in users' browsers.",
 	create: (context) => ({
 		JSXOpeningElement(node) {
 			const propAttribute = hasJsxProp(node.attributes, "dangerouslySetInnerHTML");
@@ -15907,7 +15909,7 @@ const noDangerWithChildren = defineRule({
 	id: "no-danger-with-children",
 	title: "dangerouslySetInnerHTML with children",
 	severity: "error",
-	recommendation: "Use either `children` or `dangerouslySetInnerHTML`, never both.",
+	recommendation: "Use either `children` or `dangerouslySetInnerHTML` so React does not ignore one source of content.",
 	category: "Correctness",
 	create: (context) => ({
 		JSXElement(node) {
@@ -16066,7 +16068,7 @@ const noDarkModeGlow = defineRule({
 		if (!hasDarkBackground || !shadowValue || !shadowProperty) return;
 		if (hasColoredGlowShadow(shadowValue)) context.report({
 			node: shadowProperty,
-			message: "Your users see a cheap, overdone colored glow on the dark background, so use a subtle, neutral shadow instead."
+			message: "A strong colored glow on a dark background can feel heavy. Use a subtle, neutral shadow instead."
 		});
 	} })
 });
@@ -16442,7 +16444,7 @@ const noDerivedUseState = defineRule({
 	title: "Prop derived into useState",
 	tags: ["test-noise"],
 	severity: "warn",
-	recommendation: "Remove useState and compute the value inline: `const value = transform(propName)`",
+	recommendation: "Compute the value inline so prop changes do not leave `useState` holding a stale copy.",
 	create: (context) => {
 		const propStackTracker = createComponentPropStackTracker();
 		return {
@@ -16534,7 +16536,7 @@ const noDidMountSetState = defineRule({
 //#endregion
 //#region src/plugin/rules/react-builtins/no-did-update-set-state.ts
 const LIFECYCLE_NAMES$1 = new Set(["componentDidUpdate"]);
-const MESSAGE$21 = "This can loop forever & freeze the component.";
+const MESSAGE$21 = "Calling setState in componentDidUpdate can trigger another update immediately, loop forever, and freeze the component.";
 const resolveSettings$19 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { mode: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.noDidUpdateSetState ?? {} : {}).mode ?? "allowed" };
@@ -16774,7 +16776,7 @@ const noDistractingElements = defineRule({
 	title: "Distracting marquee or blink element",
 	tags: ["react-jsx-only"],
 	severity: "error",
-	recommendation: "Replace `<marquee>` and `<blink>` with normal, accessible markup.",
+	recommendation: "Replace `<marquee>` and `<blink>` with normal markup so motion does not distract or disorient users.",
 	category: "Accessibility",
 	create: (context) => {
 		const { distractingTags } = resolveSettings$18(context.settings);
@@ -16803,7 +16805,7 @@ const noDocumentStartViewTransition = defineRule({
 		if (!isNodeOfType(callee.property, "Identifier") || callee.property.name !== "startViewTransition") return;
 		context.report({
 			node,
-			message: "Your users lose React's <ViewTransition> animations when document.startViewTransition() runs directly."
+			message: "Calling `document.startViewTransition()` directly can bypass React's `<ViewTransition>` animation lifecycle."
 		});
 	} })
 });
@@ -16821,13 +16823,13 @@ const noDynamicImportPath = defineRule({
 			if (source && !isNodeOfType(source, "Literal") && !isNodeOfType(source, "TemplateLiteral")) {
 				context.report({
 					node,
-					message: "This ships in the main bundle & slows page load, since the bundler can't code-split a dynamic import path. Use a plain string path instead."
+					message: "This can stay in the main bundle because the bundler cannot code-split a dynamic import path. Use a plain string path instead."
 				});
 				return;
 			}
 			if (isNodeOfType(source, "TemplateLiteral") && (source.expressions?.length ?? 0) > 0) context.report({
 				node,
-				message: "This ships in the main bundle & slows page load, since the bundler can't code-split a dynamic import path. Use a plain string path instead of one with `${...}`."
+				message: "This can stay in the main bundle because the bundler cannot code-split a dynamic import path with `${dynamic_path}`. Use a plain string path instead."
 			});
 		},
 		CallExpression(node) {
@@ -17118,7 +17120,7 @@ const noEffectEventHandler = defineRule({
 	title: "Effect used as an event handler",
 	tags: ["test-noise"],
 	severity: "warn",
-	recommendation: "Move the conditional logic into onClick, onChange, or onSubmit handlers directly",
+	recommendation: "Move event logic into the handler that starts it so the side effect does not run late after an extra render.",
 	create: (context) => {
 		const propStackTracker = createComponentPropStackTracker();
 		return {
@@ -17295,7 +17297,7 @@ const noEffectWithFreshDeps = defineRule({
 //#region src/plugin/rules/security/no-eval.ts
 const noEval = defineRule({
 	id: "no-eval",
-	title: "Use of eval()",
+	title: "eval() runs untrusted code strings",
 	severity: "error",
 	recommendation: "Use `JSON.parse` for data, or rewrite the code so it doesn't build and run code from strings.",
 	create: (context) => ({
@@ -18168,14 +18170,14 @@ const noFetchInEffect = defineRule({
 	id: "no-fetch-in-effect",
 	title: "Data fetching inside an effect",
 	severity: "warn",
-	recommendation: "Use `useQuery()` from @tanstack/react-query, `useSWR()`, or fetch in a Server Component instead",
+	recommendation: "Use a data-fetching layer or Server Component so fetches do not race, double-fire, or leak from `useEffect`.",
 	create: (context) => ({ CallExpression(node) {
 		if (!isHookCall$1(node, EFFECT_HOOK_NAMES$1)) return;
 		const callback = getEffectCallback(node);
 		if (!callback) return;
 		if (containsFetchCall(callback)) context.report({
 			node,
-			message: "fetch() inside useEffect races, double-fires & leaks for your users."
+			message: "fetch() inside useEffect can race, double-fire, or leak. Use a data-fetching layer or Server Component instead."
 		});
 	} })
 });
@@ -18189,9 +18191,9 @@ const ALLOWED_NAMESPACES = new Set([
 const MESSAGE$19 = "`findDOMNode` crashes your app in React 19 because it was removed.";
 const noFindDomNode = defineRule({
 	id: "no-find-dom-node",
-	title: "Use of findDOMNode",
+	title: "findDOMNode breaks component encapsulation",
 	severity: "warn",
-	recommendation: "Use a ref (`useRef` or `createRef`) to reach DOM nodes instead of `findDOMNode`.",
+	recommendation: "Use a ref to reach DOM nodes because `findDOMNode` was removed in React 19 and can crash the app.",
 	create: (context) => ({ CallExpression(node) {
 		const callee = node.callee;
 		if (isNodeOfType(callee, "Identifier") && callee.name === "findDOMNode") {
@@ -18228,7 +18230,7 @@ const noFlushSync = defineRule({
 			if (!isNodeOfType(specifier, "ImportSpecifier")) continue;
 			if (getImportedName$1(specifier) === "flushSync") context.report({
 				node: specifier,
-				message: "Your users lose View Transitions & concurrent rendering when flushSync from react-dom forces an immediate update."
+				message: "`flushSync` forces an immediate update, which skips View Transitions and concurrent rendering."
 			});
 		}
 	} })
@@ -18332,10 +18334,10 @@ const functionContainsReactRenderOutput = (functionNode, scopes) => containsRend
 //#region src/plugin/rules/architecture/no-giant-component.ts
 const noGiantComponent = defineRule({
 	id: "no-giant-component",
-	title: "Component is too large",
+	title: "Large component is hard to read and change",
 	severity: "warn",
 	tags: ["test-noise", "react-jsx-only"],
-	recommendation: "Pull each section into its own component, like `<UserHeader />` and `<UserActions />`.",
+	recommendation: "Pull each section into its own component so the parent is easier to read, test, and change.",
 	create: (context) => {
 		const getOversizedComponentLineCount = (bodyNode) => {
 			if (!bodyNode.loc) return null;
@@ -18573,11 +18575,11 @@ const noInlineBounceEasing = defineRule({
 				if (!value) continue;
 				if ((key === "transition" || key === "transitionTimingFunction" || key === "animation" || key === "animationTimingFunction") && isOvershootCubicBezier(value)) context.report({
 					node: property,
-					message: "Your users see a dated, bouncy animation, so use ease-out or cubic-bezier(0.16, 1, 0.3, 1) for a smooth finish."
+					message: "This bouncy easing can feel distracting. Use ease-out or cubic-bezier(0.16, 1, 0.3, 1) for a smoother finish."
 				});
 				if ((key === "animation" || key === "animationName") && hasBounceAnimationName(value)) context.report({
 					node: property,
-					message: "Your users see a tacky bounce animation, so use a smooth ease-out (like ease-out-quart or expo) for a natural finish."
+					message: "This bounce animation can feel distracting. Use a smooth ease-out, like ease-out-quart or expo, for a natural finish."
 				});
 			}
 		},
@@ -18595,7 +18597,7 @@ const noInlineBounceEasing = defineRule({
 //#region src/plugin/rules/design/no-inline-exhaustive-style.ts
 const noInlineExhaustiveStyle = defineRule({
 	id: "no-inline-exhaustive-style",
-	title: "Too many inline style properties",
+	title: "Large inline style object rebuilds every render",
 	severity: "warn",
 	tags: ["test-noise", "react-jsx-only"],
 	recommendation: "Move the styles to a CSS class, CSS module, Tailwind utilities, or a styled component. Big inline objects are hard to read and rebuild on every update.",
@@ -18715,7 +18717,7 @@ const noInteractiveElementToNoninteractiveRole = defineRule({
 //#region src/plugin/rules/react-builtins/no-is-mounted.ts
 const noIsMounted = defineRule({
 	id: "no-is-mounted",
-	title: "Use of isMounted",
+	title: "isMounted lets async callbacks update after unmount",
 	severity: "warn",
 	recommendation: "`isMounted` doesn't work in modern React. Track mount state with a ref, or cancel the async work instead.",
 	create: (context) => ({ CallExpression(node) {
@@ -18727,7 +18729,7 @@ const noIsMounted = defineRule({
 			if (ancestor.type === "MethodDefinition" || ancestor.type === "Property") {
 				context.report({
 					node,
-					message: "`isMounted` is unreliable in modern React & leads to bugs."
+					message: "`isMounted` is unreliable in modern React, so async callbacks can update state after unmount."
 				});
 				return;
 			}
@@ -18832,7 +18834,7 @@ const noLargeAnimatedBlur = defineRule({
 			const blurRadius = Number.parseFloat(match[1]);
 			if (blurRadius > 10) context.report({
 				node: property,
-				message: `This can run out of GPU memory on phones because blur(${blurRadius}px) gets heavier as the blur & element grow, so use a smaller blur or a smaller element`
+				message: `Large animated blurs can use significant GPU memory on phones because blur(${blurRadius}px) gets heavier as the blur and element grow. Use a smaller blur or a smaller element.`
 			});
 		}
 	} })
@@ -19076,10 +19078,10 @@ const collectBooleanLikePropsFromBody = (componentBody, propsParamName) => {
 };
 const noManyBooleanProps = defineRule({
 	id: "no-many-boolean-props",
-	title: "Too many boolean props",
+	title: "Boolean prop combinations are hard to test",
 	severity: "warn",
 	tags: ["test-noise", "react-jsx-only"],
-	recommendation: "Split into smaller components or named variants, like `<Button.Primary />` and `<DialogConfirm />`, instead of stacking `isPrimary` and `isConfirm` flags.",
+	recommendation: "Split boolean-heavy APIs into smaller components or named variants so combinations stay testable.",
 	create: (context) => {
 		const reportIfMany = (booleanLikePropNames, componentName, reportNode) => {
 			if (booleanLikePropNames.length >= 4) context.report({
@@ -19210,7 +19212,7 @@ const noMoment = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/no-multi-comp.ts
-const MESSAGE$17 = "This file is harder to navigate with more than one component.";
+const MESSAGE$17 = "This file declares several components, so each component is harder to find, test, and change.";
 const resolveSettings$16 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { ignoreStateless: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.noMultiComp ?? {} : {}).ignoreStateless ?? false };
@@ -19507,7 +19509,7 @@ const noMultiComp = defineRule({
 	id: "no-multi-comp",
 	title: "Multiple components in one file",
 	severity: "warn",
-	recommendation: "Move secondary components into their own files.",
+	recommendation: "Move secondary components into their own files so each component stays easier to find, test, and change.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$16(context.settings);
@@ -19587,11 +19589,11 @@ const noMutableInDeps = defineRule({
 					if (!issue) continue;
 					if (issue.kind === "ref-current") context.report({
 						node: element,
-						message: `Your effect silently never re-runs on "${issue.rootName}.current" because changing a ref doesn't redraw the screen.`
+						message: `Changing "${issue.rootName}.current" does not re-render the component, so this dependency will not make the effect run again.`
 					});
 					else context.report({
 						node: element,
-						message: `Your effect silently never re-runs on "${issue.rootName}.*" because values like \`location.pathname\` can change without redrawing the screen.`
+						message: `Values like "${issue.rootName}.*" can change without re-rendering the component, so this dependency will not make the effect run again.`
 					});
 				}
 			});
@@ -20022,7 +20024,7 @@ const noNamespace = defineRule({
 	id: "no-namespace",
 	title: "Namespaced JSX element",
 	severity: "warn",
-	recommendation: "Drop the namespace and use a plain (Pascal-cased) component or DOM tag.",
+	recommendation: "Use a plain component or DOM tag because React cannot render JSX namespaced names like `ns:Foo`.",
 	create: (context) => ({
 		JSXOpeningElement(node) {
 			if (!isNodeOfType(node.name, "JSXNamespacedName")) return;
@@ -20054,7 +20056,7 @@ const noNestedComponentDefinition = defineRule({
 	tags: ["test-noise", "react-jsx-only"],
 	severity: "error",
 	category: "Correctness",
-	recommendation: "Move to a separate file or to module scope above the parent component",
+	recommendation: "Move it to module scope or a separate file so React does not recreate the component and erase its state on every parent render.",
 	create: (context) => {
 		const componentStack = [];
 		return {
@@ -20119,7 +20121,7 @@ const noNoninteractiveElementInteractions = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/a11y/no-noninteractive-element-to-interactive-role.ts
-const buildMessage$11 = (tag, role) => `Screen reader users get confused because role \`${role}\` makes \`<${tag}>\` act interactive when it isn't, so use a real interactive element instead.`;
+const buildMessage$11 = (tag, role) => `Role \`${role}\` gives \`<${tag}>\` interactive semantics even though the element is noninteractive, so screen reader users get the wrong controls.`;
 const DEFAULT_ALLOWED_ROLES = {
 	ul: [
 		"menu",
@@ -20958,13 +20960,13 @@ const noRandomKey = defineRule({
 		if (!freshDescription) return;
 		context.report({
 			node: node.value,
-			message: `Your users lose typed input, focus & scroll position because \`key={${freshDescription}}\` makes a new key every render, so React rebuilds every item. Use a stable id from the item.`
+			message: `A changing key makes React rebuild each item, which can reset typed input, focus, and scroll position. Use a stable id from the item instead of \`key={${freshDescription}}\`.`
 		});
 	} })
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/no-react-children.ts
-const MESSAGE$14 = "`React.Children` breaks easily when the children change shape.";
+const MESSAGE$14 = "`React.Children` traversal depends on the runtime child shape, so wrapping or unwrapping a child can silently change what gets visited.";
 const isChildrenIdentifier = (node, contextNode) => {
 	if (!isNodeOfType(node, "Identifier") || node.name !== "Children") return false;
 	return isImportedFromModule(contextNode, "Children", "react");
@@ -20978,10 +20980,10 @@ const isReactNamespaceMember = (node, contextNode) => {
 };
 const noReactChildren = defineRule({
 	id: "no-react-children",
-	title: "Use of React.Children",
+	title: "React.Children is fragile when child shape changes",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pass children as props or render them directly instead of using React.Children.",
+	recommendation: "Pass children as explicit props or render them directly so child shape changes do not break traversal logic.",
 	category: "Architecture",
 	create: (context) => ({ CallExpression(node) {
 		const calleeOuter = stripParenExpression(node.callee);
@@ -21079,7 +21081,7 @@ const reportTestUtilsImports = (node, context) => {
 };
 const noReactDomDeprecatedApis = defineRule({
 	id: "no-react-dom-deprecated-apis",
-	title: "Deprecated react-dom APIs",
+	title: "Deprecated react-dom APIs break in React 19",
 	requires: ["react:18"],
 	tags: ["test-noise", "migration-hint"],
 	severity: "warn",
@@ -21096,7 +21098,7 @@ const noReactDomDeprecatedApis = defineRule({
 });
 const noReact19DeprecatedApis = defineRule({
 	id: "no-react19-deprecated-apis",
-	title: "Deprecated React 19 APIs",
+	title: "React 19 API migration can break callers",
 	requires: ["react:19"],
 	tags: ["test-noise", "migration-hint"],
 	severity: "warn",
@@ -21204,7 +21206,7 @@ const noRedundantRoles = defineRule({
 	title: "Redundant ARIA role",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Remove `role` attributes that match what the element already does.",
+	recommendation: "Remove redundant `role` attributes so assistive tech reads the element's native semantics without extra noise.",
 	category: "Accessibility",
 	create: (context) => {
 		const settings = resolveSettings$13(context.settings);
@@ -21274,7 +21276,7 @@ const noRenderInRender = defineRule({
 	title: "Component rendered by inline function call",
 	severity: "warn",
 	tags: ["test-noise"],
-	recommendation: "Make it a named component, like `const ListItem = ({ item }) => <div>{item.name}</div>`.",
+	recommendation: "Make it a named component so React preserves its identity and does not remount its state.",
 	create: (context) => ({ JSXExpressionContainer(node) {
 		const expression = node.expression;
 		if (!isNodeOfType(expression, "CallExpression")) return;
@@ -21293,7 +21295,7 @@ const noRenderInRender = defineRule({
 const RENDER_PROP_PATTERN = /^render[A-Z]/;
 const noRenderPropChildren = defineRule({
 	id: "no-render-prop-children",
-	title: "Too many render props",
+	title: "Render-prop slots make this component hard to extend",
 	tags: ["test-noise"],
 	severity: "warn",
 	recommendation: "Swap `renderXxx` props for child components like `<Modal.Header>` or plain `children`, so the parent doesn't control every slot.",
@@ -21473,12 +21475,22 @@ const PUBLIC_CLIENT_KEY_PATTERNS = [
 	/^public-token-(?:live|test)-/,
 	/^pk\.eyJ/
 ];
+const SECRET_UNAMBIGUOUS_PLACEHOLDER_VALUE_PATTERNS = [
+	/^[\s._\-*\u2022xX]{8,}$/,
+	/(?:\.{3,}|\u2026|[*\u2022]{3,})/,
+	/(?:^|[_\-\s])(?:your|redacted|masked|placeholder|replace[_\-\s]?me|changeme)(?:$|[_\-\s])/i,
+	/<[^>]*(?:auth|credential|key|password|secret|token|your|redacted|placeholder|masked)[^>]*>/i,
+	/\[[^\]]*(?:auth|credential|key|password|secret|token|your|redacted|placeholder|masked)[^\]]*\]/i,
+	/\{[^}]*(?:auth|credential|key|password|secret|token|your|redacted|placeholder|masked)[^}]*\}/i
+];
+const SECRET_CONTEXTUAL_PLACEHOLDER_VALUE_PATTERNS = [/(?:^|[_\-\s])(?:example|sample|dummy)(?:$|[_\-\s])/i];
+const SECRET_PLACEHOLDER_CONTEXT_PATTERN = /(?:placeholder|example|sample|dummy|masked|redacted|mask)/i;
 const SECRET_VARIABLE_PATTERN = /(?:api_?key|secret|token|password|credential|auth)/i;
 const SECRET_TOOLING_FILE_PATTERN = /(?:^|\/)[^/]+\.config\.[cm]?[jt]s$/;
 const SECRET_TOOLING_RC_FILE_PATTERN = /(?:^|\/)(?:\.[a-z-]+rc|[a-z-]+\.rc)\.[cm]?[jt]s$/;
 const SECRET_TEST_FILE_PATTERN = /(?:^|\/)[^/]+\.(?:test|spec|stories|story|fixture|fixtures)\.[cm]?[jt]sx?$/;
 const SECRET_SERVER_FILE_SUFFIX_PATTERN = /(?:^|\/)[^/]+\.server\.[cm]?[jt]sx?$/;
-const SECRET_SERVER_ENTRY_FILE_PATTERN = /(?:^|\/)(?:middleware|route)\.[cm]?[jt]sx?$/;
+const SECRET_SERVER_ENTRY_FILE_PATTERN = /(?:^|\/)(?:middleware|proxy|route)\.[cm]?[jt]sx?$/;
 const SECRET_NEXT_PAGES_API_FILE_PATTERN = /(?:^|\/)pages\/api\/.+\.[cm]?[jt]sx?$/;
 const SECRET_CLIENT_FILE_SUFFIX_PATTERN = /(?:^|\/)[^/]+\.(?:client|browser|web)\.[cm]?[jt]sx?$/;
 const SECRET_CLIENT_ENTRY_FILE_PATTERN = /(?:^|\/)(?:src\/)?(?:main|index|[Aa]pp|client)\.[cm]?[jt]sx?$/;
@@ -21758,6 +21770,15 @@ const isInsideServerOnlyScope = (node) => {
 	return false;
 };
 //#endregion
+//#region src/plugin/utils/is-placeholder-secret-value.ts
+const isPlaceholderSecretValue = (literalValue, options) => {
+	const trimmedValue = literalValue.trim();
+	if (trimmedValue.length === 0) return false;
+	if (SECRET_UNAMBIGUOUS_PLACEHOLDER_VALUE_PATTERNS.some((pattern) => pattern.test(trimmedValue))) return true;
+	if (!options.allowContextualExamples) return false;
+	return SECRET_CONTEXTUAL_PLACEHOLDER_VALUE_PATTERNS.some((pattern) => pattern.test(trimmedValue));
+};
+//#endregion
 //#region src/plugin/rules/security/no-secrets-in-client-code.ts
 const noSecretsInClientCode = defineRule({
 	id: "no-secrets-in-client-code",
@@ -21786,21 +21807,28 @@ const noSecretsInClientCode = defineRule({
 				if (!isNodeOfType(node.init, "Literal") || typeof node.init.value !== "string") return;
 				const variableName = node.id.name;
 				const literalValue = node.init.value;
+				const componentOrHookName = enclosingComponentOrHookName(node);
+				const hasPlaceholderContext = SECRET_PLACEHOLDER_CONTEXT_PATTERN.test(variableName) || componentOrHookName !== null && SECRET_PLACEHOLDER_CONTEXT_PATTERN.test(componentOrHookName);
+				const isUnambiguousPlaceholderValue = isPlaceholderSecretValue(literalValue, { allowContextualExamples: false });
+				const isPlaceholderValueForVariableHeuristic = isPlaceholderSecretValue(literalValue, { allowContextualExamples: hasPlaceholderContext });
 				if (PUBLIC_CLIENT_KEY_PATTERNS.some((pattern) => pattern.test(literalValue))) return;
+				if (SECRET_PATTERNS.some((pattern) => pattern.test(literalValue))) {
+					if (!isUnambiguousPlaceholderValue) context.report({
+						node,
+						message: "This hardcoded secret is a security vulnerability: it ships to the browser where anyone can read it."
+					});
+					return;
+				}
 				const isServerOnlyScope = isInsideServerOnlyScope(node);
 				const trailingSuffix = getIdentifierTrailingWord(variableName);
 				const isUiConstant = SECRET_FALSE_POSITIVE_SUFFIXES.has(trailingSuffix);
-				if (shouldUseVariableNameHeuristic && !isServerOnlyScope && SECRET_VARIABLE_PATTERN.test(variableName) && !isUiConstant && literalValue.length > 24) {
+				if (shouldUseVariableNameHeuristic && !isServerOnlyScope && SECRET_VARIABLE_PATTERN.test(variableName) && !isUiConstant && !isPlaceholderValueForVariableHeuristic && literalValue.length > 24) {
 					context.report({
 						node,
 						message: `Hardcoding "${variableName}" in client code is a security vulnerability: the secret ships to the browser where anyone can read it.`
 					});
 					return;
 				}
-				if (SECRET_PATTERNS.some((pattern) => pattern.test(literalValue))) context.report({
-					node,
-					message: "This hardcoded secret is a security vulnerability: it ships to the browser where anyone can read it."
-				});
 			}
 		};
 	}
@@ -22143,7 +22171,7 @@ const noSelfUpdatingEffect = defineRule({
 					reportedStateNames.add(stateName);
 					context.report({
 						node: setterCall,
-						message: `${setterCall.callee.name}() loops forever because it sets \`${stateName}\`, the same state this effect watches.`
+						message: `${setterCall.callee.name}() updates \`${stateName}\`, which is also in this effect's dependency list. Guard the update or move the derivation out of the effect.`
 					});
 				}
 			}
@@ -22175,13 +22203,13 @@ const getParentComponent = (node) => {
 };
 //#endregion
 //#region src/plugin/rules/react-builtins/no-set-state.ts
-const MESSAGE$12 = "Your project discourages `this.setState` here.";
+const MESSAGE$12 = "`this.setState` keeps local class state in a project that forbids it, so state ownership becomes harder to reason about.";
 const noSetState = defineRule({
 	id: "no-set-state",
-	title: "Use of this.setState",
+	title: "Local class state forbidden",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Lift state up or use an external store instead of `this.setState`.",
+	recommendation: "Lift state up or use an external store so class-local state does not hide ownership.",
 	category: "Architecture",
 	create: (context) => ({ CallExpression(node) {
 		if (!isNodeOfType(node.callee, "MemberExpression")) return;
@@ -22223,7 +22251,7 @@ const noSetStateInRender = defineRule({
 				const setterIdentifierName = setterCall.callee.name;
 				context.report({
 					node: setterCall,
-					message: `${setterIdentifierName}() loops forever because it runs during render & triggers another render.`
+					message: `${setterIdentifierName}() triggers another render while rendering. Move it to an effect or event handler, or compute the value during render.`
 				});
 			}
 		};
@@ -22457,9 +22485,9 @@ const resolveSettings$11 = (settings) => {
 };
 const noStringRefs = defineRule({
 	id: "no-string-refs",
-	title: "Use of string refs",
+	title: "String refs are legacy and fragile",
 	severity: "warn",
-	recommendation: "Use a callback ref (`ref={(node) => { this.foo = node }}`) or `useRef` instead of string refs.",
+	recommendation: "Use a callback ref or `useRef` so ref ownership is explicit and not tied to legacy string lookup.",
 	create: (context) => {
 		const { noTemplateLiterals = false } = resolveSettings$11(context.settings);
 		const isTestlikeFile = isTestlikeFilename(context.filename);
@@ -22538,7 +22566,7 @@ const noThisInSfc = defineRule({
 	id: "no-this-in-sfc",
 	title: "this used in function component",
 	severity: "warn",
-	recommendation: "Read from the `props` argument instead of `this.props`.",
+	recommendation: "Read from the `props` argument because function components do not have a React instance `this`.",
 	create: (context) => {
 		const configured = (context.settings?.react)?.createClass;
 		const customClassFactoryNames = /* @__PURE__ */ new Set();
@@ -22682,10 +22710,10 @@ const noUncontrolledInput = defineRule({
 				const hasAllowedPartner = VALUE_PARTNER_ATTRIBUTES.some((partnerAttributeName) => findJsxAttribute(attributes, partnerAttributeName));
 				if (isNodeOfType(valueAttribute.value, "JSXExpressionContainer") && isNodeOfType(valueAttribute.value.expression, "Identifier") && undefinedInitialStateNames.has(valueAttribute.value.expression.name)) {
 					const stateName = valueAttribute.value.expression.name;
-					const partnerHint = hasAllowedPartner ? "Give useState a starting value" : "Give useState a starting value & add onChange (or readOnly)";
+					const partnerHint = hasAllowedPartner ? "Give useState a starting value" : "Give useState a starting value and add onChange (or readOnly)";
 					context.report({
 						node: child,
-						message: `Your users hit a console warning & a field that can reset because "${stateName}" starts undefined, so <${tagName} value={${stateName}}> flips from uncontrolled to controlled. ${partnerHint} (e.g. \`useState("")\`).`
+						message: `This can trigger a console warning and reset the field because "${stateName}" starts undefined, so <${tagName} value={${stateName}}> flips from uncontrolled to controlled. ${partnerHint} (e.g. \`useState("")\`).`
 					});
 					return;
 				}
@@ -22747,7 +22775,7 @@ const noUnescapedEntities = defineRule({
 	title: "Unescaped entities in JSX",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Replace bare `'` / `\"` / `>` / `}` characters in JSX text with HTML entities.",
+	recommendation: "Replace bare `'` / `\"` / `>` / `}` characters with HTML entities so literal UI text is encoded consistently.",
 	create: (context) => ({ JSXText(node) {
 		const value = node.value;
 		for (const character of value) if (character in ESCAPED_VERSIONS) {
@@ -23682,7 +23710,7 @@ const noUnknownProperty = defineRule({
 	id: "no-unknown-property",
 	title: "Unknown DOM property",
 	severity: "warn",
-	recommendation: "Use the prop name React expects, like `className`, `htmlFor`, or `tabIndex`.",
+	recommendation: "Use the prop name React expects, like `className`, `htmlFor`, or `tabIndex`, so the attribute is applied correctly.",
 	create: (context) => {
 		const { ignore = [], requireDataLowercase = false } = resolveSettings$10(context.settings);
 		const ignoreSet = new Set(ignore);
@@ -23768,7 +23796,7 @@ const UNSAFE_ALIASES = new Set([
 	"componentWillReceiveProps",
 	"componentWillUpdate"
 ]);
-const buildMessage$6 = (methodName) => `\`${methodName}\` causes subtle bugs & React is removing it.`;
+const buildMessage$6 = (methodName) => `\`${methodName}\` runs during unsafe legacy render timing and is deprecated, so React may double-invoke or remove it.`;
 const resolveSettings$9 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { checkAliases: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.noUnsafe ?? {} : {}).checkAliases ?? false };
@@ -23801,7 +23829,7 @@ const noUnsafe = defineRule({
 	id: "no-unsafe",
 	title: "Unsafe legacy lifecycle method",
 	severity: "warn",
-	recommendation: "Replace `UNSAFE_componentWillMount` / `…WillReceiveProps` / `…WillUpdate` with the modern equivalents.",
+	recommendation: "Move setup to `constructor` or `componentDidMount`, prop-derived state to `getDerivedStateFromProps`, and update side effects to `componentDidUpdate` so React does not rely on deprecated unsafe lifecycles.",
 	create: (context) => {
 		const { checkAliases } = resolveSettings$9(context.settings);
 		const flagsUnsafePrefix = isReactVersionAtLeast(getConfiguredReactMajorMinor(context.settings), 16, 3);
@@ -24057,7 +24085,7 @@ const noUnstableNestedComponents = defineRule({
 	id: "no-unstable-nested-components",
 	title: "Component defined inside a component",
 	severity: "warn",
-	recommendation: "Move nested components to the top of the file. Never define one inside another.",
+	recommendation: "Move nested components to module scope so React does not remount them and lose state on every render.",
 	category: "Performance",
 	create: (context) => {
 		const settings = resolveSettings$8(context.settings);
@@ -24231,7 +24259,7 @@ const noWideLetterSpacing = defineRule({
 //#endregion
 //#region src/plugin/rules/react-builtins/no-will-update-set-state.ts
 const LIFECYCLE_NAMES = new Set(["componentWillUpdate", "UNSAFE_componentWillUpdate"]);
-const MESSAGE$9 = "This can loop forever & freeze the component.";
+const MESSAGE$9 = "Calling setState in componentWillUpdate can trigger another update immediately, loop forever, and freeze the component.";
 const resolveSettings$7 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { mode: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.noWillUpdateSetState ?? {} : {}).mode ?? "allowed" };
@@ -24254,7 +24282,7 @@ const noWillUpdateSetState = defineRule({
 	id: "no-will-update-set-state",
 	title: "setState in componentWillUpdate",
 	severity: "warn",
-	recommendation: "Don't set state in `componentWillUpdate`. Use `getDerivedStateFromProps` or `componentDidUpdate` instead.",
+	recommendation: "Avoid setState in componentWillUpdate because it can loop forever; derive state before render or move guarded updates to componentDidUpdate.",
 	create: (context) => {
 		const { mode } = resolveSettings$7(context.settings);
 		const activeLifecycleNames = isReactBelow16_3(context.settings) ? new Set(["componentWillUpdate"]) : LIFECYCLE_NAMES;
@@ -24288,7 +24316,7 @@ const noZIndex9999 = defineRule({
 				const zValue = getStylePropertyNumberValue(property);
 				if (zValue !== null && Math.abs(zValue) >= 1e3) context.report({
 					node: property,
-					message: `z-index ${zValue} is way too high & usually hides a layering bug instead of fixing it, so use a small set scale, like 1 to 50.`
+					message: `z-index ${zValue} is unusually high and can hide a layering bug instead of fixing it. Use a small set scale, like 1 to 50.`
 				});
 			}
 		},
@@ -24471,12 +24499,12 @@ const UTILITY_FILE_BASENAMES = new Set([
 ]);
 //#endregion
 //#region src/plugin/rules/react-builtins/only-export-components.ts
-const NAMED_EXPORT_MESSAGE = "Fast Refresh stops working when a file exports non-components.";
-const ANONYMOUS_MESSAGE = "Fast Refresh can't track an unnamed component & full-reloads instead.";
-const EXPORT_ALL_MESSAGE = "`export *` hides what's exported, so Fast Refresh stops working.";
-const REACT_CONTEXT_MESSAGE = "Fast Refresh stops working when a file exports a context too.";
-const LOCAL_COMPONENT_MESSAGE = "Fast Refresh skips this component because it isn't exported.";
-const NO_EXPORT_MESSAGE = "Fast Refresh can't track this component because the file exports nothing.";
+const NAMED_EXPORT_MESSAGE = "This file exports non-components, so Fast Refresh can't safely preserve component state.";
+const ANONYMOUS_MESSAGE = "This component is unnamed, so Fast Refresh can't track it and falls back to a full reload.";
+const EXPORT_ALL_MESSAGE = "`export *` hides what's exported, so Fast Refresh can't safely preserve component state.";
+const REACT_CONTEXT_MESSAGE = "This file exports a context with components, so Fast Refresh can't safely preserve component state.";
+const LOCAL_COMPONENT_MESSAGE = "This component is not exported, so Fast Refresh skips it and local edits can full-reload.";
+const NO_EXPORT_MESSAGE = "This file exports nothing, so Fast Refresh can't track the component and local edits can full-reload.";
 const DEFAULT_REACT_HOCS = [
 	"memo",
 	"forwardRef",
@@ -24629,7 +24657,7 @@ const onlyExportComponents = defineRule({
 	id: "only-export-components",
 	title: "Non-component export in component file",
 	severity: "warn",
-	recommendation: "Move non-component exports out of files that export components.",
+	recommendation: "Move non-component exports out of component files so Fast Refresh can preserve component state instead of full-reloading.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$6(context.settings);
@@ -24850,10 +24878,10 @@ const isChildrenMemberExpression = (node) => {
 };
 const preactNoChildrenLength = defineRule({
 	id: "preact-no-children-length",
-	title: "Array methods on props.children",
+	title: "Array methods on Preact children can crash",
 	requires: ["preact"],
 	severity: "warn",
-	recommendation: "Wrap with `toChildArray(children)` from `preact` before accessing array methods or `.length`.",
+	recommendation: "Wrap with `toChildArray(children)` because Preact's `props.children` is not always an array and array methods can crash.",
 	create: (context) => ({ MemberExpression(node) {
 		if (node.computed) return;
 		if (!isNodeOfType(node.property, "Identifier")) return;
@@ -24887,10 +24915,10 @@ const REACT_HOOK_NAMES = new Set([
 const buildMessage$4 = (importedNames) => `Your users hit \`__H\` undefined errors because importing ${importedNames.map((innerName) => `\`${innerName}\``).join(", ")} from \`react\` in a pure-Preact project loads a second copy of the hook state, so import from \`preact/hooks\` (or \`preact/compat\`) instead.`;
 const preactNoReactHooksImport = defineRule({
 	id: "preact-no-react-hooks-import",
-	title: "Hooks imported from react",
+	title: "React hook imports break pure Preact hook state",
 	requires: ["pure-preact"],
 	severity: "warn",
-	recommendation: "Replace `from \"react\"` with `from \"preact/hooks\"` (or `from \"preact/compat\"` if other React API surface is needed).",
+	recommendation: "Import hooks from `preact/hooks` so they share Preact's renderer state instead of loading a second hook implementation.",
 	create: (context) => ({ ImportDeclaration(node) {
 		const source = node.source;
 		if (!isNodeOfType(source, "Literal") || source.value !== "react") return;
@@ -24950,7 +24978,7 @@ const preactNoRenderArguments = defineRule({
 	title: "render() reads props from arguments",
 	requires: ["preact"],
 	severity: "warn",
-	recommendation: "Read state/props from `this.props` / `this.state` inside `render()` instead of declaring positional parameters.",
+	recommendation: "Read from `this.props` and `this.state` because `preact/compat` uses React's parameterless `render()` and positional props/state become undefined.",
 	create: (context) => ({ MethodDefinition(node) {
 		if (!isInstanceMethodNamedRender(node)) return;
 		if (!isInsideEs6Component$1(node)) return;
@@ -24972,7 +25000,7 @@ const preactPreferOndblclick = defineRule({
 	title: "onDoubleClick instead of onDblClick",
 	requires: ["pure-preact"],
 	severity: "warn",
-	recommendation: "Rename the handler from `onDoubleClick` to `onDblClick` to match the DOM event name.",
+	recommendation: "Rename `onDoubleClick` to `onDblClick` because Preact core listens for the DOM `dblclick` event name and `onDoubleClick` never fires.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier")) return;
 		const tagName = node.name.name;
@@ -25044,8 +25072,8 @@ const preferDynamicImport = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/prefer-es6-class.ts
-const ALWAYS_MESSAGE$1 = "`createReactClass` is legacy & adds a dependency.";
-const NEVER_MESSAGE$1 = "This component is defined inconsistently.";
+const ALWAYS_MESSAGE$1 = "`createReactClass` is legacy and adds a dependency, so this component diverges from modern React class syntax.";
+const NEVER_MESSAGE$1 = "This component uses an ES6 class where `createReactClass` is configured, so component style is inconsistent across the codebase.";
 const resolveSettings$5 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	if (typeof reactDoctor !== "object" || reactDoctor === null) return {};
@@ -25056,7 +25084,7 @@ const preferEs6Class = defineRule({
 	title: "createClass instead of ES6 class",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pick one component style for the whole codebase: `class extends React.Component` (default) or `createReactClass` (legacy).",
+	recommendation: "Pick one component style so readers do not have to switch between legacy `createReactClass` patterns and modern class components.",
 	category: "Architecture",
 	create: (context) => {
 		const { mode = "always" } = resolveSettings$5(context.settings);
@@ -25215,7 +25243,7 @@ const preferExplicitVariants = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/prefer-function-component.ts
-const MESSAGE$7 = "This class component is harder to maintain than a function component.";
+const MESSAGE$7 = "This class component keeps behavior in lifecycle methods, so state and effects are harder to follow than in a hook-based function component.";
 const resolveSettings$4 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.preferFunctionComponent ?? {} : {};
@@ -25241,7 +25269,7 @@ const preferFunctionComponent = defineRule({
 	title: "Class component instead of function",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Re-write the class component as a function component using hooks.",
+	recommendation: "Rewrite the class component as a function component so state and effects use modern hook patterns instead of class lifecycles.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$4(context.settings);
@@ -25593,7 +25621,7 @@ const preferTagOverRole = defineRule({
 	title: "Role used instead of HTML tag",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Replace `role` with the matching HTML element when one exists.",
+	recommendation: "Use the matching HTML element when one exists so browsers and assistive tech get native semantics.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const tag = getElementType(node, context.settings);
@@ -25899,7 +25927,7 @@ const preferUseReducer = defineRule({
 	title: "Many related useState calls",
 	tags: ["test-noise"],
 	severity: "warn",
-	recommendation: "Group related state: `const [state, dispatch] = useReducer(reducer, { field1, field2, ... })`",
+	recommendation: "Group related state in `useReducer` so one logical update does not fan out into separate renders.",
 	create: (context) => {
 		const reportExcessiveUseState = (body, componentName) => {
 			if (!isNodeOfType(body, "BlockStatement")) return;
@@ -25931,7 +25959,7 @@ const preferUseReducer = defineRule({
 //#region src/plugin/rules/tanstack-query/query-destructure-result.ts
 const queryDestructureResult = defineRule({
 	id: "query-destructure-result",
-	title: "Destructure TanStack Query result",
+	title: "Whole query result subscribes to every field",
 	tags: ["test-noise"],
 	requires: ["tanstack-query"],
 	severity: "error",
@@ -25984,7 +26012,7 @@ const queryNoQueryInEffect = defineRule({
 	tags: ["test-noise"],
 	requires: ["tanstack-query"],
 	severity: "warn",
-	recommendation: "React Query refetches automatically via queryKey changes and the `enabled` option. A manual refetch() in useEffect is usually unnecessary.",
+	recommendation: "Use `queryKey` changes or `enabled` so React Query schedules the fetch once instead of refetching again from `useEffect`.",
 	create: (context) => ({ CallExpression(node) {
 		if (!isHookCall$1(node, EFFECT_HOOK_NAMES$1)) return;
 		const callback = getEffectCallback(node);
@@ -26307,7 +26335,7 @@ const reduxUseselectorInlineDerivation = defineRule({
 	severity: "warn",
 	category: "Performance",
 	disabledBy: ["react-compiler"],
-	recommendation: "Select the raw slice and derive with `useMemo`, or use `createSelector` from `reselect`.",
+	recommendation: "Select the raw slice and memoize derivation so Redux actions do not rebuild a collection and redraw this component.",
 	create: (context) => {
 		let aliases = /* @__PURE__ */ new Set();
 		return {
@@ -26367,7 +26395,7 @@ const reduxUseselectorReturnsNewCollection = defineRule({
 	severity: "warn",
 	category: "Performance",
 	disabledBy: ["react-compiler"],
-	recommendation: "Return a primitive, split into multiple useSelector calls, or pass `shallowEqual` from `react-redux` as the second argument.",
+	recommendation: "Return a stable selected value, split selectors, or pass `shallowEqual` so every Redux action does not redraw this component.",
 	create: (context) => {
 		let aliases = /* @__PURE__ */ new Set();
 		return {
@@ -26393,7 +26421,7 @@ const renderingAnimateSvgWrapper = defineRule({
 	title: "Animating an SVG directly",
 	tags: ["test-noise"],
 	severity: "warn",
-	recommendation: "Wrap the SVG: `<motion.div animate={...}><svg>...</svg></motion.div>`",
+	recommendation: "Wrap the SVG in a motion element so animation props apply to a stable wrapper instead of the SVG node itself.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		if (!isNodeOfType(node.name, "JSXIdentifier") || node.name.name !== "svg") return;
 		if (node.attributes?.some((attribute) => isNodeOfType(attribute, "JSXAttribute") && isNodeOfType(attribute.name, "JSXIdentifier") && MOTION_ANIMATE_PROPS.has(attribute.name.name))) context.report({
@@ -26543,7 +26571,7 @@ const renderingHydrationMismatchTime = defineRule({
 			if (hasSuppressHydrationWarningAttribute(findOpeningElementOfChild(node))) return;
 			context.report({
 				node,
-				message: `This breaks hydration because ${matched.display} in JSX gives a different value on the server than in the browser, so move it into useEffect+useState to run only in the browser, or add suppressHydrationWarning to the parent if it's on purpose`
+				message: `This can cause a hydration mismatch because ${matched.display} in JSX gives a different value on the server than in the browser. Move it into useEffect+useState to run only in the browser, or add suppressHydrationWarning to the parent if it's on purpose.`
 			});
 			return;
 		}
@@ -26552,7 +26580,7 @@ const renderingHydrationMismatchTime = defineRule({
 				if (hasSuppressHydrationWarningAttribute(findOpeningElementOfChild(node))) return;
 				context.report({
 					node: child,
-					message: `This breaks hydration because ${pattern.display} reached from JSX gives a different value on the server than in the browser, so move it into useEffect+useState to run only in the browser, or add suppressHydrationWarning to the parent if it's on purpose`
+					message: `This can cause a hydration mismatch because ${pattern.display} reached from JSX gives a different value on the server than in the browser. Move it into useEffect+useState to run only in the browser, or add suppressHydrationWarning to the parent if it's on purpose.`
 				});
 				return;
 			}
@@ -26831,7 +26859,7 @@ const requireRenderReturn = defineRule({
 	id: "require-render-return",
 	title: "Render method does not return",
 	severity: "error",
-	recommendation: "Return JSX from your component's `render` method.",
+	recommendation: "Return JSX or `null` from `render` so the component intentionally shows something or nothing.",
 	create: (context) => {
 		const checkFunction = (functionNode) => {
 			const host = resolveRenderHost(functionNode);
@@ -27153,7 +27181,7 @@ const rerenderLazyRefInit = defineRule({
 	tags: ["test-noise"],
 	severity: "warn",
 	category: "Performance",
-	recommendation: "Set it up only once: `const ref = useRef<T | null>(null); if (ref.current === null) ref.current = expensiveCall();`",
+	recommendation: "Initialize the ref lazily so expensive values are not rebuilt and discarded on every render.",
 	create: (context) => ({ CallExpression(node) {
 		if (!isHookCall$1(node, "useRef") || !node.arguments?.length) return;
 		const initializer = node.arguments[0];
@@ -27180,7 +27208,7 @@ const rerenderLazyStateInit = defineRule({
 	tags: ["test-noise"],
 	severity: "warn",
 	category: "Performance",
-	recommendation: "Wrap in an arrow function so it only runs once: `useState(() => expensiveComputation())`",
+	recommendation: "Wrap expensive initial state in an arrow function so the initializer does not rerun and get thrown away on every render.",
 	create: (context) => ({ CallExpression(node) {
 		if (!isHookCall$1(node, "useState") || !node.arguments?.length) return;
 		const initializer = node.arguments[0];
@@ -27463,7 +27491,7 @@ const rerenderTransitionsScroll = defineRule({
 		}
 		context.report({
 			node: setStateCall,
-			message: `This causes jank because setState in a "${eventName}" handler redraws the screen many times a second, so wrap it in startTransition, use useDeferredValue, or keep the value in a ref & throttle with requestAnimationFrame`
+			message: `This can make scrolling stutter because setState in a "${eventName}" handler redraws on every event. Wrap it in startTransition, use useDeferredValue, or keep the value in a ref and throttle with requestAnimationFrame.`
 		});
 	} })
 });
@@ -27483,7 +27511,7 @@ const rnAnimateLayoutProperty = defineRetiredRule({
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
-	recommendation: "Reanimated useAnimatedStyle runs on the UI thread; layout-affecting properties driven by animation helpers, interpolate, or shared values are valid."
+	recommendation: "Retired: Reanimated `useAnimatedStyle` can safely drive layout-affecting properties on the UI thread, so this pattern should not be flagged."
 });
 //#endregion
 //#region src/plugin/rules/react-native/rn-animation-reaction-as-derived.ts
@@ -27514,7 +27542,7 @@ const rnAnimationReactionAsDerived = defineRule({
 		if (!isValueAssignment && !isSetCall) return;
 		context.report({
 			node,
-			message: "Your users can see a stale value when this useAnimatedReaction only copies one value to another."
+			message: "This useAnimatedReaction only copies one shared value into another, so it can miss Reanimated's derived-value dependency tracking."
 		});
 	} })
 });
@@ -27531,17 +27559,17 @@ const JS_BOTTOM_SHEET_PACKAGES = new Set([
 ]);
 const rnBottomSheetPreferNative = defineRule({
 	id: "rn-bottom-sheet-prefer-native",
-	title: "JS bottom sheet over native Modal",
+	title: "JS bottom sheet misses native sheet behavior",
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
-	recommendation: "On RN v7+, use `<Modal presentationStyle=\"formSheet\">` for native gestures and snap points.",
+	recommendation: "On RN v7+, use `<Modal presentationStyle=\"formSheet\">` so the sheet uses platform-native gestures, detents, accessibility, and presentation behavior.",
 	create: (context) => ({ ImportDeclaration(node) {
 		const source = node.source?.value;
 		if (typeof source !== "string" || !JS_BOTTOM_SHEET_PACKAGES.has(source)) return;
 		context.report({
 			node,
-			message: `Your users feel a less native bottom sheet with ${source}.`
+			message: `Users get JS-driven sheet gestures and presentation with ${source}, instead of the platform-native formSheet behavior.`
 		});
 	} })
 });
@@ -27627,13 +27655,13 @@ const rnDetoxMissingAwait = defineRule({
 			if (root.calleeName === "waitFor") {
 				context.report({
 					node,
-					message: "This Detox `waitFor(...)` chain isn't awaited. Prepend `await`."
+					message: "This Detox `waitFor` chain isn't awaited, so the test can continue before the condition settles. Prepend `await`."
 				});
 				return;
 			}
 			if (root.calleeName === "expect" && isDetoxExpectSubject(root.rootCall)) context.report({
 				node,
-				message: "This Detox `expect(element(...))` assertion isn't awaited. Prepend `await`."
+				message: "This Detox `expect(element)` assertion isn't awaited, so the test can pass or fail before the assertion settles. Prepend `await`."
 			});
 		} };
 	}
@@ -28264,7 +28292,7 @@ const rnNoLegacyExpoPackages = defineRule({
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
-	recommendation: "These Expo packages are no longer maintained. Switch to the recommended replacement package.",
+	recommendation: "Switch to the maintained replacement package so users are not stuck with unfixed bugs in deprecated Expo packages.",
 	create: (context) => ({ ImportDeclaration(node) {
 		const source = node.source?.value;
 		if (typeof source !== "string") return;
@@ -28346,7 +28374,7 @@ const rnNoNonNativeNavigator = defineRule({
 		if (!NON_NATIVE_NAVIGATOR_PACKAGES.get(source)) return;
 		context.report({
 			node,
-			message: `Your users feel less native transitions when ${source} uses a JS navigator.`
+			message: `Users get JS-driven transitions and gestures from ${source}, instead of platform-native navigation behavior.`
 		});
 	} })
 });
@@ -28652,7 +28680,7 @@ const collectReturnedJsxElements = (expression) => {
 };
 const rnNoRenderitemKey = defineRule({
 	id: "rn-no-renderitem-key",
-	title: "Useless key on renderItem JSX",
+	title: "renderItem key is ignored by React Native lists",
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
@@ -28793,7 +28821,7 @@ const rnNoSetNativeProps = defineRule({
 //#region src/plugin/rules/react-native/rn-no-single-element-style-array.ts
 const rnNoSingleElementStyleArray = defineRule({
 	id: "rn-no-single-element-style-array",
-	title: "Single-element style array",
+	title: "Single-element style array adds wasted allocation",
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
@@ -28816,11 +28844,11 @@ const rnNoSingleElementStyleArray = defineRule({
 //#region src/plugin/rules/react-native/rn-prefer-content-inset-adjustment.ts
 const rnPreferContentInsetAdjustment = defineRetiredRule({
 	id: "rn-prefer-content-inset-adjustment",
-	title: "Manual safe-area inset adjustment",
+	title: "Manual safe-area insets can duplicate offsets",
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
-	recommendation: "Prefer native content inset adjustment only when it replaces manual inset plumbing; SafeAreaView wrappers are valid and intentionally ignored."
+	recommendation: "Retired: SafeAreaView wrappers are valid; prefer native content inset adjustment only when manual inset plumbing causes scroll jumps or duplicated safe-area offsets."
 });
 //#endregion
 //#region src/react-native-dependency-names.ts
@@ -29005,7 +29033,7 @@ const rnPreferPressable = defineRule({
 	tags: ["test-noise"],
 	requires: ["react-native"],
 	severity: "warn",
-	recommendation: "Use `<Pressable>` from react-native (or react-native-gesture-handler) instead of the old Touchable* components.",
+	recommendation: "Use `<Pressable>` because Touchable* components are frozen and lack Pressable's state-based feedback and accessibility behavior.",
 	create: (context) => ({ ImportDeclaration(node) {
 		const source = node.source?.value;
 		if (typeof source !== "string" || !TOUCHABLE_SOURCES.has(source)) return;
@@ -29441,7 +29469,7 @@ const roleHasRequiredAriaProps = defineRule({
 	title: "Role missing required ARIA props",
 	tags: ["react-jsx-only"],
 	severity: "error",
-	recommendation: "Add every required `aria-*` attribute when you set an interactive role.",
+	recommendation: "Add every required `aria-*` attribute so assistive tech can expose the role's state correctly.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const roleAttribute = hasJsxPropIgnoreCase(node.attributes, "role");
@@ -32687,16 +32715,16 @@ const roleSupportsAriaProps = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/rules-of-hooks.ts
-const buildTopLevelMessage = (hookName) => `\`${hookName}\` crashes at the top level of a file.`;
-const buildNonComponentMessage = (hookName, functionName) => `\`${hookName}\` crashes inside \`${functionName}\` because it isn't a component or a hook.`;
-const buildConditionalMessage = (hookName) => `\`${hookName}\` crashes when you call it conditionally.`;
-const buildLoopMessage = (hookName) => `\`${hookName}\` crashes when you call it inside a loop.`;
-const buildAsyncMessage = (hookName) => `\`${hookName}\` crashes inside an async function.`;
-const buildClassComponentMessage = (hookName) => `\`${hookName}\` crashes in a class component.`;
-const buildTryMessage = (hookName) => `\`${hookName}\` crashes inside a try/catch/finally block.`;
+const buildTopLevelMessage = (hookName) => `\`${hookName}\` can only run inside a React component or custom Hook because React needs that render scope to track Hook state.`;
+const buildNonComponentMessage = (hookName, functionName) => `\`${hookName}\` runs inside \`${functionName}\`, which is not a component or Hook, so React cannot attach Hook state to a render.`;
+const buildConditionalMessage = (hookName) => `\`${hookName}\` changes Hook order between renders when called conditionally, so React can attach state to the wrong Hook.`;
+const buildLoopMessage = (hookName) => `\`${hookName}\` can run a different number of times inside a loop, so React can attach state to the wrong Hook.`;
+const buildAsyncMessage = (hookName) => `\`${hookName}\` runs inside an async function, so React cannot guarantee the same Hook order during render.`;
+const buildClassComponentMessage = (hookName) => `\`${hookName}\` cannot run in a class component because Hooks require a function component or custom Hook render scope.`;
+const buildTryMessage = (hookName) => `\`${hookName}\` can be skipped by try/catch/finally control flow, so React can attach state to the wrong Hook.`;
 const buildEffectEventCallMessage = (bindingName) => `\`${bindingName}\` comes from useEffectEvent, so it only works when called from Effects in the same component.`;
 const buildEffectEventAssignmentMessage = (bindingName) => `${buildEffectEventCallMessage(bindingName)} It also breaks if saved in a variable or passed around.`;
-const buildEffectEventPassedDownMessage = () => `A function from useEffectEvent breaks when passed around.`;
+const buildEffectEventPassedDownMessage = () => `A function from useEffectEvent only works inside Effects in the same component, so passing it around breaks the event/dependency split.`;
 const ASCII_UPPERCASE_A = 65;
 const ASCII_UPPERCASE_Z = 90;
 const EFFECT_HOOK_NAMES = new Set([
@@ -32949,7 +32977,7 @@ const rulesOfHooks = defineRule({
 	title: "Hook called conditionally",
 	severity: "error",
 	tags: ["test-noise"],
-	recommendation: "Call hooks at the top level of a React function component or a custom Hook.",
+	recommendation: "Call hooks at the top level of a React function component or custom Hook so React sees the same hook order on every render.",
 	category: "Correctness",
 	create: (context) => {
 		const settings = resolveSettings$3(context.settings);
@@ -33077,13 +33105,13 @@ const rulesOfHooks = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/a11y/scope.ts
-const MESSAGE$3 = "Screen reader users get no help from `scope` here because it only works on `<th>` cells, so remove it.";
+const MESSAGE$3 = "The `scope` attribute only works on `<th>` cells, so screen readers get no table-header help from it here.";
 const scope = defineRule({
 	id: "scope",
 	title: "scope attribute on non-th element",
 	tags: ["react-jsx-only"],
 	severity: "warn",
-	recommendation: "Only use `scope` on `<th>` cells.",
+	recommendation: "Remove `scope` from this element or move it to the related `<th>` cell.",
 	category: "Accessibility",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const scopeAttribute = hasJsxProp(node.attributes, "scope");
@@ -33098,7 +33126,7 @@ const scope = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/self-closing-comp.ts
-const MESSAGE$2 = "This tag has no children.";
+const MESSAGE$2 = "This tag has no children, so the closing tag adds noise without changing output.";
 const resolveSettings$2 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	const ruleSettings = typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.selfClosingComp ?? {} : {};
@@ -33117,7 +33145,7 @@ const selfClosingComp = defineRule({
 	title: "Element not self-closing",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Use the self-closing form `<X />` for elements with no children.",
+	recommendation: "Use `<X />` for childless elements so empty closing tags do not add noise.",
 	category: "Architecture",
 	create: (context) => {
 		const settings = resolveSettings$2(context.settings);
@@ -33314,9 +33342,9 @@ const getCandidateFromDefaultDeclaration = (node) => {
 };
 const serverAuthActions = defineRule({
 	id: "server-auth-actions",
-	title: "Server action without auth check",
+	title: "Unauthenticated server action can be called directly",
 	severity: "error",
-	recommendation: "Add `const session = await auth()` at the top, and throw or redirect if the user isn't allowed before touching any data.",
+	recommendation: "Check auth before touching data because exported server actions can be called directly by unauthenticated clients.",
 	create: (context) => {
 		let fileHasUseServerDirective = false;
 		const customAuthFunctionNames = getReactDoctorStringArraySetting(context.settings, "serverAuthFunctionNames");
@@ -33454,7 +33482,7 @@ const objectExpressionHasNextRevalidate = (objectExpression) => {
 	}
 	return false;
 };
-const APP_ROUTER_FILE_PATTERN = /\/app\/(?:[^/]+\/)*(?:route|page|layout|template|loading|error|default)\.(?:tsx?|jsx?)$/;
+const APP_ROUTER_FILE_PATTERN = new RegExp(`/app/(?:[^/]+/)*(?:route|page|layout|template|loading|error|default)\\.${NEXTJS_SOURCE_FILE_EXTENSION_GROUP}$`);
 const NON_PROJECT_PATH_PATTERN = /\/(?:node_modules|dist|build|\.next)\//;
 const serverFetchWithoutRevalidate = defineRule({
 	id: "server-fetch-without-revalidate",
@@ -33697,8 +33725,8 @@ const serverSequentialIndependentAwait = defineRule({
 });
 //#endregion
 //#region src/plugin/rules/react-builtins/state-in-constructor.ts
-const ALWAYS_MESSAGE = "This component's state is set up inconsistently.";
-const NEVER_MESSAGE = "This component's state is set up inconsistently.";
+const ALWAYS_MESSAGE = "This class uses a state field instead of the configured constructor pattern, so state setup is inconsistent across the codebase.";
+const NEVER_MESSAGE = "This class sets state in the constructor instead of the configured class-field pattern, so state setup is inconsistent across the codebase.";
 const resolveSettings$1 = (settings) => {
 	const reactDoctor = settings?.["react-doctor"];
 	return { mode: (typeof reactDoctor === "object" && reactDoctor !== null ? reactDoctor.stateInConstructor ?? {} : {}).mode ?? "always" };
@@ -33730,7 +33758,7 @@ const stateInConstructor = defineRule({
 	title: "State initialized in constructor",
 	severity: "warn",
 	defaultEnabled: false,
-	recommendation: "Pick one way to set up state in class components and stick with it.",
+	recommendation: "Use one class-state setup pattern so readers know where initial state lives.",
 	category: "Architecture",
 	create: (context) => {
 		const { mode } = resolveSettings$1(context.settings);
@@ -33833,7 +33861,7 @@ const stylePropObject = defineRule({
 	id: "style-prop-object",
 	title: "Style prop is not an object",
 	severity: "warn",
-	recommendation: "Pass the `style` prop as `{{ color: 'red' }}` (object literal), not a string.",
+	recommendation: "Pass `style` as an object so React can apply CSS properties instead of ignoring a string style value.",
 	category: "Correctness",
 	create: (context) => {
 		const { allow } = resolveSettings(context.settings);
@@ -34179,11 +34207,11 @@ const tanstackStartMissingHeadContent = defineRule({
 //#region src/plugin/rules/tanstack-start/tanstack-start-no-anchor-element.ts
 const tanstackStartNoAnchorElement = defineRule({
 	id: "tanstack-start-no-anchor-element",
-	title: "Plain anchor for internal navigation",
+	title: "Plain anchor reloads TanStack Router navigation",
 	tags: ["test-noise"],
 	requires: ["tanstack-start"],
 	severity: "warn",
-	recommendation: "`import { Link } from '@tanstack/react-router'` for type-safe routes, preloading via `preload=\"intent\"`, and client-side navigation",
+	recommendation: "Use `Link` from `@tanstack/react-router` so internal navigation keeps client state, preloading, and typed routes.",
 	create: (context) => ({ JSXOpeningElement(node) {
 		const filename = normalizeFilename$1(context.filename ?? "");
 		if (!TANSTACK_ROUTE_FILE_PATTERN.test(filename)) return;
@@ -34196,7 +34224,7 @@ const tanstackStartNoAnchorElement = defineRule({
 		else if (isNodeOfType(hrefAttribute.value, "JSXExpressionContainer") && isNodeOfType(hrefAttribute.value.expression, "Literal")) hrefValue = hrefAttribute.value.expression.value;
 		if (typeof hrefValue === "string" && hrefValue.startsWith("/")) context.report({
 			node,
-			message: "Plain <a> reloads the whole page on internal navigation."
+			message: "Plain <a> reloads the whole page for internal navigation, so TanStack Router loses client state and preloading."
 		});
 	} })
 });
@@ -34268,7 +34296,7 @@ const tanstackStartNoNavigateInRender = defineRule({
 				if (deferredCallbackDepth > 0 || eventHandlerDepth > 0) return;
 				if (isNodeOfType(node.callee, "Identifier") && node.callee.name === "navigate" && (node.arguments?.length ?? 0) > 0) context.report({
 					node,
-					message: "navigate() during render causes hydration errors."
+					message: "navigate() runs during render here, so server and browser output can diverge during hydration."
 				});
 			},
 			"CallExpression:exit"(node) {
@@ -34352,7 +34380,7 @@ const tanstackStartNoUseServerInHandler = defineRule({
 		if (!isNodeOfType(body, "BlockStatement")) return;
 		if (body.body?.some((statement) => isNodeOfType(statement, "ExpressionStatement") && (statement.directive === "use server" || isNodeOfType(statement.expression, "Literal") && statement.expression.value === "use server"))) context.report({
 			node: handlerFunction,
-			message: "\"use server\" inside a createServerFn handler causes compile errors."
+			message: "\"use server\" inside a createServerFn handler duplicates TanStack Start's server boundary, so the route can fail to compile."
 		});
 	} })
 });
@@ -34426,11 +34454,11 @@ const tanstackStartRedirectInTryCatch = defineRule({
 //#region src/plugin/rules/tanstack-start/tanstack-start-route-property-order.ts
 const tanstackStartRoutePropertyOrder = defineRule({
 	id: "tanstack-start-route-property-order",
-	title: "Wrong route property order",
+	title: "Route property order breaks type inference",
 	tags: ["test-noise"],
 	requires: ["tanstack-start"],
 	severity: "error",
-	recommendation: "Follow the order: params/validateSearch → loaderDeps → context → beforeLoad → loader → head. See https://tanstack.com/router/latest/docs/eslint/create-route-property-order",
+	recommendation: "Follow the route property order because TanStack Router's type inference depends on earlier properties feeding later ones.",
 	create: (context) => ({ CallExpression(node) {
 		const optionsObject = getRouteOptionsObject(node);
 		if (!optionsObject) return;
@@ -34460,7 +34488,7 @@ const tanstackStartRoutePropertyOrder = defineRule({
 //#region src/plugin/rules/tanstack-start/tanstack-start-server-fn-method-order.ts
 const tanstackStartServerFnMethodOrder = defineRule({
 	id: "tanstack-start-server-fn-method-order",
-	title: "Wrong server function method order",
+	title: "Server function method order breaks type inference",
 	tags: ["test-noise"],
 	requires: ["tanstack-start"],
 	severity: "error",
@@ -34541,7 +34569,7 @@ const useLazyMotion = defineRule({
 			return getImportedName$1(specifier) === "motion";
 		})) context.report({
 			node,
-			message: "Importing \"motion\" ships about 30 kb of extra code to your users & slows page load. Use \"m\" with LazyMotion instead."
+			message: "Importing \"motion\" ships about 30 kb of extra code and slows page load. Use \"m\" with LazyMotion instead."
 		});
 	} })
 });
@@ -34578,7 +34606,7 @@ const voidDomElementsNoChildren = defineRule({
 	id: "void-dom-elements-no-children",
 	title: "Children on a void element",
 	severity: "warn",
-	recommendation: "Remove the children, or use a tag that can hold children.",
+	recommendation: "Remove the children or use a non-void tag so React does not drop content the element cannot render.",
 	create: (context) => ({
 		JSXElement(node) {
 			const openingElement = node.openingElement;
@@ -34726,7 +34754,7 @@ const DEPRECATED_ZOD_ERROR_MEMBERS = new Set([
 	"formErrors",
 	"format"
 ]);
-const ZOD_ERROR_API_MESSAGE = "Zod 4 dropped this ZodError method, so it breaks when you upgrade.";
+const ZOD_ERROR_API_MESSAGE = "This ZodError API was removed in Zod 4, so error handling can break during the upgrade.";
 const isZodErrorReference = (node) => {
 	const inner = stripParenExpression(node);
 	if (isNodeOfType(inner, "Identifier")) return getZodNamedImport(inner) === "ZodError";
@@ -34758,7 +34786,7 @@ const isReceiverOfDeprecatedZodErrorMember = (callExpression) => {
 };
 const zodV4NoDeprecatedErrorApis = defineRule({
 	id: "zod-v4-no-deprecated-error-apis",
-	title: "Deprecated Zod error API",
+	title: "Zod 3 error API breaks in Zod 4",
 	requires: ["zod:4"],
 	tags: ["migration-hint"],
 	severity: "warn",
@@ -34847,7 +34875,7 @@ const parseCallUsesErrorMap = (callExpression) => {
 };
 const zodV4NoDeprecatedErrorCustomization = defineRule({
 	id: "zod-v4-no-deprecated-error-customization",
-	title: "Deprecated Zod error customization",
+	title: "Zod 3 error customization breaks in Zod 4",
 	requires: ["zod:4"],
 	tags: ["migration-hint"],
 	severity: "warn",
@@ -34856,7 +34884,7 @@ const zodV4NoDeprecatedErrorCustomization = defineRule({
 		if (!factoryUsesDeprecatedErrorParameter(node) && !parseCallUsesErrorMap(node)) return;
 		context.report({
 			node,
-			message: "Zod 4 changed how you customize error messages, so this breaks when you upgrade."
+			message: "This Zod 3 error-customization form is not compatible with Zod 4, so custom messages can stop applying during the upgrade."
 		});
 	} })
 });
@@ -34916,7 +34944,7 @@ const LITERAL_FACTORY = new Set(["literal"]);
 const reportSchemaMigration = (context, node) => {
 	context.report({
 		node,
-		message: "Zod 4 deprecated or changed this API, so it breaks when you upgrade."
+		message: "This Zod 3 schema API changed in Zod 4, so this schema can fail after the upgrade."
 	});
 };
 const isCallToDeprecatedTopLevelFactory = (callExpression) => isZodFactoryCall(callExpression, DEPRECATED_TOP_LEVEL_FACTORIES);
@@ -34968,7 +34996,7 @@ const isZodNamespaceImportMemberCreate = (memberExpression) => {
 };
 const zodV4NoDeprecatedSchemaApis = defineRule({
 	id: "zod-v4-no-deprecated-schema-apis",
-	title: "Deprecated Zod schema API",
+	title: "Zod 3 schema API breaks in Zod 4",
 	requires: ["zod:4"],
 	tags: ["migration-hint"],
 	severity: "warn",
@@ -35021,7 +35049,7 @@ const zodV4PreferTopLevelStringFormats = defineRule({
 		if (!isDirectMethodCallOnZodFactory(node, ZOD_STRING_FACTORY, STRING_FORMAT_METHODS)) return;
 		context.report({
 			node,
-			message: "Zod 4 deprecated format methods on `z.string()`, so they break when you upgrade."
+			message: "This `z.string().<format>()` check is deprecated in Zod 4, so it can break during the upgrade."
 		});
 	} })
 });