@svelte-vitals/core 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -328,21 +328,29 @@ interface ComponentFacts {
         name: string;
         line: number;
     }[];
-    /** Mutations of a non-`$bindable` prop from `$props()` — member writes, `delete`, or a mutating method call (correctness/prop-mutation). */
+    /** Mutations of a non-`$bindable` prop from `$props()`, or a legacy `export let` prop — member writes, `delete`, or a mutating method call (correctness/prop-mutation). `legacy` distinguishes which mode the prop was declared in (absent/false: `$props()`), since the fix differs — optional so existing external constructors of `ComponentFacts` are unaffected. */
     mutatedProps: {
         name: string;
         line: number;
+        legacy?: boolean;
     }[];
-    /** Top-level const/let bindings computed from a $props() prop without $derived, never reassigned or escaped, and referenced (eagerly) in the template — frozen at init (correctness/stale-prop-derivation). */
+    /** Top-level const/let bindings computed from a $props() or legacy `export let` prop without $derived (or `$:`), never reassigned or escaped, and referenced (eagerly) in the template — frozen at init (correctness/stale-prop-derivation). `legacy` distinguishes which mode the prop was declared in, since the fix differs — optional so existing external constructors of `ComponentFacts` are unaffected. */
     stalePropDerivations: {
         name: string;
         line: number;
+        legacy?: boolean;
     }[];
     /** Object/array-literal $state bindings reassigned at least once but never mutated, escaped, aliased, or item-edited — $state.raw candidates (performance/state-raw). */
     rawableStates: {
         name: string;
         line: number;
     }[];
+    /** Plain built-in instances (Map/Set/Date/URL/URLSearchParams) in $state whose type-specific mutations were observed inside functions, with no exempting reassignment — untracked by reactivity (correctness/nonreactive-builtin-state). */
+    nonreactiveBuiltinStates: {
+        name: string;
+        type: string;
+        line: number;
+    }[];
     /** `$effect` calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-effect). */
     orphanEffects: OrphanEffectFact[];
     /** Svelte lifecycle/context calls guaranteed to run outside component initialisation — module scope in `.svelte.ts`/`.svelte.js` or `<script module>` (correctness/orphan-lifecycle). */
@@ -715,15 +723,34 @@ declare const correctnessEffectAsOnMount: Rule;
 
 declare const correctnessUnmutatedState: Rule;
 
+/**
+ * correctness/prop-mutation — mutating a prop directly is a silent bug in both Svelte modes,
+ * for different reasons: in runes mode, a non-$bindable prop mutation doesn't propagate to the
+ * parent; in legacy mode (export let), Svelte's reactivity is assignment-based, so a mutating
+ * method call (`.push(...)`, etc.) doesn't trigger an update at all without a following
+ * reassignment. The two modes can't be mixed in one component, so a given finding is always
+ * exactly one or the other — see `legacy` on `ComponentFacts.mutatedProps` (component-parse.ts).
+ */
 declare const correctnessPropMutation: Rule;
 
 /**
- * correctness/stale-prop-derivation — a value computed from a prop without
- * $derived is evaluated once, at init, and silently stops tracking the parent.
- * Svelte's own guidance: treat props as though they will change.
+ * correctness/stale-prop-derivation — a value computed from a prop without $derived (runes
+ * mode) or $: (legacy mode) is evaluated once, at init, and silently stops tracking the
+ * parent. Svelte's own guidance: treat props as though they will change. The two modes can't
+ * be mixed in one component, so a given finding is always exactly one or the other — see
+ * `legacy` on `ComponentFacts.stalePropDerivations` (component-parse.ts).
  */
 declare const correctnessStalePropDerivation: Rule;
 
+/**
+ * correctness/nonreactive-builtin-state — $state's deep proxy covers plain
+ * objects and arrays only. A plain Map/Set/Date/URL/URLSearchParams in $state
+ * keeps working as data, but its mutations never reach effects, deriveds, or
+ * the template: the UI silently stops updating. svelte/reactivity ships
+ * drop-in reactive equivalents for exactly this.
+ */
+declare const correctnessNonreactiveBuiltinState: Rule;
+
 declare const correctnessOrphanEffect: Rule;
 
 /**
@@ -1088,4 +1115,4 @@ declare function applyRuleSeverities(results: Result[], config: Config): Result[
  */
 declare function applyOverrides(results: Result[], config: Config): Result[];
 
