svelte-vitals 0.23.0 → 0.25.0

package/README.md

@@ -9,7 +9,7 @@
 > **ESM-only** (Node 18+). Ships ES modules only; `require()` is unsupported by design.
 
 ```bash
-npx svelte-vitals
+npx svelte-vitals@latest
 ```
 
 > [!NOTE]
@@ -20,8 +20,8 @@ npx svelte-vitals
 Run inside any SvelteKit project:
 
 ```bash
-npx svelte-vitals          # analyze the current directory
-npx svelte-vitals ./apps/web   # or a specific path
+npx svelte-vitals@latest              # analyze the current directory
+npx svelte-vitals@latest ./apps/web   # or a specific path
 ```
 
 ```
@@ -40,6 +40,8 @@ Passed (3)
 
 By default, console output groups failures by rule (top 5 per severity, each with one example location and an "…and N more" count) and collapses the Passed section to a bare count, so large projects don't flood the terminal. Pass `--verbose` to see every finding uncapped and ungrouped, with each passed item listed individually. On an interactive, color-capable terminal the Health score plays a short reveal animation; pass `--no-animation` to disable it.
 
+On an interactive terminal wide enough for the mascot (20+ columns), a small line-art face appears alongside both the analysis spinner and the Health-score reveal, reacting to the score (a perfect 100 gets a confetti flourish). On a wider terminal still (55+ columns) it also greets you with a short line in a speech bubble at startup, and again with a matching reaction line at the score reveal. `--no-animation` disables all of it, falling back to the plain spinner and plain score animation.
+
 ### Exit codes
 
 | Code | Meaning                                                         |

package/dist/bin.js

@@ -7,7 +7,7 @@ import {
   readCoreVersion,
   readPackageVersion,
   run
-} from "./chunk-HYTPZVSU.js";
+} from "./chunk-OCLDCX4Y.js";
 
 // src/bin.ts
 import mri3 from "mri";
@@ -109,9 +109,7 @@ function resolveArgs(argv) {
     errors.push(`Known rule ids: ${knownRuleIds().join(", ")}`);
   }
   let reporter;
-  if (argv.json) {
-    reporter = "json";
-  } else if (typeof argv.reporter === "string") {
+  if (typeof argv.reporter === "string") {
     if (!isReporterName(argv.reporter)) {
       errors.push(
         `svelte-vitals: unknown reporter '${argv.reporter}'. Valid values: console, json, agent, sarif, github, html, md.`
@@ -127,14 +125,21 @@ function resolveArgs(argv) {
       `svelte-vitals: unknown --fail-on '${failOnRaw}'; expected critical|warning|info. No threshold applied.`
     );
   }
-  const failOn = argv["fail-on-warning"] ? "warning" : failOnValid ? failOnRaw : void 0;
+  const failOn = failOnValid ? failOnRaw : void 0;
   const weights = parseWeights(argv.weights, errors);
   const categories = parseCategories(argv.category, errors);
   const score = Boolean(argv.score);
-  if (score && (argv.json || typeof argv.reporter === "string")) {
+  if (score && typeof argv.reporter === "string") {
     warnings.push("svelte-vitals: --score overrides --reporter; reporter output suppressed.");
   }
   const verbose = Boolean(argv["verbose"]);
+  const noColor = argv.color === false;
+  const noAnimation = argv.animation === false;
+  const noSuppressions = argv.suppressions === false;
+  const updateSuppressions = Boolean(argv["update-suppressions"]);
+  if (updateSuppressions && noSuppressions) {
+    errors.push("svelte-vitals: --update-suppressions and --no-suppressions cannot be used together.");
+  }
   const rulesConfig = buildRulesConfig(allow, ignore);
   const rules = Object.keys(rulesConfig).length > 0 ? rulesConfig : void 0;
   if (errors.length > 0) return { options: null, warnings, errors };
@@ -156,9 +161,13 @@ function resolveArgs(argv) {
       ...categories !== void 0 ? { categories } : {},
       ...score ? { score } : {},
       ...verbose ? { verbose } : {},
+      ...noColor ? { noColor } : {},
+      ...noAnimation ? { noAnimation } : {},
       ...diffBase !== void 0 ? { diffBase } : {},
       ...staged ? { staged } : {},
-      ...baselineRef !== void 0 ? { baseline: baselineRef } : {}
+      ...baselineRef !== void 0 ? { baseline: baselineRef } : {},
+      ...noSuppressions ? { noSuppressions } : {},
+      ...updateSuppressions ? { updateSuppressions } : {}
     },
     warnings,
     errors
@@ -267,9 +276,9 @@ var VITE_TARGETS = [
     hint: "Fails `vite build` when prerendered pages cross the SEO/Performance threshold"
   },
   {
-    id: "vite-dev-overlay",
-    label: "Dev overlay",
-    hint: "Live warnings in `vite dev` only \u2014 never fails a build or CI"
+    id: "vite-hooks",
+    label: "Live dashboard accuracy",
+    hint: "Feeds real rendered results into the live dashboard as you browse \u2014 improves per-route accuracy, never fails a build"
   }
 ];
 function viteTargetById(id) {
@@ -301,6 +310,22 @@ function isAgentTargetId(id) {
   return AGENT_TARGETS.some((t) => t.id === id);
 }
 
+// src/install/config-targets.ts
+var CONFIG_TARGETS = [
+  {
+    id: "config-file",
+    label: "Config file",
+    hint: "Scaffolds svelte-vitals.config.mjs with every option commented out",
+    relPath: "svelte-vitals.config.mjs"
+  }
+];
+function configTargetById(id) {
+  return CONFIG_TARGETS.find((t) => t.id === id);
+}
+function isConfigTargetId(id) {
+  return CONFIG_TARGETS.some((t) => t.id === id);
+}
+
 // src/install/skill-content.ts
 import { allRules, docsUrlFor } from "@svelte-vitals/core";
 var CATEGORY_ORDER = ["seo", "performance", "correctness", "security", "architecture"];
@@ -366,6 +391,19 @@ alwaysApply: false
 ${sharedBody(version)}`;
 }
 
