@svelte-vitals/core 0.39.0 → 0.40.1

package/dist/index.d.ts

@@ -309,6 +309,13 @@ interface HeadingInfo {
 interface ResolvedHeadings {
     route: string;
     headings: HeadingInfo[];
+    /**
+     * Headings found in child components rendered (transitively) by this route's
+     * chain files — source mode only; absent in rendered mode. Kept separate from
+     * `headings` because their position in document order is unknown: safe for
+     * counting (seo/single-h1), unusable for outline order (seo/heading-level-skip).
+     */
+    componentHeadings?: HeadingInfo[];
 }
 
 /**
@@ -479,6 +486,8 @@ interface ComponentFacts {
         url: string;
         line: number;
     }[];
+    /** Set when the file failed to read or parse and these facts are the empty fallback — the file was NOT analyzed. */
+    parseFailed?: true;
 }
 
 /** What the per-file parsers produce — `ComponentFacts` minus `file`, with `suppressions` always present. */
@@ -599,6 +608,8 @@ interface KitModuleFacts {
     };
     /** Inline `svelte-vitals-disable-next-line` directives in this file. */
     suppressions: SuppressionDirective[];
+    /** Set when the file failed to read or parse and these facts are the empty fallback — the file was NOT analyzed. */
+    parseFailed?: true;
 }
 
 /**
@@ -1119,9 +1130,15 @@ declare const seoHreflang: Rule;
 
 /**
  * seo/single-h1 — Heading hierarchy (single H1). Reads the per-route page-body headings
- * channel (collected by both providers). Zero <h1> (no primary heading) and two
- * or more (diluted topic) are both flagged; exactly one passes. A route whose
- * headings were not collected (channel unset) emits nothing.
+ * channel (collected by both providers), counting `headings` plus `componentHeadings`
+ * (static mode only — headings found transitively in rendered child components) as one
+ * combined list. Zero <h1> (no primary heading) is a `warning`: defensible, a page needs
+ * a primary heading. Two or more is only `info`: a single <h1> is the conventional
+ * signal, but no official source documents a ranking penalty for several (2026-08-09 v1
+ * rule-validity review, P2 #11) — so it's flagged as a style nit, not a defect. Exactly
+ * one passes. A route whose headings were not collected (channel unset) emits nothing. A
+ * global `rules: { 'seo/single-h1': <severity> }` override flattens both arms to one
+ * severity (design, `applyRuleSeverities`).
  */
 declare const seoSingleH1: Rule;
 
@@ -1179,8 +1196,9 @@ declare const correctnessNonreactiveBuiltinState: Rule;
 
 /**
  * correctness/checkable-bind-value — bind:value binds the DOM value property. A
- * checkbox/radio's user interaction toggles checkedness, which bind:value never observes, so
- * the bound state is frozen at its initial value and silently never updates in production.
+ * checkbox/radio's user interaction toggles checkedness, which bind:value never observes. A
+ * checkbox throws bind_invalid_checkbox_value in dev (silently tracks value instead of
+ * checkedness in prod); a radio throws nothing and its bound state silently never updates.
  * bind:checked (single checkbox) / bind:group (checkbox list, radio group) are the correct
  * bindings.
  */

package/dist/index.js

@@ -94,7 +94,7 @@ function attrTextOf(attr) {
 // src/component-parse.ts
 function unwrapTs(expr) {
   let cur = expr;
-  while (cur.type === "TSSatisfiesExpression" || cur.type === "TSAsExpression" || cur.type === "TSNonNullExpression")
+  while (cur !== void 0 && (cur.type === "TSSatisfiesExpression" || cur.type === "TSAsExpression" || cur.type === "TSNonNullExpression"))
     cur = cur.expression;
   return cur;
 }
@@ -623,6 +623,21 @@ function collectDirectiveEscapes(node, names, acc) {
   }
 }
 var RUNE_NAMES = /* @__PURE__ */ new Set(["$state", "$derived", "$effect", "$props", "$bindable", "$inspect", "$host"]);
+function collectImportedLocalNames(program, acc) {
+  for (const stmt of program?.body ?? []) {
+    if (stmt?.type !== "ImportDeclaration" || stmt.importKind === "type") continue;
+    for (const s of stmt.specifiers ?? []) {
+      if (s?.importKind === "type" || s?.local?.type !== "Identifier") continue;
+      acc.add(s.local.name);
+    }
+  }
+}
+function collectNewExprLocalNames(program, acc) {
+  walkEstree(program, (n) => {
+    if (n.type !== "VariableDeclarator" || n.id?.type !== "Identifier" || !n.init) return;
+    if (unwrapTs(n.init).type === "NewExpression") acc.add(n.id.name);
+  });
+}
 function bodyReadsReactive(fn, reactiveNames) {
   let reads = false;
   const visit = (n) => {
@@ -1398,6 +1413,12 @@ function parseComponentFacts(source, filename) {
     }
     const stateNames = /* @__PURE__ */ new Set();
     const reactiveNames = /* @__PURE__ */ new Set();
+    collectImportedLocalNames(program, reactiveNames);
+    collectNewExprLocalNames(program, reactiveNames);
+    if (moduleProgram) {
+      collectImportedLocalNames(moduleProgram, reactiveNames);
+      collectNewExprLocalNames(moduleProgram, reactiveNames);
+    }
     const stateDecls = [];
     walkEstree(program, (n) => {
       if (n.type !== "VariableDeclarator" || !n.init) return;
@@ -1566,7 +1587,7 @@ async function collectComponentFacts(rt, cwd) {
         const source = await rt.readFile(rt.join(cwd, rel));
         return { file: rel, ...parseComponentFacts(source, rel) };
       } catch {
-        return emptyComponentFacts(rel);
+        return { ...emptyComponentFacts(rel), parseFailed: true };
       }
     })
   );
@@ -2146,7 +2167,7 @@ async function collectKitModuleFacts(rt, cwd, aliases) {
         const source = await rt.readFile(rt.join(cwd, rel));
         return { file: rel, kind, ...parseKitModuleFacts(source, rel, aliases) };
       } catch {
-        return emptyKitModuleFacts(rel, kind);
+        return { ...emptyKitModuleFacts(rel, kind), parseFailed: true };
       }
     })
   );