-export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CHILD_NODE_KEYS, type Category, type Classification, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleOverride, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, type Value, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architecturePropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, computeHealth, computeScore, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, summarize, textFromNodes, valueFromNodes };
+export { APP_SCRIPT, APP_STYLE, type AppSnapshot, BAND_COLOR, CHILD_NODE_KEYS, type Category, type Classification, type ComponentFacts, type Config, type ConsoleReportOptions, type Detection, type EachBlockFact, type EffectFact, type Fix, type HeadProvider, type HeadTag, type HeadingInfo, type HealthResult, type ImageInfo, type JsonReport, type KitModuleFacts, type OrphanEffectFact, type Palette, type Presence, type Project, ROBOTS_SOURCE_PATHS, type ResolvedHead, type ResolvedHeadings, type ResolvedImages, type Result, type RouteBadge, type Rule, type RuleContext, type RuleInfo, type RuleOverride, type RuleSetting, type Runtime, SITEMAP_SOURCE_PATHS, type Scope, type ScoreModel, type ScoreOptions, type ScoreResult, type Severity, type SourceSpan, type Summary, type SuppressionDirective, type TreatDynamicAs, type Value, allRules, applyOverrides, applyRuleSeverities, architectureComponentSize, architecturePropCount, attrText, attrTextOf, attrValue, attrValueOf, buildHtmlDocument, buildJsonReport, classify, collectComponentFacts, collectKitModuleFacts, computeHealth, computeScore, correctnessEachIndexKey, correctnessEachKey, correctnessEffectAsDerived, correctnessEffectAsOnMount, correctnessInstanceBrowserGlobal, correctnessNonreactiveBuiltinState, correctnessOrphanEffect, correctnessOrphanLifecycle, correctnessPropMutation, correctnessServerBrowserGlobal, correctnessStalePropDerivation, correctnessUnmutatedState, defaultConfig, defaultProject, defineConfig, docsUrlFor, effectiveSeverity, emptyComponentFacts, emptyKitModuleFacts, escapeHtml, explainRule, findAttr, findMinifyDisabled, formatAgentReport, formatConsoleReport, formatGithubReport, formatHtmlReport, formatJsonReport, formatMarkdownReport, formatSarifReport, hasFailureAtOrAbove, headTagRule, imageRule, isPenalized, lineOf, linkRule, noColorPalette, parseComponentFacts, parseKitModuleFacts, performanceFontPreloadCrossorigin, performanceHeavyImport, performanceImageDimensions, performanceImageLoadingHint, performanceLcpImage, performanceLoadWaterfall, performanceMinifyDisabled, performanceNamespaceImport, performancePreconnect, performancePreloadMissingAs, performanceRenderBlockingScript, performanceResponsiveImage, performanceSequentialAwaits, performanceStateRaw, renderAppShell, resolveRunesModuleSpecifier, runRules, safeHref, scoreBand, scoreColor, scoresByCategory, securityHandlerStateWrite, securityJavascriptUrl, securityRawHtml, securityServerModuleState, securitySharedStateImport, selectRules, seoCanonicalUrl, seoCharset, seoDescriptionLength, seoDescriptionPresence, seoDuplicateDescription, seoDuplicateTitle, seoHeadingLevelSkip, seoHreflang, seoHtmlLang, seoImageAlt, seoIndexability, seoJsonLd, seoJsonLdDateFormat, seoJsonLdDeprecatedType, seoJsonLdPlaceholder, seoJsonLdRelativeUrl, seoJsonLdRequiredProps, seoJsonLdValidity, seoOgDescription, seoOgImage, seoOgTitle, seoOgUrl, seoRobotsTxt, seoSingleH1, seoSitemapInRobots, seoSitemapXml, seoSsrDisabled, seoTitleLength, seoTitlePresence, seoTwitterCard, seoViewport, summarize, textFromNodes, valueFromNodes };

package/dist/index.js

