@svelte-vitals/core 0.38.0 → 0.40.0

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[];
 }
 
 /**
@@ -971,7 +978,7 @@ interface Rule {
     category: Category;
     /** Default severity (overridable by config in later slices). */
     severity: Severity;
-    /** 'route' = evaluated per route, 'project' = site-wide (design §10, §12). */
+    /** 'route' = evaluated per route, 'project' = site-wide, 'component' = evaluated per source file (design §10, §12). */
     scope: Scope;
     /** Why this rule matters — one or two sentences, surfaced by `svelte-vitals explain` (issue #24). */
     rationale: string;
@@ -1119,9 +1126,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 +1192,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.
  */
@@ -1268,11 +1282,19 @@ declare const architectureDirectoryNaming: Rule;
 
 /**
  * architecture/reserved-directory-names — a directory's immediate subdirectories may only take names
- * the project declared for that position (design 2026-07-29). L3: inert until a scope is declared.
+ * the project declared for that position (design 2026-07-29, extended 2026-08-08 for lowercase units —
+ * issue #386).
  *
- * Two option maps, differing in what their key names. A `scopes` key names the parent directly. A
+ * The option maps differ in what their keys name. A `scopes` key names the parent directly. A
  * `unitScopes` key names a root, and the rule governs the children of whichever directories beneath
- * it are units — the shape a glob cannot reach, because units nest to arbitrary depth.
+ * it are units whose name begins A–Z — the shape a glob cannot reach, because units nest to arbitrary
+ * depth. An `anyCaseUnitScopes` key names a root the same way, but governs units of *either* case:
+ * `isUnitDir`'s letter test — A–Z plus a same-stemmed entry file, whatever its extension — excludes a
+ * lowercase unit, so without this map no generic unit-map declaration governed one's children (a
+ * `scopes` key naming the parent directly could still reach one) — measured at 129 of 299 units (43%)
+ * on a real tree. Neither map is named with the bare word "unit": the
+ * sibling rule `architecture/reserved-name-placement` records why that word alone is ambiguous between
+ * the two predicates once both exist.
  *
  * There are no pass results. `computeScore` seeds every distinct `route` at 100 and averages, and the
  * subject here is a directory with no pre-existing score key, so a pass per directory would add

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) => {
@@ -826,7 +841,7 @@ function countProps(program) {
     if (n.type !== "VariableDeclarator" || !n.init || !isPropsCall(unwrapTs(n.init))) return;
     seen++;
     const props = n.id?.type === "ObjectPattern" ? n.id.properties : void 0;
-    if (!Array.isArray(props) || props.some((p) => p?.type === "RestElement")) {
+    if (!Array.isArray(props)) {
       uncountable = true;
       return;
     }
@@ -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;
@@ -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;
@@ -2737,6 +2758,13 @@ function imageRule(opts) {
             severity: opts.severity,
             detection: { presence: "own", value: "static" },
             route: route.route,
+            // No single route-level file exists here (unlike ResolvedHead.file) — the
+            // route's first image stands in as its attributed file (design
+            // 2026-08-08-pass-result-location-design.md; this uncaught inline PASS literal
+            // was missed by the design spike's grep and added to its blast-radius table
+            // afterward, maintainer ruling, same date). `route.images.length === 0` already
+            // continued above, so `[0]` is always defined here.
+            location: route.images[0].file,
             message: opts.label,
             recommendation: opts.recommendation,
             docsUrl: docsUrl12
@@ -2771,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" />',
@@ -2836,6 +2864,13 @@ function linkRule(opts) {
             severity: opts.severity,
             detection: { presence: "own", value: "static" },
             route: head.route,
+            // The route's own attributed file (design 2026-08-08-pass-result-location-design.md)
+            // — this uncaught inline PASS literal was missed by the design spike's grep and
+            // added to its blast-radius table afterward (maintainer ruling, same date). No
+            // single per-tag location applies here (many links can back one pass), so the
+            // route's own head file is the uniform attribution; per-tag penalized locations
+            // above remain per-tag.
+            location: head.file,
             message: opts.label,
             recommendation: opts.recommendation,
             docsUrl: docsUrl12
@@ -2938,6 +2973,11 @@ var performanceLcpImage = {
           severity: "warning",
           detection: { presence: "own", value: "static" },
           route: route.route,
+          // Same `location` the penalized branch above uses (design
+          // 2026-08-08-pass-result-location-design.md) — this uncaught inline PASS literal
+          // was missed by the design spike's grep and added to its blast-radius table
+          // afterward (maintainer ruling, same date).
+          location: first.file,
           message: "LCP image eager loading",
           recommendation,
           docsUrl
@@ -2992,6 +3032,10 @@ var performanceRenderBlockingScript = {
           severity: "warning",
           detection: { presence: "own", value: "static" },
           route: head.route,
+          // The route's own attributed file (design 2026-08-08-pass-result-location-design.md)
+          // — this uncaught inline PASS literal was missed by the design spike's grep and
+          // added to its blast-radius table afterward (maintainer ruling, same date).
+          location: head.file,
           message: "No render-blocking scripts",
           recommendation: recommendation2,
           docsUrl: docsUrl2
@@ -3210,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,
@@ -3247,6 +3291,10 @@ var performancePreconnect = {
           severity: "info",
           detection: { presence: "own", value: "static" },
           route: head.route,
+          // head.file — the same target used to resolve options above (design
+          // 2026-08-08-pass-result-location-design.md) — so a `files:`-scoped override can
+          // also match this passing seed via `severity: 'off'`.
+          location: head.file,
           message: "Third-party origins are preconnected",
           recommendation: recommendation3,
           docsUrl: docsUrl3
@@ -3330,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>',
@@ -3346,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>',
@@ -3370,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" />',
@@ -3535,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");
 }
@@ -3588,6 +3642,9 @@ function jsonldRule(opts) {
               severity: opts.severity,
               detection: PASS,
               route: head.route,
+              // Same `location` the penalized branch above uses (design
+              // 2026-08-08-pass-result-location-design.md).
+              location: head.file,
               message: opts.label,
               recommendation: opts.recommendation,
               docsUrl: docsUrl12
@@ -3641,6 +3698,9 @@ var seoJsonLdValidity = {
             severity: "warning",
             detection: PASS,
             route: head.route,
+            // Same `location` the penalized branch above uses (design
+            // 2026-08-08-pass-result-location-design.md).
+            location: head.file,
             message: "JSON-LD validity",
             recommendation: "Make the JSON-LD valid JSON with both @context and @type.",
             docsUrl: docsUrl12
@@ -3733,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(", ")}`;
       }
     }
@@ -3775,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})`;
@@ -3789,7 +3849,7 @@ function lengthRule(opts) {
             route: head.route,
             location,
             message: problem,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           } : {
             id: opts.id,
@@ -3797,8 +3857,13 @@ function lengthRule(opts) {
             severity: "info",
             detection: PASS,
             route: head.route,
+            // Same `location` the penalized branch above uses (design
+            // 2026-08-08-pass-result-location-design.md) — without it, a `files:`-scoped
+            // override can flip this result to PASS via its `options` but can never match
+            // it to also apply `severity: 'off'`.
+            location,
             message: opts.label,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           }
         );
@@ -3866,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
@@ -3874,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);
@@ -3885,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) {
@@ -3898,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 ? {
@@ -3911,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",
@@ -3920,8 +3990,11 @@ var seoHreflang = {
           severity: "warning",
           detection: PASS,
           route: head.route,
+          // Same `location` the penalized branch above uses (design
+          // 2026-08-08-pass-result-location-design.md).
+          location,
           message: "hreflang",
-          recommendation: recommendation4,
+          recommendation: passRecommendation,
           docsUrl: docsUrl4
         }
       );
@@ -3932,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 } : {} };
       }
@@ -3959,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",
@@ -3972,8 +4052,12 @@ var seoSingleH1 = {
           severity: "warning",
           detection: PASS,
           route: route.route,
+          // No single route-level file exists here (unlike ResolvedHead.file) — the
+          // passing route's own <h1> stands in as its attributed file (design
+          // 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
         }
       );
@@ -4021,6 +4105,9 @@ function uniquenessRule(opts) {
           severity: "warning",
           detection: PASS,
           route: e.route,
+          // Same `location` the penalized branch above uses (design
+          // 2026-08-08-pass-result-location-design.md).
+          location: e.file,
           message: opts.label,
           recommendation: opts.recommendation,
           docsUrl: docsUrl12
@@ -4054,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 ?? []) {
@@ -4086,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",
@@ -4094,8 +4181,13 @@ var seoHeadingLevelSkip = {
           severity: "info",
           detection: PASS,
           route: route.route,
+          // No single route-level file exists here (unlike ResolvedHead.file) — the
+          // route's first heading stands in as its attributed file (design
+          // 2026-08-08-pass-result-location-design.md). `route.headings.length === 0`
+          // already continued above, so `[0]` is always defined here.
+          location: route.headings[0].file,
           message: "Heading order",
-          recommendation: recommendation6,
+          recommendation: recommendation4,
           docsUrl: docsUrl6
         }
       );
@@ -4133,6 +4225,9 @@ function kitModuleRule(opts) {
             severity,
             detection: PASS2,
             route: m.file,
+            // Uniform PASS-result attribution (design 2026-08-08-pass-result-location-design.md):
+            // same location a penalized result for this file would carry.
+            location: m.file,
             message: opts.label,
             recommendation: opts.recommendation,
             docsUrl: docsUrl12
@@ -4202,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) {
@@ -4212,8 +4307,11 @@ function componentRule(opts) {
             severity,
             detection: PASS3,
             route: c.file,
+            // Uniform PASS-result attribution (design 2026-08-08-pass-result-location-design.md):
+            // same location a penalized result for this file would carry.
+            location: c.file,
             message: opts.label,
-            recommendation: recommendation12,
+            recommendation: recommendation10,
             docsUrl: docsUrl12
           });
           continue;
@@ -4228,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 } } : {}
           });
@@ -4284,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
@@ -4367,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."
   }))
 });
 
@@ -4386,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.
@@ -4405,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)));
 }
@@ -4417,6 +4526,9 @@ function emitFile(out, file, issues, suppressions) {
       severity: "critical",
       detection: PASS4,
       route: file,
+      // Uniform PASS-result attribution (design 2026-08-08-pass-result-location-design.md):
+      // same location a penalized result for this file would carry.
+      location: file,
       message: LABEL,
       recommendation: RECOMMENDATION,
       docsUrl: DOCS_URL
@@ -4444,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 ?? []) {
@@ -4468,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
       );
@@ -4508,6 +4620,9 @@ function emitFile2(out, file, links, suppressions) {
       severity: "warning",
       detection: PASS5,
       route: file,
+      // Uniform PASS-result attribution (design 2026-08-08-pass-result-location-design.md):
+      // same location a penalized result for this file would carry.
+      location: file,
       message: LABEL2,
       recommendation: RECOMMENDATION2,
       docsUrl: DOCS_URL2
@@ -4575,6 +4690,9 @@ function emitFile3(out, file, issues, suppressions) {
       severity: "critical",
       detection: PASS6,
       route: file,
+      // Uniform PASS-result attribution (design 2026-08-08-pass-result-location-design.md):
+      // same location a penalized result for this file would carry.
+      location: file,
       message: LABEL3,
       recommendation: RECOMMENDATION3,
       docsUrl: DOCS_URL3
@@ -4653,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" }))
@@ -4666,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" }))
 });
@@ -4678,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`
   }))
 });
 
@@ -4713,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));
@@ -4773,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("/");
@@ -4853,8 +4971,13 @@ var architecturePrivateScopeImport = {
           severity: "info",
           detection: { presence: "own", value: "static" },
           route: c.file,
+          // Same location the penalized branch below uses (design
+          // 2026-08-08-pass-result-location-design.md) — this uncaught inline PASS literal
+          // was missed by the design spike's grep and added to its blast-radius table
+          // afterward (maintainer ruling, same date).
+          location: c.file,
           message: "No private-scope imports",
-          recommendation: recommendation7,
+          recommendation: recommendation5,
           docsUrl: docsUrl7
         });
         continue;
@@ -4869,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 }
         });
@@ -4994,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: {} },
@@ -5031,6 +5154,8 @@ var architectureUnitEntryFile = {
       ...Object.keys(mapOption(globalOptions, "pascalCaseUnits"))
     ]);
     const usedKeys = /* @__PURE__ */ new Set();
