@chrrxs/robloxstudio-mcp-inspector 3.1.2 → 3.1.4

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -278,6 +278,326 @@ return {
         </Properties>
       </Item>
       <Item class="ModuleScript" referent="3">
+        <Properties>
+          <string name="Name">CaptureTransfer</string>
+          <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
+-- Private ClientBroker transport. Only metadata and <=1 MiB data chunks cross
+-- InvokeClient; callers still receive the original capture-studio response.
+local HttpService = game:GetService("HttpService")
+local READ_ENDPOINT = "/__mcp/capture-studio/read"
+local RELEASE_ENDPOINT = "/__mcp/capture-studio/release"
+local CHUNK_BYTES = 1024 * 1024
+local MAX_TRANSFER_BYTES = 64 * 1024 * 1024
+local MAX_TRANSFERS = 2
+local TRANSFER_TTL_SECONDS = 60
+local transfers = {}
+local function integer(value, min, max)
+	local _value = value
+	local _condition = type(_value) == "number"
+	if _condition then
+		_condition = value >= min and value <= max and value == math.floor(value)
+	end
+	return _condition
+end
+local function validId(value)
+	local _value = value
+	local _condition = type(_value) == "string"
+	if _condition then
+		_condition = #value > 0 and #value <= 64
+	end
+	return _condition
+end
+local function metadata(value)
+	local _value = value
+	if not (type(_value) == "table") then
+		return nil
+	end
+	local fields = value
+	if fields.success ~= true or (fields.encoding ~= "png" and fields.encoding ~= "rgba8") or fields.source ~= "StudioCaptureService" or not integer(fields.width, 1, 65536) or not integer(fields.height, 1, 65536) or not integer(fields.nativeWidth, 1, 65536) or not integer(fields.nativeHeight, 1, 65536) then
+		return nil
+	end
+	return {
+		success = true,
+		encoding = fields.encoding,
+		source = fields.source,
+		width = fields.width,
+		height = fields.height,
+		nativeWidth = fields.nativeWidth,
+		nativeHeight = fields.nativeHeight,
+	}
+end
+local function fail(message)
+	return {
+		success = false,
+		error = `Capture transfer: {message}`,
+	}
+end
+local function discard(id)
+	local _id = id
+	local transfer = transfers[_id]
+	if transfer == nil then
+		return nil
+	end
+	local _id_1 = id
+	transfers[_id_1] = nil
+	if transfer.expiryThread ~= nil then
+		task.cancel(transfer.expiryThread)
+	end
+end
+local function prune()
+	local now = os.clock()
+	for id, transfer in transfers do
+		if now >= transfer.expiresAt then
+			discard(id)
+		end
+	end
+end
+local function release(data)
+	if not validId(data.transferId) then
+		return fail("invalid transfer ID")
+	end
+	discard(data.transferId)
+	-- Idempotent release also negotiates chunk support before capture starts.
+	return {
+		success = true,
+		chunkBytes = CHUNK_BYTES,
+	}
+end
+local validSize
+local function begin(data, capture)
+	prune()
+	local id = data.transferId
+	-- An older server cannot consume chunk descriptors. Let it use legacy
+	-- capture rather than returning an unsafe inline image or a hard error.
+	if id == nil then
+		return {
+			unavailable = "Client capture requires bounded transfer support",
+		}
+	end
+	if not validId(id) then
+		return fail("invalid transfer ID")
+	end
+	if transfers[id] ~= nil then
+		return fail("duplicate transfer ID")
+	end
+	-- Reserve before capture yields: concurrent captures cannot over-admit or
+	-- evict each other's data. Retained strings are capped at 2 * 64 MiB.
+	-- ▼ ReadonlyMap.size ▼
+	local _size = 0
+	for _ in transfers do
+		_size += 1
+	end
+	-- ▲ ReadonlyMap.size ▲
+	if _size >= MAX_TRANSFERS then
+		return fail("two captures are already in flight; release or await them first")
+	end
+	local transfer = {
+		offset = 0,
+		expiresAt = os.clock() + TRANSFER_TTL_SECONDS,
+	}
+	transfers[id] = transfer
+	-- Capture only the ID, not the large payload, in the expiry closure.
+	transfer.expiryThread = task.delay(TRANSFER_TTL_SECONDS, function()
+		local current = transfers[id]
+		if current ~= nil and os.clock() >= current.expiresAt then
+			current.expiryThread = nil
+			discard(id)
+		end
+	end)
+	local ok, result = pcall(capture)
+	if not ok then
+		if transfers[id] == transfer then
+			discard(id)
+		end
+		return fail(`capture failed: {tostring(result)}`)
+	end
+	if transfers[id] ~= transfer or os.clock() >= transfer.expiresAt then
+		if transfers[id] == transfer then
+			discard(id)
+		end
+		return fail("capture expired before it completed")
+	end
+	local info = metadata(result)
+	if info == nil then
+		discard(id)
+		-- Unavailability must reach core unchanged to preserve legacy fallback.
+		if type(result) == "table" then
+			local fields = result
+			local _unavailable = fields.unavailable
+			if type(_unavailable) == "string" then
+				return {
+					unavailable = string.sub(fields.unavailable, 1, 4096),
+				}
+			end
+			local _error = fields.error
+			if type(_error) == "string" then
+				return fail(string.sub(fields.error, 1, 4096))
+			end
+		end
+		return fail("invalid capture response")
+	end
+	local fields = result
+	local pixels = fields.data
+	if not (type(pixels) == "string") or not validSize(#pixels, info) then
+		discard(id)
+		return fail("invalid or oversized capture data")
+	end
+	transfer.data = pixels
+	return {
+		transferId = id,
+		totalBytes = #pixels,
+		chunkBytes = CHUNK_BYTES,
+		metadata = info,
+	}
+end
+function validSize(size, info)
+	if not integer(size, 4, MAX_TRANSFER_BYTES) or size % 4 ~= 0 then
+		return false
+	end
+	return info.encoding ~= "rgba8" or size == math.ceil(info.width * info.height * 4 / 3) * 4
+end
+local function read(data)
+	prune()
+	local id = data.transferId
+	if not validId(id) then
+		return fail("invalid transfer ID")
+	end
+	local transfer = transfers[id]
+	if transfer == nil then
+		return fail("unknown or expired transfer")
+	end
+	local pixels = transfer.data
+	local offset = data.offset
+	local length = data.length
+	if pixels == nil or not integer(offset, 0, #pixels - 1) or not integer(length, 1, CHUNK_BYTES) or offset ~= transfer.offset or length ~= math.min(CHUNK_BYTES, #pixels - offset) then
+		discard(id)
+		return fail("invalid chunk offset or length")
+	end
+	local _arg0 = offset + 1
+	local _arg1 = offset + length
+	local chunk = string.sub(pixels, _arg0, _arg1)
+	transfer.offset += length
+	-- Last read releases immediately, even if the receiver disappears before
+	-- its explicit release. Explicit release is idempotent for error paths.
+	if transfer.offset == #pixels then
+		discard(id)
+	end
+	return {
+		transferId = id,
+		offset = offset,
+		data = chunk,
+	}
+end
+local function receive(invoke, data)
+	local id = HttpService:GenerateGUID(false)
+	local ok, result = pcall(function()
+		-- Older clients return inline data and may disconnect on a large capture.
+		-- Probe a harmless release of our fresh ID before requesting any pixels.
+		local probe = invoke(RELEASE_ENDPOINT, {
+			transferId = id,
+		})
+		if not (type(probe) == "table") then
+			return {
+				unavailable = "Client capture lacks bounded transfer support",
+			}
+		end
+		local capability = probe
+		if capability.success ~= true or capability.chunkBytes ~= CHUNK_BYTES then
+			return {
+				unavailable = "Client capture lacks bounded transfer support",
+			}
+		end
+		local response = invoke("/api/capture-studio", {
+			encoding = data.encoding,
+			transferId = id,
+		})
+		if not (type(response) == "table") then
+			error("invalid transfer response")
+		end
+		local fields = response
+		local _unavailable = fields.unavailable
+		if type(_unavailable) == "string" then
+			return {
+				unavailable = string.sub(fields.unavailable, 1, 4096),
+			}
+		end
+		local _error = fields.error
+		if type(_error) == "string" then
+			error(string.sub(fields.error, 1, 4096))
+		end
+		local info = metadata(fields.metadata)
+		if info == nil or fields.transferId ~= id or fields.chunkBytes ~= CHUNK_BYTES or not validSize(fields.totalBytes, info) then
+			error("invalid transfer metadata or size")
+		end
+		local size = fields.totalBytes
+		local chunks = {}
+		local offset = 0
+		while offset < size do
+			local length = math.min(CHUNK_BYTES, size - offset)
+			local response = invoke(READ_ENDPOINT, {
+				transferId = id,
+				offset = offset,
+				length = length,
+			})
+			if not (type(response) == "table") then
+				error("invalid chunk response")
+			end
+			local chunk = response
+			local _error_1 = chunk.error
+			if type(_error_1) == "string" then
+				error(string.sub(chunk.error, 1, 4096))
+			end
+			local _condition = chunk.transferId ~= id or chunk.offset ~= offset
+			if not _condition then
+				local _data = chunk.data
+				_condition = not (type(_data) == "string")
+				if not _condition then
+					_condition = #chunk.data ~= length
+				end
+			end
+			if _condition then
+				error("chunk ID, offset or length mismatch")
+			end
+			local _data = chunk.data
+			table.insert(chunks, _data)
+			offset += length
+		end
+		return {
+			success = true,
+			encoding = info.encoding,
+			source = info.source,
+			width = info.width,
+			height = info.height,
+			nativeWidth = info.nativeWidth,
+			nativeHeight = info.nativeHeight,
+			data = table.concat(chunks, ""),
+		}
+	end)
+	-- The final read already frees successful transfers. Cleanup is best-effort:
+	-- it must not mask an unavailable signal from an older client or a completed
+	-- image. Failed partial transfers also have the bounded expiry above.
+	pcall(function()
+		return invoke(RELEASE_ENDPOINT, {
+			transferId = id,
+		})
+	end)
+	if not ok then
+		return fail(tostring(result))
+	end
+	return result
+end
+return {
+	READ_ENDPOINT = READ_ENDPOINT,
+	RELEASE_ENDPOINT = RELEASE_ENDPOINT,
+	begin = begin,
+	read = read,
+	release = release,
+	receive = receive,
+}
+]]></string>
+        </Properties>
+      </Item>
+      <Item class="ModuleScript" referent="4">
         <Properties>
           <string name="Name">ClientBroker</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -291,6 +611,7 @@ local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
 local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
 local CaptureHandlers = TS.import(script, script.Parent, "handlers", "CaptureHandlers")
+local CaptureTransfer = TS.import(script, script.Parent, "CaptureTransfer")
 local InputHandlers = TS.import(script, script.Parent, "handlers", "InputHandlers")
 local MetadataHandlers = TS.import(script, script.Parent, "handlers", "MetadataHandlers")
 local EvalRuntimeHandlers = TS.import(script, script.Parent, "handlers", "EvalRuntimeHandlers")
@@ -327,6 +648,7 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/multiplayer-test-state"] = true,
 	["/api/multiplayer-test-leave-client"] = true,
 	["/api/capture-begin"] = true,
+	["/api/capture-studio"] = true,
 	["/api/simulate-mouse-input"] = true,
 	["/api/simulate-keyboard-input"] = true,
 	["/api/focus-viewport"] = true,
@@ -528,6 +850,17 @@ local function setupClientBroker(attempt)
 		if payload and payload.endpoint == "/api/capture-begin" then
 			return CaptureHandlers.captureBegin()
 		end
+		if payload and payload.endpoint == "/api/capture-studio" then
+			return CaptureTransfer.begin(payload.data or {}, function()
+				return CaptureHandlers.captureStudio(payload.data or {})
+			end)
+		end
+		if payload and payload.endpoint == CaptureTransfer.READ_ENDPOINT then
+			return CaptureTransfer.read(payload.data or {})
+		end
+		if payload and payload.endpoint == CaptureTransfer.RELEASE_ENDPOINT then
+			return CaptureTransfer.release(payload.data or {})
+		end
 		if payload and payload.endpoint == "/api/simulate-mouse-input" then
 			return InputHandlers.simulateMouseInput(payload.data or {})
 		end
@@ -840,6 +1173,14 @@ local function dispatchClientRequest(peerId, target, endpoint, data)
 			error = `Client-proxy does not forward {endpoint}. Allowed: {table.concat(allowed, ", ")}.`,
 		}
 	end
