@chrrxs/robloxstudio-mcp-inspector 2.15.2 → 2.16.1

package/dist/index.js

@@ -386,30 +386,60 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
   });
   app.post("/ready", (req, res) => {
     const { pluginSessionId, instanceId, role, placeId, placeName, dataModelName, isRunning, pluginVersion, pluginVariant } = req.body;
+    const requestContext = {
+      instanceId: typeof instanceId === "string" ? instanceId : void 0,
+      role: typeof role === "string" ? role : void 0,
+      placeId: typeof placeId === "number" ? placeId : void 0,
+      placeName: typeof placeName === "string" ? placeName : void 0,
+      dataModelName: typeof dataModelName === "string" ? dataModelName : void 0,
+      isRunning: typeof isRunning === "boolean" ? isRunning : void 0,
+      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : void 0,
+      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : void 0
+    };
     if (!pluginSessionId || !instanceId || !role) {
+      const missingFields = [
+        !pluginSessionId ? "pluginSessionId" : void 0,
+        !instanceId ? "instanceId" : void 0,
+        !role ? "role" : void 0
+      ].filter((field) => !!field);
       res.status(400).json({
         success: false,
-        error: "pluginSessionId, instanceId, and role are required"
+        error: "missing_ready_fields",
+        message: `/ready missing required field(s): ${missingFields.join(", ")}`,
+        missingFields,
+        request: requestContext
+      });
+      return;
+    }
+    let result;
+    try {
+      result = bridge.registerInstance({
+        pluginSessionId,
+        instanceId,
+        role,
+        placeId: typeof placeId === "number" ? placeId : 0,
+        placeName: typeof placeName === "string" ? placeName : "",
+        dataModelName: typeof dataModelName === "string" ? dataModelName : "",
+        isRunning: !!isRunning,
+        pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
+        pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
+        serverVersion: serverConfig?.version ?? ""
+      });
+    } catch (err) {
+      res.status(500).json({
+        success: false,
+        error: "ready_registration_exception",
+        message: err instanceof Error ? err.message : String(err),
+        request: requestContext
       });
       return;
     }
-    const result = bridge.registerInstance({
-      pluginSessionId,
-      instanceId,
-      role,
-      placeId: typeof placeId === "number" ? placeId : 0,
-      placeName: typeof placeName === "string" ? placeName : "",
-      dataModelName: typeof dataModelName === "string" ? dataModelName : "",
-      isRunning: !!isRunning,
-      pluginVersion: typeof pluginVersion === "string" ? pluginVersion : "",
-      pluginVariant: typeof pluginVariant === "string" ? pluginVariant : "unknown",
-      serverVersion: serverConfig?.version ?? ""
-    });
     if (!result.ok) {
       res.status(409).json({
         success: false,
         error: result.error.code,
         message: result.error.message,
+        request: requestContext,
         existing: result.error.existing
       });
       return;
@@ -737,6 +767,12 @@ var init_http_server = __esm({
       execute_luau: (tools, body) => tools.executeLuau(body.code, body.target, body.instance_id),
       eval_server_runtime: (tools, body) => tools.evalServerRuntime(body.code, body.instance_id),
       eval_client_runtime: (tools, body) => tools.evalClientRuntime(body.code, body.target, body.instance_id),
+      set_network_profile: (tools, body) => tools.setNetworkProfile(body.profile, body.target, body.overrides, body.instance_id),
+      get_simulation_state: (tools, body) => tools.getSimulationState(body.include, body.target, body.instance_id),
+      reset_simulation_state: (tools, body) => tools.resetSimulationState(body.target, body.network, body.deviceSimulator, body.instance_id),
+      get_device_simulator_state: (tools, body) => tools.getDeviceSimulatorState(body.target, body.deviceId, body.includeDeviceList, body.instance_id),
+      set_device_simulator: (tools, body) => tools.setDeviceSimulator(body.target, body.deviceId, body.orientation, body.resolution, body.pixelDensity, body.scalingMode, body.stopSimulation, body.instance_id),
+      capture_device_matrix: (tools, body) => tools.captureDeviceMatrix(body.entries, body.target, body.format, body.quality, body.settleSeconds, body.restoreAfter, body.instance_id),
       start_playtest: (tools, body) => tools.startPlaytest(body.mode, body.numPlayers, body.instance_id),
       stop_playtest: (tools, body) => tools.stopPlaytest(body.instance_id),
       get_playtest_output: (tools, body) => tools.getPlaytestOutput(body.target, body.instance_id),
@@ -1261,21 +1297,21 @@ var init_opencloud_client = __esm({
           clearTimeout(timeoutId);
           if (!response.ok) {
             const errorBody = await response.text();
-            let errorMessage;
+            let errorMessage2;
             try {
               const errorJson = JSON.parse(errorBody);
-              errorMessage = errorJson.detail || errorJson.message || errorBody;
+              errorMessage2 = errorJson.detail || errorJson.message || errorBody;
             } catch {
-              errorMessage = errorBody;
+              errorMessage2 = errorBody;
             }
             if (response.status === 401) {
               throw new Error("Invalid or expired API key");
             } else if (response.status === 403) {
-              throw new Error(`API key lacks required permissions: ${errorMessage}`);
+              throw new Error(`API key lacks required permissions: ${errorMessage2}`);
             } else if (response.status === 429) {
               throw new Error("Rate limit exceeded. Please try again later.");
             } else {
-              throw new Error(`Open Cloud API error (${response.status}): ${errorMessage}`);
+              throw new Error(`Open Cloud API error (${response.status}): ${errorMessage2}`);
             }
           }
           return await response.json();
@@ -1410,21 +1446,21 @@ var init_opencloud_client = __esm({
           clearTimeout(timeoutId);
           if (!response.ok) {
             const errorBody = await response.text();
-            let errorMessage;
+            let errorMessage2;
             try {
               const errorJson = JSON.parse(errorBody);
-              errorMessage = errorJson.detail || errorJson.message || errorBody;
+              errorMessage2 = errorJson.detail || errorJson.message || errorBody;
             } catch {
-              errorMessage = errorBody;
+              errorMessage2 = errorBody;
             }
             if (response.status === 401) {
               throw new Error("Invalid or expired API key");
             } else if (response.status === 403) {
-              throw new Error(`API key lacks required permissions: ${errorMessage}`);
+              throw new Error(`API key lacks required permissions: ${errorMessage2}`);
             } else if (response.status === 429) {
               throw new Error("Rate limit exceeded. Please try again later.");
             } else {
-              throw new Error(`Open Cloud API error (${response.status}): ${errorMessage}`);
+              throw new Error(`Open Cloud API error (${response.status}): ${errorMessage2}`);
             }
           }
           return await response.json();
@@ -2573,7 +2609,337 @@ function encodeImageFromRgbaResponse(response, format, quality) {
 function sleep(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
-var RobloxStudioTools;
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function normalizeNetworkProfile(profile, overrides) {
+  if (!["great", "good", "poor", "custom"].includes(profile)) {
+    throw new Error('profile must be "great", "good", "poor", or "custom"');
+  }
+  const values = profile === "custom" ? {} : { ...NETWORK_PROFILES[profile] };
+  if (overrides !== void 0) {
+    if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
+      throw new Error("overrides must be an object when provided");
+    }
+    const allowed = new Set(NETWORK_PROFILE_KEYS);
+    for (const [key, value] of Object.entries(overrides)) {
+      if (!allowed.has(key)) {
+        throw new Error(`Unsupported network override "${key}". Allowed: ${NETWORK_PROFILE_KEYS.join(", ")}`);
+      }
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Network override "${key}" must be a finite number`);
+      }
+      if (value < 0) {
+        throw new Error(`Network override "${key}" must be greater than or equal to 0`);
+      }
+      if ((key === "InboundNetworkLossPercent" || key === "OutboundNetworkLossPercent") && value > MAX_NETWORK_PACKET_LOSS_PERCENT) {
+        throw new Error(`Network override "${key}" cannot exceed ${MAX_NETWORK_PACKET_LOSS_PERCENT}; Roblox engine limits packet loss simulation to 0.5%.`);
+      }
+      values[key] = value;
+    }
+  }
+  if (Object.keys(values).length === 0) {
+    throw new Error("custom profile requires at least one override");
+  }
+  return values;
+}
+function buildNetworkProfileLuau(profile, values) {
+  const valuesJson = JSON.stringify(values);
+  const keysJson = JSON.stringify(NETWORK_PROFILE_KEYS);
+  return `
+local HttpService = game:GetService("HttpService")
+local ns = settings():GetService("NetworkSettings")
+local keys = HttpService:JSONDecode(${JSON.stringify(keysJson)})
+local desired = HttpService:JSONDecode(${JSON.stringify(valuesJson)})
+local before = {}
+for _, key in ipairs(keys) do
+	before[key] = ns[key]
+end
+for key, value in pairs(desired) do
+	ns[key] = value
+end
+local after = {}
+for _, key in ipairs(keys) do
+	after[key] = ns[key]
+end
+return HttpService:JSONEncode({
+	profile = ${JSON.stringify(profile)},
+	applied = desired,
+	before = before,
+	after = after,
+})
+`.trim();
+}
+function buildNetworkStateLuau(operation) {
+  const keysJson = JSON.stringify(NETWORK_PROFILE_KEYS);
+  const resetJson = JSON.stringify(ZERO_NETWORK_PROFILE);
+  return `
+local HttpService = game:GetService("HttpService")
+local ns = settings():GetService("NetworkSettings")
+local operation = ${JSON.stringify(operation)}
+local keys = HttpService:JSONDecode(${JSON.stringify(keysJson)})
+local resetValues = HttpService:JSONDecode(${JSON.stringify(resetJson)})
+
+local function readState()
+	local state = {}
+	for _, key in ipairs(keys) do
+		state[key] = ns[key]
+	end
+	return state
+end
+
+if operation == "get" then
+	return HttpService:JSONEncode({
+		success = true,
+		state = readState(),
+	})
+end
+
+if operation == "reset" then
+	local before = readState()
+	for key, value in pairs(resetValues) do
+		ns[key] = value
+	end
+	return HttpService:JSONEncode({
+		success = true,
+		applied = resetValues,
+		before = before,
+		after = readState(),
+	})
+end
+
+error("Unsupported network simulation operation: " .. tostring(operation), 0)
+`.trim();
+}
+function normalizeDeviceSimulatorResolution(value) {
+  if (value === void 0)
+    return void 0;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("resolution must be an object with positive integer width and height");
+  }
+  const resolution = value;
+  const width = resolution.width;
+  const height = resolution.height;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error("resolution.width and resolution.height must be positive integers");
+  }
+  return { width, height };
+}
+function normalizeDeviceSimulatorSettings(input) {
+  const settings = {};
+  if (input.deviceId !== void 0) {
+    if (typeof input.deviceId !== "string" || input.deviceId.trim() === "") {
+      throw new Error("deviceId must be a non-empty string");
+    }
+    settings.deviceId = input.deviceId;
+  }
+  if (input.orientation !== void 0) {
+    if (typeof input.orientation !== "string" || input.orientation.trim() === "") {
+      throw new Error("orientation must be a non-empty string");
+    }
+    settings.orientation = input.orientation;
+  }
+  const resolution = normalizeDeviceSimulatorResolution(input.resolution);
+  if (resolution !== void 0)
+    settings.resolution = resolution;
+  if (input.pixelDensity !== void 0) {
+    if (typeof input.pixelDensity !== "number" || !Number.isFinite(input.pixelDensity) || input.pixelDensity <= 0) {
+      throw new Error("pixelDensity must be a positive finite number");
+    }
+    settings.pixelDensity = input.pixelDensity;
+  }
+  if (input.scalingMode !== void 0) {
+    if (typeof input.scalingMode !== "string" || input.scalingMode.trim() === "") {
+      throw new Error("scalingMode must be a non-empty string");
+    }
+    settings.scalingMode = input.scalingMode;
+  }
+  return settings;
+}
+function hasDeviceSimulatorSettings(settings) {
+  return settings.deviceId !== void 0 || settings.orientation !== void 0 || settings.resolution !== void 0 || settings.pixelDensity !== void 0 || settings.scalingMode !== void 0;
+}
+function buildDeviceSimulatorLuau(operation, options) {
+  const payload = JSON.stringify({ operation, ...options });
+  return `
+local HttpService = game:GetService("HttpService")
+local simulator = game:GetService("StudioDeviceSimulatorService")
+local opts = HttpService:JSONDecode(${JSON.stringify(payload)})
+
+local function plain(value)
+	local valueType = typeof(value)
+	if valueType == "Vector2" then
+		return { x = value.X, y = value.Y, width = value.X, height = value.Y }
+	end
+	if valueType == "EnumItem" then
+		return value.Name
+	end
+	if type(value) == "table" then
+		local out = {}
+		for k, v in pairs(value) do
+			out[tostring(k)] = plain(v)
+		end
+		return out
+	end
+	return value
+end
+
+local function getDeviceInfo(deviceId)
+	local ok, info = pcall(function()
+		return simulator:GetDeviceInfoAsync(deviceId)
+	end)
+	if ok then
+		return plain(info), nil
+	end
+	return nil, tostring(info)
+end
+
+local function normalizeDeviceList(rawList)
+	local devices = {}
+	local ids = {}
+	for _, entry in ipairs(rawList) do
+		local item
+		local id
+		if type(entry) == "table" then
+			item = plain(entry)
+			id = item.DeviceId or item.deviceId or item.Id or item.id or item[1]
+		else
+			id = tostring(entry)
+			item = { DeviceId = id }
+		end
+		if id ~= nil then
+			id = tostring(id)
+			local info = getDeviceInfo(id)
+			if type(info) == "table" then
+				item = info
+				if item.DeviceId == nil then item.DeviceId = id end
+			end
+			if item.IsCustom ~= true then
+				ids[id] = true
+				table.insert(devices, item)
+			end
+		end
+	end
+	return devices, ids
+end
+
+local function getDeviceList()
+	local rawList = simulator:GetDeviceListAsync()
+	return normalizeDeviceList(rawList)
+end
+
+local function assertBuiltInDeviceExists(deviceId)
+	local _, ids = getDeviceList()
+	if ids[deviceId] then return end
+	local available = {}
+	for id in pairs(ids) do table.insert(available, id) end
+	table.sort(available)
+	error('deviceId "' .. tostring(deviceId) .. '" is not an available built-in device. Use get_device_simulator_state to list supported device IDs. Available: ' .. table.concat(available, ", "), 0)
+end
+
+local function enumByName(enumType, raw, label)
+	local name = tostring(raw)
+	name = string.match(name, "([^%.]+)$") or name
+	local available = {}
+	for _, item in ipairs(enumType:GetEnumItems()) do
+		table.insert(available, item.Name)
+		if item.Name == name then
+			return item, item.Name
+		end
+	end
+	error(label .. ' "' .. tostring(raw) .. '" is not valid. Available: ' .. table.concat(available, ", "), 0)
+end
+
+local function tryActiveGetter(state, key, fn)
+	local ok, value = pcall(fn)
+	if ok then
+		state[key] = plain(value)
+	else
+		state.unavailable = state.unavailable or {}
+		state.unavailable[key] = tostring(value)
+	end
+end
+
+local function readState(includeDeviceList, requestedDeviceId)
+	local activeDeviceId = tostring(simulator:GetDeviceAsync())
+	local state = {
+		activeDeviceId = activeDeviceId,
+		isSimulating = activeDeviceId ~= "default",
+	}
+
+	if includeDeviceList then
+		local devices = getDeviceList()
+		state.devices = devices
+	end
+
+	if requestedDeviceId ~= nil then
+		assertBuiltInDeviceExists(requestedDeviceId)
+		state.deviceInfo = plain(simulator:GetDeviceInfoAsync(requestedDeviceId))
+	end
+
+	if state.isSimulating then
+		tryActiveGetter(state, "resolution", function() return simulator:GetResolutionAsync() end)
+		tryActiveGetter(state, "pixelDensity", function() return simulator:GetPixelDensityAsync() end)
+		tryActiveGetter(state, "orientation", function() return simulator:GetOrientationAsync() end)
+		tryActiveGetter(state, "scalingMode", function() return simulator:GetScalingModeAsync() end)
+	end
+
+	return state
+end
+
+local function applySettings(settings)
+	local applied = {}
+	if settings.deviceId ~= nil then
+		assertBuiltInDeviceExists(settings.deviceId)
+		simulator:SetDeviceAsync(settings.deviceId)
+		applied.deviceId = settings.deviceId
+	end
+	if settings.orientation ~= nil then
+		local item, name = enumByName(Enum.ScreenOrientation, settings.orientation, "orientation")
+		simulator:SetOrientationAsync(item)
+		applied.orientation = name
+	end
+	if settings.resolution ~= nil then
+		simulator:SetResolutionAsync(settings.resolution.width, settings.resolution.height)
+		applied.resolution = { width = settings.resolution.width, height = settings.resolution.height }
+	end
+	if settings.pixelDensity ~= nil then
+		simulator:SetPixelDensityAsync(settings.pixelDensity)
+		applied.pixelDensity = settings.pixelDensity
+	end
+	if settings.scalingMode ~= nil then
+		local item, name = enumByName(Enum.DeviceSimulatorScalingMode, settings.scalingMode, "scalingMode")
+		simulator:SetScalingModeAsync(item)
+		applied.scalingMode = name
+	end
+	return applied
+end
+
+if opts.operation == "get" then
+	return readState(opts.includeDeviceList ~= false, opts.deviceId)
+end
+
+if opts.operation == "set" then
+	local before = readState(false, nil)
+	local applied
+	if opts.stopSimulation == true then
+		simulator:StopSimulationAsync()
+		applied = { stopSimulation = true }
+	else
+		applied = applySettings(opts.settings or {})
+	end
+	return {
+		success = true,
+		applied = applied,
+		before = before,
+		after = readState(false, nil),
+	}
+end
+
+error("Unsupported device simulator operation: " .. tostring(opts.operation), 0)
+`.trim();
+}
+var MAX_INLINE_IMAGE_BYTES, MAX_DEVICE_MATRIX_ENTRIES, MAX_NETWORK_PACKET_LOSS_PERCENT, NETWORK_PROFILE_KEYS, NETWORK_PROFILES, ZERO_NETWORK_PROFILE, SIMULATION_PERSISTENCE_NOTES, RobloxStudioTools;
 var init_tools = __esm({
   "../core/dist/tools/index.js"() {
     "use strict";
@@ -2584,6 +2950,56 @@ var init_tools = __esm({
     init_roblox_cookie_client();
     init_jpeg_encoder();
     init_png_encoder();
+    MAX_INLINE_IMAGE_BYTES = 6e6;
+    MAX_DEVICE_MATRIX_ENTRIES = 6;
+    MAX_NETWORK_PACKET_LOSS_PERCENT = 0.5;
+    NETWORK_PROFILE_KEYS = [
+      "InboundNetworkMinDelayMs",
+      "OutboundNetworkMinDelayMs",
+      "InboundNetworkJitterMs",
+      "OutboundNetworkJitterMs",
+      "InboundNetworkLossPercent",
+      "OutboundNetworkLossPercent"
+    ];
+    NETWORK_PROFILES = {
+      great: {
+        InboundNetworkMinDelayMs: 15,
+        OutboundNetworkMinDelayMs: 15,
+        InboundNetworkJitterMs: 0,
+        OutboundNetworkJitterMs: 0,
+        InboundNetworkLossPercent: 0,
+        OutboundNetworkLossPercent: 0
+      },
+      good: {
+        InboundNetworkMinDelayMs: 50,
+        OutboundNetworkMinDelayMs: 50,
+        InboundNetworkJitterMs: 10,
+        OutboundNetworkJitterMs: 10,
+        InboundNetworkLossPercent: 0,
+        OutboundNetworkLossPercent: 0
+      },
+      poor: {
+        InboundNetworkMinDelayMs: 150,
+        OutboundNetworkMinDelayMs: 150,
+        InboundNetworkJitterMs: 100,
+        OutboundNetworkJitterMs: 100,
+        InboundNetworkLossPercent: 0.5,
+        OutboundNetworkLossPercent: 0.5
+      }
+    };
+    ZERO_NETWORK_PROFILE = {
+      InboundNetworkMinDelayMs: 0,
+      OutboundNetworkMinDelayMs: 0,
+      InboundNetworkJitterMs: 0,
+      OutboundNetworkJitterMs: 0,
+      InboundNetworkLossPercent: 0,
+      OutboundNetworkLossPercent: 0
+    };
+    SIMULATION_PERSISTENCE_NOTES = [
+      "Normal Play client changes can write back to edit state.",
+      "Multiplayer clients inherit baseline at startup but are isolated afterward.",
+      "StudioTestService client device simulator state may appear stale on fresh clients, so reset after client startup is required."
+    ];
     RobloxStudioTools = class _RobloxStudioTools {
       client;
       bridge;
@@ -2683,6 +3099,160 @@ var init_tools = __esm({
       _clientRolesForInstance(instanceId) {
         return this._rolesForInstance(instanceId).filter((role) => /^client-\d+$/.test(role)).sort((a, b) => Number(a.slice("client-".length)) - Number(b.slice("client-".length)));
       }
+      _resolveDeviceSimulatorSingleTarget(target, instance_id, toolName) {
+        const selectedTarget = target ?? "edit";
+        if (selectedTarget === "server" || selectedTarget === "all" || selectedTarget === "all-clients" || selectedTarget === "edit-proxy") {
+          throw new Error(`${toolName} target must be "edit" or "client-N" (got: ${selectedTarget})`);
+        }
+        if (selectedTarget !== "edit" && !/^client-\d+$/.test(selectedTarget)) {
+          throw new Error(`${toolName} target must be "edit" or "client-N" (got: ${selectedTarget})`);
+        }
+        const resolved = this._resolveSingleTarget(selectedTarget, instance_id);
+        return { ...resolved, selectedTarget };
+      }
+      _resolveDeviceSimulatorSetTargets(target, instance_id) {
+        const selectedTarget = target ?? "edit";
+        if (selectedTarget === "all-clients") {
+          const instanceId = this._resolveInstanceIdOnly(instance_id);
+          const roles = this._clientRolesForInstance(instanceId);
+          if (roles.length === 0) {
+            throw new RoutingFailure({
+              code: "target_role_not_present_on_instance",
+              message: `instance "${instanceId}" has no connected playtest client roles. Start a playtest first.`,
+              data: {
+                instances: this.bridge.getPublicInstances(),
+                count: this.bridge.getInstances().length
+              }
+            });
+          }
+          return { instanceId, selectedTarget, roles };
+        }
+        const resolved = this._resolveDeviceSimulatorSingleTarget(selectedTarget, instance_id, "set_device_simulator");
+        return { instanceId: resolved.instanceId, selectedTarget, roles: [resolved.role] };
+      }
+      _normalizeSimulationInclude(include) {
+        const selectedInclude = include ?? "both";
+        if (selectedInclude !== "network" && selectedInclude !== "deviceSimulator" && selectedInclude !== "both") {
+          throw new Error(`get_simulation_state include must be "network", "deviceSimulator", or "both" (got: ${selectedInclude})`);
+        }
+        return selectedInclude;
+      }
+      _resolveSimulationTargets(target, instance_id, toolName) {
+        const selectedTarget = target ?? "edit-and-clients";
+        if (selectedTarget === "server" || selectedTarget === "all" || selectedTarget === "edit-proxy") {
+          throw new Error(`${toolName} target must be "edit", "client-N", "all-clients", or "edit-and-clients" (got: ${selectedTarget})`);
+        }
+        const instanceId = this._resolveInstanceIdOnly(instance_id);
+        const connectedRoles = this._rolesForInstance(instanceId);
+        const clientRoles = this._clientRolesForInstance(instanceId);
+        const warnings = [];
+        let roles;
+        if (selectedTarget === "edit") {
+          if (!connectedRoles.includes("edit")) {
+            throw new RoutingFailure({
+              code: "target_role_not_present_on_instance",
+              message: `instance "${instanceId}" has no role "edit". Available roles: ${connectedRoles.join(", ") || "none"}.`,
+              data: {
+                instances: this.bridge.getPublicInstances(),
+                count: this.bridge.getInstances().length
+              }
+            });
+          }
+          roles = ["edit"];
+        } else if (selectedTarget === "all-clients") {
+          roles = clientRoles;
+          if (roles.length === 0) {
+            warnings.push(`No connected playtest client roles found for instance "${instanceId}".`);
+          }
+        } else if (selectedTarget === "edit-and-clients") {
+          roles = [];
+          if (connectedRoles.includes("edit")) {
+            roles.push("edit");
+          } else {
+            warnings.push(`No edit role found for instance "${instanceId}".`);
+          }
+          roles.push(...clientRoles);
+        } else if (/^client-\d+$/.test(selectedTarget)) {
+          if (!clientRoles.includes(selectedTarget)) {
+            throw new RoutingFailure({
+              code: "target_role_not_present_on_instance",
+              message: `instance "${instanceId}" has no role "${selectedTarget}". Available client roles: ${clientRoles.join(", ") || "none"}.`,
+              data: {
+                instances: this.bridge.getPublicInstances(),
+                count: this.bridge.getInstances().length
+              }
+            });
+          }
+          roles = [selectedTarget];
+        } else {
+          throw new Error(`${toolName} target must be "edit", "client-N", "all-clients", or "edit-and-clients" (got: ${selectedTarget})`);
+        }
+        return { instanceId, selectedTarget, roles, warnings };
+      }
+      _parseExecuteLuauJsonResponse(response, toolName) {
+        const r = response;
+        if (r?.success === false) {
+          throw new Error(r.error || r.message || `${toolName} Luau execution failed`);
+        }
+        if (typeof r?.returnValue !== "string") {
+          return response;
+        }
+        if (r.returnValue === "") {
+          return {};
+        }
+        try {
+          return JSON.parse(r.returnValue);
+        } catch {
+          throw new Error(`${toolName} returned non-JSON data: ${r.returnValue}`);
+        }
+      }
+      async _executeNetworkStateOperation(instanceId, role, operation) {
+        const code = buildNetworkStateLuau(operation);
+        const response = await this.client.request("/api/execute-luau", { code }, instanceId, role);
+        return this._parseExecuteLuauJsonResponse(response, `network simulation ${operation}`);
+      }
+      async _executeDeviceSimulatorOperation(instanceId, role, operation, options) {
+        const code = buildDeviceSimulatorLuau(operation, options);
+        const response = await this.client.request("/api/execute-luau", { code }, instanceId, role);
+        return this._parseExecuteLuauJsonResponse(response, `device simulator ${operation}`);
+      }
+      _settingsFromDeviceSimulatorState(state) {
+        const s = state;
+        if (!s || s.isSimulating !== true || typeof s.activeDeviceId !== "string" || s.activeDeviceId === "default") {
+          return { stopSimulation: true };
+        }
+        return normalizeDeviceSimulatorSettings({
+          deviceId: s.activeDeviceId,
+          orientation: s.orientation,
+          resolution: s.resolution,
+          pixelDensity: s.pixelDensity,
+          scalingMode: s.scalingMode
+        });
+      }
+      _deviceSimulatorStateWithoutDeviceList(state) {
+        if (typeof state !== "object" || state === null || Array.isArray(state)) {
+          return state;
+        }
+        const { devices: _devices, ...rest } = state;
+        return rest;
+      }
+      _assertCanRestoreDeviceSimulatorState(state) {
+        const s = state;
+        if (!s || s.isSimulating !== true || typeof s.activeDeviceId !== "string" || s.activeDeviceId === "default") {
+          return;
+        }
+        const devices = Array.isArray(s.devices) ? s.devices : [];
+        const isBuiltIn = devices.some((entry) => {
+          if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return false;
+          const device = entry;
+          const id = device.DeviceId ?? device.deviceId ?? device.Id ?? device.id;
+          return id === s.activeDeviceId && device.IsCustom !== true;
+        });
+        if (!isBuiltIn) {
+          throw new Error(`capture_device_matrix cannot safely restore active custom device "${s.activeDeviceId}". Switch the simulator to default or a built-in preset first, or pass restoreAfter=false only if you intentionally accept changing the simulator state.`);
+        }
+      }
       async _waitForRuntimeRoles(instanceId, opts, timeoutSec = 30) {
         const deadline = Date.now() + timeoutSec * 1e3;
         while (Date.now() < deadline) {
@@ -3288,6 +3858,365 @@ ${code}`
           ]
         };
       }
+      async setNetworkProfile(profile, target, overrides, instance_id) {
+        const values = normalizeNetworkProfile(profile, overrides);
+        const instanceId = this._resolveInstanceIdOnly(instance_id);
+        const clientRoles = this._clientRolesForInstance(instanceId);
+        const selectedTarget = target ?? "client-1";
+        let targetRoles;
+        if (selectedTarget === "all-clients") {
+          targetRoles = clientRoles;
+        } else if (/^client-\d+$/.test(selectedTarget)) {
+          if (!clientRoles.includes(selectedTarget)) {
+            throw new RoutingFailure({
+              code: "target_role_not_present_on_instance",
+              message: `instance "${instanceId}" has no role "${selectedTarget}". Available client roles: ${clientRoles.join(", ") || "none"}.`,
+              data: {
+                instances: this.bridge.getPublicInstances(),
+                count: this.bridge.getInstances().length
+              }
+            });
+          }
+          targetRoles = [selectedTarget];
+        } else {
+          throw new Error(`set_network_profile target must be "client-N" or "all-clients" (got: ${selectedTarget})`);
+        }
+        if (targetRoles.length === 0) {
+          throw new RoutingFailure({
+            code: "target_role_not_present_on_instance",
+            message: `instance "${instanceId}" has no connected playtest client roles. Start a playtest first.`,
+            data: {
+              instances: this.bridge.getPublicInstances(),
+              count: this.bridge.getInstances().length
+            }
+          });
+        }
+        const code = buildNetworkProfileLuau(profile, values);
+        const responses = await Promise.allSettled(targetRoles.map(async (role) => {
+          const response = await this.client.request("/api/execute-luau", { code }, instanceId, role);
+          const result = this._parseExecuteLuauJsonResponse(response, "set_network_profile");
+          return { role, result };
+        }));
+        const body = {
+          profile,
+          target: selectedTarget,
+          applied: values,
+          targets: {}
+        };
+        const targetResults = body.targets;
+        const failures = [];
+        for (let i = 0; i < responses.length; i++) {
+          const role = targetRoles[i];
+          const response = responses[i];
+          if (response.status === "fulfilled") {
+            targetResults[role] = response.value.result;
+          } else {
+            const message = errorMessage(response.reason);
+            targetResults[role] = { error: message };
+            failures.push(`${role}: ${message}`);
+          }
+        }
+        if (failures.length > 0) {
+          throw new Error(`set_network_profile failed for ${failures.join("; ")}. Partial result: ${JSON.stringify(body)}`);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(body)
+            }
+          ]
+        };
+      }
+      async getSimulationState(include, target, instance_id) {
+        const selectedInclude = this._normalizeSimulationInclude(include);
+        const includeNetwork = selectedInclude === "network" || selectedInclude === "both";
+        const includeDeviceSimulator = selectedInclude === "deviceSimulator" || selectedInclude === "both";
+        const resolved = this._resolveSimulationTargets(target, instance_id, "get_simulation_state");
+        const roleEntries = await Promise.all(resolved.roles.map(async (role) => {
+          const state = {};
+          const errors = {};
+          if (includeNetwork) {
+            try {
+              state.network = await this._executeNetworkStateOperation(resolved.instanceId, role, "get");
+            } catch (error) {
+              errors.network = errorMessage(error);
+            }
+          }
+          if (includeDeviceSimulator) {
+            try {
+              state.deviceSimulator = await this._executeDeviceSimulatorOperation(resolved.instanceId, role, "get", { includeDeviceList: false });
+            } catch (error) {
+              errors.deviceSimulator = errorMessage(error);
+            }
+          }
+          if (Object.keys(errors).length > 0) {
+            state.errors = errors;
+          }
+          return { role, state };
+        }));
+        const roles = {};
+        for (const entry of roleEntries) {
+          roles[entry.role] = entry.state;
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              include: selectedInclude,
+              target: resolved.selectedTarget,
+              roles,
+              warnings: resolved.warnings,
+              persistenceNotes: SIMULATION_PERSISTENCE_NOTES
+            })
+          }]
+        };
+      }
+      async resetSimulationState(target, network, deviceSimulator, instance_id) {
+        const resetNetwork = network !== false;
+        const resetDeviceSimulator = deviceSimulator !== false;
+        if (!resetNetwork && !resetDeviceSimulator) {
+          throw new Error("reset_simulation_state requires network=true and/or deviceSimulator=true; both default to true");
+        }
+        const resolved = this._resolveSimulationTargets(target, instance_id, "reset_simulation_state");
+        const roleEntries = await Promise.all(resolved.roles.map(async (role) => {
+          const result = {};
+          const errors = {};
+          if (resetNetwork) {
+            try {
+              result.network = await this._executeNetworkStateOperation(resolved.instanceId, role, "reset");
+            } catch (error) {
+              errors.network = errorMessage(error);
+            }
+          }
+          if (resetDeviceSimulator) {
+            try {
+              result.deviceSimulator = await this._executeDeviceSimulatorOperation(resolved.instanceId, role, "set", { stopSimulation: true });
+            } catch (error) {
+              errors.deviceSimulator = errorMessage(error);
+            }
+          }
+          if (Object.keys(errors).length > 0) {
+            result.errors = errors;
+          }
+          return { role, result };
+        }));
+        const roles = {};
+        const failures = [];
+        for (const entry of roleEntries) {
+          roles[entry.role] = entry.result;
+          const errors = entry.result.errors;
+          if (errors) {
+            for (const [kind, message] of Object.entries(errors)) {
+              failures.push(`${entry.role}.${kind}: ${message}`);
+            }
+          }
+        }
+        const body = {
+          target: resolved.selectedTarget,
+          network: resetNetwork,
+          deviceSimulator: resetDeviceSimulator,
+          roles,
+          warnings: resolved.warnings,
+          persistenceNotes: SIMULATION_PERSISTENCE_NOTES
+        };
+        if (failures.length > 0) {
+          throw new Error(`reset_simulation_state failed for ${failures.join("; ")}. Partial result: ${JSON.stringify(body)}`);
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(body)
+          }]
+        };
+      }
+      async getDeviceSimulatorState(target, deviceId, includeDeviceList, instance_id) {
+        if (deviceId !== void 0 && (typeof deviceId !== "string" || deviceId.trim() === "")) {
+          throw new Error("deviceId must be a non-empty string when provided");
+        }
+        const resolved = this._resolveDeviceSimulatorSingleTarget(target, instance_id, "get_device_simulator_state");
+        const state = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "get", {
+          includeDeviceList: includeDeviceList !== false,
+          deviceId
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              target: resolved.selectedTarget,
+              role: resolved.role,
+              ...state
+            })
+          }]
+        };
+      }
+      async setDeviceSimulator(target, deviceId, orientation, resolution, pixelDensity, scalingMode, stopSimulation, instance_id) {
+        const settings = normalizeDeviceSimulatorSettings({ deviceId, orientation, resolution, pixelDensity, scalingMode });
+        if (stopSimulation === true && hasDeviceSimulatorSettings(settings)) {
+          throw new Error("stopSimulation=true cannot be combined with deviceId, orientation, resolution, pixelDensity, or scalingMode");
+        }
+        if (stopSimulation !== true && !hasDeviceSimulatorSettings(settings)) {
+          throw new Error("set_device_simulator requires stopSimulation=true or at least one simulator setting");
+        }
+        const resolved = this._resolveDeviceSimulatorSetTargets(target, instance_id);
+        const responses = await Promise.allSettled(resolved.roles.map(async (role) => {
+          const result = await this._executeDeviceSimulatorOperation(resolved.instanceId, role, "set", stopSimulation === true ? { stopSimulation: true } : { settings });
+          return { role, result };
+        }));
+        const body = {
+          target: resolved.selectedTarget,
+          targets: {}
+        };
+        const targets = body.targets;
+        const failures = [];
+        for (let i = 0; i < responses.length; i++) {
+          const role = resolved.roles[i];
+          const response = responses[i];
+          if (response.status === "fulfilled") {
+            targets[role] = response.value.result;
+          } else {
+            const message = errorMessage(response.reason);
+            targets[role] = { error: message };
+            failures.push(`${role}: ${message}`);
+          }
+        }
+        if (failures.length > 0) {
+          throw new Error(`set_device_simulator failed for ${failures.join("; ")}. Partial result: ${JSON.stringify(body)}`);
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(body)
+          }]
+        };
+      }
+      async captureDeviceMatrix(entries, target, format, quality, settleSeconds, restoreAfter, instance_id) {
+        if (!Array.isArray(entries) || entries.length === 0) {
+          throw new Error("capture_device_matrix requires a non-empty entries array");
+        }
+        if (entries.length > MAX_DEVICE_MATRIX_ENTRIES) {
+          throw new Error(`capture_device_matrix supports at most ${MAX_DEVICE_MATRIX_ENTRIES} entries per call; split larger matrices into multiple calls`);
+        }
+        const matrixEntries = entries.map((entry, index) => {
+          if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new Error(`entries[${index}] must be an object`);
+          }
+          const raw = entry;
+          if (raw.label !== void 0 && typeof raw.label !== "string") {
+            throw new Error(`entries[${index}].label must be a string when provided`);
+          }
+          return {
+            ...normalizeDeviceSimulatorSettings({
+              deviceId: raw.deviceId,
+              orientation: raw.orientation,
+              resolution: raw.resolution,
+              pixelDensity: raw.pixelDensity,
+              scalingMode: raw.scalingMode
+            }),
+            label: raw.label
+          };
+        });
+        const resolved = this._resolveDeviceSimulatorSingleTarget(target, instance_id, "capture_device_matrix");
+        if (resolved.role.startsWith("client-") && await this._isMultiplayerTestRunning(resolved.instanceId)) {
+          throw new Error("capture_device_matrix does not support StudioTestService multiplayer client targets because Roblox scopes temporary screenshot textures per client process");
+        }
+        const settleMs = settleSeconds === void 0 ? 300 : Math.max(0, Math.floor(settleSeconds * 1e3));
+        const shouldRestore = restoreAfter !== false;
+        const before = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "get", { includeDeviceList: shouldRestore });
+        if (shouldRestore) {
+          this._assertCanRestoreDeviceSimulatorState(before);
+        }
+        const summary = {
+          target: resolved.selectedTarget,
+          role: resolved.role,
+          restoreAfter: shouldRestore,
+          before: this._deviceSimulatorStateWithoutDeviceList(before),
+          entries: []
+        };
+        const entrySummaries = summary.entries;
+        const content = [];
+        const failures = [];
+        try {
+          for (let i = 0; i < matrixEntries.length; i++) {
+            const entry = matrixEntries[i];
+            const label = entry.label ?? `entry-${i + 1}`;
+            const entrySummary = {
+              index: i,
+              label,
+              settings: entry
+            };
+            entrySummaries.push(entrySummary);
+            try {
+              const { label: _label, ...settings } = entry;
+              const applied = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "set", { settings });
+              entrySummary.applied = applied;
+              if (settleMs > 0)
+                await sleep(settleMs);
+              const capture = await this._captureViewportImage(resolved.instanceId, resolved.role, format, quality);
+              if (capture.success) {
+                entrySummary.screenshot = {
+                  width: capture.width,
+                  height: capture.height,
+                  format: capture.format,
+                  quality: capture.quality,
+                  mimeType: capture.mimeType
+                };
+                content.push({
+                  type: "text",
+                  text: `capture_device_matrix ${i + 1}/${matrixEntries.length} ${label}: ${capture.message}`
+                });
+                content.push({
+                  type: "image",
+                  data: capture.data,
+                  mimeType: capture.mimeType
+                });
+              } else {
+                entrySummary.error = capture.error;
+                failures.push(`${label}: ${capture.error}`);
+                content.push({
+                  type: "text",
+                  text: `capture_device_matrix ${i + 1}/${matrixEntries.length} ${label}: ${capture.error}`
+                });
+              }
+            } catch (error) {
+              const message = errorMessage(error);
+              entrySummary.error = message;
+              failures.push(`${label}: ${message}`);
+              content.push({
+                type: "text",
+                text: `capture_device_matrix ${i + 1}/${matrixEntries.length} ${label}: ${message}`
+              });
+            }
+          }
+        } finally {
+          if (shouldRestore) {
+            try {
+              const restoreSettings = this._settingsFromDeviceSimulatorState(before);
+              if ("stopSimulation" in restoreSettings) {
+                summary.restore = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "set", { stopSimulation: true });
+              } else {
+                summary.restore = await this._executeDeviceSimulatorOperation(resolved.instanceId, resolved.role, "set", { settings: restoreSettings });
+              }
+            } catch (error) {
+              const message = errorMessage(error);
+              summary.restoreError = message;
+              failures.push(`restore: ${message}`);
+            }
+          }
+        }
+        if (failures.length > 0) {
+          throw new Error(`capture_device_matrix failed for ${failures.join("; ")}. Partial result: ${JSON.stringify(summary)}`);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(summary)
+            },
+            ...content
+          ]
+        };
+      }
       async getRuntimeLogs(target, since, tail, filter, instance_id) {
         const tgt = target ?? "all";
         const data = {};
@@ -3425,9 +4354,20 @@ ${code}`
         };
       }
       async stopPlaytest(instance_id) {
-        const response = await this._callSingle("/api/stop-playtest", {}, "edit", instance_id);
+        const { instanceId } = this._resolveSingleTarget("edit", instance_id);
+        const response = await this.client.request("/api/stop-playtest", {}, instanceId, "edit");
+        let wait;
+        if (response?.success === true) {
+          wait = await this._waitForRuntimeRoles(instanceId, { noRuntime: true }, 15);
+        }
+        const body = wait ? {
+          ...response,
+          runtimeStopped: wait.ok,
+          timedOut: wait.timedOut,
+          roles: wait.roles
+        } : response;
         return {
-          content: [{ type: "text", text: JSON.stringify(response) }]
+          content: [{ type: "text", text: JSON.stringify(body) }]
         };
       }
       async getPlaytestOutput(target, instance_id) {
@@ -3499,15 +4439,19 @@ ${code}`
         return false;
       }
       async _isMultiplayerTestRunning(instanceId) {
-        if (!this._rolesForInstance(instanceId).includes("edit"))
-          return false;
-        try {
-          const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
-          const phase = editState?.session?.phase;
-          return phase === "starting" || phase === "running";
-        } catch {
-          return false;
+        const roles = this._rolesForInstance(instanceId);
+        const hasServer = roles.includes("server");
+        const clientCount = roles.filter((role) => role.startsWith("client-")).length;
+        if (roles.includes("edit")) {
+          try {
+            const editState = await this.client.request("/api/multiplayer-test-state", {}, instanceId, "edit");
+            const phase = editState?.session?.phase;
+            if (phase === "starting" || phase === "running")
+              return true;
+          } catch {
+          }
         }
+        return hasServer && clientCount >= 2;
       }
       async _waitForMultiplayerStart(instanceId, clientCount, timeoutSec = 30) {
         const deadline = Date.now() + timeoutSec * 1e3;
@@ -4624,16 +5568,15 @@ ${code}`
         }, tgt, instance_id);
         return { content: [{ type: "text", text: JSON.stringify(response) }] };
       }
-      async captureScreenshot(instance_id, format, quality) {
-        const { instanceId, clientRole } = this._resolveRuntime(instance_id);
+      async _captureViewportImage(instanceId, targetRole, format, quality) {
         let response;
-        if (clientRole) {
-          const begin = await this._callSingle("/api/capture-begin", {}, clientRole, instanceId);
+        if (targetRole.startsWith("client-")) {
+          const begin = await this._callSingle("/api/capture-begin", {}, targetRole, instanceId);
           if (begin.error) {
-            return { content: [{ type: "text", text: begin.error }] };
+            return { success: false, error: begin.error };
           }
           if (!begin.contentId) {
-            return { content: [{ type: "text", text: "Screenshot capture failed: no content id returned from client." }] };
+            return { success: false, error: "Screenshot capture failed: no content id returned from client." };
           }
           response = await this._callSingle("/api/capture-read", { contentId: begin.contentId }, "edit", instanceId);
         } else {
@@ -4641,55 +5584,66 @@ ${code}`
         }
         if (response.error) {
           let text = response.error;
-          if (clientRole && response.error.includes("Failed to load texture, unexpected format") && await this._isMultiplayerTestRunning(instanceId)) {
+          if (targetRole.startsWith("client-") && response.error.includes("Failed to load texture, unexpected format") && await this._isMultiplayerTestRunning(instanceId)) {
             text = `Screenshot capture reached the multiplayer client, but Roblox returned a temporary screenshot texture that the edit peer cannot read in StudioTestService multiplayer sessions. Regular start_playtest capture works because the temporary rbxtemp:// handle is readable from the edit process; multiplayer client handles appear to be scoped to the client process. Raw error: ${response.error}`;
           }
-          return {
-            content: [{
-              type: "text",
-              text
-            }]
-          };
+          return { success: false, error: text };
         }
         const w = response.width;
         const h = response.height;
         if (w === void 0 || h === void 0) {
-          return { content: [{ type: "text", text: "Screenshot response missing dimensions." }] };
+          return { success: false, error: "Screenshot response missing dimensions." };
         }
         const fmt = format === "png" ? "png" : "jpeg";
         const q = quality === void 0 ? 92 : Math.max(1, Math.min(100, Math.floor(quality)));
-        const MAX_IMAGE_BYTES = 6e6;
         const encoded = encodeImageFromRgbaResponse(response, fmt, q);
         let { buffer } = encoded;
         const { mimeType } = encoded;
         let usedQ = q;
         let note = "";
-        if (buffer.length > MAX_IMAGE_BYTES) {
+        if (buffer.length > MAX_INLINE_IMAGE_BYTES) {
           if (fmt === "png") {
             const mb = (buffer.length / 1048576).toFixed(1);
             return {
-              content: [{
-                type: "text",
-                text: `PNG screenshot is ${mb}MB, over the ~${(MAX_IMAGE_BYTES / 1048576).toFixed(0)}MB inline image limit. Use the default jpeg format (optionally with a "quality" value) or make the Studio window smaller for a lossless capture.`
-              }]
+              success: false,
+              error: `PNG screenshot is ${mb}MB, over the ~${(MAX_INLINE_IMAGE_BYTES / 1048576).toFixed(0)}MB inline image limit. Use the default jpeg format (optionally with a "quality" value) or make the Studio window smaller for a lossless capture.`
             };
           }
-          while (buffer.length > MAX_IMAGE_BYTES && usedQ > 25) {
+          while (buffer.length > MAX_INLINE_IMAGE_BYTES && usedQ > 25) {
             usedQ = Math.max(25, usedQ - 20);
             buffer = encodeImageFromRgbaResponse(response, "jpeg", usedQ).buffer;
           }
           note = ` \u2014 auto-reduced to q${usedQ} to fit the inline size limit; enlarge the Studio window or capture a smaller region for finer detail`;
         }
+        const message = `Screenshot ${w}x${h}px (${fmt}${fmt === "jpeg" ? ` q${usedQ}` : ""})${note}. For simulate_mouse_input, x/y are pixel coordinates in this exact image with (0,0) at the top-left; it is not downscaled, so use coordinates as you read them off the image.`;
+        return {
+          success: true,
+          width: w,
+          height: h,
+          format: fmt,
+          quality: fmt === "jpeg" ? usedQ : void 0,
+          note,
+          data: buffer.toString("base64"),
+          mimeType,
+          message
+        };
+      }
+      async captureScreenshot(instance_id, format, quality) {
+        const { instanceId, clientRole } = this._resolveRuntime(instance_id);
+        const capture = await this._captureViewportImage(instanceId, clientRole ?? "edit", format, quality);
+        if (!capture.success) {
+          return { content: [{ type: "text", text: capture.error }] };
+        }
         return {
           content: [
             {
               type: "text",
-              text: `Screenshot ${w}x${h}px (${fmt}${fmt === "jpeg" ? ` q${usedQ}` : ""})${note}. For simulate_mouse_input, x/y are pixel coordinates in this exact image with (0,0) at the top-left; it is not downscaled, so use coordinates as you read them off the image.`
+              text: capture.message
             },
             {
               type: "image",
-              data: buffer.toString("base64"),
-              mimeType
+              data: capture.data,
+              mimeType: capture.mimeType
             }
           ]
         };
@@ -5851,7 +6805,7 @@ var init_definitions = __esm({
       {
         name: "eval_server_runtime",
         category: "write",
-        description: "Execute Luau on the server peer in the running game's Script VM (shares require cache with user game scripts, unlike execute_luau target=server which runs in plugin context). Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
+        description: "Execute Luau on the server peer in the running game's Script VM (shares require cache with user game scripts, unlike execute_luau target=server which runs in plugin context). Requires a running playtest; the runtime bridge is created automatically inside the play DataModel, including for playtests started manually via the Studio Play button.",
         inputSchema: {
           type: "object",
           properties: {
@@ -5870,7 +6824,7 @@ var init_definitions = __esm({
       {
         name: "eval_client_runtime",
         category: "write",
-        description: "Execute Luau on a client peer in the running game's LocalScript VM (shares require cache with user game scripts, unlike execute_luau target=client-N which runs in plugin context). Requires a running playtest; the bridge is installed automatically (including for playtests started manually via the Studio Play button).",
+        description: "Execute Luau on a client peer in the running game's LocalScript VM (shares require cache with user game scripts, unlike execute_luau target=client-N which runs in plugin context). Requires a running playtest; the runtime bridge is created automatically inside the play DataModel, including for playtests started manually via the Studio Play button.",
         inputSchema: {
           type: "object",
           properties: {
@@ -6000,6 +6954,280 @@ var init_definitions = __esm({
           }
         }
       },
+      {
+        name: "set_network_profile",
+        category: "write",
+        description: `Apply simulated network conditions to active playtest client peers via NetworkSettings in plugin context. Requires a running playtest and targets only client peers: pass target="client-1", "client-2", etc., or target="all-clients". Presets: great = 30ms total latency (15ms in / 15ms out), 0ms jitter, 0% packet loss; good = 100ms total latency (50ms in / 50ms out), 10ms jitter, 0% packet loss; poor = 300ms (150ms in / 150ms out), 100ms jitter, 0.5% packet loss. profile="custom" applies only the numeric overrides provided; packet loss values above Roblox's 0.5% engine limit are rejected.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            profile: {
+              type: "string",
+              enum: ["great", "good", "poor", "custom"],
+              description: "Network condition preset. Presets set all six simulation fields; custom requires overrides."
+            },
+            target: {
+              type: "string",
+              description: 'Client target: "client-1" (default), "client-2", etc., or "all-clients" to apply to every connected playtest client.'
+            },
+            overrides: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                InboundNetworkMinDelayMs: {
+                  type: "number",
+                  minimum: 0,
+                  description: "Server-to-client minimum latency in milliseconds."
+                },
+                OutboundNetworkMinDelayMs: {
+                  type: "number",
+                  minimum: 0,
+                  description: "Client-to-server minimum latency in milliseconds."
+                },
+                InboundNetworkJitterMs: {
+                  type: "number",
+                  minimum: 0,
+                  description: "Server-to-client latency jitter in milliseconds."
+                },
+                OutboundNetworkJitterMs: {
+                  type: "number",
+                  minimum: 0,
+                  description: "Client-to-server latency jitter in milliseconds."
+                },
+                InboundNetworkLossPercent: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 0.5,
+                  description: "Server-to-client packet loss percentage. Roblox engine limit is 0.5%; larger values are rejected."
+                },
+                OutboundNetworkLossPercent: {
+                  type: "number",
+                  minimum: 0,
+                  maximum: 0.5,
+                  description: "Client-to-server packet loss percentage. Roblox engine limit is 0.5%; larger values are rejected."
+                }
+              },
+              description: "Optional exact NetworkSettings property overrides. For preset profiles, overrides replace preset fields. For custom, only these properties are applied."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          },
+          required: ["profile"]
+        }
+      },
+      {
+        name: "get_simulation_state",
+        category: "read",
+        description: 'Inspect current NetworkSettings and/or StudioDeviceSimulatorService state for edit and connected playtest clients only. Defaults to include="both" and target="edit-and-clients"; server peers are skipped. Use before diagnosing network or device-sensitive tests, especially because normal Play can write client simulator changes back to edit and StudioTestService clients can inherit stale device simulator state.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            include: {
+              type: "string",
+              enum: ["network", "deviceSimulator", "both"],
+              description: 'Simulation state to inspect: "network", "deviceSimulator", or "both" (default both).'
+            },
+            target: {
+              type: "string",
+              description: 'Simulation target scope: "edit-and-clients" (default), "edit", "all-clients", or a specific "client-N". Server peers are never included.'
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "reset_simulation_state",
+        category: "write",
+        description: 'Reset reachable simulation state to a clean baseline for deterministic tests. Defaults to target="edit-and-clients" and resets both network and device simulator state. Network reset sets all six simulated NetworkSettings fields to 0; device reset calls StopSimulationAsync(). Call before tests, after starting Play or multiplayer, before stopping, and again on edit after stopping.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: 'Simulation target scope: "edit-and-clients" (default), "edit", "all-clients", or a specific "client-N". Server peers are skipped.'
+            },
+            network: {
+              type: "boolean",
+              description: "Reset simulated NetworkSettings fields to 0 (default true)."
+            },
+            deviceSimulator: {
+              type: "boolean",
+              description: "Stop Studio device simulation with StopSimulationAsync() (default true)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "get_device_simulator_state",
+        category: "read",
+        description: 'Inspect StudioDeviceSimulatorService state and supported built-in device presets. Defaults to target="edit"; also supports a regular playtest client target such as "client-1". Server targets are not supported. When no simulated device is active, active-only fields are omitted and isSimulating=false.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: 'Device simulator target: "edit" (default) or a regular playtest client like "client-1". Server targets are rejected.'
+            },
+            deviceId: {
+              type: "string",
+              description: "Optional built-in device preset ID to inspect with GetDeviceInfoAsync."
+            },
+            includeDeviceList: {
+              type: "boolean",
+              description: "Include the built-in device preset list from GetDeviceListAsync (default true)."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "set_device_simulator",
+        category: "write",
+        description: 'Set or stop StudioDeviceSimulatorService using built-in device presets only. Defaults to target="edit"; supports "client-N" and "all-clients"; rejects server targets. Applies deviceId first, then orientation, resolution, pixelDensity, and scalingMode overrides.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              description: 'Device simulator target: "edit" (default), "client-1", "client-2", etc., or "all-clients".'
+            },
+            deviceId: {
+              type: "string",
+              description: "Built-in device preset ID from get_device_simulator_state."
+            },
+            orientation: {
+              type: "string",
+              description: 'ScreenOrientation enum name, e.g. "LandscapeRight", "LandscapeLeft", "Portrait", or a full Enum.ScreenOrientation.* string.'
+            },
+            resolution: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                width: {
+                  type: "number",
+                  description: "Viewport width in pixels."
+                },
+                height: {
+                  type: "number",
+                  description: "Viewport height in pixels."
+                }
+              },
+              required: ["width", "height"],
+              description: "Optional resolution override applied after the device preset."
+            },
+            pixelDensity: {
+              type: "number",
+              description: "Optional positive pixel density override applied after the device preset."
+            },
+            scalingMode: {
+              type: "string",
+              description: 'DeviceSimulatorScalingMode enum name, e.g. "ScaleToPhysicalSize", or a full Enum.DeviceSimulatorScalingMode.* string.'
+            },
+            stopSimulation: {
+              type: "boolean",
+              description: "Stop device simulation. When true, do not pass other simulator setters."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          }
+        }
+      },
+      {
+        name: "capture_device_matrix",
+        category: "write",
+        description: 'Apply up to 6 ordered Studio device simulator settings, capture each viewport screenshot, and restore the previous simulator state by default when the prior state is default or a built-in preset. Custom device persistence is intentionally unsupported. Defaults to target="edit"; supports regular playtest client targets but not server or all-clients targets.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            entries: {
+              type: "array",
+              maxItems: 6,
+              description: "Ordered device capture entries. Each entry may set a deviceId and optional simulator overrides before capture.",
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  label: {
+                    type: "string",
+                    description: "Optional label included in the screenshot metadata."
+                  },
+                  deviceId: {
+                    type: "string",
+                    description: "Built-in device preset ID from get_device_simulator_state."
+                  },
+                  orientation: {
+                    type: "string",
+                    description: "ScreenOrientation enum name or full Enum.ScreenOrientation.* string."
+                  },
+                  resolution: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      width: {
+                        type: "number",
+                        description: "Viewport width in pixels."
+                      },
+                      height: {
+                        type: "number",
+                        description: "Viewport height in pixels."
+                      }
+                    },
+                    required: ["width", "height"]
+                  },
+                  pixelDensity: {
+                    type: "number",
+                    description: "Optional positive pixel density override."
+                  },
+                  scalingMode: {
+                    type: "string",
+                    description: "DeviceSimulatorScalingMode enum name or full Enum.DeviceSimulatorScalingMode.* string."
+                  }
+                }
+              }
+            },
+            target: {
+              type: "string",
+              description: 'Device simulator target: "edit" (default) or a regular playtest client such as "client-1". all-clients and server targets are rejected.'
+            },
+            format: {
+              type: "string",
+              enum: ["jpeg", "png"],
+              description: 'Screenshot image format. "jpeg" (default) is compact; "png" is lossless but may exceed inline size limits.'
+            },
+            quality: {
+              type: "number",
+              description: "JPEG quality 1-100 (default 92). Ignored for png."
+            },
+            settleSeconds: {
+              type: "number",
+              description: "Seconds to wait after applying each simulator entry before capturing (default 0.3)."
+            },
+            restoreAfter: {
+              type: "boolean",
+              description: "Restore the previous default or built-in preset simulator state after the matrix finishes (default true). Custom active devices are not preserved."
+            },
+            instance_id: {
+              type: "string",
+              description: "Which connected Studio place to target. Required when multiple places are connected; omit when one. Use get_connected_instances to list available IDs."
+            }
+          },
+          required: ["entries"]
+        }
+      },
       {
         name: "multiplayer_test_start",
         category: "write",