@chrrxs/robloxstudio-mcp-inspector 3.2.0 → 3.3.0

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -64,8 +64,8 @@ applyRememberedServerUrl()
 -- down their VM. Close the persistent WebStreamClient while BindToClose still
 -- gives this server peer a live execution context; otherwise each play cycle
 -- can retain one native WebSocket until Studio itself is restarted. The
--- transport releases that native socket before yielding to unregister the
--- logical server peer.
+-- transport unregisters the server peer on that socket and waits at most two
+-- seconds for the server to close it, so no HTTP request can hold up shutdown.
 if startupRole == "server" then
 	game:BindToClose(StudioWebSocket.suspendForShutdown)
 end
@@ -104,8 +104,20 @@ plugin.Unloading:Connect(function()
 	Communication.deactivateAll()
 end)
 UI.updateUIState()
-Communication.checkForUpdates()
+-- Every DataModel shares Studio's five plugin HTTP request slots, and a
+-- request has no time limit. Check for updates once, from the edit DataModel,
+-- instead of again in every play server and client.
+if startupRole == "edit" then
+	Communication.checkForUpdates()
+end
 task.delay(TOOLBAR_REGISTRATION_DELAY_SECONDS, registerToolbarButton)
+--* Runs one startup step so that its failure cannot skip the steps after it. 
+local function runStartupStep(description, step)
+	local ok, err = pcall(step)
+	if not ok then
+		warn(`[robloxstudio-mcp] {description} failed: {err}`)
+	end
+end
 -- Auto-activate per Peer. Runtime plugin VMs can load before their first
 -- Heartbeat; task.delay() would then wait behind the very multiplayer startup
 -- that needs this Peer to register. Start runtime initialization immediately,
@@ -123,10 +135,13 @@ local function autoActivatePeer()
 	if role == "server" then
 		-- Yields until this playtest server knows which edit session (or
 		-- multiplayer group) it belongs to, so it registers under that identity.
-		PluginSession.resolveRuntimeTopology()
+		-- On failure the server still registers, under its own identity.
+		runStartupStep("Playtest topology resolution", function()
+			return PluginSession.resolveRuntimeTopology()
+		end)
 	end
 	if role == "edit" or role == "server" then
