@colrealpro/react-luau-doctor 0.18.3 → 0.19.0

package/dist/scan-worker.js

@@ -1433,6 +1433,8 @@ function hasRobloxReceiver(path3, 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) {
@@ -1497,6 +1499,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;
@@ -1513,6 +1542,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(path3, call, context) {
   const normalized = path3.replace(/\s+/g, "");
   if (normalized === "task.wait")
@@ -4059,7 +4118,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."
@@ -4336,7 +4395,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;
@@ -4459,13 +4520,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 path4 = context.resolveCallPath(context.getCallPath(call) ?? "").replace(/\s+/g, "");
+  return PURE_BINDING_DERIVATION_CALL.test(path4);
+}
+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 isInside(node, ancestor) {
   let current = node;
   while (current) {
@@ -4549,13 +4661,75 @@ 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;
+    if (!parent)
+      return null;
+    if (parent.type === "variable_declaration")
+      return parent;
+    if (parent.type === "function_definition" || parent.type === "function_declaration")
+      return null;
+    if (!isTransparentParent(parent, context))
+      return null;
+    current = parent;
+  }
+  return null;
+}
+function opaqueDerivedLocalDeclarationForRead(node, context) {
   let current = node;
   while (current) {
     const parent = current.parent;
@@ -4565,7 +4739,14 @@ function derivedLocalDeclarationForRead(node) {
       return parent;
     if (parent.type === "function_definition" || parent.type === "function_declaration")
       return null;
-    if (!TRANSPARENT_PARENTS.has(parent.type))
+    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 path4 = context.resolveCallPath(context.getCallPath(parent) ?? "");
+      if (/^React\.use(?:Memo|Callback|Effect|LayoutEffect)$/.test(path4))
+        return null;
+    }
+    if (!TRANSPARENT_PARENTS.has(parent.type) && parent.type !== "arguments" && parent.type !== "function_call")
       return null;
     current = parent;
   }
@@ -4585,7 +4766,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)))
@@ -4595,12 +4776,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 path4 = context.getCallPath(call) ?? "";
@@ -4611,12 +4826,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;
@@ -4624,14 +4841,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;
@@ -4639,14 +4859,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;
@@ -4660,25 +4878,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 path4 = context.getCallPath(node);
-    if (path4 !== binding.setterName)
+    if (path4 === 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;
@@ -4756,14 +5127,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) {
@@ -4792,7 +5157,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;
   }
@@ -4824,17 +5189,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;
   }
@@ -4847,11 +5212,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,
@@ -4863,9 +5228,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);
@@ -4888,11 +5289,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 path4 = context.resolveCallPath(context.getCallPath(call) ?? "");
+    if (path4 !== "React.useEffect" && path4 !== "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;
@@ -4909,75 +5393,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 ? `${path4} is using its React state mode for an externally changing GUI measurement, so ${localName} rerenders this consumer when the measurement changes.` : `${path4} returns React state for an externally changing GUI measurement, so ${localName} rerenders this consumer when the measurement changes.` : summary.sourceKind === "derived-external-state" ? `${path4} derives React state from another externally updated reactive value, so ${localName} adds another rerendering state layer.` : `${path4} 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 ? `${path4} mirrors ${observedProperty} through React state even though every analyzed use is presentation-only, so the measurement rerenders this consumer without needing reconciliation.` : likelyContinuousProperty ? `${path4} mirrors continuously mutable ${observedProperty} through React state, and ${localName} only feeds presentation updates that do not need reconciliation.` : `${path4} 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 path4 = context.getCallPath(call) ?? "";
-      const member = path4.split(/[.:]/).at(-1) ?? path4;
-      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: `${path4} 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: `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: `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 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
         });
       }
     }
@@ -4998,27 +5479,49 @@ var preferBindingOverStateCandidate = {
     for (const call of context.findCalls()) {
       const path4 = context.getCallPath(call) ?? "";
       const summary = importedHooks.get(path4);
-      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 = `${path4} 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 = `${path4} 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 = `${path4} 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 = `${path4} 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 = `${path4} 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: `${path4} 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()) {
@@ -5032,39 +5535,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: `${path4} 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: `${path4} 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;
@@ -6423,6 +6967,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);
@@ -6480,11 +7034,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
   };
 }
 
@@ -7455,5 +8010,5 @@ parentPort.on("message", async (request) => {
   }
 });
 
-//# debugId=CD648BE1625A701464756E2164756E21
+//# debugId=07C5601A473D8F7164756E2164756E21
 //# sourceMappingURL=scan-worker.js.map