@@ -245,8 +245,10 @@ function scopeIntroducedNames(node) {
     addBoundNames(node.param, introduced);
   } else if (node.type === "BlockStatement") {
     for (const stmt of node.body ?? []) {
-      if (stmt?.type === "VariableDeclaration" && stmt.kind !== "var") {
+      if (stmt?.type === "VariableDeclaration") {
         for (const d of stmt.declarations ?? []) addBoundNames(d.id, introduced);
+      } else if ((stmt?.type === "FunctionDeclaration" || stmt?.type === "ClassDeclaration") && typeof stmt.id?.name === "string") {
+        introduced.add(stmt.id.name);
       }
     }
   } else if (node.type === "ForStatement" || node.type === "ForOfStatement" || node.type === "ForInStatement") {
@@ -330,6 +332,81 @@ function isDeferredBody(n) {
 function isPlainStateCall(node) {
   return node?.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "$state";
 }
+var BUILTIN_STATE_TYPES = /* @__PURE__ */ new Set(["Map", "Set", "Date", "URL", "URLSearchParams"]);
+var BUILTIN_MUTATIONS = {
+  Map: /* @__PURE__ */ new Set(["set", "delete", "clear"]),
+  Set: /* @__PURE__ */ new Set(["add", "delete", "clear"]),
+  Date: /* @__PURE__ */ new Set([
+    "setTime",
+    "setFullYear",
+    "setMonth",
+    "setDate",
+    "setHours",
+    "setMinutes",
+    "setSeconds",
+    "setMilliseconds",
+    "setYear",
+    "setUTCFullYear",
+    "setUTCMonth",
+    "setUTCDate",
+    "setUTCHours",
+    "setUTCMinutes",
+    "setUTCSeconds",
+    "setUTCMilliseconds"
+  ]),
+  URL: /* @__PURE__ */ new Set(),
+  URLSearchParams: /* @__PURE__ */ new Set(["append", "set", "delete", "sort"])
+};
+function collectBuiltinStateSignals(node, candidates, mutated, reassigned, shadowed = /* @__PURE__ */ new Set(), inFunction = false) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectBuiltinStateSignals(child, candidates, mutated, reassigned, shadowed, inFunction);
+    return;
+  }
+  if (!node || typeof node !== "object" || typeof node.type !== "string") return;
+  const introduced = scopeIntroducedNames(node);
+  const scope = introduced.size > 0 ? /* @__PURE__ */ new Set([...shadowed, ...introduced]) : shadowed;
+  const boundary = isDeferredBody(node) || node.type === "ClassDeclaration" || node.type === "ClassExpression";
+  const nextInFunction = inFunction || boundary;
+  const hit = (name) => typeof name === "string" && candidates.has(name) && !scope.has(name) ? name : void 0;
+  if (node.type === "AssignmentExpression") {
+    if (node.left?.type === "Identifier") {
+      const n = hit(node.left.name);
+      const isBareSelfAssign = node.right?.type === "Identifier" && node.right.name === n;
+      if (n && !isBareSelfAssign) reassigned.add(n);
+    } else if (node.left?.type === "ObjectPattern" || node.left?.type === "ArrayPattern") {
+      const bound = /* @__PURE__ */ new Set();
+      addBoundNames(node.left, bound);
+      for (const name of bound) {
+        const n = hit(name);
+        if (n) reassigned.add(n);
+      }
+    } else if (node.left?.type === "MemberExpression" && inFunction) {
+      const n = hit(rootObjectName(node.left));
+      if (n && candidates.get(n) === "URL") mutated.add(n);
+    }
+  } else if (node.type === "UpdateExpression" && node.argument?.type === "MemberExpression" && inFunction) {
+    const n = hit(rootObjectName(node.argument));
+    if (n && candidates.get(n) === "URL") mutated.add(n);
+  } else if (node.type === "UnaryExpression" && node.operator === "delete" && inFunction) {
+    const n = hit(rootObjectName(node.argument));
+    if (n && candidates.get(n) === "URL") mutated.add(n);
+  } else if (node.type === "CallExpression" && node.callee?.type === "MemberExpression" && !node.callee.computed && inFunction) {
+    const method = node.callee.property?.name;
+    if (typeof method === "string") {
+      if (node.callee.object?.type === "Identifier") {
+        const n = hit(node.callee.object.name);
+        if (n && BUILTIN_MUTATIONS[candidates.get(n)]?.has(method)) mutated.add(n);
+      } else if (node.callee.object?.type === "MemberExpression") {
+        const n = hit(rootObjectName(node.callee));
+        if (n && candidates.get(n) === "URL" && BUILTIN_MUTATIONS.URLSearchParams.has(method)) mutated.add(n);
+      }
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (WALK_IGNORED_KEYS.has(key)) continue;
+    collectBuiltinStateSignals(node[key], candidates, mutated, reassigned, scope, nextInFunction);
+  }
+}
 function collectPatternAliasRefs(node, names, acc, scope, ownRhs) {
   if (!node || typeof node !== "object" || typeof node.type !== "string") return;
   if (node.type === "Identifier") return;
@@ -651,6 +728,16 @@ function collectPropNames(program, includeBindable) {
   });
   return ambiguous || seen > 1 ? /* @__PURE__ */ new Set() : names;
 }
+function collectLegacyPropNames(program) {
+  const names = /* @__PURE__ */ new Set();
+  for (const stmt of program.body ?? []) {
+    if (stmt?.type !== "ExportNamedDeclaration" || stmt.declaration?.type !== "VariableDeclaration") continue;
+    for (const d of stmt.declaration.declarations ?? []) {
+      if (d?.id?.type === "Identifier") names.add(d.id.name);
+    }
+  }
+  return names;
+}
 var MUTATING_METHODS = /* @__PURE__ */ new Set([
   "push",
   "pop",
@@ -1095,6 +1182,7 @@ function parseModuleFacts(source, filename) {
     mutatedProps: [],
     stalePropDerivations: [],
     rawableStates: [],
+    nonreactiveBuiltinStates: [],
     suppressions: collectSuppressions(source),
     orphanEffects,
     orphanLifecycleCalls,
@@ -1132,16 +1220,20 @@ function parseComponentFacts(source, filename) {
   const mutatedProps = [];
   const stalePropDerivations = [];
   const rawableStates = [];
+  const nonreactiveBuiltinStates = [];
   let propCount = 0;
   const program = ast.instance?.content;
   if (program) {
     collectImportSources(program, source, importSpans);
     collectNamespaceImports(program, source, namespaceImports);
     propCount = countProps(program);
-    const nonBindableProps = collectPropNames(program, false);
-    collectPropMutations(program, nonBindableProps, source, mutatedProps);
-    if (ast.fragment) collectPropMutations(ast.fragment, nonBindableProps, source, mutatedProps);
-    const allPropNames = collectPropNames(program, true);
+    const legacyPropNames = collectLegacyPropNames(program);
+    const nonBindableProps = /* @__PURE__ */ new Set([...collectPropNames(program, false), ...legacyPropNames]);
+    const rawMutations = [];
+    collectPropMutations(program, nonBindableProps, source, rawMutations);
+    if (ast.fragment) collectPropMutations(ast.fragment, nonBindableProps, source, rawMutations);
+    for (const m of rawMutations) mutatedProps.push(legacyPropNames.has(m.name) ? { ...m, legacy: true } : m);
+    const allPropNames = /* @__PURE__ */ new Set([...collectPropNames(program, true), ...legacyPropNames]);
     if (allPropNames.size > 0) {
       const candidates = collectStalePropCandidates(program, allPropNames, source);
       if (candidates.length > 0) {
@@ -1154,8 +1246,11 @@ function parseComponentFacts(source, filename) {
         }
         const referenced = /* @__PURE__ */ new Set();
         if (ast.fragment) collectFragmentRefs(ast.fragment, candidateNames, referenced);
+        const isLegacy = legacyPropNames.size > 0;
         for (const c of candidates) {
-          if (!disqualified.has(c.name) && referenced.has(c.name)) stalePropDerivations.push(c);
+          if (!disqualified.has(c.name) && referenced.has(c.name)) {
+            stalePropDerivations.push(isLegacy ? { ...c, legacy: true } : c);
+          }
         }
       }
     }
@@ -1186,6 +1281,7 @@ function parseComponentFacts(source, filename) {
     if (ast.fragment) {
       collectStateWrites(ast.fragment, stateNames, writtenOrEscaped);
       collectTemplateEscapes(ast.fragment, stateNames, writtenOrEscaped);
+      collectDirectiveEscapes(ast.fragment, stateNames, writtenOrEscaped);
     }
     for (const d of stateDecls) {
       if (!writtenOrEscaped.has(d.name)) constableStates.push(d);
@@ -1225,6 +1321,29 @@ function parseComponentFacts(source, filename) {
         if (reassigned && !dirty) rawableStates.push(c);
       }
     }
+    const builtinCandidates = /* @__PURE__ */ new Map();
+    for (const stmt of program.body ?? []) {
+      if (stmt?.type !== "VariableDeclaration") continue;
+      for (const d of stmt.declarations ?? []) {
+        if (d?.id?.type !== "Identifier" || !d.init || !isPlainStateCall(d.init)) continue;
+        const arg = unwrapTs(d.init.arguments?.[0]);
+        if (arg?.type === "NewExpression" && arg.callee?.type === "Identifier" && BUILTIN_STATE_TYPES.has(arg.callee.name)) {
+          builtinCandidates.set(d.id.name, { type: arg.callee.name, line: lineOf(source, d.start) });
+        }
+      }
+    }
+    if (builtinCandidates.size > 0) {
+      const types = new Map([...builtinCandidates].map(([n, meta]) => [n, meta.type]));
+      const mutatedBuiltins = /* @__PURE__ */ new Set();
+      const reassignedBuiltins = /* @__PURE__ */ new Set();
+      collectBuiltinStateSignals(program, types, mutatedBuiltins, reassignedBuiltins);
+      if (ast.fragment) collectBuiltinStateSignals(ast.fragment, types, mutatedBuiltins, reassignedBuiltins);
+      for (const [name, meta] of builtinCandidates) {
+        if (mutatedBuiltins.has(name) && !reassignedBuiltins.has(name)) {
+          nonreactiveBuiltinStates.push({ name, type: meta.type, line: meta.line });
+        }
+      }
+    }
     let moduleExtra;
     if (moduleProgram) {
       const moduleBrowserImports = collectBrowserGuardImports(moduleProgram);
@@ -1252,6 +1371,7 @@ function parseComponentFacts(source, filename) {
     mutatedProps,
     stalePropDerivations,
     rawableStates,
+    nonreactiveBuiltinStates,
     orphanEffects,
     orphanLifecycleCalls,
     browserGlobalRefs,
@@ -1277,6 +1397,7 @@ function emptyComponentFacts(file) {
     mutatedProps: [],
     stalePropDerivations: [],
     rawableStates: [],
+    nonreactiveBuiltinStates: [],
     orphanEffects: [],
     orphanLifecycleCalls: [],
     browserGlobalRefs: [],
@@ -3526,12 +3647,12 @@ var correctnessPropMutation = componentRule({
   title: "Mutated non-bindable prop",
   category: "correctness",
   label: "Prop mutation",
-  recommendation: "Clone the value before mutating it, communicate the change via a callback prop, or declare the prop $bindable if the parent and child should share it.",
-  rationale: "Svelte's docs say plainly: don't mutate props unless they are $bindable. A plain-object prop mutation is a silent no-op (the object isn't a state proxy); a reactive-state-proxy prop mutation works but triggers the ownership_invalid_mutation dev warning only when that code path actually runs. Neither is caught by the compiler, so this rule catches both statically.",
+  recommendation: "Runes mode: clone the value before mutating it, communicate the change via a callback prop, or declare the prop $bindable if the parent and child should share it. Legacy mode: reassign the prop after mutating it (e.g. `list = list`) so Svelte's assignment-based reactivity picks up the change.",
+  rationale: "Svelte's docs say plainly: don't mutate props unless they are $bindable. A plain-object prop mutation is a silent no-op (the object isn't a state proxy); a reactive-state-proxy prop mutation works but triggers the ownership_invalid_mutation dev warning only when that code path actually runs. In legacy mode, mutating methods like .push()/.splice() never trigger an update on their own \u2014 Svelte's reactivity there is based on assignments, not mutations. Neither case is caught by the compiler, so this rule catches both statically.",
   applies: (c) => c.mutatedProps.length > 0,
   bad: (c) => c.mutatedProps.map((m) => ({
     line: m.line,
-    message: `Prop "${m.name}" is mutated, but it is not declared $bindable`
+    message: m.legacy ? `Prop "${m.name}" is mutated directly \u2014 Svelte's legacy-mode reactivity is assignment-based, so this alone will not update the UI. Reassign it after mutating (e.g. "${m.name} = ${m.name}").` : `Prop "${m.name}" is mutated, but it is not declared $bindable`
   }))
 });
 
@@ -3542,15 +3663,34 @@ var correctnessStalePropDerivation = componentRule({
   category: "correctness",
   severity: "warning",
   label: "Props derived reactively",
-  recommendation: "Wrap the computation in $derived(...), or $derived.by(() => ...) when it needs a function body.",
-  rationale: "Svelte's guidance is to treat props as though they will change: a plain `let color = type === 'danger' ? 'red' : 'green'` freezes the first render's value, so the UI silently stops tracking the parent when the prop changes. $derived keeps the computation live at no cost.",
+  recommendation: "Wrap the computation in $derived(...) (or $derived.by(() => ...) for a function body) in runes-mode components; prefix the assignment with $: in legacy-mode components.",
+  rationale: "Svelte's guidance is to treat props as though they will change: a plain `let color = type === 'danger' ? 'red' : 'green'` freezes the first render's value, so the UI silently stops tracking the parent when the prop changes. In runes mode, $derived keeps the computation live at no cost; in legacy mode (export let props), a $: reactive statement does the same job.",
   fix: {
-    description: "Wrap the prop-derived computation in $derived(...) (or $derived.by(() => ...) for a function body), keeping the same expression."
+    description: "Wrap the prop-derived computation in $derived(...) (or $derived.by(() => ...) for a function body) in runes mode, or prefix the assignment with $: in legacy mode, keeping the same expression."
   },
   applies: (c) => c.stalePropDerivations.length > 0,
   bad: (c) => c.stalePropDerivations.map((s) => ({
     line: s.line,
-    message: `"${s.name}" is computed from a prop once, at initialization \u2014 it will not update when the prop changes. Wrap it in $derived.`
+    message: s.legacy ? `"${s.name}" is computed from a prop once, at initialization \u2014 it will not update when the prop changes. Prefix the assignment with $: to make it a reactive statement.` : `"${s.name}" is computed from a prop once, at initialization \u2014 it will not update when the prop changes. Wrap it in $derived.`
+  }))
+});
+
+// src/rules/correctness/nonreactive-builtin-state.ts
+var correctnessNonreactiveBuiltinState = componentRule({
+  id: "correctness/nonreactive-builtin-state",
+  title: "Non-reactive built-in in $state",
+  category: "correctness",
+  severity: "warning",
+  label: "Reactive collections in $state",
+  recommendation: "Import the reactive equivalent from 'svelte/reactivity' (SvelteMap, SvelteSet, SvelteDate, SvelteURL, SvelteURLSearchParams) and construct that instead.",
+  rationale: "$state deep-proxies plain objects and arrays only; built-in collection, date, and URL instances stay untracked, so property-level changes never reach effects, deriveds, or the template. Svelte's own answer is the drop-in classes in svelte/reactivity.",
+  fix: {
+    description: "Import Svelte<Type> from 'svelte/reactivity' and replace new <Type>(...) with new Svelte<Type>(...) \u2014 the API is identical."
+  },
+  applies: (c) => c.nonreactiveBuiltinStates.length > 0,
+  bad: (c) => c.nonreactiveBuiltinStates.map((s) => ({
+    line: s.line,
+    message: `"${s.name}" is a plain ${s.type} in $state \u2014 its mutations are not tracked, so the UI silently stops updating when it changes. Use Svelte${s.type} from 'svelte/reactivity'.`
   }))
 });
 
@@ -4056,6 +4196,7 @@ var allRules = [
   correctnessUnmutatedState,
   correctnessPropMutation,
   correctnessStalePropDerivation,
+  correctnessNonreactiveBuiltinState,
   correctnessOrphanEffect,
   correctnessOrphanLifecycle,
   correctnessServerBrowserGlobal,
@@ -5374,6 +5515,7 @@ export {
   correctnessEffectAsDerived,
   correctnessEffectAsOnMount,
   correctnessInstanceBrowserGlobal,
+  correctnessNonreactiveBuiltinState,
   correctnessOrphanEffect,
   correctnessOrphanLifecycle,
   correctnessPropMutation,

package/package.json

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