-		local activationOk, activationError = pcall(function()
+		runStartupStep(`Automatic {role} Peer activation`, function()
 			local conn = State.getActiveConnection()
 			if not conn.isActive then
 				if role == "server" then
@@ -155,19 +170,20 @@ local function autoActivatePeer()
 				Communication.activatePlugin()
 			end
 		end)
-		if not activationOk then
-			warn(`[robloxstudio-mcp] Automatic {role} Peer activation failed: {activationError}`)
-		end
 	end
 	if role == "server" then
-		ClientBroker.setupServerBroker()
+		runStartupStep("Client broker setup", function()
+			return ClientBroker.setupServerBroker()
+		end)
 		-- The play-server DM is the only one where StudioTestService:EndTest is
 		-- legal, so the stop-play monitor lives here. It consumes tokenized
 		-- stop requests from plugin settings and acknowledges EndTest results.
-		StopPlayMonitor.startMonitor({
-			beforeEndTest = StudioWebSocket.suspendForShutdown,
-			afterEndTestFailure = StudioWebSocket.resumeAfterShutdownFailure,
-		})
+		runStartupStep("Stop-play monitor startup", function()
+			return StopPlayMonitor.startMonitor({
+				beforeEndTest = StudioWebSocket.suspendForShutdown,
+				afterEndTestFailure = StudioWebSocket.resumeAfterShutdownFailure,
+			})
+		end)
 	elseif role == "client" then
 		ClientBroker.setupClientBroker()
 	end
@@ -1455,6 +1471,7 @@ local ClientBroker = TS.import(script, script.Parent, "ClientBroker")
 local ServerUrlSettings = TS.import(script, script.Parent, "ServerUrlSettings")
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
 local StudioWebSocket = TS.import(script, script.Parent, "StudioWebSocket")
+local PathGuard = TS.import(script, script.Parent, "PathGuard")
 local assignedRole
 local lastReadyPlaceKey
 local initialRole = PluginSession.getRole()
@@ -1507,12 +1524,17 @@ local routeMap = {
 	["/api/get-memory-breakdown"] = MemoryHandlers.getMemoryBreakdown,
 	["/api/get-scene-analysis"] = SceneAnalysisHandlers.getSceneAnalysis,
 }
+local pathGuard = PathGuard.createPathGuard(function(path)
+	return Utils.resolveInstancePath(path).ambiguity
+end)
 local function processRequest(request, context)
 	local endpoint = request.endpoint
-	local data = request.data or {}
+	local data = (request.data or {})
 	local handler = routeMap[endpoint]
 	if handler then
-		return handler(data, context)
+		return pathGuard.run(endpoint, data, function()
+			return handler(data, context)
+		end)
 	else
 		return {
 			error = `Unknown endpoint: {endpoint}`,
@@ -1959,9 +1981,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.2.0" is replaced with the package version at package time
+	-- "3.3.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.2.0`
+	return `{tostring(h)}-3.3.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -4197,15 +4219,20 @@ local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 -- capability and drives the REAL input pipeline: SendKey feeds
 -- UserInputService.InputBegan/Ended and the control modules (so WASD walks the
 -- character at full WalkSpeed with controls intact, no Humanoid hijack),
--- SendMouseButton feeds UIS and activates GUI buttons (and hit-tests against
--- CoreGui), and SendTextInput types into the focused TextBox.
+-- SendMouseButton feeds UIS and activates GUI buttons, SendMousePosition moves
+-- the cursor (hover, MouseEnter, InputChanged), SendPointerAction scrolls
+-- under a position, and SendTextInput types into the focused TextBox. Every method throws when the
+-- input would hit interactive CoreGui.
+--
+-- Verified live on a play client: move and scroll reach game scripts with
+-- the device simulator stopped. Under touch device emulation the client has
+-- no mouse: clicks arrive as Touch, scroll still works, but moves never reach
+-- the game, so we reject move there instead of returning a false success.
 --
--- Method set on the VirtualInput object (verified live):
---   SendKey(isDown: boolean, keyCode: Enum.KeyCode)
---   SendMouseButton(position: Vector2, inputType: Enum.UserInputType, isDown: boolean)
---   SendTextInput(text: string)
--- There is NO SendMouseMove / SendMouseWheel / SendKeyEvent — so "move" and
--- "scroll" mouse actions are not supported.
+-- SendMouseDelta is deliberately NOT exposed. It only works while the cursor
+-- is locked (MouseBehavior.LockCenter), and on desktop Studio holds that lock
+-- by pinning and hiding the user's real OS cursor — an unacceptable takeover
+-- of the host's input.
 --
 -- Coordinate space: SendMouseButton coordinates are viewport pixels matching
 -- what capture_screenshot returns (window space, origin at the top-left of the
@@ -4238,6 +4265,7 @@ local MOUSE_TYPE_MAP = {
 	Right = Enum.UserInputType.MouseButton2,
 	Middle = Enum.UserInputType.MouseButton3,
 }
+local NO_MOUSE_ERROR = "This client has no mouse (touch device emulation is active), so cursor movement never reaches the game. " .. "Stop it with set_device_simulator stopSimulation=true, then retry."
 local function simulateMouseInput(requestData)
 	local action = requestData.action
 	local x = requestData.x
@@ -4247,6 +4275,7 @@ local function simulateMouseInput(requestData)
 		_condition = "Left"
 	end
 	local button = _condition
+	local wheel = requestData.wheel
 	if not (action ~= "" and action) then
 		return {
 			error = "action is required",
@@ -4257,6 +4286,11 @@ local function simulateMouseInput(requestData)
 			error = "x and y are required",
 		}
 	end
+	if action == "scroll" and (not (type(wheel) == "number") or wheel == 0) then
+		return {
+			error = "wheel must be a non-zero number for scroll",
+		}
+	end
 	-- Input is silently dropped by the engine when the window isn't rendering
 	-- (e.g. minimized). Surface that instead of returning a false success.
 	local notRendering = RenderMonitor.notRenderingReason()
@@ -4265,6 +4299,11 @@ local function simulateMouseInput(requestData)
 			error = notRendering,
 		}
 	end
+	if action == "move" and not UserInputService.MouseEnabled then
+		return {
+			error = NO_MOUSE_ERROR,
+		}
+	end
 	local vi = getVI()
 	if not vi then
 		return {
@@ -4282,18 +4321,29 @@ local function simulateMouseInput(requestData)
 			vi:SendMouseButton(pos, inputType, true)
 		elseif action == "mouseUp" then
 			vi:SendMouseButton(pos, inputType, false)
+		elseif action == "move" then
+			vi:SendMousePosition(pos)
+		elseif action == "scroll" then
+			vi:SendPointerAction(pos, {
+				Wheel = wheel,
+			})
 		else
-			error(`Unsupported action "{action}". CreateVirtualInput supports click, mouseDown, mouseUp ` .. `(no move/scroll — those methods don't exist on VirtualInput).`)
+			error(`Unsupported action "{action}". Use click, mouseDown, mouseUp, move, or scroll.`)
 		end
 	end)
 	if success then
-		return {
+		local result = {
 			success = true,
 			action = action,
 			x = x,
 			y = y,
-			button = button,
 		}
+		if action == "scroll" then
+			result.wheel = wheel
+		elseif action ~= "move" then
+			result.button = button
+		end
+		return result
 	end
 	return {
 		error = `Failed to simulate mouse input: {err}`,
@@ -4484,6 +4534,7 @@ local Selection = game:GetService("Selection")
 local _binding = Utils
 local getInstancePath = _binding.getInstancePath
 local getInstanceByPath = _binding.getInstanceByPath
+local createPathAmbiguityChecker = _binding.createPathAmbiguityChecker
 local function serializeValue(value)
 	local _value = value
 	local vType = typeof(_value)
@@ -4585,15 +4636,20 @@ local function getSelection(_requestData)
 			message = "No objects selected",
 		}
 	end
+	local isAmbiguous = createPathAmbiguityChecker()
 	-- ▼ ReadonlyArray.map ▼
 	local _newValue = table.create(#selection)
 	local _callback = function(instance)
-		return {
+		local entry = {
 			name = instance.Name,
 			className = instance.ClassName,
 			path = getInstancePath(instance),
 			parent = if instance.Parent then getInstancePath(instance.Parent) else nil,
 		}
+		if isAmbiguous(instance) then
+			entry.ambiguous = true
+		end
+		return entry
 	end
 	for _k, _v in selection do
 		_newValue[_k] = _callback(_v, _k - 1, selection)
@@ -6732,9 +6788,11 @@ local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 local Utils = TS.import(script, script.Parent.Parent, "Utils")
 local CooperativeJobRunner = TS.import(script, script.Parent.Parent, "CooperativeJobRunner")
 local ScriptSearch = TS.import(script, script.Parent.Parent, "ScriptSearch")
+local InstanceSearch = TS.import(script, script.Parent.Parent, "InstanceSearch")
 local _binding = Utils
 local getInstancePath = _binding.getInstancePath
 local getInstanceByPath = _binding.getInstanceByPath
+local createPathAmbiguityChecker = _binding.createPathAmbiguityChecker
 local readScriptSource = _binding.readScriptSource
 local function getFileTree(requestData)
 	local _condition = (requestData.path)
@@ -6860,62 +6918,42 @@ local function getPlaceInfo(_requestData)
 		},
 	}
 end
-local function searchObjects(requestData)
-	local query = requestData.query
-	local _condition = (requestData.searchType)
-	if _condition == nil then
-		_condition = "name"
-	end
-	local searchType = _condition
-	local propertyName = requestData.propertyName
-	if not (query ~= "" and query) then
-		return {
-			error = "Query is required",
-		}
-	end
-	local results = {}
-	local function searchRecursive(instance)
-		local match = false
-		if searchType == "name" then
-			local _exp = string.lower(instance.Name)
-			local _arg0 = string.lower(query)
-			match = (string.find(_exp, _arg0)) ~= nil
-		elseif searchType == "class" then
-			local _exp = string.lower(instance.ClassName)
-			local _arg0 = string.lower(query)
-			match = (string.find(_exp, _arg0)) ~= nil
-		else
-			local _value = searchType == "property" and propertyName
-			if _value ~= "" and _value then
-				local success, value = pcall(function()
-					return tostring(instance[propertyName])
-				end)
-				if success then
-					local _exp = string.lower(value)
-					local _arg0 = string.lower(query)
-					match = (string.find(_exp, _arg0)) ~= nil
-				end
-			end
-		end
-		if match then
-			local _arg0 = {
-				name = instance.Name,
-				className = instance.ClassName,
-				path = getInstancePath(instance),
-			}
-			table.insert(results, _arg0)
-		end
-		for _, child in instance:GetChildren() do
-			searchRecursive(child)
-		end
+local instanceSearch = InstanceSearch.createInstanceSearch({
+	resolveRoot = getInstanceByPath,
+	getChildren = function(instance)
+		return instance:GetChildren()
+	end,
+	getName = function(instance)
+		return instance.Name
+	end,
+	getClassName = function(instance)
+		return instance.ClassName
+	end,
+	isA = function(instance, className)
+		return instance:IsA(className)
+	end,
+	readPropertyText = function(instance, propertyName)
+		local success, value = pcall(function()
+			return tostring(instance[propertyName])
+		end)
+		return if success then value else nil
+	end,
+	getPath = getInstancePath,
+	createAmbiguityChecker = createPathAmbiguityChecker,
+})
+local function searchObjects(requestData, execution)
+	-- Keyed per request: concurrent searches are independent reads, so the
+	-- runner is used only for yielding, deadlines and cancellation.
+	local result = CooperativeJobRunner.runExclusive(`instance-search:{execution.requestId}`, execution, function(control)
+		return instanceSearch.search(requestData, control)
+	end)
+	if result.error == "deadline_exceeded" then
+		local _object = table.clone(result)
+		setmetatable(_object, nil)
+		_object.message = "search_objects exceeded its bridge deadline before the scan completed. Narrow it with path or className."
+		return _object
 	end
-	searchRecursive(game)
-	return {
-		results = results,
-		query = query,
-		searchType = searchType,
-		count = #results,
-	}
+	return result
 end
 local function getInstanceProperties(requestData)
 	local instancePath = requestData.instancePath
@@ -7183,9 +7221,10 @@ local function getProjectStructure(requestData)
 			error = `Path not found: {startPath}`,
 		}
 	end
+	local isAmbiguous = createPathAmbiguityChecker()
 	local function getStructure(instance, depth)
 		if depth > maxDepth then
-			return {
+			local truncatedNode = {
 				name = instance.Name,
 				className = instance.ClassName,
 				path = getInstancePath(instance),
@@ -7193,12 +7232,19 @@ local function getProjectStructure(requestData)
 				hasMore = true,
 				note = "Max depth reached - use this path to explore further",
 			}
+			if isAmbiguous(instance) then
+				truncatedNode.ambiguous = true
+			end
+			return truncatedNode
 		end
 		local node = {
 			name = instance.Name,
 			className = instance.ClassName,
 			path = getInstancePath(instance),
 		}
+		if isAmbiguous(instance) then
+			node.ambiguous = true
+		end
 		if instance:IsA("LuaSourceContainer") then
 			node.hasSource = true
 			node.scriptType = instance.ClassName
@@ -7328,6 +7374,9 @@ local scriptSearch = ScriptSearch.createScriptSearch({
 	resolveRoot = function(self, path)
 		return getInstanceByPath(path)
 	end,
+	createAmbiguityChecker = function(self)
+		return createPathAmbiguityChecker()
+	end,
 	getChildren = function(self, instance)
 		return instance:GetChildren()
 	end,
@@ -7635,6 +7684,9 @@ return {
 local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 local Utils = TS.import(script, script.Parent.Parent, "Utils")
 local Recording = TS.import(script, script.Parent.Parent, "Recording")
+local _ScriptEdits = TS.import(script, script.Parent.Parent, "ScriptEdits")
+local planScriptEdits = _ScriptEdits.planScriptEdits
+local sourceRevision = _ScriptEdits.sourceRevision
 local _binding = Utils
 local getInstancePath = _binding.getInstancePath
 local getInstanceByPath = _binding.getInstanceByPath
@@ -7750,6 +7802,7 @@ local function getScriptSource(requestData)
 			numberedSource = numberLines(selectedLines, returnedStartLine),
 			sourceLength = #fullSource,
 			lineCount = totalLineCount,
+			revision = sourceRevision(fullSource),
 			startLine = returnedStartLine,
 			endLine = returnedEndLine,
 			isPartial = explicitRange,
@@ -7821,14 +7874,74 @@ local function setScriptSource(requestData)
 		error = `Failed to set script source: {applyResult.error}`,
 	}
 end
+-- Accepts the batched `edits` array or the single top-level old_string form.
+local function readScriptEdits(requestData)
+	local rawEdits = requestData.edits
+	if rawEdits == nil then
+		local oldString = requestData.old_string
+		local newString = requestData.new_string
+		local startLine = requestData.startLine
+		if not (type(oldString) == "string") or not (type(newString) == "string") then
+			return "Instance path, old_string, and new_string are required"
+		end
+		if startLine ~= nil and not (type(startLine) == "number") then
+			return "startLine must be a number"
+		end
+		return { {
+			oldString = oldString,
+			newString = newString,
+			startLine = startLine,
+		} }
+	end
+	if not (type(rawEdits) == "table") then
+		return "edits must be an array"
+	end
+	local edits = {}
+	for _, rawEdit in rawEdits do
+		local index = #edits
+		if not (type(rawEdit) == "table") then
+			return `edits[{index}] must be an object`
+		end
+		local fields = rawEdit
+		local oldString = fields.old_string
+		local newString = fields.new_string
+		local startLine = fields.startLine
+		if not (type(oldString) == "string") or not (type(newString) == "string") then
+			return `edits[{index}] requires old_string and new_string`
+		end
+		if startLine ~= nil and not (type(startLine) == "number") then
+			return `edits[{index}].startLine must be a number`
+		end
+		local _arg0 = {
+			oldString = oldString,
+			newString = newString,
+			startLine = startLine,
+		}
+		table.insert(edits, _arg0)
+	end
+	if #edits == 0 then
+		return "edits must contain at least one edit"
+	end
+	return edits
+end
 local function editScriptLines(requestData)
 	local instancePath = requestData.instancePath
-	local oldString = requestData.old_string
-	local newString = requestData.new_string
-	local startLine = requestData.startLine
-	if not (instancePath ~= "" and instancePath) or oldString == nil or newString == nil then
+	local expectedRevision = requestData.expectedRevision
+	local dryRun = requestData.dryRun == true
+	if not (instancePath ~= "" and instancePath) then
 		return {
-			error = "Instance path, old_string, and new_string are required",
+			error = "Instance path is required",
+		}
+	end
+	local edits = readScriptEdits(requestData)
+	if type(edits) == "string" then
+		return {
+			error = edits,
+		}
+	end
+	if expectedRevision ~= nil and not (type(expectedRevision) == "string") then
+		return {
+			error = "expectedRevision must be a string",
 		}
 	end
 	local instance = getInstanceByPath(instancePath)
@@ -7842,76 +7955,63 @@ local function editScriptLines(requestData)
 			error = `Instance is not a script-like object: {instance.ClassName}`,
 		}
 	end
-	local recordingId = beginRecording(`Edit script: {instance.Name}`)
-	local success, result = pcall(function()
-		local source = readScriptSource(instance)
-		local searchLen = #oldString
-		local matchStart
-		if startLine ~= nil then
-			if startLine < 1 then
-				error(`startLine must be >= 1 (got {startLine})`)
-			end
-			local lineStartByte = 1
-			local currentLine = 1
-			while currentLine < startLine do
-				local nlPos = string.find(source, "\n", lineStartByte, true)
-				if nlPos == nil then
-					error(`startLine {startLine} is past end of script ({currentLine} lines)`)
-				end
-				lineStartByte = nlPos + 1
-				currentLine += 1
-			end
-			local candidate = string.sub(source, lineStartByte, lineStartByte + searchLen - 1)
-			if candidate ~= oldString then
-				error(`old_string does not match at line {startLine}. Use get_script_source to verify the exact text at that line.`)
-			end
-			matchStart = lineStartByte
-		else
-			local count = 0
-			local searchPos = 1
-			local firstMatch
-			while true do
-				local foundStart = string.find(source, oldString, searchPos, true)
-				if foundStart == nil then
-					break
-				end
-				if firstMatch == nil then
-					firstMatch = foundStart
-				end
-				count += 1
-				if count > 1 then
-					break
-				end
-				searchPos = foundStart + searchLen
-			end
-			if count == 0 then
-				error("old_string not found in script. If old_string contains repeated patterns (e.g. closing braces), pass startLine to anchor the edit.")
-			end
-			if count > 1 then
-				error("old_string matches multiple locations. Provide more surrounding context, or pass startLine to anchor the edit to a specific line.")
-			end
-			matchStart = firstMatch
-		end
-		-- Byte-slice replacement avoids Lua pattern escaping (safe for multi-byte chars like em dashes).
-		local newSource = string.sub(source, 1, matchStart - 1) .. newString .. string.sub(source, matchStart + searchLen)
-		local applyResult = applyScriptSource(instance, newSource, source)
-		if not applyResult.success then
-			error(applyResult.error)
-		end
+	local readSuccess, readResult = pcall(function()
+		return readScriptSource(instance)
+	end)
+	if not readSuccess then
 		return {
+			error = `Failed to edit script: {readResult}`,
+		}
+	end
+	local source = readResult
+	local revision = sourceRevision(source)
+	if expectedRevision ~= nil and expectedRevision ~= revision then
+		return {
+			error = "Script changed since expected_revision; read it again with get_script_source and retry.",
+			code = "revision_mismatch",
+			instancePath = instancePath,
+			expectedRevision = expectedRevision,
+			revision = revision,
+		}
+	end
+	local plan = planScriptEdits(source, edits, dryRun)
+	if not plan.ok then
+		return {
+			error = `Failed to edit script: {plan.error}`,
+		}
+	end
+	if dryRun then
+		local preview = {
 			success = true,
+			dryRun = true,
 			instancePath = instancePath,
-			method = applyResult.method,
-			message = "Script edited successfully",
+			editCount = #edits,
+			revision = revision,
+			resultRevision = sourceRevision(plan.newSource),
+			diff = plan.diff,
 		}
-	end)
-	if success then
-		finishRecording(recordingId, true)
-		return result
+		if plan.diffTruncated then
+			preview.diffTruncated = true
+		end
+		return preview
 	end
-	finishRecording(recordingId, false)
+	local recordingId = beginRecording(if #edits > 1 then `Edit script ({#edits} edits): {instance.Name}` else `Edit script: {instance.Name}`)
+	-- One compare-and-set write: a draft typed since the read rejects the whole batch.
+	local applyResult = applyScriptSource(instance, plan.newSource, source)
+	if not applyResult.success then
+		finishRecording(recordingId, false)
+		return {
+			error = `Failed to edit script: {applyResult.error}`,
+		}
+	end
+	finishRecording(recordingId, true)
 	return {
-		error = `Failed to edit script: {result}`,
+		success = true,
+		instancePath = instancePath,
+		editCount = #edits,
+		revision = sourceRevision(plan.newSource),
+		method = applyResult.method,
+		message = "Script edited successfully",
 	}
 end
 local function insertScriptLines(requestData)
@@ -9432,6 +9532,166 @@ return {
         </Properties>
       </Item>
       <Item class="ModuleScript" referent="27">
+        <Properties>
+          <string name="Name">InstanceSearch</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+-- Bounded instance search behind search_objects. It walks one subtree in
+-- GetChildren order, applies an optional IsA filter, and stops after
+-- maxResults matches. An ambiguous `path` is reported by PathGuard before this
+-- runs. It is written against an injected corpus so it can run outside Studio.
+-- Function properties rather than methods, so plain functions can be assigned
+-- directly under roblox-ts.
+local SEARCH_TYPES = {
+	["name"] = true,
+	["class"] = true,
+	["property"] = true,
+}
+local DEFAULT_MAX_RESULTS = 100
+local MAX_RESULTS = 10000
+local function invalid(message)
+	return {
+		error = "invalid_request",
+		message = message,
+	}
+end
+local function containsText(haystack, needle)
+	return (string.find(string.lower(haystack), needle, 1, true)) ~= nil
+end
+local function createInstanceSearch(corpus)
+	local function search(requestData, control)
+		local rawQuery = requestData.query
+		if rawQuery ~= nil and not (type(rawQuery) == "string") then
+			return invalid("query must be a string")
+		end
+		local _condition = rawQuery
+		if _condition == nil then
+			_condition = ""
+		end
+		local query = _condition
+		local _condition_1 = requestData.searchType
+		if _condition_1 == nil then
+			_condition_1 = "name"
+		end
+		local rawSearchType = _condition_1
+		if not (type(rawSearchType) == "string") or not (SEARCH_TYPES[rawSearchType] ~= nil) then
+			return invalid("searchType must be one of name, class, property")
+		end
+		local searchType = rawSearchType
+		local propertyName = requestData.propertyName
+		if searchType == "property" and (not (type(propertyName) == "string") or propertyName == "") then
+			return invalid("propertyName is required when searchType is property")
+		end
+		local className = requestData.className
+		if className ~= nil and (not (type(className) == "string") or className == "") then
+			return invalid("className must be a non-empty string")
+		end
+		if query == "" and className == nil then
+			return {
+				error = "query is required unless className is set",
+			}
+		end
+		local requestedMaxResults = requestData.maxResults
+		if requestedMaxResults ~= nil and (not (type(requestedMaxResults) == "number") or math.floor(requestedMaxResults) ~= requestedMaxResults or requestedMaxResults < 1 or requestedMaxResults > MAX_RESULTS) then
+			return invalid(`maxResults must be an integer between 1 and {MAX_RESULTS}`)
+		end
+		local _condition_2 = requestedMaxResults
+		if _condition_2 == nil then
+			_condition_2 = DEFAULT_MAX_RESULTS
+		end
+		local maxResults = _condition_2
+		local rawPath = requestData.path
+		if rawPath ~= nil and not (type(rawPath) == "string") then
+			return invalid("path must be a string")
+		end
+		local _condition_3 = rawPath
+		if _condition_3 == nil then
+			_condition_3 = ""
+		end
+		local searchPath = _condition_3
+		local root = corpus.resolveRoot(searchPath)
+		if root == nil then
+			return {
+				error = `Path not found: {searchPath}`,
+			}
+		end
+		local needle = string.lower(query)
+		local isAmbiguous = corpus.createAmbiguityChecker()
+		local function matches(node)
+			if className ~= nil and not corpus.isA(node, className) then
+				return false
+			end
+			if needle == "" then
+				return true
+			end
+			if searchType == "name" then
+				return containsText(corpus.getName(node), needle)
+			end
+			if searchType == "class" then
+				return containsText(corpus.getClassName(node), needle)
+			end
+			local text = corpus.readPropertyText(node, propertyName)
+			return text ~= nil and containsText(text, needle)
+		end
+		local results = {}
+		local stack = { root }
+		local truncated = false
+		while #stack > 0 do
+			control:checkpoint()
+			-- ▼ Array.pop ▼
+			local _length = #stack
+			local _result = stack[_length]
+			stack[_length] = nil
+			-- ▲ Array.pop ▲
+			local node = _result
+			if matches(node) then
+				if #results >= maxResults then
+					truncated = true
+					break
+				end
+				local entry = {
+					name = corpus.getName(node),
+					className = corpus.getClassName(node),
+					path = corpus.getPath(node),
+				}
+				if isAmbiguous(node) then
+					entry.ambiguous = true
+				end
+				table.insert(results, entry)
+			end
+			local children = corpus.getChildren(node)
+			for index = #children - 1, 0, -1 do
+				local _arg0 = children[index + 1]
+				table.insert(stack, _arg0)
+			end
+		end
+		local response = {
+			results = results,
+			query = query,
+			searchType = searchType,
+			count = #results,
+			truncated = truncated,
+			maxResults = maxResults,
+			path = corpus.getPath(root),
+		}
+		if searchType == "property" then
+			response.propertyName = propertyName
+		end
+		if className ~= nil then
+			response.className = className
+		end
+		return response
+	end
+	return {
+		search = search,
+	}
+end
+return {
+	createInstanceSearch = createInstanceSearch,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">LuauExec</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9865,7 +10125,331 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
+        <Properties>
+          <string name="Name">PathAmbiguity</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+-- Canonical instance paths address children by name, so siblings that share a
+-- name produce identical paths. This module resolves paths while reporting the
+-- first ambiguous segment, and marks emitted paths that cannot identify one
+-- instance. It is written against an injected tree so it can run outside Studio.
+local function findNamedChild(tree, parent, name)
+	local first
+	local count = 0
+	for _, child in tree.getChildren(parent) do
+		if tree.getName(child) == name then
+			if first == nil then
+				first = child
+			end
+			count += 1
+		end
+	end
+	return { first, count }
+end
+-- Mirrors Utils.getInstanceByPath: the root segment prefers service lookup and
+-- later segments take the first child with a matching name. The resolved
+-- instance is returned even when ambiguous, so callers decide whether to refuse.
+local function resolvePath(tree, parts)
+	if #parts == 0 then
+		return {
+			instance = tree.root,
+		}
+	end
+	local ambiguity
+	local current = tree.getService(parts[1])
+	if current == nil then
+		local _binding = findNamedChild(tree, tree.root, parts[1])
+		local first = _binding[1]
+		local count = _binding[2]
+		current = first
+		if count > 1 then
+			ambiguity = {
+				segment = parts[1],
+				parentPath = tree.getPath(tree.root),
+				matchCount = count,
+			}
+		end
+	end
+	for i = 1, #parts - 1 do
+		if current == nil then
+			break
+		end
+		local _binding = findNamedChild(tree, current, parts[i + 1])
+		local first = _binding[1]
+		local count = _binding[2]
+		if count > 1 and ambiguity == nil then
+			ambiguity = {
+				segment = parts[i + 1],
+				parentPath = tree.getPath(current),
+				matchCount = count,
+			}
+		end
+		current = first
+	end
+	return {
+		instance = current,
+		ambiguity = ambiguity,
+	}
+end
+-- Returns a checker for one request. Sibling name counts and verdicts are
+-- cached per node, so marking many results under one parent stays linear.
+local function createAmbiguityChecker(tree)
+	local nameCounts = {}
+	local verdicts = {}
+	local function countNamed(parent, name)
+		local _parent = parent
+		local counts = nameCounts[_parent]
+		if counts == nil then
+			counts = {}
+			for _, child in tree.getChildren(parent) do
+				local childName = tree.getName(child)
+				local _counts = counts
+				local _condition = counts[childName]
+				if _condition == nil then
+					_condition = 0
+				end
+				_counts[childName] = _condition + 1
+			end
+			local _parent_1 = parent
+			local _counts = counts
+			nameCounts[_parent_1] = _counts
+		end
+		local _counts = counts
+		local _name = name
+		local _condition = _counts[_name]
+		if _condition == nil then
+			_condition = 0
+		end
+		return _condition
+	end
+	local function segmentIsAmbiguous(node, parent)
+		local name = tree.getName(node)
+		if parent == tree.root then
+			if tree.isRootService(node) then
+				return false
+			end
+			-- A root segment that names a service resolves to that service,
+			-- never to this child.
+			local service = tree.getService(name)
+			if service ~= nil and service ~= node then
+				return true
+			end
+		end
+		return countNamed(parent, name) > 1
+	end
+	return function(node)
+		local visited = {}
+		local result = false
+		local current = node
+		while current ~= tree.root do
+			local _current = current
+			local cached = verdicts[_current]
+			if cached ~= nil then
+				result = cached
+				break
+			end
+			local parent = tree.getParent(current)
+			if parent == nil then
+				break
+			end
+			local _current_1 = current
+			table.insert(visited, _current_1)
+			if segmentIsAmbiguous(current, parent) then
+				result = true
+				break
+			end
+			current = parent
+		end
+		for _, visitedNode in visited do
+			local _result = result
+			verdicts[visitedNode] = _result
+		end
+		return result
+	end
+end
+return {
+	resolvePath = resolvePath,
+	createAmbiguityChecker = createAmbiguityChecker,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="30">
+        <Properties>
+          <string name="Name">PathGuard</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+-- Central handling of request paths that name more than one instance.
+-- Every endpoint that accepts instance paths declares them here. Before the
+-- handler runs, each declared path is checked:
+--   - write: an ambiguous path refuses the request, so no arbitrary duplicate
+--     is modified;
+--   - read: the handler runs on the first match, and the response gains
+--     `ambiguousPaths` and `pathWarning` so the caller knows it may be wrong.
+-- Written against an injected resolver so it can run outside Studio.
+local function pathField(field, access)
+	return function(data)
+		local value = data[field]
+		if not (type(value) == "string") or value == "" then
+			return {}
+		end
+		local _object = {
+			field = field,
+			path = value,
+		}
+		local _left = "access"
+		local _access = access
+		_object[_left] = if type(_access) == "string" then access else access(data)
+		return { _object }
+	end
+end
+local function pathListField(field, access)
+	return function(data)
+		local value = data[field]
+		local references = {}
+		if not (type(value) == "table") then
+			return references
+		end
+		local index = 0
+		for _, entry in value do
+			if type(entry) == "string" and entry ~= "" then
+				local _arg0 = {
+					field = `{field}[{index}]`,
+					path = entry,
+					access = access,
+				}
+				table.insert(references, _arg0)
+			end
+			index += 1
+		end
+		return references
+	end
+end
+-- set_properties takes instance paths as the values of reference properties.
+local REFERENCE_PROPERTIES = { "Parent", "PrimaryPart" }
+local function referencePropertyPaths(data)
+	local properties = data.properties
+	local references = {}
+	if not (type(properties) == "table") then
+		return references
+	end
+	for _, propertyName in REFERENCE_PROPERTIES do
+		local value = properties[propertyName]
+		if type(value) == "string" and value ~= "" then
+			local _arg0 = {
+				field = `properties.{propertyName}`,
+				path = value,
+				access = "write",
+			}
+			table.insert(references, _arg0)
+		end
+	end
+	return references
+end
+local dryRunIsRead = function(data)
+	return if data.dryRun == true then "read" else "write"
+end
+local ENDPOINT_PATHS = {
+	["/api/file-tree"] = { pathField("path", "read") },
+	["/api/search-objects"] = { pathField("path", "read") },
+	["/api/instance-properties"] = { pathField("instancePath", "read") },
+	["/api/project-structure"] = { pathField("path", "read") },
+	["/api/grep-scripts"] = { pathField("path", "read") },
+	["/api/get-script-source"] = { pathField("instancePath", "read") },
+	["/api/get-attributes"] = { pathField("instancePath", "read") },
+	["/api/set-selection"] = { pathListField("paths", "read") },
+	["/api/focus-viewport"] = { pathField("path", "read") },
+	["/api/breakpoints"] = { pathField("script_path", "read") },
+	["/api/export-rbxm"] = { pathListField("instance_paths", "read") },
+	["/api/set-properties"] = { pathField("instancePath", "write"), referencePropertyPaths },
+	["/api/set-script-source"] = { pathField("instancePath", "write") },
+	["/api/edit-script-lines"] = { pathField("instancePath", dryRunIsRead) },
+	["/api/insert-script-lines"] = { pathField("instancePath", "write") },
+	["/api/delete-script-lines"] = { pathField("instancePath", "write") },
+	["/api/find-and-replace-in-scripts"] = { pathField("path", dryRunIsRead) },
+	["/api/insert-asset"] = { pathField("parentPath", "write") },
+	["/api/import-rbxm"] = { pathField("parent_path", "write") },
+}
+local function describe(report)
+	return `{report.path} ({report.field}): {report.matchCount} children of {report.parentPath} are named "{report.segment}"`
+end
+local function describeAll(reports)
+	local parts = {}
+	for _, report in reports do
+		local _arg0 = describe(report)
+		table.insert(parts, _arg0)
+	end
+	return table.concat(parts, "; ")
+end
+local function createPathGuard(findAmbiguity)
+	local function inspect(endpoint, data)
+		local reports = {}
+		local extractors = ENDPOINT_PATHS[endpoint]
+		if extractors == nil then
+			return reports
+		end
+		for _, extract in extractors do
+			for _1, reference in extract(data) do
+				local ambiguity = findAmbiguity(reference.path)
+				if ambiguity ~= nil then
+					local _arg0 = {
+						field = reference.field,
+						path = reference.path,
+						access = reference.access,
+						segment = ambiguity.segment,
+						parentPath = ambiguity.parentPath,
+						matchCount = ambiguity.matchCount,
+					}
+					table.insert(reports, _arg0)
+				end
+			end
+		end
+		return reports
+	end
+	local function run(endpoint, data, handle)
+		local reports = inspect(endpoint, data)
+		if #reports == 0 then
+			return handle()
+		end
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(report)
+			return report.access == "write"
+		end
+		local _length = 0
+		for _k, _v in reports do
+			if _callback(_v, _k - 1, reports) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local writes = _newValue
+		if #writes > 0 then
+			return {
+				error = `Ambiguous path {describeAll(writes)}. Refusing to modify an arbitrary match; rename the duplicates or target the instance with execute_luau.`,
+				ambiguousPaths = writes,
+			}
+		end
+		local result = handle()
+		if type(result) == "table" then
+			local response = result
+			response.ambiguousPaths = reports
+			response.pathWarning = `Ambiguous path {describeAll(reports)}; the first match was used.`
+		end
+		return result
+	end
+	return {
+		inspect = inspect,
+		run = run,
+	}
+end
+return {
+	createPathGuard = createPathGuard,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="31">
         <Properties>
           <string name="Name">PeerRole</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9886,7 +10470,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="32">
         <Properties>
           <string name="Name">PlaytestTickets</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10067,7 +10651,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="30">
+      <Item class="ModuleScript" referent="33">
         <Properties>
           <string name="Name">PluginSession</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10092,10 +10676,12 @@ local TOPOLOGY_TOKEN_ATTRIBUTE = "__MCPTopologyToken"
 -- saved or published DataModel, so edit sessions remove them on load.
 local LEGACY_TOPOLOGY_ATTRIBUTES = { TOPOLOGY_MODE_ATTRIBUTE, TOPOLOGY_INSTANCE_ID_ATTRIBUTE, TOPOLOGY_GROUP_ID_ATTRIBUTE, TOPOLOGY_TOKEN_ATTRIBUTE }
 local SESSION_IDENTITY_NAME = "__MCPSessionIdentity"
--- Attributes on the CoreGui identity value: CoreGui survives plugin reloads but
--- is never saved with the place or copied into playtest DataModels.
-local PLAY_RECORD_ATTRIBUTE = "PlayRecord"
-local RUNTIME_TOPOLOGY_ATTRIBUTE = "RuntimeTopology"
+-- JSON session state lives in StringValue children of the CoreGui identity
+-- value: CoreGui survives plugin reloads but is never saved with the place or
+-- copied into playtest DataModels. Not attributes: with NextGenerationReplication,
+-- playtest DataModels reject attribute strings longer than 50 characters.
+local PLAY_RECORD_NAME = "PlayRecord"
+local RUNTIME_TOPOLOGY_NAME = "RuntimeTopology"
 -- MCP-started solo and Run playtests carry their topology in StudioTestService
 -- test args, which never touch the DataModel.
 local TEST_ARGS_TOPOLOGY_KEY = "__mcpTopology"
@@ -10216,18 +10802,54 @@ local function optionalString(value)
 	end
 	return if _condition then value else nil
 end
-function readPlayRecord()
-	local raw = sessionIdentity:GetAttribute(PLAY_RECORD_ATTRIBUTE)
-	if not (type(raw) == "string") then
+local function readSessionState(name)
+	local holder = sessionIdentity:FindFirstChild(name)
+	if holder == nil or not holder:IsA("StringValue") then
 		return nil
 	end
 	local ok, decoded = pcall(function()
-		return HttpService:JSONDecode(raw)
+		return HttpService:JSONDecode(holder.Value)
 	end)
 	if not ok or not (type(decoded) == "table") then
 		return nil
 	end
-	local data = decoded
+	return decoded
+end
+--* Best effort: saved session state only lets a plugin reload resume where it left off. 
+local function writeSessionState(name, state)
+	local ok, err = pcall(function()
+		local existing = sessionIdentity:FindFirstChild(name)
+		if state == nil then
+			local _result = existing
+			if _result ~= nil then
+				_result:Destroy()
+			end
+			return nil
+		end
+		local encoded = HttpService:JSONEncode(state)
+		if existing ~= nil and existing:IsA("StringValue") then
+			existing.Value = encoded
+			return nil
+		end
+		local _result = existing
+		if _result ~= nil then
+			_result:Destroy()
+		end
+		local holder = Instance.new("StringValue")
+		holder.Name = name
+		holder.Value = encoded
+		holder.Archivable = false
+		holder.Parent = sessionIdentity
+	end)
+	if not ok then
+		warn(`[robloxstudio-mcp] Could not save {name} session state: {err}`)
+	end
+end
+function readPlayRecord()
+	local data = readSessionState(PLAY_RECORD_NAME)
+	if data == nil then
+		return nil
+	end
 	local phase = if data.phase == "armed" or data.phase == "active" then data.phase else nil
 	if phase == nil then
 		return nil
@@ -10243,16 +10865,7 @@ function readPlayRecord()
 	}
 end
 local function writePlayRecord(record)
-	if record == nil then
-		sessionIdentity:SetAttribute(PLAY_RECORD_ATTRIBUTE, nil)
-		return nil
-	end
-	local ok, encoded = pcall(function()
-		return HttpService:JSONEncode(record)
-	end)
-	if ok and type(encoded) == "string" then
-		sessionIdentity:SetAttribute(PLAY_RECORD_ATTRIBUTE, encoded)
-	end
+	writeSessionState(PLAY_RECORD_NAME, record)
 end
 local function createTicket(instanceId, groupId)
 	local now = PlaytestTickets.nowMs()
@@ -10544,17 +11157,10 @@ local function topologyFromTestArgs()
 	}
 end
 local function readRememberedRuntimeTopology()
-	local raw = sessionIdentity:GetAttribute(RUNTIME_TOPOLOGY_ATTRIBUTE)
-	if not (type(raw) == "string") then
+	local data = readSessionState(RUNTIME_TOPOLOGY_NAME)
+	if data == nil then
 		return nil
 	end
-	local ok, decoded = pcall(function()
-		return HttpService:JSONDecode(raw)
-	end)
-	if not ok or not (type(decoded) == "table") then
-		return nil
-	end
-	local data = decoded
 	return {
 		instanceId = optionalString(data.instanceId),
 		groupId = optionalString(data.groupId),
@@ -10564,12 +11170,7 @@ local function readRememberedRuntimeTopology()
 end
 local function adoptRuntimeTopology(topology)
 	runtimeTopology = topology
-	local ok, encoded = pcall(function()
-		return HttpService:JSONEncode(topology)
-	end)
-	if ok and type(encoded) == "string" then
-		sessionIdentity:SetAttribute(RUNTIME_TOPOLOGY_ATTRIBUTE, encoded)
-	end
+	writeSessionState(RUNTIME_TOPOLOGY_NAME, topology)
 end
 --[[
 	*
@@ -10717,7 +11318,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="31">
+      <Item class="ModuleScript" referent="34">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10747,7 +11348,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="32">
+      <Item class="ModuleScript" referent="35">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10815,7 +11416,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="33">
+      <Item class="ModuleScript" referent="36">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11051,7 +11652,357 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="34">
+      <Item class="ModuleScript" referent="37">
+        <Properties>
+          <string name="Name">ScriptEdits</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+-- Exact-text script edits resolved against one source snapshot, so several
+-- replacements either all apply or none do. Kept free of Studio services so
+-- the planning logic can be exercised outside Studio.
+local FNV_OFFSET_BASIS = 2166136261
+local UINT32_MODULUS = 4294967296
+local BYTE_CHUNK = 4096
+local DIFF_CHAR_BUDGET = 20000
+--[[
+	*
+	 * Content revision of the exact script text: byte length plus FNV-1a 32.
+	 * It is an optimistic-concurrency token, not a security hash.
+	 
+]]
+local function sourceRevision(source)
+	local length = #source
+	local hash = FNV_OFFSET_BASIS
+	do
+		local chunkStart = 1
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				chunkStart += BYTE_CHUNK
+			else
+				_shouldIncrement = true
+			end
+			if not (chunkStart <= length) then
+				break
+			end
+			local _array = {}
+			local _length = #_array
+			local _array_1 = { string.byte(source, chunkStart, math.min(chunkStart + BYTE_CHUNK - 1, length)) }
+			table.move(_array_1, 1, #_array_1, _length + 1, _array)
+			local bytes = _array
+			for _, byte in bytes do
+				hash = bit32.bxor(hash, byte)
+				-- hash * 16777619 mod 2^32. The FNV prime is 2^24 + 403; splitting the
+				-- product keeps every intermediate below 2^53, where doubles stay exact.
+				hash = (bit32.lshift(hash, 24) + hash * 403) % UINT32_MODULUS
+			end
+		end
+	end
+	return `{length}:{hash}`
+end
+-- 1-based byte offset at which each line starts. A trailing newline yields a
+-- final empty line, which is where an anchored insertion at EOF lands.
+local function lineStarts(source)
+	local starts = { 1 }
+	local searchFrom = 1
+	while true do
+		local newline = string.find(source, "\n", searchFrom, true)
+		if newline == nil then
+			break
+		end
+		local _arg0 = newline + 1
+		table.insert(starts, _arg0)
+		searchFrom = newline + 1
+	end
+	return starts
+end
+-- Line containing a byte offset; a newline belongs to the line it ends.
+local function lineAt(starts, offset)
+	local low = 0
+	local high = #starts - 1
+	while low < high do
+		local middle = math.floor((low + high + 1) / 2)
+		if starts[middle + 1] <= offset then
+			low = middle
+		else
+			high = middle - 1
+		end
+	end
+	return low + 1
+end
+-- Byte offset just past the line's terminator, or past the end of the source.
+local function lineEnd(starts, source, line)
+	return if line < #starts then starts[line + 1] else #source + 1
+end
+local function locateEdit(source, starts, edit, label)
+	local searchLength = #edit.oldString
+	if edit.startLine ~= nil then
+		if edit.startLine < 1 or edit.startLine % 1 ~= 0 then
+			return `{label}line must be a positive whole number (got {edit.startLine}).`
+		end
+		if edit.startLine > #starts then
+			return `{label}line {edit.startLine} is past the end of the script.`
+		end
+		local start = starts[edit.startLine]
+		if string.sub(source, start, start + searchLength - 1) ~= edit.oldString then
+			return `{label}old_string does not match at line {edit.startLine}. Use get_script_source to verify the exact text at that line.`
+		end
+		return start
+	end
+	if searchLength == 0 then
+		return `{label}old_string is empty; pass line_range to insert at the start of a line.`
+	end
+	local first = string.find(source, edit.oldString, 1, true)
+	if first == nil then
+		return `{label}old_string not found in script. If old_string contains repeated patterns (e.g. closing braces), pass line_range to anchor the edit.`
+	end
+	local second = string.find(source, edit.oldString, first + searchLength, true)
+	if second ~= nil then
+		return `{label}old_string matches multiple locations (lines {lineAt(starts, first)} and {lineAt(starts, second)}). Provide more surrounding context, or pass line_range to anchor the edit.`
+	end
+	return first
+end
+-- Source text in [regionStart, regionEnd) with every edit in resolved[from, to) applied.
+local function applyWithin(source, resolved, from, to, regionStart, regionEnd)
+	local parts = {}
+	local cursor = regionStart
+	do
+		local index = from
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				index += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (index < to) then
+				break
+			end
+			local edit = resolved[index + 1]
+			local _arg0 = string.sub(source, cursor, edit.start - 1)
+			table.insert(parts, _arg0)
+			local _newString = edit.newString
+			table.insert(parts, _newString)
+			cursor = edit.finish
+		end
+	end
+	local _arg0 = string.sub(source, cursor, regionEnd - 1)
+	table.insert(parts, _arg0)
+	return table.concat(parts, "")
+end
+local NO_FINAL_NEWLINE = "\"
+-- Lines of a diff region. A last line without its newline only occurs at the
+-- end of the file; it is flagged so that adding or removing that newline still
+-- differs, as in a unified diff.
+local function textLines(text)
+	if text == "" then
+		return {
+			lines = {},
+			missingFinalNewline = false,
+		}
+	end
+	local lines = string.split(text, "\n")
+	local missingFinalNewline = string.sub(text, -1) ~= "\n"
+	if not missingFinalNewline then
+		lines[#lines] = nil
+	end
+	return {
+		lines = lines,
+		missingFinalNewline = missingFinalNewline,
+	}
+end
+local function sameLine(a, aIndex, b, bIndex)
+	return a.lines[aIndex + 1] == b.lines[bIndex + 1] and (a.missingFinalNewline and aIndex == #a.lines - 1) == (b.missingFinalNewline and bIndex == #b.lines - 1)
+end
+local function pushHunkLines(hunk, text, from, count, prefix)
+	do
+		local index = from
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				index += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (index < from + count) then
+				break
+			end
+			local _hunk = hunk
+			local _arg0 = `{prefix}{text.lines[index + 1]}`
+			table.insert(_hunk, _arg0)
+			if text.missingFinalNewline and index == #text.lines - 1 then
+				table.insert(hunk, NO_FINAL_NEWLINE)
+			end
+		end
+	end
+end
+local function hunkStart(line, count)
+	return if count == 0 then line - 1 else line
+end
+local function editFirstLine(starts, edit)
+	return lineAt(starts, edit.start)
+end
+local function editLastLine(starts, edit)
+	return lineAt(starts, if edit.finish > edit.start then edit.finish - 1 else edit.start)
+end
+-- Unified diff of whole changed lines, without context lines. Edits that share
+-- a line become one hunk; lines the edit left unchanged are trimmed away.
+local function buildDiff(source, starts, resolved)
+	local output = {}
+	local outputSize = 0
+	local truncated = false
+	local lineDelta = 0
+	local groupStart = 0
+	while groupStart < #resolved and not truncated do
+		local firstLine = editFirstLine(starts, resolved[groupStart + 1])
+		local lastLine = editLastLine(starts, resolved[groupStart + 1])
+		local groupEnd = groupStart + 1
+		local oldText
+		local newText
+		while true do
+			while groupEnd < #resolved and editFirstLine(starts, resolved[groupEnd + 1]) <= lastLine do
+				lastLine = math.max(lastLine, editLastLine(starts, resolved[groupEnd + 1]))
+				groupEnd += 1
+			end
+			local regionStart = starts[firstLine]
+			local regionEnd = lineEnd(starts, source, lastLine)
+			oldText = string.sub(source, regionStart, regionEnd - 1)
+			newText = applyWithin(source, resolved, groupStart, groupEnd, regionStart, regionEnd)
+			-- A replacement that drops the region's final newline joins the next
+			-- line onto it, so that line belongs in the hunk too.
+			local nextLineHasText = lastLine < #starts and starts[lastLine + 1] <= #source
+			if nextLineHasText and string.sub(oldText, -1) == "\n" and string.sub(newText, -1) ~= "\n" then
+				lastLine += 1
+				continue
+			end
+			break
+		end
+		local oldRegion = textLines(oldText)
+		local newRegion = textLines(newText)
+		local oldSize = #oldRegion.lines
+		local newSize = #newRegion.lines
+		local prefix = 0
+		while prefix < oldSize and prefix < newSize and sameLine(oldRegion, prefix, newRegion, prefix) do
+			prefix += 1
+		end
+		local suffix = 0
+		while suffix < oldSize - prefix and suffix < newSize - prefix and sameLine(oldRegion, oldSize - 1 - suffix, newRegion, newSize - 1 - suffix) do
+			suffix += 1
+		end
+		local oldCount = oldSize - prefix - suffix
+		local newCount = newSize - prefix - suffix
+		if oldCount > 0 or newCount > 0 then
+			local oldStart = firstLine + prefix
+			local newStart = oldStart + lineDelta
+			local hunk = { `@@ -{hunkStart(oldStart, oldCount)},{oldCount} +{hunkStart(newStart, newCount)},{newCount} @@` }
+			pushHunkLines(hunk, oldRegion, prefix, oldCount, "-")
+			pushHunkLines(hunk, newRegion, prefix, newCount, "+")
+			for _, line in hunk do
+				if outputSize + #line + 1 > DIFF_CHAR_BUDGET then
+					truncated = true
+					break
+				end
+				table.insert(output, line)
+				outputSize += #line + 1
+			end
+		end
+		lineDelta += newSize - oldSize
+		groupStart = groupEnd
+	end
+	return {
+		diff = table.concat(output, "\n"),
+		truncated = truncated,
+	}
+end
+--[[
+	*
+	 * Resolves every edit against the same source, rejects overlaps, and builds
+	 * the edited source in memory. Nothing is written: the caller applies
+	 * newSource in one compare-and-set write, so a bad edit changes nothing.
+	 * line_range anchors refer to the source as it was before any edit.
+	 
+]]
+local function planScriptEdits(source, edits, includeDiff)
+	if #edits == 0 then
+		return {
+			ok = false,
+			error = "At least one edit is required.",
+		}
+	end
+	local starts = lineStarts(source)
+	local resolved = {}
+	for index = 0, #edits - 1 do
+		local edit = edits[index + 1]
+		local label = if #edits > 1 then `edits[{index}]: ` else ""
+		local located = locateEdit(source, starts, edit, label)
+		if type(located) == "string" then
+			return {
+				ok = false,
+				error = located,
+			}
+		end
+		local _arg0 = {
+			index = index,
+			start = located,
+			finish = located + #edit.oldString,
+			newString = edit.newString,
+		}
+		table.insert(resolved, _arg0)
+		-- Insertion sort by position; k is small and ties keep request order.
+		do
+			local at = #resolved - 1
+			local _shouldIncrement = false
+			while true do
+				if _shouldIncrement then
+					at -= 1
+				else
+					_shouldIncrement = true
+				end
+				if not (at > 0 and resolved[at].start > resolved[at + 1].start) then
+					break
+				end
+				local swap = resolved[at]
+				resolved[at] = resolved[at + 1]
+				resolved[at + 1] = swap
+			end
+		end
+	end
+	for at = 1, #resolved - 1 do
+		local previous = resolved[at]
+		local current = resolved[at + 1]
+		if current.start < previous.finish or current.start == previous.start then
+			local first = math.min(previous.index, current.index)
+			local second = math.max(previous.index, current.index)
+			return {
+				ok = false,
+				error = `edits[{first}] and edits[{second}] overlap at line {lineAt(starts, current.start)}; combine them into one edit.`,
+			}
+		end
+	end
+	local newSource = applyWithin(source, resolved, 0, #resolved, 1, #source + 1)
+	if not includeDiff then
+		return {
+			ok = true,
+			newSource = newSource,
+			diff = "",
+			diffTruncated = false,
+		}
+	end
+	local built = buildDiff(source, starts, resolved)
+	return {
+		ok = true,
+		newSource = newSource,
+		diff = built.diff,
+		diffTruncated = built.truncated,
+	}
+end
+return {
+	sourceRevision = sourceRevision,
+	planScriptEdits = planScriptEdits,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="38">
         <Properties>
           <string name="Name">ScriptSearch</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11240,6 +12191,18 @@ local function createScriptSearch(corpus)
 				error = `Path not found: {searchPath}`,
 			}
 		end
+		local _self = corpus
+		local _result_1 = _self.createAmbiguityChecker
+		if _result_1 ~= nil then
+			_result_1 = _result_1(_self)
+		end
+		local _condition_6 = _result_1
+		if _condition_6 == nil then
+			_condition_6 = (function()
+				return false
+			end)
+		end
+		local isAmbiguous = _condition_6
 		local searchPattern = if caseSensitive then pattern else string.lower(pattern)
 		local patternAlternatives = if usePattern then splitLuaAlternation(searchPattern) else nil
 		local results = {}
@@ -11251,10 +12214,10 @@ local function createScriptSearch(corpus)
 			control:checkpoint()
 			-- ▼ Array.pop ▼
 			local _length = #stack
-			local _result_1 = stack[_length]
+			local _result_2 = stack[_length]
 			stack[_length] = nil
 			-- ▲ Array.pop ▲
-			local instance = _result_1
+			local instance = _result_2
 			local snapshot = corpus:readScript(instance, classFilter)
 			if snapshot ~= nil and (classFilter == nil or snapshot.className == classFilter) then
 				scriptsSearched += 1
@@ -11339,6 +12302,9 @@ local function createScriptSearch(corpus)
 					if snapshot.enabled ~= nil then
 						scriptResult.enabled = snapshot.enabled
 					end
+					if isAmbiguous(instance) then
+						scriptResult.ambiguous = true
+					end
 					table.insert(results, scriptResult)
 				end
 			end
@@ -11378,7 +12344,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="35">
+      <Item class="ModuleScript" referent="39">
         <Properties>
           <string name="Name">ServerUrlSettings</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11492,11 +12458,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="36">
+      <Item class="ModuleScript" referent="40">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.2.0"
+local CURRENT_VERSION = "3.3.0"
 local PLUGIN_VARIANT = "inspector"
 local BASE_PORT = 58741
 local SENSITIVE_DIAGNOSTIC_TERMS = { "token", "authorization", "bearer", "password", "cookie", "secret" }
@@ -11634,7 +12600,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="37">
+      <Item class="ModuleScript" referent="41">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11920,7 +12886,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="38">
+      <Item class="ModuleScript" referent="42">
         <Properties>
           <string name="Name">StudioWebSocket</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11943,6 +12909,10 @@ local MAX_PENDING_RESPONSE_BYTES = 64 * 1024 * 1024
 local RESERVED_ERROR_BYTES = 4096
 -- The bridge admits 128 UTF-16 code units; each can require three UTF-8 bytes.
 local MAX_REQUEST_ID_BYTES = 128 * 3
+-- Upper bound on BindToClose waiting for the server to close the socket after
+-- the unregister frame; it normally closes within milliseconds.
+local SHUTDOWN_UNREGISTER_WAIT_SECONDS = 2
+local SHUTDOWN_UNREGISTER_POLL_SECONDS = 0.05
 local options
 local active = false
 local shutdownSuspended = false
@@ -12985,8 +13955,13 @@ local function refresh()
 	refreshRequested = true
 	flushRefresh()
 end
--- EndTest may tear down this VM without an Unloading callback. Release the
--- native socket before yielding to unregister; a failed EndTest can resume.
+-- EndTest may tear down this VM without an Unloading callback, and BindToClose
+-- waits for this function. It unregisters on the socket itself: Studio runs at
+-- most five plugin HTTP requests at a time across the whole process, with no
+-- time limit, so a /disconnect queued behind five that never finish held
+-- shutdown until Studio's 30 s deadline. Closing right after Send can drop the
+-- frame, so it waits briefly for the server to close the socket first. A
+-- failed EndTest can resume and registers again.
 local function suspendForShutdown()
 	local currentOptions = options
 	if not active or currentOptions == nil then
@@ -12998,9 +13973,34 @@ local function suspendForShutdown()
 	cancelTransportWork()
 	refreshRequested = false
 	reconnectAttempt = 0
+	local client = socketClient
+	local unregistered = false
+	if client ~= nil and socketOpen then
+		local serverClosed = false
+		local closedConnection = client.Closed:Connect(function()
+			serverClosed = true
+		end)
+		local sent = pcall(function()
+			return client:Send(HttpService:JSONEncode({
+				kind = "disconnect",
+			}))
+		end)
+		unregistered = sent
+		local deadline = os.clock() + SHUTDOWN_UNREGISTER_WAIT_SECONDS
+		while sent and not serverClosed and os.clock() < deadline do
+			task.wait(SHUTDOWN_UNREGISTER_POLL_SECONDS)
+		end
+		closedConnection:Disconnect()
+	end
 	closeCurrentSocket()
 	cachedReady = nil
-	disconnectSession(currentOptions)
+	-- Without an open socket, unregister over HTTP on another thread rather
+	-- than wait; the server also drops a peer whose socket stays closed.
+	if not unregistered then
+		task.spawn(function()
+			return disconnectSession(currentOptions)
+		end)
+	end
 end
 local function resumeAfterShutdownFailure()
 	if not shutdownSuspended or options == nil then
@@ -13044,7 +14044,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="39">
+      <Item class="ModuleScript" referent="43">
         <Properties>
           <string name="Name">TopologyId</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -13089,7 +14089,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="40">
+      <Item class="ModuleScript" referent="44">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -13614,10 +14614,12 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="41">
+      <Item class="ModuleScript" referent="45">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+local TS = require(script.Parent.Parent.include.RuntimeLib)
+local PathAmbiguity = TS.import(script, script.Parent, "PathAmbiguity")
 local ScriptEditorService = game:GetService("ScriptEditorService")
 local LUAU_KEYWORDS = {
 	["and"] = true,
@@ -13832,16 +14834,17 @@ local function parseInstancePath(path)
 	end
 	return parts
 end
+local function getService(segment)
+	local ok, service = pcall(function()
+		return game:GetService(segment)
+	end)
+	return if ok and service then service else nil
+end
+local function isRootService(instance)
+	return instance.Parent == game and getService(instance.ClassName) == instance
+end
 local function getRootSegment(instance)
-	if instance.Parent == game then
-		local ok, service = pcall(function()
-			return game:GetService(instance.ClassName)
-		end)
-		if ok and service == instance then
-			return instance.ClassName
-		end
-	end
-	return instance.Name
+	return if isRootService(instance) then instance.ClassName else instance.Name
 end
 local function getInstancePath(instance)
 	if not instance or instance == game then
@@ -13865,13 +14868,7 @@ local function getInstancePath(instance)
 	return path
 end
 local function getRootInstance(segment)
-	local ok, service = pcall(function()
-		return game:GetService(segment)
-	end)
-	if ok and service then
-		return service
-	end
-	return game:FindFirstChild(segment)
+	return getService(segment) or game:FindFirstChild(segment)
 end
 local function getInstanceByPath(path)
 	local parts = parseInstancePath(path)
@@ -13891,6 +14888,36 @@ local function getInstanceByPath(path)
 	end
 	return current
 end
+local instancePathTree = {
+	root = game,
+	getParent = function(instance)
+		return instance.Parent
+	end,
+	getChildren = function(instance)
+		return instance:GetChildren()
+	end,
+	getName = function(instance)
+		return instance.Name
+	end,
+	getService = getService,
+	isRootService = isRootService,
+	getPath = getInstancePath,
+}
+-- Like getInstanceByPath, but also reports the first segment that names more
+-- than one sibling. Costs one child scan per segment. PathGuard applies it to
+-- every declared request path before the handler runs.
+local function resolveInstancePath(path)
+	local parts = parseInstancePath(path)
+	if parts == nil then
+		return {}
+	end
+	return PathAmbiguity.resolvePath(instancePathTree, parts)
+end
+-- Returns a per-request predicate that is true when getInstancePath(instance)
+-- does not identify exactly that instance.
+local function createPathAmbiguityChecker()
+	return PathAmbiguity.createAmbiguityChecker(instancePathTree)
+end
 local function splitLines(source)
 	local _condition = source
 	if _condition == nil then
@@ -14445,6 +15472,8 @@ return {
 	safeCall = safeCall,
 	getInstancePath = getInstancePath,
 	getInstanceByPath = getInstanceByPath,
+	resolveInstancePath = resolveInstancePath,
+	createPathAmbiguityChecker = createPathAmbiguityChecker,
 	splitLines = splitLines,
 	joinLines = joinLines,
 	readScriptSource = readScriptSource,
@@ -14457,11 +15486,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="46">
+    <Item class="Folder" referent="50">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="42">
+      <Item class="ModuleScript" referent="46">
         <Properties>
           <string name="Name">LibMP</string>
           <string name="Source"><![CDATA[-- =============================================================================
@@ -170845,7 +171874,7 @@ return LibMP
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="43">
+      <Item class="ModuleScript" referent="47">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -172919,7 +173948,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="44">
+      <Item class="ModuleScript" referent="48">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -173186,15 +174215,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="47">
+    <Item class="Folder" referent="51">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="48">
+      <Item class="Folder" referent="52">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="45">
+      <Item class="ModuleScript" referent="49">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {