@colrealpro/react-luau-doctor 0.18.2 → 0.19.0

package/dist/cli.js

@@ -11,7 +11,7 @@ var package_default = {
   publishConfig: {
     access: "public"
   },
-  version: "0.18.2",
+  version: "0.19.0",
   description: "Static analysis for React-Luau hooks, effects, rendering, and performance.",
   license: "MIT",
   type: "module",
@@ -22,6 +22,7 @@ var package_default = {
     "dist",
     "vendor",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md"
   ],
@@ -864,7 +865,7 @@ import crypto from "crypto";
 import fs4 from "fs";
 import os from "os";
 import path4 from "path";
-var CACHE_SCHEMA_VERSION = 1;
+import { fileURLToPath } from "url";
 var MAX_CACHED_REPORTS = 8;
 function normalizeRelative(value) {
   return value.split(path4.sep).join("/");
@@ -872,6 +873,54 @@ function normalizeRelative(value) {
 function hashText(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
+var analyzerHash = null;
+function hashAnalyzerFile(hash, root, filename) {
+  if (!fs4.existsSync(filename))
+    return;
+  hash.update(normalizeRelative(path4.relative(root, filename)));
+  hash.update("\x00");
+  hash.update(fs4.readFileSync(filename));
+  hash.update("\x00");
+}
+function sourceFiles(directory) {
+  if (!fs4.existsSync(directory))
+    return [];
+  const files = [];
+  for (const entry of fs4.readdirSync(directory, { withFileTypes: true })) {
+    const filename = path4.join(directory, entry.name);
+    if (entry.isDirectory())
+      files.push(...sourceFiles(filename));
+    else if (entry.isFile() && entry.name.endsWith(".ts"))
+      files.push(filename);
+  }
+  return files;
+}
+function currentAnalyzerHash() {
+  if (analyzerHash)
+    return analyzerHash;
+  const hash = crypto.createHash("sha256");
+  let packageRoot = path4.resolve(path4.dirname(fileURLToPath(import.meta.url)), "..");
+  let bundledCli = null;
+  try {
+    const entrypoint = process.argv[1] ? fs4.realpathSync(process.argv[1]) : null;
+    if (entrypoint && path4.basename(entrypoint) === "cli.js" && path4.basename(path4.dirname(entrypoint)) === "dist") {
+      bundledCli = entrypoint;
+      packageRoot = path4.dirname(path4.dirname(entrypoint));
+    }
+  } catch {}
+  if (bundledCli) {
+    hashAnalyzerFile(hash, packageRoot, bundledCli);
+    hashAnalyzerFile(hash, packageRoot, path4.join(path4.dirname(bundledCli), "scan-worker.js"));
+  } else {
+    for (const filename of sourceFiles(path4.join(packageRoot, "src")).sort()) {
+      hashAnalyzerFile(hash, packageRoot, filename);
+    }
+  }
+  hashAnalyzerFile(hash, packageRoot, path4.join(packageRoot, "package.json"));
+  hashAnalyzerFile(hash, packageRoot, path4.join(packageRoot, "vendor", "tree-sitter-luau.wasm"));
+  analyzerHash = hash.digest("hex");
+  return analyzerHash;
+}
 function stableValue(value) {
   if (Array.isArray(value))
     return value.map(stableValue);
@@ -901,7 +950,7 @@ function projectCacheFilename(root) {
 function readPayload(filename, root) {
   try {
     const parsed = JSON.parse(fs4.readFileSync(filename, "utf8"));
-    if (parsed.schemaVersion !== CACHE_SCHEMA_VERSION || parsed.analyzerVersion !== package_default.version || path4.resolve(parsed.root) !== path4.resolve(root) || !parsed.files || typeof parsed.fingerprint !== "string")
+    if (parsed.analyzerHash !== currentAnalyzerHash() || path4.resolve(parsed.root) !== path4.resolve(root) || !parsed.files || typeof parsed.fingerprint !== "string")
       return null;
     return parsed;
   } catch {
@@ -1121,8 +1170,7 @@ function saveProjectCache(session, project, effectModules = session.previous?.ef
     reports[reportKey] = { ...report, lastUsedAt: Date.now() };
   const prunedReports = Object.fromEntries(Object.entries(reports).sort(([, left], [, right]) => right.lastUsedAt - left.lastUsedAt).slice(0, MAX_CACHED_REPORTS));
   writePayload(session.filename, {
-    schemaVersion: CACHE_SCHEMA_VERSION,
-    analyzerVersion: package_default.version,
+    analyzerHash: currentAnalyzerHash(),
     root: path4.resolve(session.root),
     fingerprint: session.fingerprint,
     files: session.files,
@@ -2141,6 +2189,71 @@ function applyMasks(source, ranges) {
   }
   return output;
 }
+function genericFunctionParameterRanges(source, mask) {
+  const ranges = [];
+  const functionPattern = /\bfunction\b/g;
+  for (const match of source.matchAll(functionPattern)) {
+    const start = match.index;
+    if (!isCode(mask, start, start + match[0].length))
+      continue;
+    let cursor = start + match[0].length;
+    while (cursor < source.length) {
+      const char = source[cursor];
+      if (/\s/.test(char)) {
+        cursor += 1;
+        continue;
+      }
+      if (char === "(")
+        break;
+      if (char === "<") {
+        let depth = 0;
+        const rangeStart = cursor;
+        while (cursor < source.length) {
+          if (isCode(mask, cursor)) {
+            if (source[cursor] === "<")
+              depth += 1;
+            else if (source[cursor] === ">") {
+              depth -= 1;
+              if (depth === 0) {
+                cursor += 1;
+                ranges.push({ start: rangeStart, end: cursor });
+                break;
+              }
+            }
+          }
+          cursor += 1;
+        }
+        break;
+      }
+      if (/[A-Za-z0-9_.:]/.test(char)) {
+        cursor += 1;
+        continue;
+      }
+      break;
+    }
+  }
+  return ranges;
+}
+function normalizeGenericTypePackUses(source, mask) {
+  const declarationRanges = genericFunctionParameterRanges(source, mask);
+  const replacements = [];
+  const packPattern = /\b[A-Za-z_][A-Za-z0-9_]*\.\.\./g;
+  for (const match of source.matchAll(packPattern)) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (!isCode(mask, start, end))
+      continue;
+    if (declarationRanges.some((range) => start >= range.start && end <= range.end))
+      continue;
+    const name = match[0].slice(0, -3);
+    replacements.push({ start, end, value: `...${name}` });
+  }
+  let output = source;
+  for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+    output = `${output.slice(0, replacement.start)}${replacement.value}${output.slice(replacement.end)}`;
+  }
+  return output;
+}
 function normalizeIntegerLiteralSuffixes(source, mask) {
   const suffixes = [];
   const integerPattern = /\b(?:0[xX][0-9A-Fa-f_]+|0[bB][01_]+|[0-9][0-9_]*)i\b/g;
@@ -2180,13 +2293,14 @@ function parserCompatibleSource(source) {
   const mask = codeMask(source);
   const keywordCompatible = replaceContextualKeywords(source, mask);
   const literalCompatible = normalizeIntegerLiteralSuffixes(keywordCompatible, mask);
+  const packCompatible = normalizeGenericTypePackUses(literalCompatible, mask);
   const ranges = [
     ...maskTypeAliases(source, mask),
     ...maskTypeLevelBlocks(source, mask),
     ...attributeRanges(source, mask),
     ...explicitTypeArgumentRanges(source, mask)
   ];
-  const masked = applyMasks(literalCompatible, ranges);
+  const masked = applyMasks(packCompatible, ranges);
   return masked.replace(/^(\s*)type(?=\s*(?:\+=|-=|\*=|\/=|%=|\^=|\.\.=|=(?!=)))/gm, "$1_typ");
 }
 
@@ -2399,6 +2513,8 @@ function hasRobloxReceiver(path6, call, context) {
 }
 var runServiceCallCache = new WeakMap;
 var runServiceExpressionCache = new WeakMap;
+var highFrequencyRobloxCallCache = new WeakMap;
+var highFrequencyRobloxExpressionCache = new WeakMap;
 function cachedNodeBoolean(cache, context, node, compute) {
   let entries = cache.get(context);
   if (!entries) {
@@ -2463,6 +2579,33 @@ function isHighFrequencyRunServiceCall(call, context) {
     return Boolean(bind && rootIsRunService(bind[1], call, context));
   });
 }
+var HIGH_FREQUENCY_ROBLOX_EVENTS = new Set([
+  "InputChanged",
+  "TouchMoved",
+  "Move"
+]);
+function isHighFrequencyRobloxExpression(node, context) {
+  return cachedNodeBoolean(highFrequencyRobloxExpressionCache, context, node, () => {
+    if (isHighFrequencyRunServiceExpression(node, context))
+      return true;
+    const normalized = node.text.replace(/\s+/g, "");
+    const match = normalized.match(/^(.+)\.(InputChanged|TouchMoved|Move)$/);
+    if (!match || !HIGH_FREQUENCY_ROBLOX_EVENTS.has(match[2]))
+      return false;
+    return hasRobloxReceiver(match[1], node, context);
+  });
+}
+function isHighFrequencyRobloxCall(call, context) {
+  return cachedNodeBoolean(highFrequencyRobloxCallCache, context, call, () => {
+    if (isHighFrequencyRunServiceCall(call, context))
+      return true;
+    const normalized = (context.getCallPath(call) ?? "").replace(/\s+/g, "");
+    const event = normalized.match(/^(.+)\.(InputChanged|TouchMoved|Move):Connect$/);
+    if (!event || !HIGH_FREQUENCY_ROBLOX_EVENTS.has(event[2]))
+      return false;
+    return hasRobloxReceiver(event[1], call, context);
+  });
+}
 function sourceHasHighFrequencyRunService(source) {
   if (/game\s*:\s*GetService\s*\(\s*["']RunService["']\s*\)\s*(?:\.\s*(?:RenderStepped|Heartbeat|Stepped|PreRender|PreSimulation|PostSimulation)\s*:\s*Connect|:\s*(?:BindToRenderStep|BindToSimulation))/.test(source)) {
     return true;
@@ -2479,6 +2622,36 @@ function sourceHasHighFrequencyRunService(source) {
   }
   return false;
 }
+function sourceHasHighFrequencyRobloxEvent(source) {
+  if (sourceHasHighFrequencyRunService(source))
+    return true;
+  if (/game\s*:\s*GetService\s*\(\s*["']UserInputService["']\s*\)\s*\.\s*(?:InputChanged|TouchMoved)\s*:\s*Connect/.test(source)) {
+    return true;
+  }
+  const serviceAliases = new Set;
+  for (const match of source.matchAll(/\blocal\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*game\s*:\s*GetService\s*\(\s*["']UserInputService["']\s*\)/g)) {
+    serviceAliases.add(match[1]);
+  }
+  for (const alias of serviceAliases) {
+    const escaped = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${escaped}\\s*\\.\\s*(?:InputChanged|TouchMoved)\\s*:\\s*Connect`).test(source)) {
+      return true;
+    }
+  }
+  const playersAliases = new Set;
+  for (const match of source.matchAll(/\blocal\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*game\s*:\s*GetService\s*\(\s*["']Players["']\s*\)/g)) {
+    playersAliases.add(match[1]);
+  }
+  for (const players of playersAliases) {
+    const escapedPlayers = players.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    for (const match of source.matchAll(new RegExp(`\\blocal\\s+([A-Za-z_][A-Za-z0-9_]*)\\s*=\\s*${escapedPlayers}\\s*\\.\\s*LocalPlayer\\s*:\\s*GetMouse\\s*\\(\\s*\\)`, "g"))) {
+      const mouse = match[1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (new RegExp(`\\b${mouse}\\s*\\.\\s*Move\\s*:\\s*Connect`).test(source))
+        return true;
+    }
+  }
+  return false;
+}
 function knownYieldReason(path6, call, context) {
   const normalized = path6.replace(/\s+/g, "");
   if (normalized === "task.wait")
@@ -5025,7 +5198,7 @@ var rerenderHighFrequencyState = {
       seen.add(key);
       const renderCost = componentRenderCost(context, component);
       diagnostics.push({
-        node: callNameNode(call),
+        node: callNameNode(binding.call),
         severity: "warning",
         message: `${binding.valueName} has a state setter called from a per-frame callback and may cause frequent rerenders when its value changes.`,
         help: renderCost.length > 0 ? `This render also performs ${renderCost.join(" and ")}. Isolate or throttle the high-frequency state, or use Bindings for host-property-only updates.` : "Isolate or throttle the high-frequency state. Use React.useBinding when the value only drives host Instance properties."
@@ -5302,7 +5475,9 @@ var preferUseRefForMutableCell = {
 };
 
 // src/rules/prefer-binding-over-state.ts
-var EXTERNAL_CALLBACK = /(?:^|[.:])(?:Connect|Once|Subscribe|Observe|Listen|Watch)$/i;
+var EXTERNAL_CALLBACK = /(?:^|[.:])(?:Connect|Subscribe|Observe|Listen|Watch|onStep|onUpdate|onChange|onChanged)$/i;
+var PERSISTENT_MIRROR_CALLBACK = /(?:^|[.:])(?:Connect|Subscribe|Observe|Listen|Watch|onStep|onUpdate|onChange|onChanged)$/i;
+var LIKELY_CONTINUOUS_CALLBACK = /(?:^|[.:])onStep$/i;
 var NON_BINDABLE_HOST_FIELDS = new Set(["ref", "key", "children"]);
 function replaceWithinNode(container, target, replacement) {
   const start = target.startIndex - container.startIndex;
@@ -5425,13 +5600,64 @@ var TRANSPARENT_PARENTS = new Set([
   "string_interpolation",
   "expression_list",
   "assignment_statement",
-  "arguments",
-  "function_call",
   "dot_index_expression",
   "method_index_expression",
   "table_constructor",
   "field"
 ]);
+var PURE_BINDING_DERIVATION_CALL = /^(?:tostring|tonumber|type|typeof|math\.[A-Za-z_][A-Za-z0-9_]*|string\.[A-Za-z_][A-Za-z0-9_]*|utf8\.[A-Za-z_][A-Za-z0-9_]*|bit32\.[A-Za-z_][A-Za-z0-9_]*|(?:UDim|UDim2|Vector2|Vector3|Color3|CFrame|Rect|NumberRange|NumberSequence|ColorSequence|BrickColor|Font)\.[A-Za-z_][A-Za-z0-9_]*)$/;
+var HOST_FEEDBACK_PROPERTIES = new Set([
+  "AbsoluteSize",
+  "AbsolutePosition",
+  "AbsoluteRotation",
+  "AbsoluteContentSize",
+  "AbsoluteCanvasSize",
+  "AbsoluteCellSize",
+  "AbsoluteCellCount",
+  "TextBounds",
+  "CanvasPosition"
+]);
+var LIKELY_CONTINUOUS_PROPERTIES = new Set([
+  "CFrame",
+  "WorldCFrame",
+  "Position",
+  "WorldPosition",
+  "Rotation",
+  "Orientation",
+  "CanvasPosition",
+  "PlaybackLoudness",
+  "TimePosition"
+]);
+var SEMANTIC_SNAPSHOT_EXPRESSION = /\b(?:getState|getSnapshot|snapshot|selector|select|table\s*\.\s*(?:clone|freeze|move))\b|(?:\.|\[\s*["'])State(?:\b|["']\s*\])/i;
+function isBindingMapSafeCall(call, context) {
+  if (call.type !== "function_call")
+    return false;
+  const path7 = context.resolveCallPath(context.getCallPath(call) ?? "").replace(/\s+/g, "");
+  return PURE_BINDING_DERIVATION_CALL.test(path7);
+}
+function isTransparentParent(parent, context) {
+  if (parent.type === "function_call")
+    return isBindingMapSafeCall(parent, context);
+  if (parent.type === "arguments") {
+    return parent.parent?.type === "function_call" && isBindingMapSafeCall(parent.parent, context);
+  }
+  return TRANSPARENT_PARENTS.has(parent.type);
+}
+function stringLiteralValue(node) {
+  if (!node)
+    return null;
+  return node.text.trim().match(/^["']([^"']+)["']$/)?.[1] ?? null;
+}
+function observedPropertyForCall(summary, call, context) {
+  if (summary.observedPropertyName)
+    return summary.observedPropertyName;
+  if (summary.observedPropertyParameterIndex === undefined)
+    return null;
+  return stringLiteralValue(context.callArguments(call)[summary.observedPropertyParameterIndex]);
+}
+function isStrongHostFeedbackProperty(property) {
+  return Boolean(property && HOST_FEEDBACK_PROPERTIES.has(property));
+}
 function isInside2(node, ancestor) {
   let current = node;
   while (current) {
@@ -5515,13 +5741,59 @@ function isTransparentUsage(node, context, compatibleComponentProps) {
     }
     if (parent.type === "function_definition" || parent.type === "function_declaration")
       return false;
-    if (!TRANSPARENT_PARENTS.has(parent.type))
+    if (!isTransparentParent(parent, context))
       return false;
     current = parent;
   }
   return false;
 }
-function derivedLocalDeclarationForRead(node) {
+function isDirectBindingValueUsage(node, context, compatibleComponentProps) {
+  let current = node;
+  while (current) {
+    const parent = current.parent;
+    if (!parent)
+      return false;
+    if (parent.type === "parenthesized_expression" || parent.type === "cast_expression" || parent.type === "type_cast_expression") {
+      current = parent;
+      continue;
+    }
+    if (parent.type !== "field")
+      return false;
+    const value = fieldValue(parent);
+    if (!value || !sameNode(value, current))
+      return false;
+    const property = fieldName(parent);
+    if (!property || NON_BINDABLE_HOST_FIELDS.has(property))
+      return false;
+    const table = parent.parent;
+    const args = table?.parent;
+    const call = args?.parent;
+    if (table?.type !== "table_constructor" || args?.type !== "arguments" || !call || !isCreateElementCall2(call, context)) {
+      return false;
+    }
+    if (!sameNode(context.callArguments(call)[1], table))
+      return false;
+    if (isHostCreateElementCall(call, context))
+      return true;
+    const component = context.callArguments(call)[0]?.text.trim() ?? "";
+    return compatibleComponentProps.get(component)?.has(property) ?? false;
+  }
+  return false;
+}
+function allReadsDirectlyBindingSubstitutable(valueName, owner, declaration, context, compatibleComponentProps) {
+  if (!owner.body)
+    return false;
+  let reads = 0;
+  for (const node of context.walk(owner.body)) {
+    if (!isReadNode(node, valueName, owner, declaration))
+      continue;
+    reads += 1;
+    if (!isDirectBindingValueUsage(node, context, compatibleComponentProps))
+      return false;
+  }
+  return reads > 0;
+}
+function derivedLocalDeclarationForRead(node, context) {
   let current = node;
   while (current) {
     const parent = current.parent;
@@ -5531,7 +5803,30 @@ function derivedLocalDeclarationForRead(node) {
       return parent;
     if (parent.type === "function_definition" || parent.type === "function_declaration")
       return null;
-    if (!TRANSPARENT_PARENTS.has(parent.type))
+    if (!isTransparentParent(parent, context))
+      return null;
+    current = parent;
+  }
+  return null;
+}
+function opaqueDerivedLocalDeclarationForRead(node, context) {
+  let current = node;
+  while (current) {
+    const parent = current.parent;
+    if (!parent)
+      return null;
+    if (parent.type === "variable_declaration")
+      return parent;
+    if (parent.type === "function_definition" || parent.type === "function_declaration")
+      return null;
+    if (parent.type === "if_statement" || parent.type === "elseif_clause" || parent.type === "while_statement" || parent.type === "repeat_statement" || parent.type === "for_statement" || parent.type === "for_in_statement" || parent.type === "return_statement")
+      return null;
+    if (parent.type === "function_call") {
+      const path7 = context.resolveCallPath(context.getCallPath(parent) ?? "");
+      if (/^React\.use(?:Memo|Callback|Effect|LayoutEffect)$/.test(path7))
+        return null;
+    }
+    if (!TRANSPARENT_PARENTS.has(parent.type) && parent.type !== "arguments" && parent.type !== "function_call")
       return null;
     current = parent;
   }
@@ -5551,7 +5846,7 @@ function stateReadsAreBindingCompatible(valueName, owner, declaration, context,
     reads += 1;
     if (isTransparentUsage(node, context, compatibleComponentProps))
       continue;
-    const derivedDeclaration = derivedLocalDeclarationForRead(node);
+    const derivedDeclaration = derivedLocalDeclarationForRead(node, context);
     const derivedNames = derivedDeclaration ? declarationNames2(derivedDeclaration) : [];
     if (derivedDeclaration && derivedNames.length === 1) {
       if (stateReadsAreBindingCompatible(derivedNames[0], owner, derivedDeclaration, context, compatibleComponentProps, new Set(visited)))
@@ -5561,12 +5856,46 @@ function stateReadsAreBindingCompatible(valueName, owner, declaration, context,
   }
   return reads > 0;
 }
+function propertyChangedSignalProperty(text) {
+  return text.match(/GetPropertyChangedSignal\s*\(\s*["']([^"']+)["']\s*\)/)?.[1] ?? null;
+}
+function reactChangePropertyForCallback(node) {
+  let current = node.parent;
+  while (current && current.type !== "function_definition" && current.type !== "function_declaration") {
+    if (current.type === "field") {
+      return current.text.match(/React\s*\.\s*Change\s*\.\s*([A-Za-z_][A-Za-z0-9_]*)/)?.[1] ?? null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+function evidenceForExternalSource(highFrequency, hostFeedbackProperty) {
+  const hostFeedbackProperties = new Set;
+  if (hostFeedbackProperty)
+    hostFeedbackProperties.add(hostFeedbackProperty);
+  return {
+    highFrequency,
+    external: true,
+    hostFeedbackProperties,
+    genericExternal: !highFrequency && !hostFeedbackProperty
+  };
+}
+function mergeSourceEvidence(target, source) {
+  target.highFrequency ||= source.highFrequency;
+  target.external ||= source.external;
+  target.genericExternal ||= source.genericExternal;
+  for (const property of source.hostFeedbackProperties)
+    target.hostFeedbackProperties.add(property);
+}
 function callbackSource(call, context) {
   const normalized = (context.getCallPath(call) ?? "").replace(/\s+/g, "");
-  const highFrequency = isHighFrequencyRunServiceCall(call, context);
+  const highFrequency = isHighFrequencyRobloxCall(call, context) || LIKELY_CONTINUOUS_CALLBACK.test(normalized);
+  const hostFeedbackProperty = propertyChangedSignalProperty(call.text);
   const final = normalized.split(/[.:]/).at(-1) ?? normalized;
-  const external = highFrequency || EXTERNAL_CALLBACK.test(normalized) || EXTERNAL_CALLBACK.test(final);
-  return { highFrequency, external };
+  const external = highFrequency || Boolean(hostFeedbackProperty) || EXTERNAL_CALLBACK.test(normalized) || EXTERNAL_CALLBACK.test(final);
+  if (!external)
+    return null;
+  return evidenceForExternalSource(highFrequency, hostFeedbackProperty);
 }
 function importedCallbackSource(call, callbackArgument, importedCallbacks, context) {
   const path7 = context.getCallPath(call) ?? "";
@@ -5577,12 +5906,14 @@ function importedCallbackSource(call, callbackArgument, importedCallbacks, conte
   const callbackIndex = args.findIndex((arg) => sameNode(arg, callbackArgument));
   if (callbackIndex < 0 || !summary.callbackParameterIndexes.includes(callbackIndex))
     return null;
-  return {
-    highFrequency: summary.highFrequency || args.some((arg) => isHighFrequencyRunServiceExpression(arg, context)),
-    external: true
-  };
+  const highFrequency = summary.highFrequency || args.some((arg) => isHighFrequencyRobloxExpression(arg, context));
+  const hostFeedbackProperty = args.map((arg) => propertyChangedSignalProperty(arg.text)).find((property) => Boolean(property));
+  return evidenceForExternalSource(highFrequency, hostFeedbackProperty);
 }
 function directCallbackSource(node, importedCallbacks, context) {
+  const reactChangeProperty = reactChangePropertyForCallback(node);
+  if (reactChangeProperty)
+    return evidenceForExternalSource(false, reactChangeProperty);
   const parent = node.parent;
   if (parent?.type !== "arguments" || parent.parent?.type !== "function_call")
     return null;
@@ -5590,14 +5921,17 @@ function directCallbackSource(node, importedCallbacks, context) {
   const imported = importedCallbackSource(call, node, importedCallbacks, context);
   if (imported)
     return imported;
-  const source = callbackSource(call, context);
-  return source.external ? source : null;
+  return callbackSource(call, context);
 }
 function namedFunctionCallbackSource(fn, owner, importedCallbacks, context) {
   if (!fn.name || !owner.body)
     return null;
-  let foundExternal = false;
-  let foundHighFrequency = false;
+  const result = {
+    highFrequency: false,
+    external: false,
+    hostFeedbackProperties: new Set,
+    genericExternal: false
+  };
   for (const call of context.walk(owner.body)) {
     if (call.type !== "function_call")
       continue;
@@ -5605,14 +5939,12 @@ function namedFunctionCallbackSource(fn, owner, importedCallbacks, context) {
     const callbackArg = args.find((arg) => arg.type === "identifier" && arg.text === fn.name);
     if (!callbackArg)
       continue;
-    const imported = importedCallbackSource(call, callbackArg, importedCallbacks, context);
-    const source = imported ?? callbackSource(call, context);
-    if (!source.external)
+    const source = importedCallbackSource(call, callbackArg, importedCallbacks, context) ?? callbackSource(call, context);
+    if (!source)
       continue;
-    foundExternal = true;
-    foundHighFrequency ||= source.highFrequency;
+    mergeSourceEvidence(result, source);
   }
-  return foundExternal ? { highFrequency: foundHighFrequency, external: true } : null;
+  return result.external ? result : null;
 }
 function setterCallbackSource(call, binding, importedCallbacks, context) {
   const owner = binding.owner;
@@ -5626,25 +5958,178 @@ function setterCallbackSource(call, binding, importedCallbacks, context) {
     return direct;
   return namedFunctionCallbackSource(nearest, owner, importedCallbacks, context);
 }
-function bindingHasExternalOrHighFrequencyUpdates(binding, importedCallbacks, context) {
+function mirrorConfidenceRank(confidence) {
+  if (confidence === "strong")
+    return 2;
+  if (confidence === "possible")
+    return 1;
+  return 0;
+}
+function mergeMirrorConfidence(a, b) {
+  return mirrorConfidenceRank(b) > mirrorConfidenceRank(a) ? b : a;
+}
+function isLiteralStateTransition(node) {
+  if (!node)
+    return true;
+  const text = node.text.trim();
+  return /^(?:true|false|nil|[-+]?\d+(?:\.\d+)?|["'][^"']*["'])$/.test(text);
+}
+function isSemanticSnapshotExpression(node) {
+  return Boolean(node && SEMANTIC_SNAPSHOT_EXPRESSION.test(node.text));
+}
+function expressionReferencesCallbackParameter(expression, callback, context) {
+  if (callback.parameters.length === 0)
+    return false;
+  const parameters = new Set(callback.parameters);
+  return [...context.walk(expression)].some((node) => node.type === "identifier" && parameters.has(node.text));
+}
+var PURE_EXPRESSION_ROOTS = new Set([
+  "math",
+  "string",
+  "utf8",
+  "bit32",
+  "UDim",
+  "UDim2",
+  "Vector2",
+  "Vector3",
+  "Color3",
+  "CFrame",
+  "Rect",
+  "NumberRange",
+  "NumberSequence",
+  "ColorSequence",
+  "BrickColor",
+  "Font",
+  "Enum",
+  "tostring",
+  "tonumber",
+  "type",
+  "typeof"
+]);
+function callbackLocalNamesBefore(callback, before, context) {
+  const names = new Set;
+  if (!callback.body)
+    return names;
+  for (const node of context.walk(callback.body)) {
+    if (node.startIndex >= before.startIndex)
+      continue;
+    if (context.nearestFunction(node) !== callback || node.type !== "variable_declaration")
+      continue;
+    for (const name of declarationNames2(node))
+      names.add(name);
+  }
+  return names;
+}
+function expressionHasExternalInput(expression, callback, setterCall, context) {
+  const callbackLocals = callbackLocalNamesBefore(callback, setterCall, context);
+  const callbackParameters = new Set(callback.parameters);
+  for (const node of context.walk(expression)) {
+    if (node.type !== "identifier" || isIdentifierPropertyName2(node))
+      continue;
+    const name = node.text;
+    if (callbackParameters.has(name))
+      return true;
+    if (callbackLocals.has(name))
+      continue;
+    if (context.model.stateValues.has(name))
+      continue;
+    if (PURE_EXPRESSION_ROOTS.has(name))
+      continue;
+    return true;
+  }
+  return false;
+}
+function setterHasDistinctValuesInCallback(call, callback, context) {
+  if (!callback.body)
+    return false;
+  const setterPath = context.getCallPath(call);
+  const distinctValues = new Set;
+  for (const sibling of context.walk(callback.body)) {
+    if (sibling.type !== "function_call" || context.nearestFunction(sibling) !== callback)
+      continue;
+    if (context.getCallPath(sibling) !== setterPath)
+      continue;
+    const argument = context.callArguments(sibling)[0];
+    if (argument)
+      distinctValues.add(argument.text.trim());
+  }
+  return distinctValues.size > 1;
+}
+function setterCallMirrorConfidence(call, callback, source, context) {
+  const value = context.callArguments(call)[0];
+  if (!value || value.type === "function_definition")
+    return "none";
+  if (isLiteralStateTransition(value)) {
+    return source.highFrequency && setterHasDistinctValuesInCallback(call, callback, context) ? "strong" : "none";
+  }
+  if (isSemanticSnapshotExpression(value))
+    return "none";
+  if (expressionReferencesCallbackParameter(value, callback, context))
+    return "strong";
+  if (source.hostFeedbackProperties.size > 0) {
+    const text = value.text;
+    if ([...source.hostFeedbackProperties].some((property) => new RegExp(`(?:\\.|["'])${property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(text))) {
+      return "strong";
+    }
+  }
+  if (!expressionHasExternalInput(value, callback, call, context)) {
+    return source.highFrequency && setterHasDistinctValuesInCallback(call, callback, context) ? "strong" : "none";
+  }
+  if (source.highFrequency)
+    return "strong";
+  return source.genericExternal ? "possible" : "strong";
+}
+function mergeBindingUpdateEvidence(target, source, mirrorConfidence) {
+  if (mirrorConfidence === "none")
+    return;
+  mergeSourceEvidence(target, source);
+  target.mirrorConfidence = mergeMirrorConfidence(target.mirrorConfidence, mirrorConfidence);
+}
+function bindingUpdateEvidence(binding, importedCallbacks, context) {
   const owner = binding.owner;
   if (!owner?.body)
     return null;
-  let highFrequency = false;
-  let external = false;
+  const result = {
+    highFrequency: false,
+    external: false,
+    hostFeedbackProperties: new Set,
+    genericExternal: false,
+    mirrorConfidence: "none"
+  };
   for (const node of context.walk(owner.body)) {
     if (node.type !== "function_call")
       continue;
     const path7 = context.getCallPath(node);
-    if (path7 !== binding.setterName)
+    if (path7 === binding.setterName) {
+      const source2 = setterCallbackSource(node, binding, importedCallbacks, context);
+      const callback = context.nearestFunction(node);
+      if (!source2 || !callback || callback === owner)
+        continue;
+      mergeBindingUpdateEvidence(result, source2, setterCallMirrorConfidence(node, callback, source2, context));
       continue;
-    const source = setterCallbackSource(node, binding, importedCallbacks, context);
+    }
+    const args = context.callArguments(node);
+    const setterArg = args.find((arg) => arg.type === "identifier" && arg.text === binding.setterName);
+    if (!setterArg)
+      continue;
+    const normalized = (context.getCallPath(node) ?? "").replace(/\s+/g, "");
+    const imported = importedCallbackSource(node, setterArg, importedCallbacks, context);
+    const source = imported ?? (PERSISTENT_MIRROR_CALLBACK.test(normalized) ? callbackSource(node, context) : null);
     if (!source)
       continue;
-    highFrequency ||= source.highFrequency;
-    external ||= source.external;
+    mergeBindingUpdateEvidence(result, source, "strong");
   }
-  return highFrequency || external ? { highFrequency, external } : null;
+  return result.external && result.mirrorConfidence !== "none" ? result : null;
+}
+function hasStrongHostFeedbackEvidence(source) {
+  if (source.genericExternal || source.hostFeedbackProperties.size === 0)
+    return false;
+  return [...source.hostFeedbackProperties].every((property) => isStrongHostFeedbackProperty(property));
+}
+function hasLikelyContinuousPropertyEvidence(source) {
+  if (source.hostFeedbackProperties.size === 0)
+    return false;
+  return [...source.hostFeedbackProperties].every((property) => LIKELY_CONTINUOUS_PROPERTIES.has(property));
 }
 function returnedHookValues(binding, context) {
   const owner = binding.owner;
@@ -5722,14 +6207,8 @@ function callDefinitelyUsesBindingMode(summary, call, context) {
     return false;
   return truthy === summary.bindingWhenTruthy;
 }
-function shouldRecommendImportedHook(summary, call, localName, owner, declaration, context, compatibleComponentProps) {
-  if (!summary.external || callDefinitelyUsesBindingMode(summary, call, context))
-    return false;
-  if (!hasAnyRead(localName, owner, declaration, context))
-    return false;
-  if (summary.sourceKind === "measurement")
-    return true;
-  return stateReadsAreBindingCompatible(localName, owner, declaration, context, compatibleComponentProps);
+function hasExplicitBindingMode(summary) {
+  return summary.bindingModeParameterIndex !== undefined && summary.bindingWhenTruthy !== undefined;
 }
 var LIKELY_VISUAL_PROP = /(?:position|size|rotation|transparency|opacity|color|image|text|anchor|visible|enabled|layout|scale|offset|zindex|canvas|viewport|cframe|width|height|radius|stroke|padding|spacing|angle|alpha|progress)/i;
 function createElementPropUsage(node, context) {
@@ -5758,7 +6237,7 @@ function createElementPropUsage(node, context) {
     }
     if (parent.type === "function_definition" || parent.type === "function_declaration")
       return null;
-    if (!TRANSPARENT_PARENTS.has(parent.type))
+    if (!isTransparentParent(parent, context))
       return null;
     current = parent;
   }
@@ -5790,17 +6269,17 @@ function isEffectUsage(node, context) {
   }
   return false;
 }
-function isStructuralUsage(node) {
+function isStructuralUsage(node, context) {
   let current = node;
   while (current) {
     const parent = current.parent;
     if (!parent)
       return false;
-    if (parent.type === "if_statement" || parent.type === "elseif_clause" || parent.type === "while_statement" || parent.type === "repeat_statement" || parent.type === "return_statement")
+    if (parent.type === "if_statement" || parent.type === "elseif_clause" || parent.type === "while_statement" || parent.type === "repeat_statement" || parent.type === "for_statement" || parent.type === "for_in_statement" || parent.type === "return_statement")
       return true;
     if (parent.type === "function_definition" || parent.type === "function_declaration")
       return false;
-    if (!TRANSPARENT_PARENTS.has(parent.type))
+    if (!isTransparentParent(parent, context))
       return false;
     current = parent;
   }
@@ -5813,11 +6292,11 @@ function classifyBindingUsage(node, context, compatibleComponentProps) {
     return "custom-component";
   if (isEffectUsage(node, context))
     return "effect";
-  if (isStructuralUsage(node))
+  if (isStructuralUsage(node, context))
     return "structural";
   return "unknown";
 }
-function bindingUsageSummary(valueName, owner, declaration, context, compatibleComponentProps) {
+function bindingUsageSummary(valueName, owner, declaration, context, compatibleComponentProps, visited = new Set) {
   const summary = {
     reads: 0,
     compatible: 0,
@@ -5829,9 +6308,45 @@ function bindingUsageSummary(valueName, owner, declaration, context, compatibleC
   };
   if (!owner.body)
     return summary;
+  const visitKey = `${declaration.startIndex}:${valueName}`;
+  if (visited.has(visitKey))
+    return summary;
+  visited.add(visitKey);
   for (const node of context.walk(owner.body)) {
     if (!isReadNode(node, valueName, owner, declaration))
       continue;
+    if (!isTransparentUsage(node, context, compatibleComponentProps)) {
+      const derivedDeclaration = derivedLocalDeclarationForRead(node, context);
+      const derivedNames = derivedDeclaration ? declarationNames2(derivedDeclaration) : [];
+      if (derivedDeclaration && derivedNames.length === 1) {
+        const derived = bindingUsageSummary(derivedNames[0], owner, derivedDeclaration, context, compatibleComponentProps, new Set(visited));
+        if (derived.reads > 0) {
+          summary.reads += derived.reads;
+          summary.compatible += derived.compatible;
+          summary.customComponent += derived.customComponent;
+          summary.visualCustomComponent += derived.visualCustomComponent;
+          summary.effect += derived.effect;
+          summary.structural += derived.structural;
+          summary.unknown += derived.unknown;
+          continue;
+        }
+      }
+      const opaqueDeclaration = opaqueDerivedLocalDeclarationForRead(node, context);
+      const opaqueNames = opaqueDeclaration ? declarationNames2(opaqueDeclaration) : [];
+      if (opaqueDeclaration && opaqueNames.length === 1) {
+        const derived = bindingUsageSummary(opaqueNames[0], owner, opaqueDeclaration, context, compatibleComponentProps, new Set(visited));
+        if (derived.reads > 0) {
+          summary.reads += derived.reads + 1;
+          summary.compatible += derived.compatible;
+          summary.customComponent += derived.customComponent;
+          summary.visualCustomComponent += derived.visualCustomComponent;
+          summary.effect += derived.effect;
+          summary.structural += derived.structural;
+          summary.unknown += derived.unknown + 1;
+          continue;
+        }
+      }
+    }
     summary.reads += 1;
     const customComponentUsage = createElementPropUsage(node, context);
     const kind = classifyBindingUsage(node, context, compatibleComponentProps);
@@ -5854,11 +6369,94 @@ function bindingUsageSummary(valueName, owner, declaration, context, compatibleC
 function hasCandidatePresentationEvidence(summary) {
   return summary.compatible > 0 || summary.visualCustomComponent > 0;
 }
+function isPresentationOnly(summary) {
+  return summary.reads > 0 && summary.compatible === summary.reads;
+}
+function stateBindingForSetter(setterName, context) {
+  const valueName = context.model.stateSetters.get(setterName);
+  if (!valueName)
+    return null;
+  return context.model.stateBindings.find((binding) => binding.setterName === setterName && binding.valueName === valueName) ?? null;
+}
+function effectOnlyDerivesPresentation(valueName, owner, declaration, context, compatibleComponentProps) {
+  if (!owner.body)
+    return false;
+  let foundRelevantEffect = false;
+  for (const call of context.walk(owner.body)) {
+    if (call.type !== "function_call" || context.nearestFunction(call) !== owner)
+      continue;
+    const path7 = context.resolveCallPath(context.getCallPath(call) ?? "");
+    if (path7 !== "React.useEffect" && path7 !== "React.useLayoutEffect")
+      continue;
+    const callbackNode = context.callArguments(call)[0];
+    if (callbackNode?.type !== "function_definition")
+      continue;
+    const callback = context.model.functionByNode.get(callbackNode.id);
+    if (!callback?.body)
+      continue;
+    const usesValue = [...context.walk(callback.body)].some((node) => context.nearestFunction(node) === callback && isReadNode(node, valueName, owner, declaration));
+    if (!usesValue)
+      continue;
+    foundRelevantEffect = true;
+    let presentationSetter = false;
+    for (const nested of context.walk(callback.body)) {
+      if (nested.type !== "function_call" || context.nearestFunction(nested) !== callback)
+        continue;
+      if (isBindingMapSafeCall(nested, context))
+        continue;
+      const nestedPath = context.resolveCallPath(context.getCallPath(nested) ?? "");
+      if (nestedPath === "debug.profilebegin" || nestedPath === "debug.profileend")
+        continue;
+      if (context.model.bindingSetters.has(nestedPath)) {
+        presentationSetter = true;
+        continue;
+      }
+      const target = stateBindingForSetter(nestedPath, context);
+      if (target?.owner && stateReadsAreBindingCompatible(target.valueName, target.owner, target.declaration, context, compatibleComponentProps)) {
+        presentationSetter = true;
+        continue;
+      }
+      return false;
+    }
+    if (!presentationSetter)
+      return false;
+  }
+  return foundRelevantEffect;
+}
+function importedHookRecommendation(summary, call, localName, owner, declaration, context, compatibleComponentProps) {
+  if (!summary.external || callDefinitelyUsesBindingMode(summary, call, context))
+    return null;
+  const usage = bindingUsageSummary(localName, owner, declaration, context, compatibleComponentProps);
+  if (usage.reads === 0)
+    return null;
+  const presentationOnly = isPresentationOnly(usage);
+  const explicitBindingMode = hasExplicitBindingMode(summary);
+  const observedProperty = observedPropertyForCall(summary, call, context);
+  const strongHostFeedback = summary.sourceKind === "instance-property" && isStrongHostFeedbackProperty(observedProperty);
+  const likelyContinuousProperty = summary.sourceKind === "instance-property" && Boolean(observedProperty && LIKELY_CONTINUOUS_PROPERTIES.has(observedProperty));
+  const mirrorsExternalValue = summary.mirrorConfidence !== "none";
+  if (presentationOnly && (summary.highFrequency || likelyContinuousProperty))
+    return "warning";
+  if (presentationOnly && strongHostFeedback && explicitBindingMode)
+    return "warning";
+  if (presentationOnly && (explicitBindingMode || strongHostFeedback || mirrorsExternalValue))
+    return "candidate";
+  if (strongHostFeedback && usage.effect > 0 && effectOnlyDerivesPresentation(localName, owner, declaration, context, compatibleComponentProps)) {
+    return "candidate";
+  }
+  if (!hasCandidatePresentationEvidence(usage))
+    return null;
+  if (summary.highFrequency || likelyContinuousProperty)
+    return "candidate";
+  if (strongHostFeedback && explicitBindingMode && usage.effect === 0)
+    return "candidate";
+  return null;
+}
 var preferBindingOverState = {
   id: "react-luau/prefer-binding-over-state",
   category: "Performance",
   severity: "warning",
-  description: "Prefer React.useBinding when externally updated values do not need React reconciliation on every change.",
+  description: "Prefer React.useBinding when proven external presentation streams do not need React reconciliation.",
   run(context) {
     const diagnostics = [];
     const seen = new Set;
@@ -5875,75 +6473,72 @@ var preferBindingOverState = {
       const owner = context.containingComponent(call) ?? context.nearestFunction(call);
       if (!declaration || !localName || !owner)
         continue;
-      if (!shouldRecommendImportedHook(summary, call, localName, owner, declaration, context, compatibleComponentProps))
+      if (importedHookRecommendation(summary, call, localName, owner, declaration, context, compatibleComponentProps) !== "warning")
         continue;
       const key = `imported:${call.startIndex}:${call.endIndex}:${localName}`;
       if (seen.has(key))
         continue;
       seen.add(key);
-      const hasBindingMode = summary.bindingModeParameterIndex !== undefined && summary.bindingWhenTruthy !== undefined;
-      const message = summary.sourceKind === "measurement" ? hasBindingMode ? `${path7} is using its React state mode for an externally changing GUI measurement, so ${localName} rerenders this consumer when the measurement changes.` : `${path7} returns React state for an externally changing GUI measurement, so ${localName} rerenders this consumer when the measurement changes.` : summary.sourceKind === "derived-external-state" ? `${path7} derives React state from another externally updated reactive value, so ${localName} adds another rerendering state layer.` : `${path7} returns state updated${summary.highFrequency ? " from a high-frequency source" : " from an external callback"}, and ${localName} only flows into bindable host properties.`;
-      const bindingModeInstruction = hasBindingMode ? `Use the hook's Binding-returning mode${summary.bindingModeParameterName ? ` by passing ${summary.bindingWhenTruthy ? "true" : "false"} for ${summary.bindingModeParameterName}` : ""}. ` : "Prefer a Binding-returning measurement hook. ";
-      const help = summary.sourceKind === "measurement" ? `${bindingModeInstruction}Use Binding:map for derived visual values or a binding-aware effect for imperative reactions; keep React state only when the measurement truly needs to rebuild component structure.` : "Prefer a Binding-returning hook API so host properties can update without rerendering the consumer.";
+      const hasBindingMode = hasExplicitBindingMode(summary);
+      const observedProperty = observedPropertyForCall(summary, call, context);
+      const hostFeedback = summary.sourceKind === "instance-property" && isStrongHostFeedbackProperty(observedProperty);
+      const likelyContinuousProperty = summary.sourceKind === "instance-property" && Boolean(observedProperty && LIKELY_CONTINUOUS_PROPERTIES.has(observedProperty));
+      const message = hostFeedback ? `${path7} mirrors ${observedProperty} through React state even though every analyzed use is presentation-only, so the measurement rerenders this consumer without needing reconciliation.` : likelyContinuousProperty ? `${path7} mirrors continuously mutable ${observedProperty} through React state, and ${localName} only feeds presentation updates that do not need reconciliation.` : `${path7} returns state updated from a high-frequency source, and ${localName} only feeds presentation updates that do not need React reconciliation.`;
+      const help = hasBindingMode ? `Use the hook's Binding-returning mode${summary.bindingModeParameterName ? ` by passing ${summary.bindingWhenTruthy ? "true" : "false"} for ${summary.bindingModeParameterName}` : ""}. Binding:map can keep pure visual derivations outside the render cycle.` : "Prefer a Binding-returning hook API so continuous presentation updates can reach host properties without rerendering the consumer.";
       diagnostics.push({
         node: callNameNode(call),
         message,
         help,
-        fixPreview: hasBindingMode ? bindingModeFixPreview(summary, call, context) : undefined
-      });
-    }
-    for (const call of context.findCalls()) {
-      const path7 = context.getCallPath(call) ?? "";
-      const member = path7.split(/[.:]/).at(-1) ?? path7;
-      const bindingAlternative = context.project.bindingApiAlternatives.get(member);
-      if (!bindingAlternative)
-        continue;
-      const declaration = declarationForCall2(call);
-      const localName = declaration ? declarationNames2(declaration)[0] ?? null : null;
-      const owner = context.containingComponent(call) ?? context.nearestFunction(call);
-      if (!declaration || !localName || !owner || !hasAnyRead(localName, owner, declaration, context))
-        continue;
-      if (!stateReadsAreBindingCompatible(localName, owner, declaration, context, compatibleComponentProps))
-        continue;
-      const field = selectorFieldName(call, context);
-      const key = `state-api:${call.startIndex}:${call.endIndex}:${localName}`;
-      if (seen.has(key))
-        continue;
-      seen.add(key);
-      diagnostics.push({
-        node: callNameNode(call),
-        message: `${path7} subscribes ${localName} through React state${field ? ` for ${field}` : ""}, but ${bindingAlternative} is available and every use of the value only updates bindable host properties.`,
-        help: `Use ${bindingAlternative} so the host property can update without rerendering the component.`,
-        fixPreview: callMemberFixPreview(call, bindingAlternative)
+        fixPreview: hasBindingMode && allReadsDirectlyBindingSubstitutable(localName, owner, declaration, context, compatibleComponentProps) ? bindingModeFixPreview(summary, call, context) : undefined
       });
     }
     for (const binding of context.model.stateBindings) {
       const owner = binding.owner;
       if (!owner || !owner.isComponent && !owner.isHook)
         continue;
-      const updateKind = bindingHasExternalOrHighFrequencyUpdates(binding, importedCallbacks, context);
-      if (!updateKind)
+      const update = bindingUpdateEvidence(binding, importedCallbacks, context);
+      if (!update)
         continue;
       const localCompatible = stateReadsAreBindingCompatible(binding.valueName, owner, binding.declaration, context, compatibleComponentProps);
       const hookCompatible = owner.isHook ? hookCallSitesAreBindingCompatible(binding, context, compatibleComponentProps) : false;
-      if (owner.isHook ? !hookCompatible : !localCompatible)
+      const strongHostFeedback = hasStrongHostFeedbackEvidence(update);
+      const likelyContinuousProperty = hasLikelyContinuousPropertyEvidence(update);
+      const shouldWarn = owner.isHook ? hookCompatible && (update.highFrequency || likelyContinuousProperty) : localCompatible && (update.highFrequency || strongHostFeedback || likelyContinuousProperty);
+      if (!shouldWarn)
         continue;
       const key = `${binding.call.startIndex}:${binding.call.endIndex}:${binding.valueName}`;
       if (seen.has(key))
         continue;
       seen.add(key);
       if (owner.isHook && hookCompatible) {
+        const properties = likelyContinuousProperty ? [...update.hostFeedbackProperties].sort().join(", ") : "";
+        diagnostics.push({
+          node: callNameNode(binding.call),
+          message: likelyContinuousProperty && !update.highFrequency ? `Hook state ${binding.valueName} mirrors continuously mutable ${properties} and is only consumed by presentation properties at analyzed call sites.` : `Hook state ${binding.valueName} is updated from a high-frequency source and is only consumed by presentation properties at analyzed call sites.`,
+          help: "Consider returning a Binding, or adding a Binding-returning variant of this hook, so continuous presentation updates do not rerender every consumer."
+        });
+      } else if (strongHostFeedback && !update.highFrequency) {
+        const properties = [...update.hostFeedbackProperties].sort().join(", ");
         diagnostics.push({
           node: callNameNode(binding.call),
-          message: `Hook state ${binding.valueName} is updated${updateKind.highFrequency ? " from a high-frequency source" : " from an external callback"} and is only consumed by host properties at analyzed call sites.`,
-          help: "Consider returning a Binding, or adding a Binding-returning variant of this hook, so consumers can update host properties without rerendering."
+          message: `State ${binding.valueName} mirrors ${properties} and only feeds presentation updates, so React reconciliation is acting as an unnecessary host-property feedback step.`,
+          help: "Prefer React.useBinding for this host feedback path. Use Binding:map for pure visual derivations and keep React state only when a change needs to affect component structure or React effects.",
+          fixPreview: allReadsDirectlyBindingSubstitutable(binding.valueName, owner, binding.declaration, context, compatibleComponentProps) ? useBindingFixPreview(binding.call) : undefined
+        });
+      } else if (likelyContinuousProperty && !update.highFrequency) {
+        const properties = [...update.hostFeedbackProperties].sort().join(", ");
+        diagnostics.push({
+          node: callNameNode(binding.call),
+          message: `State ${binding.valueName} mirrors continuously mutable ${properties} and only feeds presentation updates that do not need React reconciliation.`,
+          help: "Prefer React.useBinding so external visual property changes can reach presentation without routing every update through component state.",
+          fixPreview: allReadsDirectlyBindingSubstitutable(binding.valueName, owner, binding.declaration, context, compatibleComponentProps) ? useBindingFixPreview(binding.call) : undefined
         });
       } else {
         diagnostics.push({
           node: callNameNode(binding.call),
-          message: `State ${binding.valueName} is updated${updateKind.highFrequency ? " from a high-frequency callback" : " from an external callback"} and is read by the component render path.`,
-          help: "Prefer React.useBinding when the update is visual and does not need React to rebuild component structure.",
-          fixPreview: useBindingFixPreview(binding.call)
+          message: `State ${binding.valueName} is updated from a high-frequency callback and only feeds presentation updates that do not need React reconciliation.`,
+          help: "Prefer React.useBinding so continuous visual updates can reach host properties without rerendering the component.",
+          fixPreview: allReadsDirectlyBindingSubstitutable(binding.valueName, owner, binding.declaration, context, compatibleComponentProps) ? useBindingFixPreview(binding.call) : undefined
         });
       }
     }
@@ -5964,27 +6559,49 @@ var preferBindingOverStateCandidate = {
     for (const call of context.findCalls()) {
       const path7 = context.getCallPath(call) ?? "";
       const summary = importedHooks.get(path7);
-      if (!summary || !summary.external || callDefinitelyUsesBindingMode(summary, call, context))
+      if (!summary)
         continue;
       const declaration = declarationForCall2(call);
       const localName = declaration ? declarationNames2(declaration)[0] ?? null : null;
       const owner = context.containingComponent(call) ?? context.nearestFunction(call);
-      if (!declaration || !localName || !owner || !hasAnyRead(localName, owner, declaration, context))
+      if (!declaration || !localName || !owner)
         continue;
-      if (shouldRecommendImportedHook(summary, call, localName, owner, declaration, context, compatibleComponentProps))
+      if (importedHookRecommendation(summary, call, localName, owner, declaration, context, compatibleComponentProps) !== "candidate")
         continue;
       const usage = bindingUsageSummary(localName, owner, declaration, context, compatibleComponentProps);
-      const hasPresentationEvidence = hasCandidatePresentationEvidence(usage) || summary.sourceKind === "derived-external-state" && usage.effect > 0;
-      if (!summary.highFrequency && !hasPresentationEvidence)
-        continue;
+      const presentationOnly = isPresentationOnly(usage);
+      const observedProperty = observedPropertyForCall(summary, call, context);
+      const strongHostFeedback = summary.sourceKind === "instance-property" && isStrongHostFeedbackProperty(observedProperty);
+      const hasBindingMode = hasExplicitBindingMode(summary);
+      const mirrorsExternalValue = summary.mirrorConfidence !== "none";
+      const visualEffectBridge = strongHostFeedback && usage.effect > 0 && effectOnlyDerivesPresentation(localName, owner, declaration, context, compatibleComponentProps);
       const key = `imported:${call.startIndex}:${call.endIndex}:${localName}`;
       if (seen.has(key))
         continue;
       seen.add(key);
+      let message;
+      let help;
+      if (presentationOnly && hasBindingMode) {
+        message = `${path7} has a Binding-returning mode and ${localName} is only used for presentation, but Doctor cannot prove the updates are frequent enough to make the Binding version clearly preferable.`;
+        help = "Consider the Binding mode when this value changes often enough that avoiding reconciliation matters; ordinary React state may be clearer for infrequent semantic updates.";
+      } else if (presentationOnly && strongHostFeedback) {
+        message = `${path7} mirrors ${observedProperty} through React state only for presentation, but the hook does not expose a proven low-friction Binding mode.`;
+        help = "Consider a Binding-returning variant if this host feedback path is performance-sensitive. Keep state when the simpler API is more valuable than avoiding occasional rerenders.";
+      } else if (presentationOnly && mirrorsExternalValue) {
+        message = `${path7} mirrors an external reactive value through React state, and ${localName} is only used for presentation.`;
+        help = "Consider a Binding-returning hook API if this source changes often enough that rerendering is unnecessary. Doctor cannot prove the source's update pressure, so ordinary state may still be the clearer choice.";
+      } else if (visualEffectBridge) {
+        message = `${path7} mirrors ${observedProperty} through React state, and the dependent React effect only derives presentation state or Bindings from ${localName}.`;
+        help = hasBindingMode ? "Consider the hook's Binding mode and move the visual derivation into Binding:map/joinBindings so the measurement does not need an intermediate React rerender." : "Consider a Binding-returning hook variant if this visual feedback path is performance-sensitive; the current effect appears to use React state only as an intermediate presentation step.";
+      } else {
+        message = `${path7} updates ${localName} through React state and some consumers are presentation-only, but other consumers may still require React reconciliation.`;
+        help = "Inspect whether the presentation branch can move to a Binding while structural or effect-driven consumers keep React state. Avoid replacing the value wholesale when React still needs to react to it.";
+      }
       diagnostics.push({
         node: callNameNode(call),
-        message: `${path7} updates ${localName} through React state when outside data changes. Some uses of ${localName} may need a rerender, so switching it entirely to a Binding could change behavior.`,
-        help: "Inspect whether the value can become a Binding, use Binding:map for visual derivation, or split visual updates from the smaller part of the value that truly needs React state."
+        message,
+        help,
+        fixPreview: presentationOnly && hasBindingMode && allReadsDirectlyBindingSubstitutable(localName, owner, declaration, context, compatibleComponentProps) ? bindingModeFixPreview(summary, call, context) : undefined
       });
     }
     for (const call of context.findCalls()) {
@@ -5998,39 +6615,80 @@ var preferBindingOverStateCandidate = {
       const owner = context.containingComponent(call) ?? context.nearestFunction(call);
       if (!declaration || !localName || !owner || !hasAnyRead(localName, owner, declaration, context))
         continue;
-      if (stateReadsAreBindingCompatible(localName, owner, declaration, context, compatibleComponentProps))
+      const usage = bindingUsageSummary(localName, owner, declaration, context, compatibleComponentProps);
+      const presentationOnly = isPresentationOnly(usage);
+      if (!presentationOnly)
         continue;
+      const field = selectorFieldName(call, context);
       const key = `state-api:${call.startIndex}:${call.endIndex}:${localName}`;
       if (seen.has(key))
         continue;
       seen.add(key);
       diagnostics.push({
         node: callNameNode(call),
-        message: `${path7} uses React state even though ${bindingAlternative} is available. Some uses of ${localName} may need a rerender, so replacing it entirely with the Binding API could change behavior.`,
-        help: `Inspect whether ${bindingAlternative}, Binding:map, or splitting visual and structural consumers would avoid unnecessary rerenders.`,
-        fixPreview: callMemberFixPreview(call, bindingAlternative)
+        message: `${path7} subscribes ${localName} through React state${field ? ` for ${field}` : ""}, while ${bindingAlternative} is also available and every analyzed consumer is presentation-only.`,
+        help: `Consider ${bindingAlternative} when this value updates frequently enough that avoiding reconciliation matters; state remains reasonable for ordinary semantic store updates.`,
+        fixPreview: allReadsDirectlyBindingSubstitutable(localName, owner, declaration, context, compatibleComponentProps) ? callMemberFixPreview(call, bindingAlternative) : undefined
       });
     }
     for (const binding of context.model.stateBindings) {
       const owner = binding.owner;
-      if (!owner || !owner.isComponent || !owner.body)
+      if (!owner || !owner.isComponent && !owner.isHook || !owner.body)
         continue;
-      const updateKind = bindingHasExternalOrHighFrequencyUpdates(binding, importedCallbacks, context);
-      if (!updateKind)
+      const update = bindingUpdateEvidence(binding, importedCallbacks, context);
+      if (!update)
         continue;
-      if (stateReadsAreBindingCompatible(binding.valueName, owner, binding.declaration, context, compatibleComponentProps))
+      const localCompatible = stateReadsAreBindingCompatible(binding.valueName, owner, binding.declaration, context, compatibleComponentProps);
+      const hookCompatible = owner.isHook ? hookCallSitesAreBindingCompatible(binding, context, compatibleComponentProps) : false;
+      const strongHostFeedback = hasStrongHostFeedbackEvidence(update);
+      const likelyContinuousProperty = hasLikelyContinuousPropertyEvidence(update);
+      const mirrorsExternalValue = update.mirrorConfidence !== "none";
+      if (owner.isHook) {
+        if (hookCompatible && (update.highFrequency || likelyContinuousProperty))
+          continue;
+        if (!(hookCompatible && (strongHostFeedback || mirrorsExternalValue)))
+          continue;
+        const key2 = `hook-state:${binding.call.startIndex}:${binding.call.endIndex}:${binding.valueName}`;
+        if (seen.has(key2))
+          continue;
+        seen.add(key2);
+        const measurement = strongHostFeedback ? "a presentation measurement" : "an external reactive value";
+        diagnostics.push({
+          node: callNameNode(binding.call),
+          message: `Hook state ${binding.valueName} mirrors ${measurement} and is only consumed by presentation properties at analyzed call sites, but converting it requires changing the hook API.`,
+          help: "Consider adding a Binding-returning variant when this reactive path updates often enough that avoiding reconciliation matters; keeping the state API is reasonable when ordinary React state is simpler."
+        });
         continue;
+      }
       const usage = bindingUsageSummary(binding.valueName, owner, binding.declaration, context, compatibleComponentProps);
       if (!hasCandidatePresentationEvidence(usage))
         continue;
+      if (localCompatible && (update.highFrequency || strongHostFeedback || likelyContinuousProperty))
+        continue;
+      if (localCompatible && mirrorsExternalValue) {
+        const key2 = `state:${binding.call.startIndex}:${binding.call.endIndex}:${binding.valueName}`;
+        if (seen.has(key2))
+          continue;
+        seen.add(key2);
+        diagnostics.push({
+          node: callNameNode(binding.call),
+          message: `State ${binding.valueName} mirrors an external reactive value and only feeds presentation updates, but Doctor cannot prove the source changes frequently enough for Binding to be clearly preferable.`,
+          help: "Consider React.useBinding when this source is a stream of presentation values rather than semantic React state. Keep useState when the external event represents an infrequent UI state transition."
+        });
+        continue;
+      }
+      const mixedHighFrequency = update.highFrequency || likelyContinuousProperty;
+      const mixedHostFeedback = strongHostFeedback && usage.structural > 0 && usage.effect === 0;
+      if (!mixedHighFrequency && !mixedHostFeedback)
+        continue;
       const key = `state:${binding.call.startIndex}:${binding.call.endIndex}:${binding.valueName}`;
       if (seen.has(key))
         continue;
       seen.add(key);
       diagnostics.push({
         node: callNameNode(binding.call),
-        message: `State ${binding.valueName} is updated${updateKind.highFrequency ? " from a high-frequency source" : " from an external callback"} and appears at least partly presentation-oriented, but some consumers may still require React state.`,
-        help: "Inspect whether visual consumers can move to React.useBinding while structural consumers keep a smaller state value. Splitting the responsibilities can remove rerenders without changing component behavior."
+        message: `State ${binding.valueName} has presentation-oriented consumers, but other uses still appear to need React reconciliation.`,
+        help: "Inspect whether the presentation branch can move to React.useBinding while structural consumers keep a smaller semantic state value. Splitting the responsibilities can remove hot-path rerenders without forcing Binding semantics onto the whole value."
       });
     }
     return diagnostics;
@@ -7389,6 +8047,16 @@ function nodeLocation(node) {
     endColumn: node.endPosition.column + 1
   };
 }
+function sameLocation(left, right) {
+  return left.line === right.line && left.column === right.column && left.endLine === right.endLine && left.endColumn === right.endColumn;
+}
+function removeSupersededDiagnostics(diagnostics) {
+  return diagnostics.filter((diagnostic) => {
+    if (diagnostic.rule !== "react-luau/rerender-high-frequency-state")
+      return true;
+    return !diagnostics.some((candidate) => candidate.rule === "react-luau/prefer-binding-over-state" && sameLocation(candidate.location, diagnostic.location) && SEVERITY_RANK[candidate.severity] >= SEVERITY_RANK[diagnostic.severity]);
+  });
+}
 function toDiagnostic(file, ruleId, category, severity, input) {
   const node = input.node;
   const highlights = input.highlights?.map(nodeLocation);
@@ -7446,11 +8114,12 @@ async function analyzeReactFile(input, tree) {
     if (rule.id === "react-luau/parse-error" && findings.length > 0)
       break;
   }
+  const filteredDiagnostics = removeSupersededDiagnostics(diagnostics);
   return {
     relativePath: input.relativePath,
     isReactFile: model.isReactFile,
     scanned: true,
-    diagnostics
+    diagnostics: filteredDiagnostics
   };
 }
 
@@ -7609,7 +8278,34 @@ class AnalysisWorkerPool {
 // src/project-model.ts
 import fs6 from "fs";
 import path7 from "path";
-var EXTERNAL_UPDATE_SOURCE = /(?::|\.)(?:Connect|Once|Subscribe|Observe|Listen|Watch)\s*\(|\b(?:subscribe|observe|listen|watch)[A-Za-z0-9_]*\s*\(|GetPropertyChangedSignal\s*\(|\.Changed\b/i;
+var EXTERNAL_UPDATE_SOURCE = /(?::|\.)(?:Connect|Once|Subscribe|Observe|Listen|Watch|onStep|onUpdate|onChange|onChanged)\s*\(|\b(?:subscribe|observe|listen|watch|onStep|onUpdate|onChange|onChanged)[A-Za-z0-9_]*\s*\(|GetPropertyChangedSignal\s*\(|GetAttributeChangedSignal\s*\(|\.Changed\b/i;
+var SEMANTIC_SNAPSHOT_EXPRESSION2 = /\b(?:getState|getSnapshot|snapshot|selector|select|table\s*\.\s*(?:clone|freeze|move))\b|(?:\.|\[\s*["'])State(?:\b|["']\s*\])/i;
+var PURE_MIRROR_EXPRESSION_ROOTS = new Set([
+  "math",
+  "string",
+  "utf8",
+  "bit32",
+  "UDim",
+  "UDim2",
+  "Vector2",
+  "Vector3",
+  "Color3",
+  "CFrame",
+  "Rect",
+  "NumberRange",
+  "NumberSequence",
+  "ColorSequence",
+  "BrickColor",
+  "Font",
+  "Enum",
+  "tostring",
+  "tonumber",
+  "type",
+  "typeof",
+  "true",
+  "false",
+  "nil"
+]);
 var CALLBACK_PARAMETER_NAME = /^(?:callback|handler|listener|subscriber|observer|effect|fn)$/i;
 function exportedFunctionName(source) {
   return source.match(/\breturn\s+([A-Za-z_][A-Za-z0-9_]*)\s*$/)?.[1] ?? null;
@@ -7945,9 +8641,62 @@ function findExternalCallbackFunction(source) {
   return {
     name,
     callbackParameterIndexes,
-    highFrequency: sourceHasHighFrequencyRunService(source)
+    highFrequency: sourceHasHighFrequencyRobloxEvent(source) || sourceHasLikelyContinuousSubscription(source)
   };
 }
+function sourceHasLikelyContinuousSubscription(source) {
+  return /(?::|\.)onStep\s*\(/i.test(source);
+}
+function expressionReferencesName(expression, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`\\b${escaped}\\b`).test(expression);
+}
+function isLiteralStateTransitionExpression(expression) {
+  const text = expression.trim();
+  return /^(?:true|false|nil|[-+]?\d+(?:\.\d+)?|["'][^"']*["'])$/.test(text);
+}
+function expressionHasLikelyExternalInput(expression) {
+  const withoutMembers = expression.replace(/\.\s*[A-Za-z_][A-Za-z0-9_]*/g, "");
+  for (const match of withoutMembers.matchAll(/\b[A-Za-z_][A-Za-z0-9_]*\b/g)) {
+    if (!PURE_MIRROR_EXPRESSION_ROOTS.has(match[0]))
+      return true;
+  }
+  return false;
+}
+function subscriptionMirrorConfidence(source, setterName) {
+  const escapedSetter = setterName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const directSetter = new RegExp(`(?::|\\.)(Connect|Subscribe|Observe|Listen|Watch|onStep|onUpdate|onChange|onChanged)\\s*\\(\\s*${escapedSetter}\\b`, "i");
+  if (directSetter.test(source))
+    return "strong";
+  const callbackPattern = new RegExp(`(?::|\\.)(Connect|Subscribe|Observe|Listen|Watch|onStep|onUpdate|onChange|onChanged)\\s*\\(\\s*function\\s*\\(([^)]*)\\)[\\s\\S]{0,2400}?\\b${escapedSetter}\\s*\\(`, "gi");
+  let possible = false;
+  for (const match of source.matchAll(callbackPattern)) {
+    if (match.index === undefined)
+      continue;
+    const callbackParameters = splitTopLevelParameters(match[2] ?? "").map(parameterName).filter((name) => Boolean(name));
+    const setterOffset = match[0].lastIndexOf(setterName);
+    if (setterOffset < 0)
+      continue;
+    const setterStart = match.index + setterOffset;
+    const open = source.indexOf("(", setterStart + setterName.length);
+    const argumentsText = extractCallArguments(source, open);
+    if (argumentsText === null)
+      continue;
+    const setterArgs = splitTopLevelParameters(argumentsText);
+    const expression = setterArgs[0]?.trim() ?? "";
+    if (!expression || /^function\b/.test(expression) || isLiteralStateTransitionExpression(expression))
+      continue;
+    if (SEMANTIC_SNAPSHOT_EXPRESSION2.test(expression))
+      continue;
+    if (callbackParameters.some((name) => expressionReferencesName(expression, name))) {
+      return "strong";
+    }
+    if (!expressionHasLikelyExternalInput(expression))
+      continue;
+    possible = true;
+  }
+  return possible ? "possible" : "none";
+}
 function findBindingCandidateHook(source) {
   const exported = source.match(/\breturn\s+(use[A-Z0-9_][A-Za-z0-9_]*)\s*$/)?.[1];
   if (!exported)
@@ -7969,18 +8718,35 @@ function findBindingCandidateHook(source) {
   const setterPassedToSubscription = new RegExp(`(?::|\\.)(?:Connect|Once|Subscribe|Observe|Listen|Watch)\\s*\\(\\s*${escapedSetter}\\b`, "i").test(source);
   if (!setterCalled && !setterPassedToSubscription)
     return null;
-  const highFrequency = sourceHasHighFrequencyRunService(source);
+  const highFrequency = sourceHasHighFrequencyRobloxEvent(source) || sourceHasLikelyContinuousSubscription(source);
   const external = highFrequency || EXTERNAL_UPDATE_SOURCE.test(source);
   if (!external)
     return null;
-  const propertySignal = source.match(/GetPropertyChangedSignal\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/);
-  const observedPropertyName = propertySignal?.[1] ?? null;
-  const measurement = Boolean(observedPropertyName && new RegExp(`\\[\\s*${observedPropertyName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\]`).test(source));
+  const literalPropertySignal = source.match(/GetPropertyChangedSignal\s*\(\s*["']([^"']+)["']\s*\)/);
+  const dynamicPropertySignal = literalPropertySignal ? null : source.match(/GetPropertyChangedSignal\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/);
+  const literalPropertyName = literalPropertySignal?.[1] ?? null;
+  const dynamicPropertyName = dynamicPropertySignal?.[1] ?? null;
+  const readsObservedProperty = literalPropertyName ? new RegExp(`(?:\\.\\s*${literalPropertyName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b|\\[\\s*["']${literalPropertyName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']\\s*\\])`).test(source) : Boolean(dynamicPropertyName && new RegExp(`\\[\\s*${dynamicPropertyName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\]`).test(source));
+  const instanceProperty = Boolean((literalPropertyName || dynamicPropertyName) && readsObservedProperty);
+  const mirrorConfidence = instanceProperty ? "strong" : subscriptionMirrorConfidence(source, setterName);
+  let observedPropertyParameterIndex;
+  if (instanceProperty && dynamicPropertyName) {
+    const parameters = findFunctionParameters(source, exported);
+    if (parameters !== null) {
+      const parameterNames3 = splitTopLevelParameters(parameters).map((parameter) => parameter.match(/^([A-Za-z_][A-Za-z0-9_]*)/)?.[1] ?? "");
+      const index = parameterNames3.indexOf(dynamicPropertyName);
+      if (index >= 0)
+        observedPropertyParameterIndex = index;
+    }
+  }
   return {
     name: exported,
     highFrequency,
     external,
-    sourceKind: measurement ? "measurement" : "external-state",
+    sourceKind: instanceProperty ? "instance-property" : "external-state",
+    mirrorConfidence,
+    ...instanceProperty && literalPropertyName ? { observedPropertyName: literalPropertyName } : {},
+    ...observedPropertyParameterIndex !== undefined ? { observedPropertyParameterIndex } : {},
     ...dualMode ? {
       bindingModeParameterIndex: dualMode.bindingModeParameterIndex,
       bindingModeParameterName: dualMode.bindingModeParameterName,
@@ -8018,7 +8784,8 @@ function findDerivedBindingCandidateHook(source, bindingCandidateHooks) {
       name: exported,
       highFrequency: summary.highFrequency,
       external: true,
-      sourceKind: "derived-external-state"
+      sourceKind: "derived-external-state",
+      mirrorConfidence: summary.mirrorConfidence
     };
   }
   return null;
@@ -8382,7 +9149,11 @@ function findBindingCompatibleComponentProps(source) {
   }
   const compatible = new Set;
   for (const [property, offsets] of reads) {
-    if (offsets.length > 0 && offsets.every((offset) => ranges.some((range) => offset >= range.start && offset < range.end))) {
+    if (offsets.length > 0 && offsets.every((offset) => ranges.some((range) => {
+      if (offset < range.start || offset >= range.end)
+        return false;
+      return !/\bfunction\b/.test(source.slice(range.start, offset));
+    }))) {
       compatible.add(property);
     }
   }
@@ -10705,6 +11476,7 @@ import path12 from "path";
 var UPDATE_CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000;
 var UPDATE_REQUEST_TIMEOUT_MS = 5000;
 var UPDATE_CACHE_FILENAME = "update-check.json";
+var CHANGELOG_URL = "https://raw.githubusercontent.com/ColRealPro/react-luau-doctor/refs/heads/main/CHANGELOG.md";
 function updateCacheFilename() {
   return path12.join(cacheBaseDirectory(), UPDATE_CACHE_FILENAME);
 }
@@ -10786,6 +11558,9 @@ function updateRegistryUrl() {
   const base = registry.endsWith("/") ? registry : `${registry}/`;
   return new URL(`${encodeURIComponent(package_default.name)}/latest`, base).toString();
 }
+function changelogUrl() {
+  return process.env.REACT_LUAU_DOCTOR_CHANGELOG_URL ?? CHANGELOG_URL;
+}
 async function fetchLatestVersion() {
   const controller = new AbortController;
   const timer = setTimeout(() => controller.abort(), UPDATE_REQUEST_TIMEOUT_MS);
@@ -10806,6 +11581,50 @@ async function fetchLatestVersion() {
     clearTimeout(timer);
   }
 }
+function changelogReleasesBetween(markdown, currentVersion, latestVersion) {
+  const releases = [];
+  let active = null;
+  const flush = () => {
+    if (!active)
+      return;
+    const afterCurrent = compareVersions(active.version, currentVersion);
+    const atOrBeforeLatest = compareVersions(active.version, latestVersion);
+    if (afterCurrent !== null && atOrBeforeLatest !== null && afterCurrent > 0 && atOrBeforeLatest <= 0) {
+      releases.push({ version: active.version, notes: active.lines.join(`
+`).trim() });
+    }
+    active = null;
+  };
+  for (const line of markdown.split(/\r?\n/)) {
+    if (/^##\s+/.test(line.trim())) {
+      flush();
+      const match = /^##\s+\[?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\]?(?:\s+-.*)?\s*$/.exec(line.trim());
+      if (match)
+        active = { version: match[1], lines: [] };
+      continue;
+    }
+    active?.lines.push(line);
+  }
+  flush();
+  releases.sort((left, right) => compareVersions(right.version, left.version) ?? 0);
+  return releases;
+}
+async function fetchChangelogReleases(currentVersion, latestVersion) {
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), UPDATE_REQUEST_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    const response = await fetch(changelogUrl(), {
+      headers: { accept: "text/markdown, text/plain;q=0.9, */*;q=0.1" },
+      signal: controller.signal
+    });
+    if (!response.ok)
+      throw new Error(`changelog returned HTTP ${response.status}`);
+    return changelogReleasesBetween(await response.text(), currentVersion, latestVersion);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function updateCacheIsStale(now = Date.now()) {
   const cache = readUpdateCache();
   return !cache || now - cache.checkedAt >= UPDATE_CHECK_INTERVAL_MS;
@@ -10861,7 +11680,7 @@ async function checkForUpdatesNow(currentVersion) {
 
 // src/update-install.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 function normalizedPath(filename) {
   return filename.replaceAll("\\", "/");
 }
@@ -10889,7 +11708,7 @@ function updateInstallCommandForPath(filename) {
   return null;
 }
 function currentUpdateInstallCommand() {
-  return updateInstallCommandForPath(fileURLToPath(import.meta.url));
+  return updateInstallCommandForPath(fileURLToPath2(import.meta.url));
 }
 function installLatestVersion(command) {
   const result = spawnSync3(command.command, command.args, {
@@ -10997,10 +11816,12 @@ end, {})`,
   },
   "react-luau/prefer-binding-over-state-candidate": {
     before: `local value, setValue = React.useState(0)
--- value drives both visual and structural work`,
-    after: `local visualValue, setVisualValue = React.useBinding(0)
-local structuralValue, setStructuralValue = React.useState(0)`,
-    note: "A common fix is to split high-frequency visual updates from the smaller value that truly needs reconciliation."
+signal:Connect(setValue)
+-- value is used for presentation`,
+    after: `local value, setValue = React.useBinding(0)
+signal:Connect(setValue)
+-- keep separate React state too if structure depends on it`,
+    note: "Use a Binding when this is really an external presentation stream. Keep or split React state when the event represents semantic UI state or needs reconciliation."
   },
   "react-luau/rerender-unstable-memo-props": {
     before: `return React.createElement(MemoizedButton, {
@@ -11432,7 +12253,7 @@ CI commands:
 
 Update commands:
   update                                 Update the global installation to the latest release
-  update --check                         Check npm for a newer release without updating
+  update --check                         Check npm and show release notes without updating
 
 Rules commands:
   rules list [--category <name>] [--configured] [--json]
@@ -11449,12 +12270,67 @@ Config:
 function automaticUpdateNoticeEnabled(options, machineReadable) {
   return !options.noUpdateCheck && !machineReadable && Boolean(process.stdout.isTTY) && !process.env.CI && process.env.NO_UPDATE_NOTIFIER === undefined && process.env.REACT_LUAU_DOCTOR_NO_UPDATE_CHECK === undefined;
 }
-function renderUpdateNotice(current, latest, colorized) {
+function renderUpdateHeader(current, latest, colorized) {
   const label = whyPaint(colorized, "Update available:", WHY_ANSI.bold, WHY_ANSI.yellow);
   const oldVersion = whyPaint(colorized, `v${current}`, WHY_ANSI.dim);
   const newVersion = whyPaint(colorized, `v${latest}`, WHY_ANSI.bold);
-  return `${label} ${oldVersion} \u2192 ${newVersion}
-Run \`react-luau-doctor update\` to update.`;
+  return `${label} ${oldVersion} \u2192 ${newVersion}`;
+}
+function renderUpdateNotice(current, latest, colorized) {
+  return `${renderUpdateHeader(current, latest, colorized)}
+Run \`react-luau-doctor update --check\` to see what's new.`;
+}
+function renderChangelogInline(value, colorized, ...baseCodes) {
+  if (!colorized)
+    return value;
+  const parts = [];
+  let offset = 0;
+  for (const match of value.matchAll(/`([^`\n]+)`/g)) {
+    const index = match.index ?? 0;
+    if (index > offset)
+      parts.push(whyPaint(true, value.slice(offset, index), ...baseCodes));
+    parts.push(whyPaint(true, match[1], WHY_THEME.variable));
+    offset = index + match[0].length;
+  }
+  if (parts.length === 0)
+    return whyPaint(true, value, ...baseCodes);
+  if (offset < value.length)
+    parts.push(whyPaint(true, value.slice(offset), ...baseCodes));
+  return parts.join("");
+}
+function renderChangelogNotes(notes, colorized) {
+  return notes.split(/\r?\n/).map((line) => {
+    const heading = /^#{3,6}\s+(.+)$/.exec(line.trim());
+    if (heading)
+      return renderChangelogInline(heading[1], colorized, WHY_ANSI.bold);
+    const bullet = /^(\s*)[-*]\s+(.+)$/.exec(line);
+    if (bullet)
+      return `${bullet[1] || "  "}\u2022 ${renderChangelogInline(bullet[2], colorized)}`;
+    return renderChangelogInline(line, colorized);
+  }).join(`
+`).trim();
+}
+function renderUpdateCheck(current, latest, releases, releaseNotesUnavailable, colorized) {
+  const lines2 = [
+    renderUpdateHeader(current, latest, colorized),
+    "",
+    whyPaint(colorized, "What's new", WHY_ANSI.bold)
+  ];
+  if (releaseNotesUnavailable) {
+    lines2.push("  Release notes could not be loaded from GitHub.");
+  } else if (releases.length === 0) {
+    lines2.push("  No changelog entries were found between these versions.");
+  } else {
+    for (const release of releases) {
+      lines2.push("", whyPaint(colorized, `v${release.version}`, WHY_ANSI.bold));
+      const notes = renderChangelogNotes(release.notes, colorized);
+      if (notes)
+        lines2.push(notes);
+    }
+  }
+  lines2.push("", "Run `react-luau-doctor update` to update.");
+  return lines2.join(`
+`);
 }
 async function runUpdateCommand(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -11473,7 +12349,14 @@ async function runUpdateCommand(argv) {
   }
   const colorized = shouldUseColor(false, false);
   if (argv[0] === "--check") {
-    process.stdout.write(`${renderUpdateNotice(VERSION2, result.latest, colorized)}
+    let releases = [];
+    let releaseNotesUnavailable = false;
+    try {
+      releases = await fetchChangelogReleases(VERSION2, result.latest);
+    } catch {
+      releaseNotesUnavailable = true;
+    }
+    process.stdout.write(`${renderUpdateCheck(VERSION2, result.latest, releases, releaseNotesUnavailable, colorized)}
 `);
     return;
   }
@@ -12410,14 +13293,14 @@ function renderWhyCodeFrame(filename, diagnostic, colorized) {
 }
 function whySeverityMeaning(severity) {
   if (severity === "error")
-    return "This can violate React or Luau correctness rules and should normally be fixed.";
+    return "This can cause incorrect behavior or violate React's rules and should normally be fixed.";
   if (severity === "warning")
     return "This pattern is very likely to be a real issue in the code shown and is normally worth fixing.";
   return "This may be intentional. Doctor found a plausible improvement, but the right choice depends on how this value or pattern is meant to affect rendering.";
 }
 function whyRuleSpecificContext(diagnostic) {
   if (diagnostic.rule === "react-luau/prefer-binding-over-state-candidate") {
-    return "A Binding can update visual values without rerendering the component. Here, at least one use may be structural or otherwise depend on a rerender, so replacing all of the state with a Binding is not automatically safe.";
+    return "A Binding can update visual values without rerendering the component. Doctor found an external reactive mirror or presentation branch, but it cannot fully prove the source's update pressure, conversion safety, or that every consumer can leave React state.";
   }
   if (diagnostic.rule === "react-luau/prefer-binding-over-state") {
     return "A Binding can update these values without rerendering the component, and every use of the value only needs that kind of update. React state is therefore doing extra reconciliation work here.";
@@ -12432,7 +13315,7 @@ function whyRuleSpecificContext(diagnostic) {
 }
 function whyRuleCaveat(diagnostic) {
   if (diagnostic.rule === "react-luau/prefer-binding-over-state-candidate") {
-    return "Keep React state when the value genuinely changes component structure, conditional children, hook inputs, or other behavior that must go through React reconciliation. Mixed cases often benefit from splitting visual Binding updates from a smaller structural state value.";
+    return "Keep React state when the external event represents semantic UI state, changes component structure, drives hook/effect behavior, or is infrequent enough that a Binding would only make the code harder to follow. Mixed cases can split visual Binding updates from the smaller value that truly needs reconciliation.";
   }
   if (diagnostic.rule === "react-luau/prefer-binding-over-state") {
     return "Keep React state if changing the value must rebuild component structure rather than only update Roblox Instance properties or other Binding-aware consumers.";
@@ -12752,5 +13635,5 @@ ${renderUpdateNotice(update.current, update.latest, colorized)}
 }
 main();
 
-//# debugId=53584D6CB0EB00E064756E2164756E21
+//# debugId=569DB065E837196F64756E2164756E21
 //# sourceMappingURL=cli.js.map