+    const examinedCounts = {};
+    for (const key of globalKeys) examinedCounts[key] = 0;
     const excludedDirs = [];
     const matchedSurviving = /* @__PURE__ */ new Set();
     for (const dir of [...dirs].sort()) {
@@ -5058,6 +5183,10 @@ var architectureUnitEntryFile = {
         ext = byCasing.best === void 0 ? void 0 : pascalUnits[byCasing.best];
       }
       if (ext === void 0) continue;
+      const winningKey = viaUnits ? byPath.best : byCasing.best;
+      if (winningKey !== void 0 && globalKeys.has(winningKey)) {
+        examinedCounts[winningKey] = (examinedCounts[winningKey] ?? 0) + 1;
+      }
       const expected = `${dir}/${baseName(dir)}${ext}`;
       if (fileSet.has(expected)) {
         out.push({
@@ -5067,7 +5196,7 @@ var architectureUnitEntryFile = {
           detection: { presence: "own", value: "static" },
           location: expected,
           message: "Unit entry file",
-          recommendation: recommendation8,
+          recommendation: recommendation6,
           docsUrl: docsUrl8
         });
         continue;
@@ -5082,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.
@@ -5107,6 +5236,7 @@ var architectureUnitEntryFile = {
         docsUrl: docsUrl8
       });
     }
+    ctx.recordExamined?.(examinedCounts);
     return out;
   }
 };
@@ -5146,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: [] }
@@ -5180,6 +5310,8 @@ var architectureDirectoryNaming = {
     const globalOptions = resolveRuleOptions(ID5, OPTIONS4, ctx.config);
     const globalMap = mapOption(globalOptions, "directories");
     const globalKeys = new Set(Object.keys(globalMap));
+    const examinedCounts = {};
+    for (const key of globalKeys) examinedCounts[key] = 0;
     const usedKeys = /* @__PURE__ */ new Set();
     const excludedDirs = [];
     for (const dir of [...dirs].sort()) {
@@ -5197,6 +5329,7 @@ var architectureDirectoryNaming = {
       if (m.best === void 0) continue;
       const decoded = decodeSegment(baseName(dir));
       if (decoded === void 0) continue;
+      if (globalKeys.has(m.best)) examinedCounts[m.best] = (examinedCounts[m.best] ?? 0) + 1;
       const allowed = casingsOf(declared[m.best]).known;
       if (satisfiesCasing(decoded, allowed)) continue;
       const at = reportAt(dir, files);
@@ -5209,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." }
       });
@@ -5244,6 +5377,7 @@ var architectureDirectoryNaming = {
         docsUrl: docsUrl9
       });
     }
+    ctx.recordExamined?.(examinedCounts);
     return out;
   }
 };