+	if endpoint == "/api/capture-studio" then
+		return CaptureTransfer.receive(function(captureEndpoint, captureData)
+			return entry.remote:InvokeClient(entry.player, {
+				endpoint = captureEndpoint,
+				data = captureData,
+			})
+		end, data or {})
+	end
 	local envelope = {
 		endpoint = endpoint,
 		data = data,
@@ -920,7 +1261,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="4">
+      <Item class="ModuleScript" referent="5">
         <Properties>
           <string name="Name">Communication</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -988,6 +1329,7 @@ local routeMap = {
 	["/api/insert-asset"] = AssetHandlers.insertAsset,
 	["/api/preview-asset"] = AssetHandlers.previewAsset,
 	["/api/capture-screenshot"] = CaptureHandlers.captureScreenshot,
+	["/api/capture-studio"] = CaptureHandlers.captureStudio,
 	["/api/capture-begin"] = CaptureHandlers.captureBegin,
 	["/api/capture-read"] = CaptureHandlers.captureRead,
 	["/api/simulate-mouse-input"] = InputHandlers.simulateMouseInput,
@@ -1276,7 +1618,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="5">
+      <Item class="ModuleScript" referent="6">
         <Properties>
           <string name="Name">CooperativeJobRunner</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -1351,7 +1693,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="6">
+      <Item class="ModuleScript" referent="7">
         <Properties>
           <string name="Name">EvalBridges</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -1472,9 +1814,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.1.2" is replaced with the package version at package time
+	-- "3.1.4" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.1.2`
+	return `{tostring(h)}-3.1.4`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -1627,11 +1969,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="Folder" referent="7">
+      <Item class="Folder" referent="8">
         <Properties>
           <string name="Name">handlers</string>
         </Properties>
-        <Item class="ModuleScript" referent="8">
+        <Item class="ModuleScript" referent="9">
           <Properties>
             <string name="Name">AssetHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -2072,7 +2414,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="9">
+        <Item class="ModuleScript" referent="10">
           <Properties>
             <string name="Name">BreakpointHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -2579,7 +2921,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="10">
+        <Item class="ModuleScript" referent="11">
           <Properties>
             <string name="Name">CaptureHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -2587,11 +2929,27 @@ local TS = require(script.Parent.Parent.Parent.include.RuntimeLib)
 local RenderMonitor = TS.import(script, script.Parent.Parent, "RenderMonitor")
 local CaptureService = game:GetService("CaptureService")
 local AssetService = game:GetService("AssetService")
+local Workspace = game:GetService("Workspace")
 local MAX_TILE_SIZE = 1024
 local MAX_RAW_PIXEL_BYTES = 36 * 1024 * 1024
 local MAX_CREATED_IMAGE_DIM = 2048
 local BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 local PAD_BYTE = (string.byte("="))
+-- StudioCaptureService (Studio-only, PluginSecurity) is the fast path: it hands
+-- back the framebuffer directly, so it needs neither CaptureService's
+-- asynchronous callback nor an EditableImage round-trip — and it captures at
+-- ViewportSize, which is exactly the coordinate space simulate_mouse_input
+-- expects. It is gated behind Studio FFlags and is missing from @rbxts/types,
+-- hence the local structural declarations below.
+-- Unchecked cast, single reason: these enums exist in Studio but are missing
+-- from @rbxts/types, so the global Enum table has to be read dynamically.
+local ENUM_TABLE = Enum
+local STUDIO_CAPTURE_FORMATS = ENUM_TABLE.StudioCaptureScreenshotFormat
+-- Measured on a 1980x1032 viewport: RGBA8 completes in ~0.16s and PNG in ~1s.
+-- A capture that is still Pending well past that never completes (it happens
+-- while a playtest owns the renderer), so we stop waiting and let the caller
+-- fall back instead of stalling the tool call.
+local STUDIO_CAPTURE_TIMEOUT = 3
 local B64 = {}
 for i = 0, 63 do
 	B64[i + 1] = (string.byte(BASE64_CHARS, i + 1))
@@ -2789,6 +3147,124 @@ local function readContentToBase64(contentId)
 		nativeHeight = nativeH,
 	}
 end
+local cachedStudioService
+local function getStudioCaptureService()
+	if cachedStudioService ~= nil then
+		return cachedStudioService
+	end
+	-- Unchecked cast, single reason: StudioCaptureService is absent from
+	-- @rbxts/types, so GetService cannot be called through the typed overload.
+	local dynamicGame = game
+	local ok, service = pcall(function()
+		return dynamicGame:GetService("StudioCaptureService")
+	end)
+	if not ok or service == nil then
+		return nil
+	end
+	cachedStudioService = service
+	return cachedStudioService
+end
+-- Captures through StudioCaptureService. Returns undefined when the service
+-- cannot capture right now (missing FFlag, permission not granted, or this
+-- DataModel is not the active one) so the caller can fall back to the
+-- CaptureService + EditableImage path.
+local function doStudioCapture(wantPng)
+	if STUDIO_CAPTURE_FORMATS == nil then
+		return nil
+	end
+	local service = getStudioCaptureService()
+	if service == nil then
+		return nil
+	end
+	local canOk, can = pcall(function()
+		return service:CanCaptureScreenshot()
+	end)
+	if not canOk or can ~= true then
+		return nil
+	end
+	local camera = Workspace.CurrentCamera
+	if camera == nil then
+		return nil
+	end
+	local viewport = camera.ViewportSize
+	local nativeW = math.max(1, math.floor(viewport.X))
+	local nativeH = math.max(1, math.floor(viewport.Y))
+	local w = nativeW
+	local h = nativeH
+	-- Raw RGBA rides back base64-encoded, so an oversized viewport is
+	-- downscaled by the engine during the capture itself — no second pass.
+	if not wantPng and nativeW * nativeH * 4 > MAX_RAW_PIXEL_BYTES then
+		local scale = math.sqrt(MAX_RAW_PIXEL_BYTES / (nativeW * nativeH * 4))
+		w = math.max(1, math.floor(nativeW * scale))
+		h = math.max(1, math.floor(nativeH * scale))
+	end
+	-- CaptureSize is a framebuffer crop, not the logical viewport size. At
+	-- fractional display scaling it cuts off the right/bottom of the frame.
+	local options = {
+		OutputSize = Vector2.new(w, h),
+		ResampleMode = Enum.ResamplerMode.Default,
+		Format = if wantPng then STUDIO_CAPTURE_FORMATS.PNG else STUDIO_CAPTURE_FORMATS.RGBA8,
+	}
+	local captureOk, captureResult = pcall(function()
+		return service:CaptureScreenshot(options)
+	end)
+	if not captureOk then
+		return {
+			error = `StudioCaptureService:CaptureScreenshot failed: {tostring(captureResult)}`,
+		}
+	end
+	if captureResult == nil then
+		return nil
+	end
+	local capture = captureResult
+	local startTime = tick()
+	while capture.BufferStatus.Name == "Pending" or capture.BufferStatus.Name == "NotStarted" do
+		if tick() - startTime > STUDIO_CAPTURE_TIMEOUT then
+			return nil
+		end
+		task.wait(0.02)
+	end
+	if capture.BufferStatus.Name ~= "Ready" then
+		local errorsOk, errors = pcall(function()
+			return capture:GetErrors()
+		end)
+		local detail = if errorsOk then game:GetService("HttpService"):JSONEncode(errors) else "unavailable"
+		return {
+			error = `StudioCaptureService capture failed (status {capture.BufferStatus.Name}): {detail}`,
+		}
+	end
+	local bufferOk, captureBuffer = pcall(function()
+		return capture:GetBuffer()
+	end)
+	if not bufferOk then
+		return {
+			error = `StudioCaptureService:GetBuffer failed: {tostring(captureBuffer)}`,
+		}
+	end
+	local resolution = capture.Resolution
+	return {
+		success = true,
+		encoding = if wantPng then "png" else "rgba8",
+		source = "StudioCaptureService",
+		width = math.max(1, math.floor(resolution.X)),
+		height = math.max(1, math.floor(resolution.Y)),
+		nativeWidth = nativeW,
+		nativeHeight = nativeH,
+		data = encodeBase64(captureBuffer),
+	}
+end
+-- Studio-only capture endpoint. Reports `unavailable` (instead of an error) so
+-- the server can fall back to the legacy CaptureService path.
+local function captureStudio(requestData)
+	local wantPng = requestData.encoding == "png"
+	local result = doStudioCapture(wantPng)
+	if result == nil then
+		return {
+			unavailable = "StudioCaptureService cannot capture this DataModel right now",
+		}
+	end
+	return result
+end
 -- Edit-mode single shot: capture and read back in the same (edit) context.
 local function captureScreenshotData()
 	local cap = doCaptureScreenshot()
@@ -2817,13 +3293,14 @@ end
 return {
 	captureScreenshotData = captureScreenshotData,
 	captureScreenshot = captureScreenshot,
+	captureStudio = captureStudio,
 	captureBegin = captureBegin,
 	captureRead = captureRead,
 }
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="11">
+        <Item class="ModuleScript" referent="12">
           <Properties>
             <string name="Name">EvalRuntimeHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -2977,7 +3454,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="12">
+        <Item class="ModuleScript" referent="13">
           <Properties>
             <string name="Name">GenerateModelHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -3182,7 +3659,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="13">
+        <Item class="ModuleScript" referent="14">
           <Properties>
             <string name="Name">InputHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -3382,7 +3859,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="14">
+        <Item class="ModuleScript" referent="15">
           <Properties>
             <string name="Name">LogHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -3404,7 +3881,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="15">
+        <Item class="ModuleScript" referent="16">
           <Properties>
             <string name="Name">MemoryHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -3472,7 +3949,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="16">
+        <Item class="ModuleScript" referent="17">
           <Properties>
             <string name="Name">MetadataHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -3829,7 +4306,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="17">
+        <Item class="ModuleScript" referent="18">
           <Properties>
             <string name="Name">MicroProfilerHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5582,7 +6059,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="18">
+        <Item class="ModuleScript" referent="19">
           <Properties>
             <string name="Name">PropertyHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -5667,6 +6144,7 @@ local function setProperties(requestData)
 	-- execute_luau edits as well, even when every assignment in this call failed.
 	finishRecording(recordingId, true)
 	return {
+		success = failureCount == 0,
 		instancePath = instancePath,
 		summary = {
 			total = successCount + failureCount,
@@ -5682,7 +6160,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="19">
+        <Item class="ModuleScript" referent="20">
           <Properties>
             <string name="Name">QueryHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6337,7 +6815,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="20">
+        <Item class="ModuleScript" referent="21">
           <Properties>
             <string name="Name">SceneAnalysisHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -6586,7 +7064,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="21">
+        <Item class="ModuleScript" referent="22">
           <Properties>
             <string name="Name">ScriptHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7258,7 +7736,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="22">
+        <Item class="ModuleScript" referent="23">
           <Properties>
             <string name="Name">ScriptProfilerHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7721,7 +8199,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="23">
+        <Item class="ModuleScript" referent="24">
           <Properties>
             <string name="Name">SerializationHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7907,7 +8385,7 @@ return {
 ]]></string>
           </Properties>
         </Item>
-        <Item class="ModuleScript" referent="24">
+        <Item class="ModuleScript" referent="25">
           <Properties>
             <string name="Name">TestHandlers</string>
             <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -7985,6 +8463,16 @@ local function startPlaytest(requestData)
 			error = "start_playtest is single-player only. Use multiplayer_test_start for multi-client StudioTestService sessions.",
 		}
 	end
+	-- Peer teardown and ExecutePlayModeAsync completion can precede native edit
+	-- readiness. Do not acknowledge a new start that the engine cannot execute.
+	if not StudioTestService.EditModeActive then
+		return {
+			success = false,
+			error = "Studio is not ready to start a playtest.",
+			message = "Wait for Studio to finish its current playtest transition before starting another.",
+			editModeReady = false,
+		}
+	end
 	-- Self-heal: if testRunning is stuck true but Studio reports no active
 	-- playtest, the previous start_playtest's task.spawn was orphaned
 	-- (plugin reload mid-test, Studio entered some inconsistent state, etc).
@@ -8064,22 +8552,24 @@ local function stopPlaytest(_requestData)
 		}
 	end
 	StopPlayMonitor.clearPending(stopRequest.requestId)
-	-- Request was consumed (EndTest called). ExecutePlayModeAsync in our
-	-- startPlaytest task.spawn is still unwinding though — testRunning stays
-	-- true until that yield completes and the post-block runs. Wait so
-	-- back-to-back stop -> start sequences don't race against the prior
-	-- teardown and get "A test is already running". 10s covers play-DM
-	-- teardown on heavier places; if it still hasn't cleared we return
-	-- anyway so users aren't stuck — but note that in the response so the
-	-- caller knows a subsequent start may need a moment.
+	-- EndTest consumption, task completion, and native edit readiness are distinct
+	-- milestones. In particular, testRunning can clear before Studio accepts another
+	-- ExecutePlayModeAsync call (and is never set for manually started playtests).
+	-- Only report completion after both tracked execution and native teardown settle.
 	local deadline = tick() + 10
-	while testRunning and tick() < deadline do
+	while (testRunning or not StudioTestService.EditModeActive) and tick() < deadline do
 		task.wait(0.1)
 	end
-	if testRunning then
+	local editModeReady = StudioTestService.EditModeActive
+	if testRunning or not editModeReady then
 		return {
-			success = true,
-			message = "Playtest stop signal sent; teardown still in progress.",
+			success = false,
+			error = "Playtest teardown did not complete.",
+			message = "Stop signal was accepted, but Studio teardown did not settle before timeout.",
+			stopSignalAccepted = true,
+			editModeReady = editModeReady,
+			playtestTaskPending = testRunning,
+			timedOut = true,
 		}
 	end
 	return {
@@ -8286,7 +8776,7 @@ return {
           </Properties>
         </Item>
       </Item>
-      <Item class="ModuleScript" referent="25">
+      <Item class="ModuleScript" referent="26">
         <Properties>
           <string name="Name">HttpDiagnostics</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8367,7 +8857,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="26">
+      <Item class="ModuleScript" referent="27">
         <Properties>
           <string name="Name">LuauExec</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8801,7 +9291,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="27">
+      <Item class="ModuleScript" referent="28">
         <Properties>
           <string name="Name">PeerRole</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -8822,7 +9312,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="28">
+      <Item class="ModuleScript" referent="29">
         <Properties>
           <string name="Name">PluginSession</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9011,7 +9501,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="29">
+      <Item class="ModuleScript" referent="30">
         <Properties>
           <string name="Name">Recording</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9041,7 +9531,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="30">
+      <Item class="ModuleScript" referent="31">
         <Properties>
           <string name="Name">RenderMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9109,7 +9599,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="31">
+      <Item class="ModuleScript" referent="32">
         <Properties>
           <string name="Name">RuntimeLogBuffer</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9345,7 +9835,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="32">
+      <Item class="ModuleScript" referent="33">
         <Properties>
           <string name="Name">ScriptSearch</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9672,7 +10162,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="33">
+      <Item class="ModuleScript" referent="34">
         <Properties>
           <string name="Name">ServerUrlSettings</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -9811,11 +10301,11 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="34">
+      <Item class="ModuleScript" referent="35">
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.1.2"
+local CURRENT_VERSION = "3.1.4"
 local PLUGIN_VARIANT = "inspector"
 local BASE_PORT = 58741
 local function createConnection(port)
@@ -9845,7 +10335,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="35">
+      <Item class="ModuleScript" referent="36">
         <Properties>
           <string name="Name">StopPlayMonitor</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -10078,7 +10568,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="36">
+      <Item class="ModuleScript" referent="37">
         <Properties>
           <string name="Name">StudioWebSocket</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11029,7 +11519,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="37">
+      <Item class="ModuleScript" referent="38">
         <Properties>
           <string name="Name">TopologyId</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11074,7 +11564,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="38">
+      <Item class="ModuleScript" referent="39">
         <Properties>
           <string name="Name">UI</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -11626,7 +12116,7 @@ return {
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="39">
+      <Item class="ModuleScript" referent="40">
         <Properties>
           <string name="Name">Utils</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
@@ -12467,11 +12957,11 @@ return {
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="44">
+    <Item class="Folder" referent="45">
       <Properties>
         <string name="Name">include</string>
       </Properties>
-      <Item class="ModuleScript" referent="40">
+      <Item class="ModuleScript" referent="41">
         <Properties>
           <string name="Name">LibMP</string>
           <string name="Source"><![CDATA[-- =============================================================================
@@ -168855,7 +169345,7 @@ return LibMP
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="41">
+      <Item class="ModuleScript" referent="42">
         <Properties>
           <string name="Name">Promise</string>
           <string name="Source"><![CDATA[--[[
@@ -170929,7 +171419,7 @@ return Promise
 ]]></string>
         </Properties>
       </Item>
-      <Item class="ModuleScript" referent="42">
+      <Item class="ModuleScript" referent="43">
         <Properties>
           <string name="Name">RuntimeLib</string>
           <string name="Source"><![CDATA[local Promise = require(script.Parent.Promise)
@@ -171196,15 +171686,15 @@ return TS
         </Properties>
       </Item>
     </Item>
-    <Item class="Folder" referent="45">
+    <Item class="Folder" referent="46">
       <Properties>
         <string name="Name">node_modules</string>
       </Properties>
-      <Item class="Folder" referent="46">
+      <Item class="Folder" referent="47">
         <Properties>
           <string name="Name">@rbxts</string>
         </Properties>
-      <Item class="ModuleScript" referent="43">
+      <Item class="ModuleScript" referent="44">
         <Properties>
           <string name="Name">services</string>
           <string name="Source"><![CDATA[return setmetatable({}, {