+// src/install/config-content.ts
+function buildConfigFileTemplate() {
+  return `// svelte-vitals config file \u2014 https://oekazuma.github.io/svelte-vitals/guides/configuration/
+export default {
+  // treatDynamicAs: 'pass', // 'pass' | 'warn' | 'fail' \u2014 how {data.title}-style dynamic values are scored
+  // metaComponents: ['Seo'], // component names that resolve SEO tags into <head>
+  // rules: {}, // e.g. { SEO001: 'off' } to disable a rule
+  // failOn: 'critical', // 'critical' | 'warning' | 'info'
+  // weights: {} // e.g. { seo: 2 } \u2014 per-category weight for the combined Health score
+};
+`;
+}
+
 // src/install/codemod-vite-config.ts
 import { parseModule, generateCode, builders, MagicastError } from "magicast";
 var MANUAL_SNIPPET = `import { svelteVitals } from '@svelte-vitals/vite';
@@ -529,10 +567,10 @@ function planForVitePlugin(io) {
   const result = codemodViteConfig(content);
   return { id: "vite-plugin", label: viteTargetById("vite-plugin").label, path, ...result };
 }
-function planForDevOverlay(io) {
+function planForViteHooks(io) {
   const { path, content } = resolveCandidate(io, ["src/hooks.server.ts", "src/hooks.server.js"]);
   const result = codemodHooksServer(content);
-  return { id: "vite-dev-overlay", label: viteTargetById("vite-dev-overlay").label, path, ...result };
+  return { id: "vite-hooks", label: viteTargetById("vite-hooks").label, path, ...result };
 }
 function planForAgentTarget(target, io, force, version) {
   const path = join3(io.cwd, target.relPath);
@@ -541,6 +579,13 @@ function planForAgentTarget(target, io, force, version) {
   const status = existing === void 0 ? "created" : force ? "updated" : "exists";
   return { id: target.id, label: target.label, path, status, content };
 }
+function planForConfigTarget(target, io, force) {
+  const path = join3(io.cwd, target.relPath);
+  const existing = io.readFile(path);
+  const content = buildConfigFileTemplate();
+  const status = existing === void 0 ? "created" : force ? "updated" : "exists";
+  return { id: target.id, label: target.label, path, status, content };
+}
 function indent(text) {
   return text.split("\n").map((l) => `      ${l}`).join("\n");
 }
@@ -549,7 +594,57 @@ function rowLine(r) {
   return r.status === "manual" && r.snippet ? `${head}
 ${indent(r.snippet)}` : head;
 }
+async function runRefresh(io, flags, version) {
+  let hadFailure = false;
+  const rows = [];
+  for (const target of AGENT_TARGETS) {
+    const path = join3(io.cwd, target.relPath);
+    try {
+      if (io.readFile(path) === void 0) continue;
+      rows.push(planForAgentTarget(
+        target,
+        io,
+        /* force */
+        true,
+        version
+      ));
+    } catch (err) {
+      hadFailure = true;
+      io.errorLog(`svelte-vitals: failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (rows.length === 0) {
+    if (hadFailure) return 2;
+    io.errorLog(
+      "svelte-vitals: no generated agent files found \u2014 run `svelte-vitals install --client claude-skill,cursor-rules` first."
+    );
+    return 0;
+  }
+  const planText = rows.map(rowLine).join("\n");
+  io.log("Plan:");
+  io.log(planText);
+  if (flags.dryRun) {
+    io.log("Dry run \u2014 no files written.");
+    return hadFailure ? 2 : 0;
+  }
+  for (const r of rows) {
+    try {
+      io.writeFile(r.path, r.content ?? "");
+      io.log(`\u2713 ${r.label}: ${r.status} ${r.path}`);
+    } catch (err) {
+      hadFailure = true;
+      io.errorLog(`svelte-vitals: failed to write ${r.path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (hadFailure) return 2;
+  io.log("");
+  io.log(`\u2713 refreshed ${rows.length} file(s).`);
+  return 0;
+}
 async function runInstall(flags, io, prompts, version = "0.0.0") {
+  if (flags.refresh) {
+    return runRefresh(io, flags, version);
+  }
   let ids;
   if (flags.client && flags.client.length > 0) {
     ids = flags.client;
@@ -581,7 +676,8 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     const options = [
       ...CLIENTS.map((c) => ({ id: c.id, label: c.label })),
       ...VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
-      ...AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
+      ...AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+      ...CONFIG_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
     ];
     const picked = await prompts.selectClients(options, detected);
     if (picked === null) {
@@ -591,14 +687,15 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     ids = picked;
   } else {
     io.errorLog(
-      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-dev-overlay,claude-skill,cursor-rules> to install non-interactively."
+      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,config-file> to install non-interactively."
     );
     return 2;
   }
   const clients = ids.map(clientById).filter((c) => c !== void 0);
   const viteIds = ids.filter(isViteTargetId);
   const agentIds = ids.filter(isAgentTargetId);
-  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0) {
+  const configIds = ids.filter(isConfigTargetId);
+  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0 && configIds.length === 0) {
     io.errorLog("svelte-vitals: no valid clients or targets selected.");
     return 2;
   }
@@ -630,12 +727,16 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     }
   }
   for (const viteId of viteIds) {
-    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io) : planForDevOverlay(io));
+    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io) : planForViteHooks(io));
   }
   for (const agentId of agentIds) {
     const target = agentTargetById(agentId);
     rows.push(planForAgentTarget(target, io, flags.force ?? false, version));
   }
+  for (const configId of configIds) {
+    const target = configTargetById(configId);
+    rows.push(planForConfigTarget(target, io, flags.force ?? false));
+  }
   const planText = rows.map(rowLine).join("\n");
   io.log("Plan:");
   io.log(planText);
@@ -724,14 +825,22 @@ function resolveInstallArgs(argv) {
     if (rawScope === "project" || rawScope === "global") scope = rawScope;
     else errors.push(`svelte-vitals: unknown --scope '${rawScope}'; expected project|global.`);
   }
+  const refresh = Boolean(argv.refresh);
+  if (refresh && rawClients.length > 0) {
+    errors.push("svelte-vitals: --refresh regenerates existing files and cannot be combined with --client.");
+  }
   if (errors.length > 0) return { flags: null, warnings, errors };
+  if (refresh && (scope !== void 0 || Boolean(argv.yes) || Boolean(argv.force))) {
+    warnings.push("svelte-vitals: --scope, --yes, and --force are ignored with --refresh.");
+  }
   return {
     flags: {
       ...client.length > 0 ? { client } : {},
       ...scope ? { scope } : {},
       yes: Boolean(argv.yes),
       dryRun: Boolean(argv["dry-run"]),
-      force: Boolean(argv.force)
+      force: Boolean(argv.force),
+      ...refresh ? { refresh: true } : {}
     },
     warnings,
     errors
@@ -745,18 +854,24 @@ Usage:
   svelte-vitals install [options]
 
 Options:
-  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-dev-overlay,claude-skill,cursor-rules
+  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,config-file
                     (skips the interactive picker)
-                    vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-dev-overlay
-                    wires up the dev-overlay hook in src/hooks.server.{ts,js}. --force does not apply
+                    vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-hooks
+                    wires up the svelteVitalsHandle hook in src/hooks.server.{ts,js}, which improves the
+                    live dashboard's per-route accuracy as you browse. --force does not apply
                     to either of these two \u2014 an existing registration is always left as-is.
                     claude-skill writes a Claude Code skill (.claude/skills/svelte-vitals/SKILL.md); cursor-rules
                     writes a Cursor rules file (.cursor/rules/svelte-vitals.mdc). Both are generated from the
                     current rule set and support --force to regenerate.
+                    config-file scaffolds svelte-vitals.config.mjs with every option commented out;
+                    supports --force to regenerate.
   --scope <scope>   project | global (applies to all selected clients; codex is always global)
   --yes, -y         Skip the confirmation prompt
   --dry-run         Print the planned changes and exit without writing
   --force           Overwrite an existing svelte-vitals entry
+  --refresh         Regenerate existing agent skill/rules files with the current rule set
+                    (claude-skill / cursor-rules). Only regenerates files already present on
+                    disk \u2014 it never creates one. Cannot be combined with --client.
   -h, --help        Show this help`;
 function realIO() {
   return {
@@ -824,7 +939,7 @@ ${planText}` });
 }
 async function runInstallCli(args) {
   const argv = mri(args, {
-    boolean: ["yes", "dry-run", "force", "help"],
+    boolean: ["yes", "dry-run", "force", "refresh", "help"],
     string: ["client", "scope"],
     alias: { y: "yes", h: "help" }
   });
@@ -881,22 +996,56 @@ function buildWorkflowYaml(opts) {
   ].join("\n");
 }
 
+// src/ci/upgrade.ts
+var ACTION_USES_LINE = /^(?<indent>\s*-\s*uses:\s*(?:&\S+\s+)?oekazuma\/svelte-vitals\/packages\/action@)(?<ref>[^\s#]+)(?<comment>\s*#.*)?$/;
+function upgradeActionPin(content, sha, version) {
+  const lines = content.split("\n");
+  let replaced = 0;
+  let from;
+  const next = lines.map((line) => {
+    const eol = line.endsWith("\r") ? "\r" : "";
+    const bare = eol ? line.slice(0, -1) : line;
+    const match = ACTION_USES_LINE.exec(bare);
+    if (!match || !match.groups) return line;
+    const { indent: indent2, ref } = match.groups;
+    if (indent2 === void 0 || ref === void 0) return line;
+    if (ref === sha) return line;
+    if (from === void 0) {
+      const commentMatch = /#\s*@svelte-vitals\/action@(\S+)/.exec(match.groups.comment ?? "");
+      from = commentMatch ? commentMatch[1] : ref.slice(0, 7);
+    }
+    replaced += 1;
+    return `${indent2}${sha} # @svelte-vitals/action@${version}${eol}`;
+  });
+  if (replaced === 0) {
+    const hasAnyReference = lines.some((line) => ACTION_USES_LINE.test(line.endsWith("\r") ? line.slice(0, -1) : line));
+    return { status: hasAnyReference ? "up-to-date" : "no-reference" };
+  }
+  return { status: "upgraded", content: next.join("\n"), replaced, from };
+}
+
 // src/ci/action-pin.generated.ts
-var ACTION_SHA = "caf278cf4030801b017d31b108fa46abc15e8105";
-var ACTION_VERSION = "0.2.2";
+var ACTION_SHA = "2c21acbad36c5360228bbb0790dbb4a06b7c773a";
+var ACTION_VERSION = "0.3.0";
 
 // src/ci/cli.ts
 var CI_HELP = `svelte-vitals ci \u2014 scaffold CI integration
 
 Usage:
   svelte-vitals ci install [options]
+  svelte-vitals ci upgrade [--dry-run]
 
 Adds a GitHub Actions workflow (${WORKFLOW_PATH}) that calls the \`@svelte-vitals/action\`
 GitHub Action on pull requests: inline annotations, a job summary, and a sticky PR
 comment with the findings.
 
+\`ci upgrade\` rewrites only the pinned \`@svelte-vitals/action\` reference in an existing
+workflow to the pin bundled with this CLI, leaving the rest of the file (and any other
+pins, like actions/checkout) untouched. To pick up the latest pin, run
+\`npx svelte-vitals@latest ci upgrade\`.
+
 Options:
-  --force       Overwrite an existing workflow file
+  --force       Overwrite an existing workflow file (install only)
   --dry-run     Print the plan and exit without writing
   -h, --help    Show this help`;
 async function runCiCli(args, io = realIO()) {
@@ -905,6 +1054,9 @@ async function runCiCli(args, io = realIO()) {
     io.log(CI_HELP);
     return 0;
   }
+  if (sub === "upgrade") {
+    return runCiUpgrade(args.slice(1), io);
+  }
   if (sub !== "install") {
     io.log(CI_HELP);
     return 2;
@@ -942,6 +1094,44 @@ async function runCiCli(args, io = realIO()) {
   io.log("Done. Commit the workflow file and open a PR to see it in action.");
   return 0;
 }
+async function runCiUpgrade(args, io) {
+  const argv = mri2(args, {
+    boolean: ["dry-run", "help"],
+    alias: { h: "help" }
+  });
+  if (argv.help) {
+    io.log(CI_HELP);
+    return 0;
+  }
+  const path = join4(io.cwd, WORKFLOW_PATH);
+  const existing = io.readFile(path);
+  if (existing === void 0) {
+    io.errorLog(`svelte-vitals: no ${WORKFLOW_PATH} found \u2014 run \`svelte-vitals ci install\` first.`);
+    return 2;
+  }
+  const outcome = upgradeActionPin(existing, ACTION_SHA, ACTION_VERSION);
+  if (outcome.status === "no-reference") {
+    io.errorLog(`svelte-vitals: no @svelte-vitals/action reference found in ${WORKFLOW_PATH}.`);
+    return 2;
+  }
+  if (outcome.status === "up-to-date") {
+    io.log(`= already up to date (@svelte-vitals/action@${ACTION_VERSION}).`);
+    return 0;
+  }
+  if (argv["dry-run"]) {
+    io.log(`Would upgrade @svelte-vitals/action: ${outcome.from} \u2192 ${ACTION_VERSION} (${outcome.replaced} line(s)).`);
+    io.log("Dry run \u2014 no files written.");
+    return 0;
+  }
+  try {
+    io.writeFile(path, outcome.content ?? existing);
+  } catch (err) {
+    io.errorLog(`svelte-vitals: failed to write ${WORKFLOW_PATH}: ${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+  io.log(`\u2713 upgraded @svelte-vitals/action: ${outcome.from} \u2192 ${ACTION_VERSION} (${outcome.replaced} line(s)).`);
+  return 0;
+}
 
 // src/bin.ts
 var HELP = `svelte-vitals \u2014 a deterministic SvelteKit code-health scanner (SEO \xB7 performance \xB7 correctness \xB7 security \xB7 architecture)
@@ -950,6 +1140,7 @@ Usage:
   svelte-vitals [path] [options]
   svelte-vitals install          Set up the MCP server, Vite integration, or agent skills/rules
   svelte-vitals ci install       Add a GitHub Actions PR gate (annotations + summary comment)
+  svelte-vitals ci upgrade       Refresh the pinned @svelte-vitals/action in an existing workflow
 
 Options:
   --meta-components <names>   Comma-separated component names that emit head metadata
@@ -958,12 +1149,12 @@ Options:
   --diff [ref]                Report only findings in files changed vs ref (default HEAD; e.g. --diff main)
   --staged                    Report only findings in files staged for commit (pre-commit gate)
   --baseline <ref>            Report only findings not present at ref (compare against e.g. origin/main)
+  --update-suppressions       Write svelte-vitals-suppressions.json accepting all current findings (introduce gates on legacy projects)
+  --no-suppressions           Ignore svelte-vitals-suppressions.json for this run
   --by-route                  Show per-route score breakdown in console output
   --reporter <fmt>            console | json | agent | sarif | github | html | md (auto: agent under AI-agent envs, github under GitHub Actions)
   --out-file <path>           Output path for --reporter html (default: svelte-vitals-report.html; '-' for stdout)
-  --json                      Alias for --reporter=json
   --fail-on <severity>        Fail (exit 1) when any finding reaches this severity: critical | warning | info
-  --fail-on-warning           Alias for --fail-on=warning
   --min-health <0-100>        Fail (exit 1) when the combined Health score is below this value
   --rules <ids>               Comma-separated rule ids to enable (all others disabled)
   --ignore <ids>              Comma-separated rule ids to disable
@@ -971,7 +1162,7 @@ Options:
   --weights <pairs>           Per-category Health weight overrides, e.g. seo=2,performance=1 (unlisted categories default to 1)
   --score                     Print only the combined Health score (works with --min-health for gating)
   --no-color                  Disable ANSI color in console output
-  --no-animation               Disable the Health-score reveal animation on an interactive terminal
+  --no-animation               Disable the Health-score reveal animation and mascot on an interactive terminal
   --verbose                    Show every finding uncapped and ungrouped (default: capped, grouped by rule)
   -h, --help                  Show this help
   -v, --version               Show version
@@ -1003,7 +1194,7 @@ async function main() {
   }
   const argv = mri3(process.argv.slice(2), {
     alias: { h: "help", v: "version" },
-    boolean: ["by-route", "json", "fail-on-warning", "staged", "no-color", "score", "verbose", "no-animation"],
+    boolean: ["by-route", "staged", "score", "verbose", "update-suppressions"],
     string: [
       "meta-components",
       "treat-dynamic-as",
@@ -1045,8 +1236,6 @@ async function main() {
   const code = await run({
     ...options,
     minHealth,
-    noColor: argv["no-color"],
-    noAnimation: argv["no-animation"],
     selectApp
   });
   process.exit(code);

package/dist/{chunk-HYTPZVSU.js → chunk-OCLDCX4Y.js}

@@ -1,6 +1,6 @@
 // src/index.ts
-import { mkdirSync, writeFileSync } from "fs";
-import { dirname as dirname2, join as join5 } from "path";
+import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
 import {
   allRules as allRules2,
   runRules,
@@ -637,9 +637,8 @@ async function resolveRoute(rt, cwd, pageRel, config, layouts, cache) {
     headings: { route, headings }
   };
 }
-async function collectRoutes(rt, cwd, config = defaultConfig) {
+async function collectRoutes(rt, cwd, config = defaultConfig, cache = /* @__PURE__ */ new Map()) {
   const [pages, layouts] = await Promise.all([enumerateRoutePages(rt, cwd), collectLayouts(rt, cwd)]);
-  const cache = /* @__PURE__ */ new Map();
   const facts = await Promise.all(pages.map((page) => resolveRoute(rt, cwd, page, config, layouts, cache)));
   return {
     heads: facts.map((f) => f.head),
@@ -793,6 +792,104 @@ function filterToNewFindings(results, baselineResults) {
   return results.filter((r) => !baselineKeys.has(findingKey(r)));
 }
 
+// src/suppressions.ts
+import { readFileSync as readFileSync2, writeFileSync } from "fs";
+import { join as join4 } from "path";
+import { isPenalized } from "@svelte-vitals/core";
+var SUPPRESSIONS_FILE = "svelte-vitals-suppressions.json";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function loadSuppressions(cwd) {
+  const path = join4(cwd, SUPPRESSIONS_FILE);
+  let raw;
+  try {
+    raw = readFileSync2(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `invalid ${SUPPRESSIONS_FILE}: not valid JSON (${err instanceof Error ? err.message : String(err)}).`,
+      { cause: err }
+    );
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`invalid ${SUPPRESSIONS_FILE}: expected a top-level JSON object.`);
+  }
+  if (parsed.version !== 1) {
+    throw new Error(`invalid ${SUPPRESSIONS_FILE}: expected "version": 1, got ${JSON.stringify(parsed.version)}.`);
+  }
+  if (!Array.isArray(parsed.suppressions)) {
+    throw new Error(`invalid ${SUPPRESSIONS_FILE}: "suppressions" must be an array.`);
+  }
+  const entries = [];
+  parsed.suppressions.forEach((entry, i) => {
+    if (!isPlainObject(entry) || typeof entry.id !== "string") {
+      throw new Error(`invalid ${SUPPRESSIONS_FILE}: suppressions[${i}] must be an object with a string "id".`);
+    }
+    entries.push({
+      id: entry.id,
+      ...typeof entry.route === "string" ? { route: entry.route } : {},
+      ...typeof entry.location === "string" ? { location: entry.location } : {}
+    });
+  });
+  return entries;
+}
+function toEntry(r) {
+  return {
+    id: r.id,
+    ...r.route !== void 0 ? { route: r.route } : {},
+    ...r.location !== void 0 ? { location: r.location } : {}
+  };
+}
+function compareEntries(a, b) {
+  if (a.id !== b.id) return a.id < b.id ? -1 : 1;
+  const ar = a.route ?? "";
+  const br = b.route ?? "";
+  if (ar !== br) return ar < br ? -1 : 1;
+  const al = a.location ?? "";
+  const bl = b.location ?? "";
+  if (al !== bl) return al < bl ? -1 : 1;
+  return 0;
+}
+function writeSuppressions(cwd, results, config) {
+  const seen = /* @__PURE__ */ new Set();
+  const entries = [];
+  for (const r of results) {
+    if (!isPenalized(r.detection, config.treatDynamicAs)) continue;
+    const entry = toEntry(r);
+    const key = findingKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push(entry);
+  }
+  entries.sort(compareEntries);
+  const path = join4(cwd, SUPPRESSIONS_FILE);
+  writeFileSync(path, JSON.stringify({ version: 1, suppressions: entries }, null, 2) + "\n");
+  return entries.length;
+}
+function applySuppressions(results, entries, config) {
+  const keys = new Set(entries.map((e) => findingKey(e)));
+  const usedKeys = /* @__PURE__ */ new Set();
+  const kept = [];
+  let suppressed = 0;
+  for (const r of results) {
+    const key = findingKey(r);
+    if (keys.has(key) && isPenalized(r.detection, config.treatDynamicAs)) {
+      suppressed++;
+      usedKeys.add(key);
+      continue;
+    }
+    kept.push(r);
+  }
+  const stale = [...keys].filter((k) => !usedKeys.has(k)).length;
+  return { results: kept, suppressed, stale };
+}
+
 // src/color.ts
 import { noColorPalette } from "@svelte-vitals/core";
 var wrap = (open, close = 0) => (s) => `\x1B[${open}m${s}\x1B[${close}m`;
@@ -835,9 +932,160 @@ function startSpinner(text, opts) {
   };
 }
 
+// src/mascot.ts
+import { createLogUpdate } from "log-update";
+function mascotStateFor(score) {
+  if (score === 100) return "ecstatic";
+  if (score >= 90) return "happy";
+  return "content";
+}
+var MIN_MASCOT_COLUMNS = 20;
+function mascotFitsWidth(columns) {
+  return (columns ?? 80) >= MIN_MASCOT_COLUMNS;
+}
+var ORANGE_FG = "\x1B[38;2;255;62;0m";
+var RESET = "\x1B[0m";
+function renderFace(lines) {
+  return lines.map((line) => `${ORANGE_FG}${line}${RESET}`).join("\n");
+}
+var FACE_OPEN_EYES_NEUTRAL_MOUTH = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  \u25CF    \u25CF  \u2502", "\u2502    \u2500\u2500    \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_CLOSED_EYES_NEUTRAL_MOUTH = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  \u2500    \u2500  \u2502", "\u2502    \u2500\u2500    \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_WINK_BOTH = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  >    <  \u2502", "\u2502    \u2500\u2500    \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_WINK_ONE = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  \u25CF    <  \u2502", "\u2502    \u2500\u2500    \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_CONTENT = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  \u25CF    \u25CF  \u2502", "\u2502    \u25E1\u25E1    \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_HAPPY = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  \u25CF    \u25CF  \u2502", "\u2502   \u2570\u2500\u2500\u256F   \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var FACE_ECSTATIC = ["\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E", "\u2502  ^    ^  \u2502", "\u2502   \u2570\u2500\u2500\u256F   \u2502", "\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"];
+var REACTION_FACES = {
+  content: FACE_CONTENT,
+  happy: FACE_HAPPY,
+  ecstatic: FACE_ECSTATIC
+};
+function renderMascotReaction(state) {
+  return renderFace(REACTION_FACES[state]);
+}
+function renderMascotAnticipating() {
+  return renderFace(FACE_OPEN_EYES_NEUTRAL_MOUTH);
+}
+var IDLE_FRAME_SEQUENCE = [0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 2, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 3];
+var IDLE_FACES = {
+  0: FACE_OPEN_EYES_NEUTRAL_MOUTH,
+  1: FACE_CLOSED_EYES_NEUTRAL_MOUTH,
+  2: FACE_WINK_BOTH,
+  3: FACE_WINK_ONE
+};
+function renderMascotIdleFrame(frameIndex) {
+  const code = IDLE_FRAME_SEQUENCE[frameIndex % IDLE_FRAME_SEQUENCE.length];
+  return renderFace(IDLE_FACES[code]);
+}
+var CONFETTI_COLORS = [
+  [255, 62, 0],
+  // orange (identity accent)
+  [255, 145, 175],
+  // blush pink
+  [255, 214, 0],
+  // gold
+  [255, 255, 255]
+  // white
+];
+var CONFETTI_CHARS = ["*", ".", "\xB7", "+"];
+var CONFETTI_WIDTH = 24;
+function confettiFg(rgb) {
+  return `\x1B[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+}
+function confettiRow(offset) {
+  let out = "";
+  for (let col = 0; col < CONFETTI_WIDTH; col++) {
+    if ((col + offset) % 5 === 0) {
+      const glyph = CONFETTI_CHARS[(col + offset) % CONFETTI_CHARS.length];
+      out += confettiFg(CONFETTI_COLORS[(col + offset) % CONFETTI_COLORS.length]) + glyph + RESET;
+    } else {
+      out += " ";
+    }
+  }
+  return out;
+}
+function renderConfettiFrame(offset, mascotBlock) {
+  return [confettiRow(offset), mascotBlock, confettiRow(offset + 2)].join("\n");
+}
+var IDLE_TICK_MS = 160;
+function startMascotSpinner(text, opts) {
+  if (!opts.enabled) return { stop() {
+  } };
+  const stream = opts.stream ?? process.stderr;
+  const render = createLogUpdate(stream);
+  let i = 0;
+  const tick = () => {
+    render(`${renderMascotIdleFrame(i)}
+${text}`);
+    i++;
+  };
+  tick();
+  const timer = setInterval(tick, IDLE_TICK_MS);
+  if (typeof timer.unref === "function") timer.unref();
+  return {
+    stop() {
+      clearInterval(timer);
+      render.clear();
+    }
+  };
+}
+
+// src/speech-bubble.ts
+import { createLogUpdate as createLogUpdate2 } from "log-update";
+var MIN_BUBBLE_COLUMNS = 55;
+function bubbleFitsWidth(columns) {
+  return (columns ?? 80) >= MIN_BUBBLE_COLUMNS;
+}
+function renderSpeechBubble(text) {
+  const border = "\u2500".repeat(text.length + 2);
+  return [`\u256D${border}\u256E`, `\u2502 ${text} \u2502`, `\u2570${border}\u256F`];
+}
+function withSpeechBubble(mascotBlock, bubbleLines) {
+  const mascotLines = mascotBlock.split("\n");
+  const bubbleWidth = bubbleLines[0]?.length ?? 0;
+  const blankBubbleLine = " ".repeat(bubbleWidth);
+  const padTop = Math.floor((mascotLines.length - bubbleLines.length) / 2);
+  const padBottom = mascotLines.length - bubbleLines.length - padTop;
+  const paddedBubble = [
+    ...Array(Math.max(padTop, 0)).fill(blankBubbleLine),
+    ...bubbleLines,
+    ...Array(Math.max(padBottom, 0)).fill(blankBubbleLine)
+  ];
+  return mascotLines.map((line, i) => `${line} ${paddedBubble[i] ?? blankBubbleLine}`).join("\n");
+}
+var GREETING_MESSAGES = [
+  "Welcome to Svelte Vitals!",
+  "Let's check your project!",
+  "Ready when you are!",
+  "Hi there! Let's dig in."
+];
+var REACTION_MESSAGES = {
+  ecstatic: ["Perfect score!", "Flawless!", "You nailed it!"],
+  happy: ["Nice work!", "Looking great!", "Almost perfect!"],
+  content: ["Keep going!", "Room to grow!", "Let's improve this!"]
+};
+function pickMessage(pool, random = Math.random) {
+  return pool[Math.floor(random() * pool.length)];
+}
+function renderMascotWithSpeech(mascotBlock, message) {
+  return withSpeechBubble(mascotBlock, renderSpeechBubble(message));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var GREETING_HOLD_MS = 800;
+async function playMascotGreeting(opts) {
+  if (!opts.enabled) return;
+  const holdMs = opts.holdMs ?? GREETING_HOLD_MS;
+  const render = createLogUpdate2(opts.stream);
+  render(renderMascotWithSpeech(renderMascotAnticipating(), pickMessage(GREETING_MESSAGES)));
+  if (holdMs > 0) await sleep(holdMs);
+  render.clear();
+}
+
 // src/config-file.ts
 import { existsSync as existsSync2 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { pathToFileURL } from "url";
 
 // src/rules-config.ts
@@ -864,7 +1112,7 @@ var CATEGORIES = ["seo", "performance", "correctness", "security", "architecture
 var TREAT_DYNAMIC_AS_VALUES = ["pass", "warn", "fail"];
 var FAIL_ON_VALUES = ["critical", "warning", "info"];
 var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["treatDynamicAs", "metaComponents", "rules", "failOn", "weights"]);
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isMissingExtensionLoaderError(err) {
@@ -902,7 +1150,7 @@ function validateConfigFile(raw, path) {
     }
   }
   if (raw.rules !== void 0) {
-    if (!isPlainObject(raw.rules)) {
+    if (!isPlainObject2(raw.rules)) {
       throw new Error(`${path}: rules must be an object of rule-id \u2192 setting.`);
     }
     const rules = raw.rules;
@@ -915,7 +1163,7 @@ function validateConfigFile(raw, path) {
     config.rules = rules;
   }
   if (raw.weights !== void 0) {
-    if (!isPlainObject(raw.weights)) {
+    if (!isPlainObject2(raw.weights)) {
       throw new Error(`${path}: weights must be an object of category \u2192 number.`);
     }
     const weights = {};
@@ -934,7 +1182,7 @@ function validateConfigFile(raw, path) {
   return { config, warnings };
 }
 async function loadConfigFile(cwd) {
-  const found = CONFIG_FILENAMES.map((name) => join4(cwd, name)).find((path) => existsSync2(path));
+  const found = CONFIG_FILENAMES.map((name) => join5(cwd, name)).find((path) => existsSync2(path));
   if (!found) return void 0;
   let mod;
   try {
@@ -948,7 +1196,7 @@ async function loadConfigFile(cwd) {
     }
     throw err;
   }
-  if (!isPlainObject(mod.default)) {
+  if (!isPlainObject2(mod.default)) {
     throw new Error(
       `${found} must have a default export that is a plain object (e.g. \`export default defineConfig({...})\` or a plain object literal).`
     );
@@ -958,6 +1206,7 @@ async function loadConfigFile(cwd) {
 
 // src/pulse-animation.ts
 import { scoreColor } from "@svelte-vitals/core";
+import { createLogUpdate as createLogUpdate3 } from "log-update";
 var FRAME_COUNT = 6;
 var FRAME_DELAY_MS = 200;
 var WAVE_FRAMES = [
@@ -965,26 +1214,46 @@ var WAVE_FRAMES = [
   "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2571\u2572\u2500\u2500\u2571\u2572\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
   "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2571\u2572\u2500\u2500\u2500\u2500\u2500\u2500\u2571\u2572\u2500\u2500\u2500\u2500\u2500\u2500",
   "\u2500\u2500\u2500\u2500\u2500\u2500\u2571\u2572\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2572\u2500\u2500\u2500\u2500\u2500",
-  "\u2500\u2500\u2500\u2500\u2571\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2572\u2500\u2500\u2500\u2500",
-  "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"
+  "\u2500\u2500\u2500\u2500\u2571\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2572\u2500\u2500\u2500\u2500"
 ];
-function sleep(ms) {
+var WAVE_ORANGE_DIM = "\x1B[38;2;153;37;0m";
+var WAVE_RESET = "\x1B[0m";
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var REACTION_HOLD_MS = 500;
+var CONFETTI_FRAME_COUNT = 4;
+var CONFETTI_FRAME_DELAY_MS = 220;
 async function playScoreAnimation(opts) {
   const frameDelayMs = opts.frameDelayMs ?? FRAME_DELAY_MS;
+  const holdMs = opts.frameDelayMs ?? REACTION_HOLD_MS;
+  const confettiDelayMs = opts.frameDelayMs ?? CONFETTI_FRAME_DELAY_MS;
+  const render = createLogUpdate3(opts.stream);
+  const showMascot = mascotFitsWidth(opts.stream.columns);
+  const state = mascotStateFor(opts.score);
+  const reactionMessage = showMascot && bubbleFitsWidth(opts.stream.columns) ? pickMessage(REACTION_MESSAGES[state]) : void 0;
+  const finalMascotBlock = reactionMessage ? renderMascotWithSpeech(renderMascotReaction(state), reactionMessage) : renderMascotReaction(state);
   for (let frame = 0; frame < FRAME_COUNT; frame++) {
     const progress = frame / (FRAME_COUNT - 1);
     const displayScore = Math.round(opts.score * progress);
     const isFinalFrame = frame === FRAME_COUNT - 1;
-    const wave = WAVE_FRAMES[frame];
     const scoreText = isFinalFrame ? scoreColor(opts.palette, opts.score)(`${displayScore}/100`) : opts.palette.dim(`${displayScore}/100`);
-    const cursorUp = frame === 0 ? "" : "\x1B[2A";
-    opts.stream.write(`${cursorUp}\r  ${wave}\x1B[K
-\r  Health: ${scoreText}\x1B[K
-`);
-    if (!isFinalFrame) await sleep(frameDelayMs);
+    const waveBlock = isFinalFrame ? `Health: ${scoreText}` : `${WAVE_ORANGE_DIM}${WAVE_FRAMES[frame]}${WAVE_RESET}
+Health: ${scoreText}`;
+    const mascotBlock = showMascot ? (isFinalFrame ? finalMascotBlock : renderMascotAnticipating()) + "\n" : "";
+    render(`${mascotBlock}${waveBlock}`);
+    if (!isFinalFrame) await sleep2(frameDelayMs);
+  }
+  if (holdMs > 0) await sleep2(holdMs);
+  if (showMascot && state === "ecstatic") {
+    for (let i = 0; i < CONFETTI_FRAME_COUNT; i++) {
+      const waveBlock = `Health: ${scoreColor(opts.palette, opts.score)("100/100")}`;
+      render(`${renderConfettiFrame(i, finalMascotBlock)}
+${waveBlock}`);
+      if (i < CONFETTI_FRAME_COUNT - 1 && confettiDelayMs > 0) await sleep2(confettiDelayMs);
+    }
   }
+  render.done();
 }
 function scoreAnimationEnabled(opts) {
   return opts.reporter === "console" && opts.stdoutIsTTY && !opts.noAnimationFlag && !isAgentEnv(opts.env) && !isCiEnv(opts.env) && colorEnabled({ reporter: opts.reporter, isTTY: opts.stdoutIsTTY, env: opts.env, noColorFlag: opts.noColorFlag });
@@ -1017,7 +1286,7 @@ async function analyzeProject(opts = {}) {
   });
   await detectProject(rt, cwd);
   const matches = routeMatcher(opts.route);
-  const collected = await collectRoutes(rt, cwd, config);
+  const collected = await collectRoutes(rt, cwd, config, opts.parseCache);
   const heads = collected.heads.filter((h) => matches(h.route));
   const images = collected.images.filter((i) => matches(i.route));
   const headings = collected.headings.filter((h) => matches(h.route));
@@ -1061,6 +1330,18 @@ async function applyScope(results, opts) {
       }
     }
   }
+  if (!opts.noSuppressions && opts.config) {
+    const entries = loadSuppressions(opts.cwd);
+    if (entries !== void 0) {
+      const { results: afterSuppressions, suppressed, stale } = applySuppressions(scoped, entries, opts.config);
+      scoped = afterSuppressions;
+      if (suppressed > 0 || stale > 0) {
+        errorLog(
+          `svelte-vitals: ${suppressed} finding(s) suppressed by ${SUPPRESSIONS_FILE}` + (stale > 0 ? ` (${stale} stale entr${stale === 1 ? "y" : "ies"} \u2014 re-run --update-suppressions to prune)` : "") + "."
+        );
+      }
+    }
+  }
   return scoped;
 }
 async function run(opts = {}) {
@@ -1072,15 +1353,19 @@ async function run(opts = {}) {
   }
   const env = opts.env ?? process.env;
   const reporter = resolveReporter(opts.reporter, env);
-  const spinner = startSpinner("Analyzing\u2026", {
-    enabled: !opts.score && spinnerEnabled({
-      reporter,
-      rawReporter: opts.reporter,
-      stderrIsTTY: opts.stderrIsTTY ?? !!process.stderr.isTTY,
-      env,
-      noColorFlag: opts.noColor
-    })
+  const stderrStream = opts.stderrStream ?? process.stderr;
+  const spinnerBaseEnabled = !opts.score && spinnerEnabled({
+    reporter,
+    rawReporter: opts.reporter,
+    stderrIsTTY: opts.stderrIsTTY ?? !!process.stderr.isTTY,
+    env,
+    noColorFlag: opts.noColor
   });
+  const useMascotSpinner = spinnerBaseEnabled && !opts.noAnimation && mascotFitsWidth(stderrStream.columns);
+  if (useMascotSpinner && bubbleFitsWidth(stderrStream.columns)) {
+    await playMascotGreeting({ enabled: true, stream: stderrStream, holdMs: opts.animationFrameDelayMs });
+  }
+  const spinner = useMascotSpinner ? startMascotSpinner("Analyzing\u2026", { enabled: true, stream: stderrStream }) : startSpinner("Analyzing\u2026", { enabled: spinnerBaseEnabled, stream: stderrStream });
   let cwd = opts.cwd ?? process.cwd();
   let analysis;
   try {
@@ -1126,7 +1411,7 @@ async function run(opts = {}) {
         errorLog(`svelte-vitals: pass one as a path, e.g. \`npx svelte-vitals ${apps[0]}\`.`);
         return 2;
       }
-      cwd = join5(cwd, chosen);
+      cwd = join6(cwd, chosen);
       try {
         analysis = await analyzeProject({
           cwd,
@@ -1155,11 +1440,18 @@ async function run(opts = {}) {
   for (const w of analysis.warnings) errorLog(`svelte-vitals: ${w}`);
   try {
     const { config, version } = analysis;
+    if (opts.updateSuppressions) {
+      const count = writeSuppressions(cwd, analysis.results, config);
+      errorLog(`svelte-vitals: wrote ${count} suppression(s) to ${SUPPRESSIONS_FILE}.`);
+      return 0;
+    }
     const results = await applyScope(analysis.results, {
       cwd,
+      config,
       staged: opts.staged,
       diffBase: opts.diffBase,
       baseline: opts.baseline,
+      noSuppressions: opts.noSuppressions,
       errorLog,
       analyzeOpts: {
         metaComponents: opts.metaComponents,
@@ -1171,6 +1463,7 @@ async function run(opts = {}) {
         categories: opts.categories
       }
     });
+    const summary = summarize(results, config);
     if (opts.score) {
       log(String(computeHealth(results, config).health));
     } else {
@@ -1201,7 +1494,7 @@ async function run(opts = {}) {
           const path = opts.outFile || "svelte-vitals-report.html";
           const write = opts.writeFile ?? ((p, c) => {
             mkdirSync(dirname2(p), { recursive: true });
-            writeFileSync(p, c);
+            writeFileSync2(p, c);
           });
           write(path, html);
           errorLog(`svelte-vitals: wrote report to ${path}`);
@@ -1242,7 +1535,6 @@ async function run(opts = {}) {
         );
       }
     }
-    const summary = summarize(results, config);
     const failBySeverity = hasFailureAtOrAbove(summary, config.failOn);
     const failByHealth = opts.minHealth != null && computeHealth(results, config).health < opts.minHealth;
     return failBySeverity || failByHealth ? 1 : 0;

package/dist/index.d.ts

@@ -1,6 +1,54 @@
-import { RuleSetting, Config, Severity, Category, Result } from '@svelte-vitals/core';
+import { HeadTag, RuleSetting, Config, Severity, Category, Result } from '@svelte-vitals/core';
 export { defineConfig } from '@svelte-vitals/core';
 
+/** A resolved import binding: which module, and which export ('default' for default imports). */
+interface ImportInfo {
+    source: string;
+    imported: string;
+}
+/** local identifier -> import binding. */
+type ImportMap = Map<string, ImportInfo>;
+
+/** A head tag parsed from one file, before layout-chain presence is assigned. */
+type ParsedTag = Omit<HeadTag, 'presence' | 'file'>;
+type Node = any;
+interface ComponentUse {
+    name: string;
+    attributes: Node[];
+    hasSpread: boolean;
+}
+interface ParsedImage {
+    hasWidth: boolean;
+    hasHeight: boolean;
+    hasLoading: boolean;
+    hasAlt: boolean;
+    lazy: boolean;
+    hasSrcset: boolean;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+}
+/** A page-body heading (<h1>–<h6>) parsed from one file (SEO027). */
+interface ParsedHeading {
+    /** Heading level 1–6. */
+    level: number;
+    /** 1-based source line, or 0 if unknown. */
+    line: number;
+}
+interface ParsedFile {
+    headTags: ParsedTag[];
+    components: ComponentUse[];
+    imports: ImportMap;
+    images: ParsedImage[];
+    headings: ParsedHeading[];
+}
+
+/**
+ * Per-run read+parse memo, keyed by project-root-relative path (as normalized by
+ * chainFiles / resolveComponentPath). Shared across routes so a file imported by
+ * many pages (a root layout, a common $lib component) is only parsed once per run.
+ */
+type ParseCache = Map<string, Promise<ParsedFile>>;
+
 type ReporterName = 'console' | 'json' | 'agent' | 'sarif' | 'github' | 'html' | 'md';
 
 /** Thrown when the target directory is not a SvelteKit project (CLI maps to exit 2). */
@@ -77,6 +125,10 @@ interface RunOptions {
     staged?: boolean;
     /** Report only findings not present when analyzing this git ref (e.g. the PR base). */
     baseline?: string;
+    /** Disable applying svelte-vitals-suppressions.json for this run. */
+    noSuppressions?: boolean;
+    /** Analyze, then (re)write svelte-vitals-suppressions.json with all currently penalized findings and exit 0. */
+    updateSuppressions?: boolean;
     /** Disable ANSI color in console output. */
     noColor?: boolean;
     /** Override stdout TTY detection (tests). */
@@ -95,6 +147,8 @@ interface RunOptions {
     noAnimation?: boolean;
     /** Override the stream the score animation writes to (tests). Defaults to process.stdout. */
     stdoutStream?: NodeJS.WriteStream;
+    /** Override the stream the analysis-phase progress indicator writes to (tests). Defaults to process.stderr. */
+    stderrStream?: NodeJS.WriteStream;
     /** Override the animation's per-frame delay in ms (tests — 0 runs the real frame loop near-instantly). Defaults to the animation module's own constant. */
     animationFrameDelayMs?: number;
 }
@@ -125,6 +179,18 @@ interface AnalyzeOptions {
     weights?: Partial<Record<Category, number>>;
     /** Restrict analysis to rules in these categories (applied after rules/ignore selection). */
     categories?: Category[];
+    /**
+     * Reuse this parse cache across multiple `analyzeProject` calls instead of
+     * starting fresh each time — the vite dev dashboard passes a long-lived cache
+     * and invalidates only the changed file's entry between re-analyses, so
+     * unchanged routes/layouts are never re-read or re-parsed. This only covers
+     * the route/layout (head-resolution) parse path via `collectRoutes` —
+     * `collectComponentFacts` (Correctness facts) is unaffected and still scans
+     * every component on each call. Callers that don't need cross-call reuse
+     * (the CLI's `run()`, MCP, the Action — each analyzes once per process) can
+     * omit this; a fresh cache is created automatically.
+     */
+    parseCache?: ParseCache;
 }
 interface AnalyzeResult {
     results: Result[];
@@ -150,14 +216,25 @@ interface ApplyScopeOptions {
     staged?: boolean;
     diffBase?: string;
     baseline?: string;
+    /**
+     * Resolved config, needed to decide which findings count as "penalized" when
+     * applying svelte-vitals-suppressions.json (`isPenalized`). Suppression
+     * application is skipped entirely when omitted, keeping such callers'
+     * behavior unchanged (the CLI and @svelte-vitals/action both pass it).
+     */
+    config?: Config;
+    /** Disable applying svelte-vitals-suppressions.json for this run. */
+    noSuppressions?: boolean;
     errorLog?: (line: string) => void;
     analyzeOpts?: AnalyzeOptions;
 }
 /**
  * Narrow `results` to what a PR gate cares about: `--staged`/`--diff` restrict to
- * changed files, `--baseline` drops findings that already existed at that ref. Shared
- * by `run()` and `@svelte-vitals/action` (issue #154) so the git-diff/baseline
- * orchestration lives in exactly one place.
+ * changed files, `--baseline` drops findings that already existed at that ref,
+ * and (last) svelte-vitals-suppressions.json drops findings that were explicitly
+ * accepted via `--update-suppressions`. Shared by `run()` and
+ * `@svelte-vitals/action` (issue #154) so the git-diff/baseline orchestration
+ * lives in exactly one place.
  */
 declare function applyScope(results: Result[], opts: ApplyScopeOptions): Promise<Result[]>;
 /**
@@ -166,4 +243,4 @@ declare function applyScope(results: Result[], opts: ApplyScopeOptions): Promise
  */
 declare function run(opts?: RunOptions): Promise<number>;
 
-export { type AnalyzeOptions, type AnalyzeResult, type ApplyScopeOptions, type LoadedConfigFile, ProjectError, type RunOptions, analyzeProject, applyScope, buildRulesConfig, findUnknownRuleIds, knownRuleIds, loadConfigFile, routeMatcher, run, spinnerEnabled };
+export { type AnalyzeOptions, type AnalyzeResult, type ApplyScopeOptions, type LoadedConfigFile, type ParseCache, ProjectError, type RunOptions, analyzeProject, applyScope, buildRulesConfig, findUnknownRuleIds, knownRuleIds, loadConfigFile, routeMatcher, run, spinnerEnabled };

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   routeMatcher,
   run,
   spinnerEnabled
-} from "./chunk-HYTPZVSU.js";
+} from "./chunk-OCLDCX4Y.js";
 export {
   ProjectError,
   analyzeProject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "A SvelteKit SEO checker — not a runtime Web Vitals reporter. Static analysis of your routes' head metadata.",
   "type": "module",
   "license": "MIT",
@@ -40,15 +40,16 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "log-update": "^8.0.0",
     "magicast": "^0.5.3",
     "mri": "^1.2.0",
     "smol-toml": "^1.7.0",
     "svelte": "^5.56.4",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.23.0"
+    "@svelte-vitals/core": "0.24.0"
   },
   "devDependencies": {
-    "@types/node": "^24.13.2"
+    "@types/node": "^24.13.3"
   },
   "scripts": {
     "build": "node scripts/gen-action-pin.mjs && tsup",