@@ -5251,10 +5385,11 @@ 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: {} },
+  anyCaseUnitScopes: { kind: "string-map", default: {} },
   exclude: { kind: "string-list", default: [] }
 };
 function stem(file) {
@@ -5270,6 +5405,7 @@ function isAnyCaseUnitDir(dir, filesIn) {
   const own = filesIn.get(dir);
   return own !== void 0 && own.some((f) => stem(f) === name);
 }
+var PRIORITY = { scopes: 0, unitScopes: 1, anyCaseUnitScopes: 2 };
 var architectureReservedDirectoryNames = {
   id: ID6,
   title: "Reserved directory names",
@@ -5301,26 +5437,45 @@ var architectureReservedDirectoryNames = {
     const globalOptions = resolveRuleOptions(ID6, OPTIONS5, ctx.config);
     const globalScopes = mapOption(globalOptions, "scopes");
     const globalUnits = mapOption(globalOptions, "unitScopes");
-    const globalKeys = /* @__PURE__ */ new Set([...Object.keys(globalScopes), ...Object.keys(globalUnits)]);
+    const globalAnyUnits = mapOption(globalOptions, "anyCaseUnitScopes");
+    const globalKeys = /* @__PURE__ */ new Set([
+      ...Object.keys(globalScopes),
+      ...Object.keys(globalUnits),
+      ...Object.keys(globalAnyUnits)
+    ]);
     const usedKeys = /* @__PURE__ */ new Set();
     const excludedDirs = [];
     const nonUnitDirs = [];
-    const collisions = /* @__PURE__ */ new Set();
-    const noteCollisions = (scopesMap, unitMap) => {
+    const nonAnyUnitDirs = [];
+    const collisions = /* @__PURE__ */ new Map();
+    const collisionMessage = (losers) => {
+      const maps = ["scopes", ...losers];
+      const list = maps.length === 2 ? `both ${maps[0]} and ${maps[1]}` : maps.join(", ");
+      return `declared in ${list}, so the scopes entry wins wherever ${losers.length > 1 ? "they" : "both"} apply`;
+    };
+    const examinedCounts = {};
+    for (const key of globalKeys) examinedCounts[key] = 0;
+    const noteCollisions = (scopesMap, unitMap, anyUnitMap) => {
       for (const key of Object.keys(scopesMap)) {
-        if (!Object.hasOwn(unitMap, key)) continue;
         if (namesOf(scopesMap[key]).length === 0) continue;
-        if (namesOf(unitMap[key]).length === 0) continue;
-        collisions.add(key);
+        const losers = [];
+        if (Object.hasOwn(unitMap, key) && namesOf(unitMap[key]).length > 0) losers.push("unitScopes");
+        if (Object.hasOwn(anyUnitMap, key) && namesOf(anyUnitMap[key]).length > 0) {
+          losers.push("anyCaseUnitScopes");
+        }
+        if (losers.length > 0) collisions.set(key, collisionMessage(losers));
       }
     };
-    noteCollisions(globalScopes, globalUnits);
+    noteCollisions(globalScopes, globalUnits, globalAnyUnits);
     for (const dir of [...dirs].sort()) {
       const o = resolveRuleOptions(ID6, OPTIONS5, ctx.config, { route: dir, file: dir }, compiledOverrides);
       const scopes = mapOption(o, "scopes");
       const unitScopes = mapOption(o, "unitScopes");
-      if (Object.keys(scopes).length === 0 && Object.keys(unitScopes).length === 0) continue;
-      noteCollisions(scopes, unitScopes);
+      const anyCaseUnitScopes = mapOption(o, "anyCaseUnitScopes");
+      if (Object.keys(scopes).length === 0 && Object.keys(unitScopes).length === 0 && Object.keys(anyCaseUnitScopes).length === 0) {
+        continue;
+      }
+      noteCollisions(scopes, unitScopes, anyCaseUnitScopes);
       const excluded = compile(listOption(o, "exclude"));
       if (isExcluded(dir, ancestorDirs2(dir), excluded)) {
         excludedDirs.push(dir);
@@ -5328,22 +5483,46 @@ var architectureReservedDirectoryNames = {
       }
       const liveScopes = Object.keys(scopes).filter((k) => namesOf(scopes[k]).length > 0);
       const isUnit = isUnitDir(dir, filesIn);
+      const isAnyUnit = isAnyCaseUnitDir(dir, filesIn);
       const liveUnits = isUnit ? Object.keys(unitScopes).filter((k) => namesOf(unitScopes[k]).length > 0) : [];
+      const liveAnyUnits = isAnyUnit ? Object.keys(anyCaseUnitScopes).filter((k) => namesOf(anyCaseUnitScopes[k]).length > 0) : [];
       if (!isUnit) nonUnitDirs.push(dir);
+      if (!isAnyUnit) nonAnyUnitDirs.push(dir);
       const byPosition = matchKeys(dir, compile(liveScopes, true));
       const byUnit = matchKeys(dir, compile(liveUnits, true));
+      const byAnyUnit = matchKeys(dir, compile(liveAnyUnits, true));
       for (const k of byPosition.matched) if (globalKeys.has(k)) usedKeys.add(k);
       for (const k of byUnit.matched) if (globalKeys.has(k)) usedKeys.add(k);
-      let governing;
-      if (byPosition.best !== void 0 && byUnit.best !== void 0) {
-        governing = moreSpecificGlob(byUnit.best, byPosition.best) ? namesOf(unitScopes[byUnit.best]) : namesOf(scopes[byPosition.best]);
-      } else if (byPosition.best !== void 0) {
-        governing = namesOf(scopes[byPosition.best]);
-      } else if (byUnit.best !== void 0) {
-        governing = namesOf(unitScopes[byUnit.best]);
+      for (const k of byAnyUnit.matched) if (globalKeys.has(k)) usedKeys.add(k);
+      const candidates = [];
+      if (byPosition.best !== void 0) {
+        candidates.push({ kind: "scopes", best: byPosition.best, names: namesOf(scopes[byPosition.best]) });
+      }
+      if (byUnit.best !== void 0) {
+        candidates.push({
+          kind: "unitScopes",
+          best: byUnit.best,
+          names: namesOf(unitScopes[byUnit.best])
+        });
       }
-      if (governing === void 0) continue;
-      const allowed = new Set(governing);
+      if (byAnyUnit.best !== void 0) {
+        candidates.push({
+          kind: "anyCaseUnitScopes",
+          best: byAnyUnit.best,
+          names: namesOf(anyCaseUnitScopes[byAnyUnit.best])
+        });
+      }
+      let winner;
+      for (const c of candidates) {
+        if (winner === void 0 || moreSpecificGlob(c.best, winner.best)) {
+          winner = c;
+        } else if (!moreSpecificGlob(winner.best, c.best) && PRIORITY[c.kind] < PRIORITY[winner.kind]) {
+          winner = c;
+        }
+      }
+      if (winner === void 0) continue;
+      if (globalKeys.has(winner.best)) examinedCounts[winner.best] = (examinedCounts[winner.best] ?? 0) + 1;
+      const allowed = new Set(winner.names);
       for (const child of kids.get(dir) ?? []) {
         if (allowed.has(baseName(child))) continue;
         if (isExcluded(child, ancestorDirs2(child), excluded)) continue;
@@ -5364,8 +5543,8 @@ var architectureReservedDirectoryNames = {
           detection: { presence: "none", value: "absent" },
           route: child,
           location: at,
-          message: `${child} is not one of the names declared here: ${governing.join(", ")}.`,
-          recommendation: recommendation10,
+          message: `${child} is not one of the names declared here: ${winner.names.join(", ")}.`,
+          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."
@@ -5374,19 +5553,24 @@ var architectureReservedDirectoryNames = {
       }
     }
     const notes = /* @__PURE__ */ new Map();
-    for (const key of collisions) {
-      notes.set(key, "declared in both scopes and unitScopes, so the scopes entry wins wherever both apply");
-    }
+    for (const [key, message] of collisions) notes.set(key, message);
     for (const key of globalKeys) {
       if (notes.has(key)) continue;
       const scopesEmpty = Object.hasOwn(globalScopes, key) && namesOf(globalScopes[key]).length === 0;
       const unitsEmpty = Object.hasOwn(globalUnits, key) && namesOf(globalUnits[key]).length === 0;
-      if (scopesEmpty || unitsEmpty) {
+      const anyUnitsEmpty = Object.hasOwn(globalAnyUnits, key) && namesOf(globalAnyUnits[key]).length === 0;
+      if (scopesEmpty || unitsEmpty || anyUnitsEmpty) {
         notes.set(key, "names no directory name at all");
       }
     }
     const unused = [...globalKeys].filter((k) => !notes.has(k) && !usedKeys.has(k));
-    const unitOnly = unused.filter((k) => Object.hasOwn(globalUnits, k) && !Object.hasOwn(globalScopes, k));
+    const anyUnitOnly = unused.filter((k) => Object.hasOwn(globalAnyUnits, k) && !Object.hasOwn(globalScopes, k));
+    for (const key of keysMatchingAny(anyUnitOnly, nonAnyUnitDirs, compile)) {
+      notes.set(key, "matched directories but never a unit of either case");
+    }
+    const unitOnly = unused.filter(
+      (k) => Object.hasOwn(globalUnits, k) && !Object.hasOwn(globalScopes, k) && !notes.has(k)
+    );
     for (const key of keysMatchingAny(unitOnly, nonUnitDirs, compile)) {
       notes.set(key, "matched directories but never a unit");
     }
@@ -5410,6 +5594,7 @@ var architectureReservedDirectoryNames = {
         docsUrl: docsUrl10
       });
     }
+    ctx.recordExamined?.(examinedCounts);
     return out;
   }
 };
@@ -5417,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: {} },
@@ -5535,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
@@ -5749,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.";
@@ -6330,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();
@@ -6612,6 +6797,7 @@ body{background:var(--ground);color:var(--ink);font-family:var(--sans);line-heig
 .dv-cat-top{display:flex;justify-content:space-between;font-size:13px;margin-bottom:6px}
 .dv-bar{height:7px;border-radius:999px;background:var(--line);overflow:hidden}
 .dv-bar>i{display:block;height:100%;border-radius:999px}
+.dv-cat-reach{font-size:11.5px;color:var(--muted);margin-top:5px}
 .dv-filters{display:flex;gap:8px;flex-wrap:wrap;margin:16px 0}
 .dv-chip{font:inherit;font-size:12.5px;font-weight:600;cursor:pointer;background:var(--panel);border:1px solid var(--line-strong);color:var(--muted);padding:5px 12px;border-radius:999px}
 .dv-chip[aria-pressed="true"]{background:var(--active-bg);border-color:var(--active-bg);color:var(--active-ink)}
@@ -7084,12 +7270,21 @@ var APP_SCRIPT = `
       var band = scoreBand(c.score);
       var weight = s.report.weights[cat];
       var name = cat === 'seo' ? 'SEO' : cat.charAt(0).toUpperCase() + cat.slice(1);
+      // keys/affectedKeys are absent on hand-built snapshots (older fixtures, tests) \u2014
+      // render nothing rather than "undefined of undefined". 0 affected of N keys is still
+      // rendered: on a real project that's the signal a thin score can't give, that the
+      // category is clean project-wide and not just on the one key it happened to look at
+      // (design: 2026-08-05-score-floor-and-reach-design.md).
+      var reach = typeof c.keys === 'number' && c.keys > 0
+        ? h('div', { class: 'dv-cat-reach', text: c.affectedKeys + ' of ' + c.keys + ' keys affected' }, [])
+        : null;
       return h('div', { class: 'dv-cat' }, [
         h('div', { class: 'dv-cat-top' }, [
           h('span', { text: name + (weight !== undefined ? ' (weight ' + weight + ')' : '') }, []),
           h('span', { style: 'color:' + BAND_COLOR[band], text: String(c.score) }, [])
         ]),
-        h('div', { class: 'dv-bar' }, [h('i', { style: 'width:' + c.score + '%;background:' + BAND_COLOR[band] }, [])])
+        h('div', { class: 'dv-bar' }, [h('i', { style: 'width:' + c.score + '%;background:' + BAND_COLOR[band] }, [])]),
+        reach
       ]);
     });
     var chips = renderFilterChips(s.report.categories);

package/package.json

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