@@ -2536,7 +2557,7 @@ function headTagRule(opts) {
 var seoDescriptionPresence = headTagRule({
   id: "seo/description-presence",
   title: "Description presence",
-  severity: "critical",
+  severity: "warning",
   match: (t) => t.kind === "meta" && t.name === "description",
   label: '<meta name="description">',
   recommendation: 'Add a <meta name="description"> in <svelte:head>, or set the description on your meta component.',
@@ -2556,7 +2577,7 @@ var seoCanonicalUrl = headTagRule({
   match: (t) => t.kind === "link" && t.rel === "canonical",
   label: '<link rel="canonical">',
   recommendation: 'Add <link rel="canonical"> in <svelte:head>, or set the canonical prop on your meta component.',
-  rationale: "A canonical URL tells search engines which URL is authoritative, preventing duplicate-content dilution across query strings and trailing-slash variants.",
+  rationale: "A canonical URL tells search engines which URL is authoritative, preventing duplicate-content dilution across query-string variants of the same page.",
   fix: {
     description: 'Add <link rel="canonical"> inside <svelte:head>, or set the canonical prop on your meta component.',
     snippet: '<svelte:head>\n  <link rel="canonical" href="https://example.com/this-page" />\n</svelte:head>',
@@ -2693,7 +2714,7 @@ var seoHtmlLang = {
   category: "seo",
   severity: "warning",
   scope: "project",
-  rationale: "The <html lang> attribute declares the page language for search engines, screen readers, and translation tools.",
+  rationale: "The <html lang> attribute tells screen readers how to pronounce the page, browsers whether to offer translation, and other assistive tools how to handle the content \u2014 Google has said it does not use lang for ranking.",
   fix: FIX4,
   async check(ctx) {
     const detection = ctx.project.htmlLang;
@@ -2778,7 +2799,7 @@ var performanceImageDimensions = imageRule({
   severity: "warning",
   label: "<img> width/height",
   recommendation: "Set explicit width and height on <img> to reserve space and avoid layout shift (CLS).",
-  rationale: "An <img> without explicit width and height triggers layout shift (CLS) as it loads, hurting Core Web Vitals and visual stability.",
+  rationale: "An <img> without explicit width and height can trigger layout shift (CLS) as it loads, hurting Core Web Vitals and visual stability \u2014 unless the box is reserved another way, e.g. CSS aspect-ratio.",
   fix: {
     description: "Add explicit width and height attributes to the <img>.",
     snippet: '<img src="/hero.jpg" width="1200" height="630" alt="\u2026" />',
@@ -3233,7 +3254,7 @@ var performancePreconnect = {
   rationale: "Connecting to a third-party origin (DNS + TCP + TLS) is costly; a preconnect/dns-prefetch hint starts it early so the resource arrives sooner.",
   fix: {
     description: "Add a preconnect hint for the third-party origin.",
-    snippet: '<link rel="preconnect" href="https://fonts.googleapis.com" />',
+    snippet: '<link rel="preconnect" href="https://fonts.googleapis.com" />\n<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
     lang: "html"
   },
   options: OPTIONS,
@@ -3357,11 +3378,11 @@ var seoTwitterCard = headTagRule({
 var seoOgDescription = headTagRule({
   id: "seo/og-description",
   title: "Open Graph description",
-  severity: "warning",
+  severity: "info",
   match: (t) => t.kind === "meta" && t.property === "og:description",
   label: '<meta property="og:description">',
   recommendation: 'Add <meta property="og:description">, or set openGraph.description on your meta component.',
-  rationale: "og:description is the summary shown under the title in social previews; without it platforms guess or show nothing, lowering click-through.",
+  rationale: "og:description is the summary shown under the title in social previews; without it platforms guess or show nothing, lowering click-through. The Open Graph protocol lists it as an optional property.",
   fix: {
     description: "Add an og:description meta tag in <svelte:head>.",
     snippet: '<svelte:head>\n  <meta property="og:description" content="A concise page summary." />\n</svelte:head>',
@@ -3373,11 +3394,11 @@ var seoOgDescription = headTagRule({
 var seoOgUrl = headTagRule({
   id: "seo/og-url",
   title: "Open Graph URL",
-  severity: "info",
+  severity: "warning",
   match: (t) => t.kind === "meta" && t.property === "og:url",
   label: '<meta property="og:url">',
   recommendation: 'Add <meta property="og:url"> with the canonical URL, or set openGraph.url on your meta component.',
-  rationale: "og:url tells social platforms the canonical address to attribute shares and likes to, consolidating engagement on one URL.",
+  rationale: "og:url tells social platforms the canonical address to attribute shares and likes to, consolidating engagement on one URL. The Open Graph protocol lists it as a required property.",
   fix: {
     description: "Add an og:url meta tag in <svelte:head>.",
     snippet: '<svelte:head>\n  <meta property="og:url" content="https://example.com/this-page" />\n</svelte:head>',
@@ -3397,7 +3418,7 @@ var seoViewport = headTagRule({
   // silent there instead of false-flagging "missing" on every route.
   appliesTo: (head) => head.source === "rendered",
   recommendation: 'Add <meta name="viewport" content="width=device-width, initial-scale=1"> (usually in app.html).',
-  rationale: "Without a viewport meta tag the page is not mobile-responsive, which Google penalizes under mobile-first indexing.",
+  rationale: "Without a viewport meta tag mobile browsers render the page at a fixed ~980px layout viewport and scale it to fit, so text and controls end up too small to read or tap without pinch-zooming.",
   fix: {
     description: "Add the viewport meta tag (typically in src/app.html <head>).",
     snippet: '<meta name="viewport" content="width=device-width, initial-scale=1" />',
@@ -3562,19 +3583,25 @@ function hasNonEmpty(node, key) {
   return true;
 }
 var REQUIRED_PROPS = {
-  Article: ["headline"],
-  BlogPosting: ["headline"],
-  NewsArticle: ["headline"],
-  Product: ["name", "offers"],
+  Product: { all: ["name"], oneOf: ["review", "aggregateRating", "offers"] },
   BreadcrumbList: ["itemListElement"],
-  Organization: ["name", "url"],
   WebSite: ["name", "url"],
   Event: ["name", "startDate", "location"],
-  Recipe: ["name", "image", "recipeIngredient", "recipeInstructions"],
-  Person: ["name"],
-  VideoObject: ["name", "description", "thumbnailUrl", "uploadDate"],
+  Recipe: ["name", "image"],
+  VideoObject: ["name", "thumbnailUrl", "uploadDate"],
   LocalBusiness: ["name", "address"]
 };
+function oneOfLabel(props) {
+  const last = props.at(-1) ?? "";
+  return props.length <= 1 ? last : `one of ${props.slice(0, -1).join(", ")} or ${last}`;
+}
+function missingRequiredProps(node, row) {
+  const all = Array.isArray(row) ? row : row.all;
+  const missing = all.filter((p) => !hasNonEmpty(node, p));
+  const oneOf = Array.isArray(row) ? void 0 : row.oneOf;
+  if (oneOf && !oneOf.some((p) => hasNonEmpty(node, p))) missing.push(oneOfLabel(oneOf));
+  return missing;
+}
 function jsonldTags(head) {
   return head.tags.filter((t) => t.kind === "jsonld" && typeof t.jsonld === "string");
 }
@@ -3766,7 +3793,7 @@ var seoJsonLdRequiredProps = jsonldRule({
         const required = REQUIRED_PROPS[t];
         if (!required) continue;
         hasKnownType = true;
-        const missing = required.filter((p) => !hasNonEmpty(node, p));
+        const missing = missingRequiredProps(node, required);
         if (missing.length > 0) return `${t} JSON-LD is missing required ${missing.join(", ")}`;
       }
     }
@@ -3808,7 +3835,7 @@ function lengthRule(opts) {
         const o = resolveRuleOptions(opts.id, spec, ctx.config, { route: head.route, file: location }, compiled);
         const min = intOption(o, "min", opts.min);
         const max = intOption(o, "max", opts.max);
-        const recommendation12 = typeof opts.recommendation === "function" ? opts.recommendation(o) : opts.recommendation;
+        const recommendation10 = typeof opts.recommendation === "function" ? opts.recommendation(o) : opts.recommendation;
         const len = visibleLength(tag.text);
         let problem;
         if (len < min) problem = `${opts.noun} is too short (${len} chars; aim for ${min}\u2013${max})`;
@@ -3822,7 +3849,7 @@ function lengthRule(opts) {
             route: head.route,
             location,
             message: problem,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           } : {
             id: opts.id,
@@ -3836,7 +3863,7 @@ function lengthRule(opts) {
             // it to also apply `severity: 'off'`.
             location,
             message: opts.label,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           }
         );
@@ -3904,7 +3931,7 @@ var seoImageAlt = imageRule({
   rationale: "An <img> with no alt attribute is invisible to image search and assistive technology; a descriptive alt is an image-SEO signal.",
   fix: {
     description: 'Add a descriptive alt attribute to the <img> (or alt="" if purely decorative).',
-    snippet: '<img src="/photo.jpg" width="800" height="600" alt="Description of the image" />',
+    snippet: '<img src="/photo.jpg" width="800" height="600" alt="Golden retriever catching a frisbee in a park" />',
     lang: "svelte"
   },
   ok: (img) => img.hasAlt
@@ -3912,7 +3939,9 @@ var seoImageAlt = imageRule({
 
 // src/rules/seo/hreflang.ts
 var docsUrl4 = docsUrlFor("seo/hreflang");
-var recommendation4 = 'Use valid hreflang codes (e.g. "en", "en-US", "x-default") and include an x-default when you have multiple language alternates.';
+var malformedRecommendation = 'Use valid hreflang codes, e.g. "en", "en-US", or the literal "x-default".';
+var noDefaultRecommendation = "x-default is a Google recommendation, not a requirement \u2014 most useful for a language-selector or auto-redirecting page. Add one if this page behaves that way; otherwise search engines fall back to matching the individual alternates.";
+var passRecommendation = 'Use valid hreflang codes (e.g. "en", "en-US", "x-default") for your language alternates.';
 var HREFLANG_RE = /^[a-z]{2,3}(-[a-z]{4})?(-([a-z]{2}|\d{3}))?$/i;
 function isValidHreflang(v) {
   return v.toLowerCase() === "x-default" || HREFLANG_RE.test(v);
@@ -3923,7 +3952,7 @@ var seoHreflang = {
   category: "seo",
   severity: "warning",
   scope: "route",
-  rationale: "A malformed hreflang code or a missing x-default breaks international targeting, so search engines may serve the wrong language version.",
+  rationale: "A malformed hreflang code breaks international targeting outright. A missing x-default is a Google recommendation for language-selector or auto-redirecting pages, not a defect on every multilingual site.",
   async check(ctx) {
     const out = [];
     for (const head of ctx.heads) {
@@ -3936,10 +3965,13 @@ var seoHreflang = {
       let problem;
       let location = head.file;
       if (badTag) {
-        problem = `Invalid hreflang value "${badTag.hreflang}"`;
+        problem = { message: `Invalid hreflang value "${badTag.hreflang}"`, recommendation: malformedRecommendation };
         location = badTag.file ?? head.file;
       } else if (values.length >= 2 && !values.some((v) => v.toLowerCase() === "x-default")) {
-        problem = "Multiple hreflang alternates without an x-default";
+        problem = {
+          message: "Multiple hreflang alternates with no x-default declared",
+          recommendation: noDefaultRecommendation
+        };
       }
       out.push(
         problem ? {
@@ -3949,8 +3981,8 @@ var seoHreflang = {
           detection: PENALIZED,
           route: head.route,
           location,
-          message: problem,
-          recommendation: recommendation4,
+          message: problem.message,
+          recommendation: problem.recommendation,
           docsUrl: docsUrl4
         } : {
           id: "seo/hreflang",
@@ -3962,7 +3994,7 @@ var seoHreflang = {
           // 2026-08-08-pass-result-location-design.md).
           location,
           message: "hreflang",
-          recommendation: recommendation4,
+          recommendation: passRecommendation,
           docsUrl: docsUrl4
         }
       );
@@ -3973,26 +4005,33 @@ var seoHreflang = {
 
 // src/rules/seo/single-h1.ts
 var docsUrl5 = docsUrlFor("seo/single-h1");
-var recommendation5 = "Use exactly one <h1> per page for its main topic; demote extra top-level headings to <h2>+.";
+var passRecommendation2 = "Use exactly one <h1> per page for its main topic; demote extra top-level headings to <h2>+.";
+var missingRecommendation = "Add a single, descriptive <h1> naming the page's main topic.";
+var multipleRecommendation = "A single, clear <h1> is the conventional signal for a page \u2014 consider demoting extra top-level headings to <h2>+.";
 var seoSingleH1 = {
   id: "seo/single-h1",
   title: "Heading hierarchy",
   category: "seo",
   severity: "warning",
   scope: "route",
-  rationale: "Each page should have exactly one <h1> naming its main topic; none leaves the page without a primary heading, and several dilute the topic signal.",
+  rationale: "A page should have a primary heading naming its main topic. Zero <h1> leaves the page without one; a single, clear <h1> is the conventional signal, though multiple <h1>s are tolerated by modern heading algorithms.",
   async check(ctx) {
     const out = [];
     for (const route of ctx.headings ?? []) {
-      const h1 = route.headings.filter((h) => h.level === 1);
+      const combined = [...route.headings, ...route.componentHeadings ?? []];
+      const h1 = combined.filter((h) => h.level === 1);
       let problem;
       let where = {};
       if (h1.length === 0) {
-        problem = "Missing <h1>";
+        problem = { message: "Missing <h1>", severity: "warning", recommendation: missingRecommendation };
         const first = route.headings[0];
         if (first) where = { location: first.file, ...first.line > 0 ? { line: first.line } : {} };
       } else if (h1.length > 1) {
-        problem = `Multiple <h1> (${h1.length}); use exactly one`;
+        problem = {
+          message: `Multiple <h1> (${h1.length}); a single <h1> is the conventional signal`,
+          severity: "info",
+          recommendation: multipleRecommendation
+        };
         const extra = h1[1];
         where = { location: extra.file, ...extra.line > 0 ? { line: extra.line } : {} };
       }
@@ -4000,12 +4039,12 @@ var seoSingleH1 = {
         problem ? {
           id: "seo/single-h1",
           category: "seo",
-          severity: "warning",
+          severity: problem.severity,
           detection: PENALIZED,
           route: route.route,
           ...where,
-          message: problem,
-          recommendation: recommendation5,
+          message: problem.message,
+          recommendation: problem.recommendation,
           docsUrl: docsUrl5
         } : {
           id: "seo/single-h1",
@@ -4018,7 +4057,7 @@ var seoSingleH1 = {
           // 2026-08-08-pass-result-location-design.md). Only reached when h1.length === 1.
           location: h1[0].file,
           message: "Heading hierarchy",
-          recommendation: recommendation5,
+          recommendation: passRecommendation2,
           docsUrl: docsUrl5
         }
       );
@@ -4102,14 +4141,14 @@ var seoDuplicateDescription = uniquenessRule({
 
 // src/rules/seo/heading-level-skip.ts
 var docsUrl6 = docsUrlFor("seo/heading-level-skip");
-var recommendation6 = "Increase heading levels one step at a time (do not jump, e.g. from <h2> straight to <h4>).";
+var recommendation4 = "Increase heading levels one step at a time (do not jump, e.g. from <h2> straight to <h4>).";
 var seoHeadingLevelSkip = {
   id: "seo/heading-level-skip",
   title: "Heading order",
   category: "seo",
   severity: "info",
   scope: "route",
-  rationale: "Skipping a heading level breaks the document outline that search engines and assistive tech rely on to understand page structure.",
+  rationale: "Skipping a heading level breaks the document outline that assistive tech relies on to navigate page structure, and that search engines use as a structural signal.",
   async check(ctx) {
     const out = [];
     for (const route of ctx.headings ?? []) {
@@ -4134,7 +4173,7 @@ var seoHeadingLevelSkip = {
           location: skip.file,
           ...skip.line > 0 ? { line: skip.line } : {},
           message: `Heading level skipped (<h${skip.prev}> to <h${skip.level}>)`,
-          recommendation: recommendation6,
+          recommendation: recommendation4,
           docsUrl: docsUrl6
         } : {
           id: "seo/heading-level-skip",
@@ -4148,7 +4187,7 @@ var seoHeadingLevelSkip = {
           // already continued above, so `[0]` is always defined here.
           location: route.headings[0].file,
           message: "Heading order",
-          recommendation: recommendation6,
+          recommendation: recommendation4,
           docsUrl: docsUrl6
         }
       );
@@ -4258,7 +4297,7 @@ function componentRule(opts) {
       const compiled = compileOverrides(ctx.config);
       for (const c of ctx.components ?? []) {
         const o = resolveRuleOptions(opts.id, opts.options, ctx.config, { route: c.file, file: c.file }, compiled);
-        const recommendation12 = typeof opts.recommendation === "function" ? opts.recommendation(o) : opts.recommendation;
+        const recommendation10 = typeof opts.recommendation === "function" ? opts.recommendation(o) : opts.recommendation;
         if (!opts.applies(c, o, ctx)) continue;
         const bad = opts.bad(c, o, ctx).filter((b) => !(b.line > 0 && isSuppressed2(c, opts.id, b.line)));
         if (bad.length === 0) {
@@ -4272,7 +4311,7 @@ function componentRule(opts) {
             // same location a penalized result for this file would carry.
             location: c.file,
             message: opts.label,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           });
           continue;
@@ -4287,7 +4326,7 @@ function componentRule(opts) {
             location: c.file,
             ...b.line > 0 ? { line: b.line } : {},
             message: b.message,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12,
             ...opts.fix ? { fix: { ...opts.fix } } : {}
           });
@@ -4343,10 +4382,13 @@ var correctnessEffectAsOnMount = componentRule({
   title: "Effect used as onMount",
   category: "correctness",
   label: "$effect usage",
-  recommendation: "Move mount-time side effects to onMount (import { onMount } from 'svelte'); reserve $effect for logic that reacts to $state/$derived/$props.",
-  rationale: "An $effect that reads no reactive value runs once after mount and never re-runs \u2014 it is an onMount in disguise, which obscures intent and misuses the reactivity system.",
+  recommendation: "If this runs in response to a user interaction, use an event handler; to sync an element with an external library, use {@attach} instead. For genuine one-time mount work, use onMount (import { onMount } from 'svelte'). Reserve $effect for logic that reacts to $state/$derived/$props.",
+  rationale: "An $effect whose body reads no reactive value visible to this analysis runs once after mount and never re-runs on the paths it can see \u2014 usually a sign the code belongs in an event handler, {@attach}, or onMount instead of $effect. This can't see a reactive value reached only through a plain function's return value, so a genuinely reactive effect built that way can still be flagged.",
   applies: (c) => c.effects.length > 0,
-  bad: (c) => c.effects.filter((e) => e.mountOnly).map((e) => ({ line: e.line, message: "$effect reads no reactive value \u2014 use onMount instead" }))
+  bad: (c) => c.effects.filter((e) => e.mountOnly).map((e) => ({
+    line: e.line,
+    message: "$effect reads no reactive value this analysis can see \u2014 consider an event handler, {@attach}, or onMount instead"
+  }))
 });
 
 // src/rules/correctness/unmutated-state.ts
@@ -4426,14 +4468,14 @@ var correctnessCheckableBindValue = componentRule({
   severity: "warning",
   label: "bind:checked / bind:group on checkable inputs",
   recommendation: "Replace bind:value with bind:checked (single checkbox) or bind:group (checkbox list / radio group).",
-  rationale: "bind:value binds the DOM value property. A checkbox/radio's user interaction toggles checkedness, which bind:value never observes \u2014 the bound state is frozen at its initial value. Svelte's checked/grouped bindings (bind:checked, bind:group) are built for exactly this.",
+  rationale: "bind:value binds the DOM value property. A checkbox/radio's user interaction toggles checkedness, which bind:value never observes. On a checkbox this throws bind_invalid_checkbox_value in a development build; in production the check is skipped and the binding silently tracks the value attribute instead of checkedness. On a radio it throws nothing in either build \u2014 it renders once with the initial value, then silently never updates. Svelte's checked/grouped bindings (bind:checked, bind:group) are built for exactly this.",
   fix: {
     description: "For a single checkbox, replace bind:value={x} with bind:checked={x} (x becomes a boolean). For a checkbox list or radio group, replace bind:value={x} with bind:group={x} on every input sharing the group, keeping each input's static value attribute to identify the option."
   },
   applies: (c) => c.checkableBindValues.length > 0,
   bad: (c) => c.checkableBindValues.map((v) => ({
     line: v.line,
-    message: v.kind === "checkbox" ? "bind:value on a checkbox does not track its checked state \u2014 the bound value silently never updates when the user toggles it. Use bind:checked (single checkbox) or bind:group (checkbox list) instead." : "bind:value on a radio input does not track which option is selected \u2014 the bound value silently never updates when the user picks one. Use bind:group with a shared group variable across the radio inputs instead."
+    message: v.kind === "checkbox" ? "bind:value on a checkbox does not track its checked state \u2014 it throws bind_invalid_checkbox_value in development; in a production build it silently tracks the value attribute instead of checkedness. Use bind:checked (single checkbox) or bind:group (checkbox list) instead." : "bind:value on a radio input does not track which option is selected \u2014 the bound value silently never updates when the user picks one. Use bind:group with a shared group variable across the radio inputs instead."
   }))
 });
 
@@ -4445,7 +4487,7 @@ var correctnessOrphanEffect = componentRule({
   severity: "critical",
   label: "$effect context",
   recommendation: "Wrap the effect in $effect.root (and own the returned cleanup), or restructure so the effect is created during component initialisation (e.g. call a setup method from a component).",
-  rationale: "An $effect created outside component initialisation throws effect_orphan at runtime \u2014 the compiler does not catch it, and it typically surfaces as a production 500.",
+  rationale: "An $effect created outside component initialisation throws effect_orphan at runtime. The compiler does not catch it \u2014 the server compiler deletes $effect calls entirely, so SSR renders without error \u2014 and the crash happens client-side, when the module evaluates in the browser, breaking hydration rather than producing a server error.",
   // `orphanEffects` is typed required, but a facts object built by an older/external
   // constructor may omit it — default to empty rather than let `applies` throw and
   // take the whole `runRules` Promise.all down with it.
@@ -4464,6 +4506,14 @@ var DOCS_URL = docsUrlFor(ID);
 var LABEL = "Lifecycle-call context";
 var RECOMMENDATION = "Call lifecycle/context functions during component initialisation (the top level of a component's <script>). In load, return the data and call setContext in a layout/page component; in shared modules, expose a setup function that components call during init.";
 var topLevelMessage = (name) => `${name}() runs at module evaluation, outside component initialisation \u2014 it throws lifecycle_outside_component at runtime`;
+var ALWAYS_THROWS = /* @__PURE__ */ new Set(["getContext", "setContext", "hasContext", "getAllContexts"]);
+function kitLifecycleMessage(name, kind, inHandler) {
+  if (kind === "server" && !ALWAYS_THROWS.has(name)) {
+    const where = inHandler ? `${name}() is called in a load/handler, outside component initialisation` : `${name}() runs outside component initialisation (module evaluation or the init hook)`;
+    return name === "onDestroy" ? `${where} \u2014 on the server it still crashes, but with a plain TypeError, not lifecycle_outside_component (onDestroy has no component-context guard there)` : `${where} \u2014 on the server this is a silent no-op (it throws lifecycle_outside_component only if this module also runs in the browser)`;
+  }
+  return inHandler ? `${name}() is called in a load/handler \u2014 it runs on every request, outside component initialisation, and throws lifecycle_outside_component at runtime` : `${name}() runs outside component initialisation (module evaluation or the init hook) \u2014 it throws lifecycle_outside_component at runtime`;
+}
 function isSuppressed3(suppressions, line) {
   return (suppressions ?? []).some((s) => s.line === line && (!s.ruleIds || s.ruleIds.includes(ID)));
 }
@@ -4506,7 +4556,7 @@ var correctnessOrphanLifecycle = {
   category: "correctness",
   severity: "critical",
   scope: "component",
-  rationale: "Svelte lifecycle and context functions require an active component context; called at module scope, in a shared-state class constructor, or in a load/handler they throw lifecycle_outside_component at runtime \u2014 the compiler does not catch it, and it surfaces as a production crash.",
+  rationale: "Svelte lifecycle and context functions require an active component context; called at module scope, in a shared-state class constructor, or in a load/handler they throw lifecycle_outside_component at runtime \u2014 the compiler does not catch it, and it surfaces as a production crash. Exception: in a Kit module that only ever runs on the server (+page.server.ts, +server.ts, hooks.server.ts), onMount/beforeUpdate/afterUpdate/createEventDispatcher are silent no-ops there instead, and onDestroy throws a plain TypeError rather than lifecycle_outside_component \u2014 only getContext/setContext/hasContext/getAllContexts still throw in that channel.",
   async check(ctx) {
     const out = [];
     for (const c of ctx.components ?? []) {
@@ -4530,7 +4580,7 @@ var correctnessOrphanLifecycle = {
         m.file,
         calls.map((l) => ({
           line: l.line,
-          message: l.inHandler ? `${l.name}() is called in a load/handler \u2014 it runs on every request, outside component initialisation, and throws lifecycle_outside_component at runtime` : `${l.name}() runs outside component initialisation (module evaluation or the init hook) \u2014 it throws lifecycle_outside_component at runtime`
+          message: kitLifecycleMessage(l.name, m.kind, l.inHandler)
         })),
         m.suppressions
       );
@@ -4721,7 +4771,7 @@ var securityRawHtml = componentRule({
   title: "Raw HTML render",
   category: "security",
   label: "{@html} usage",
-  recommendation: "Sanitize the value before {@html} (e.g. DOMPurify), or render it as text/markup instead.",
+  recommendation: "Sanitize the value before {@html} (e.g. DOMPurify), or render it as text/markup instead. A sanitizer keeps {@html} in the source, so the finding persists by design \u2014 once reviewed, suppress it with the inline directive.",
   rationale: "{@html} renders its value as unescaped HTML; if the value can contain user input and is not sanitized, it is a cross-site-scripting (XSS) vector.",
   applies: (c) => c.htmlTags.length > 0,
   bad: (c) => c.htmlTags.map((h) => ({ line: h.line, message: "{@html} renders unescaped HTML \u2014 ensure it is sanitized" }))
@@ -4734,7 +4784,7 @@ var securityJavascriptUrl = componentRule({
   category: "security",
   label: "No javascript: URLs",
   recommendation: "Use an event handler or a real URL instead of a javascript: URL.",
-  rationale: "A javascript: URL in href/src/action executes arbitrary script on activation \u2014 an XSS / unsafe-navigation vector that also breaks under a strict Content-Security-Policy.",
+  rationale: "A javascript: URL in href/src/action/formaction breaks under a strict Content-Security-Policy and turns what should be a real navigation into inline script execution on activation \u2014 use an event handler on a <button> instead (the same shape is also a classic XSS vector, though detection here is literal-only, so every flagged URL is author-written, not injected).",
   applies: (c) => c.javascriptUrls.length > 0,
   bad: (c) => c.javascriptUrls.map((u) => ({ line: u.line, message: "javascript: URL in an attribute" }))
 });
@@ -4746,12 +4796,12 @@ var securityHandlerStateWrite = kitModuleRule({
   category: "security",
   severity: "critical",
   label: "Load/handler purity",
-  recommendation: "Return the data from load (or the action) and pass it via page data instead of writing it to module state; per-user data belongs in cookies/locals plus a database.",
-  rationale: "SvelteKit's docs mark this NEVER-DO-THIS: the server is one long-lived process shared by every user, so module state written during a request is visible to ALL later requests \u2014 one user's data can be served to another.",
-  applies: (m) => m.importedStateWrites.length > 0,
+  recommendation: "Return the data from load (or the action) and pass it via page data instead of writing it to module state; per-user data belongs in cookies/locals plus a database. Caches and rate limiters keyed by non-personal data are the benign shape \u2014 if that describes this write, add an inline suppression.",
+  rationale: "SvelteKit's docs mark this NEVER-DO-THIS: the server is one long-lived process shared by every user, so module state written during a request is visible to ALL later requests.",
+  applies: (m) => m.importedStateWrites.length > 0 && !(m.kind === "universal" && m.ssrDisabled),
   bad: (m) => m.importedStateWrites.map((w) => ({
     line: w.line,
-    message: `a server-executed handler writes imported module state "${w.name}" \u2014 shared across all requests on the server, one user's data can leak to another`
+    message: `a server-executed handler writes imported module state "${w.name}" \u2014 module state is shared across all requests on the server; if this holds per-request or per-user data, one user's data can leak to another. Caches and rate limiters keyed by non-personal data are the benign shape \u2014 verify which this is`
   }))
 });
 
@@ -4781,7 +4831,7 @@ var securitySharedStateImport = kitModuleRule({
   label: "Server state imports",
   recommendation: "Keep module-scope $state out of server-executed code: return data from load and share it via page data or the context API. If the module is genuinely client-only, restructure so server files do not import it, or add an inline suppression.",
   rationale: "A .svelte.ts module with module-scope $state is one shared instance on the server: mutated, it leaks data between users; read-only, every request sees the same boot-time value instead of per-user data.",
-  applies: (m) => m.runesModuleImports.length > 0,
+  applies: (m) => m.runesModuleImports.length > 0 && !(m.kind === "universal" && m.ssrDisabled),
   bad: (m, ctx) => {
     const stateFiles = new Set((ctx.components ?? []).filter((c) => c.moduleStateDecls.length > 0).map((c) => c.file));
     const writtenOutside = new Set(m.importedStateWritesOutsideHandlers.map((w) => w.name));
@@ -4841,7 +4891,7 @@ var architecturePropCount = componentRule({
 
 // src/rules/architecture/private-scope-import.ts
 var docsUrl7 = docsUrlFor("architecture/private-scope-import");
-var recommendation7 = "Move the unit to the directory shared by all of its importers, or import it only from inside its own scope.";
+var recommendation5 = "Move the unit to the directory shared by all of its importers, or import it only from inside its own scope.";
 var OPTIONS2 = { scopes: { kind: "string-list", default: [] } };
 function ancestorDirs(file) {
   const segments = file.split("/");
@@ -4927,7 +4977,7 @@ var architecturePrivateScopeImport = {
           // afterward (maintainer ruling, same date).
           location: c.file,
           message: "No private-scope imports",
-          recommendation: recommendation7,
+          recommendation: recommendation5,
           docsUrl: docsUrl7
         });
         continue;
@@ -4942,7 +4992,7 @@ var architecturePrivateScopeImport = {
           location: c.file,
           ...v.line > 0 ? { line: v.line } : {},
           message: v.message,
-          recommendation: recommendation7,
+          recommendation: recommendation5,
           docsUrl: docsUrl7,
           fix: { ...architecturePrivateScopeImport.fix }
         });
@@ -5067,7 +5117,7 @@ function classifyUnusedKeys(unused, excludedDirs, compile) {
 // src/rules/architecture/unit-entry-file.ts
 var ID4 = "architecture/unit-entry-file";
 var docsUrl8 = docsUrlFor(ID4);
-var recommendation8 = "Give every declared unit directory a file named after it, or stop declaring that directory a unit.";
+var recommendation6 = "Give every declared unit directory a file named after it, or stop declaring that directory a unit.";
 var OPTIONS3 = {
   units: { kind: "string-map", default: {} },
   pascalCaseUnits: { kind: "string-map", default: {} },
@@ -5146,7 +5196,7 @@ var architectureUnitEntryFile = {
           detection: { presence: "own", value: "static" },
           location: expected,
           message: "Unit entry file",
-          recommendation: recommendation8,
+          recommendation: recommendation6,
           docsUrl: docsUrl8
         });
         continue;
@@ -5161,7 +5211,7 @@ var architectureUnitEntryFile = {
         route: dir,
         location: at,
         message: `${dir} declares a unit but has no ${expected}`,
-        recommendation: recommendation8,
+        recommendation: recommendation6,
         docsUrl: docsUrl8,
         // Which declaration matched decides the wording: a `units` match like functions/getFoo/
         // is already camelCase, so telling its author to rename it would be nonsense.
@@ -5226,7 +5276,7 @@ function satisfiesCasing(name, allowed) {
 // src/rules/architecture/directory-naming.ts
 var ID5 = "architecture/directory-naming";
 var docsUrl9 = docsUrlFor(ID5);
-var recommendation9 = "Name each directory in the casing its location declares, or narrow the declaration.";
+var recommendation7 = "Name each directory in the casing its location declares, or narrow the declaration.";
 var OPTIONS4 = {
   directories: { kind: "string-map", default: {} },
   exclude: { kind: "string-list", default: [] }
@@ -5292,7 +5342,7 @@ var architectureDirectoryNaming = {
         route: dir,
         location: at,
         message: `${dir} must be ${allowed.join(" or ")}.`,
-        recommendation: recommendation9,
+        recommendation: recommendation7,
         docsUrl: docsUrl9,
         fix: { description: "Rename the directory, or narrow the declaration that governs it." }
       });
@@ -5335,7 +5385,7 @@ var architectureDirectoryNaming = {
 // src/rules/architecture/reserved-directory-names.ts
 var ID6 = "architecture/reserved-directory-names";
 var docsUrl10 = docsUrlFor(ID6);
-var recommendation10 = "Use one of the names this location declares, or add the new name to the declaration.";
+var recommendation8 = "Use one of the names this location declares, or add the new name to the declaration.";
 var OPTIONS5 = {
   scopes: { kind: "string-map", default: {} },
   unitScopes: { kind: "string-map", default: {} },
@@ -5494,7 +5544,7 @@ var architectureReservedDirectoryNames = {
           route: child,
           location: at,
           message: `${child} is not one of the names declared here: ${winner.names.join(", ")}.`,
-          recommendation: recommendation10,
+          recommendation: recommendation8,
           docsUrl: docsUrl10,
           fix: {
             description: "Rename it to a declared name, move it under one of them, or add its name to the declaration."
@@ -5552,7 +5602,7 @@ var architectureReservedDirectoryNames = {
 // src/rules/architecture/reserved-name-placement.ts
 var ID7 = "architecture/reserved-name-placement";
 var docsUrl11 = docsUrlFor(ID7);
-var recommendation11 = "Move it to one of the places declared for this name, or declare this place for it.";
+var recommendation9 = "Move it to one of the places declared for this name, or declare this place for it.";
 var fixDescription = "Move the directory to one of the places declared for its name, rename it, or declare this place for the name.";
 var OPTIONS6 = {
   placements: { kind: "string-map", default: {} },
@@ -5670,7 +5720,7 @@ var architectureReservedNamePlacement = {
         route: dir,
         location: at,
         message: `${dir} is not one of the places declared for '${name}'.`,
-        recommendation: recommendation11,
+        recommendation: recommendation9,
         docsUrl: docsUrl11,
         fix: {
           description: fixDescription
@@ -5884,8 +5934,8 @@ var performanceNamespaceImport = componentRule({
 // src/rules/perf/minify-disabled.ts
 var PENALIZED7 = { presence: "none", value: "absent" };
 var MINIFY_DISABLED_FIX = {
-  description: "Remove the minify: false override from vite.config (Vite minifies with esbuild by default), or scope it to non-production builds.",
-  snippet: "export default defineConfig({\n  build: {\n    minify: 'esbuild'\n  }\n});",
+  description: "Remove the minify: false override from vite.config (Vite minifies by default), or scope it to non-production builds.",
+  snippet: "export default defineConfig({\n  build: {\n    // minify: false \u2014 removed; Vite minifies production builds by default\n  }\n});",
   lang: "ts"
 };
 var RECOMMENDATION4 = "Remove build.minify: false from vite.config, or scope it to non-production builds if it is intentional.";
@@ -6465,7 +6515,7 @@ function formatAgentReport(results, config) {
     return lines.join("\n").replace(/\n+$/, "\n");
   }
   lines.push(
-    `${failing.length} issue(s) to fix, ordered most-severe first. Fix critical issues first; warning and info items improve SEO but do not fail the default build. Apply each fix below, then re-run \`svelte-vitals\` (or the build) to confirm each rule passes.`,
+    `${failing.length} issue(s) to fix, ordered most-severe first. Fix critical issues first; warning and info items improve SEO but do not fail the default build. Apply each fix below, then re-run \`svelte-vitals\` (or the build) to confirm each rule passes. Run \`svelte-vitals explain <rule-id>\` for any rule's rationale and options (works offline).`,
     ""
   );
   const groups = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svelte-vitals/core",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Shared, runtime-agnostic core for svelte-vitals (types, rule engine, scorer, reporter).",
   "type": "module",
   "license": "MIT",