@chrrxs/robloxstudio-mcp 2.11.4 → 2.13.0

package/studio-plugin/src/modules/LuauExec.ts

@@ -0,0 +1,305 @@
+/* eslint-disable */
+// Shared execute_luau machinery for edit/server (MetadataHandlers.executeLuau)
+// and the play-client peer (ClientBroker.handleExecuteLuau). Three things this
+// module owns:
+//
+//   1. The IIFE wrapper that captures print/warn, runs user code in xpcall,
+//      and always returns { ok, value, output } so the ModuleScript itself
+//      always returns exactly one value (otherwise `print("hi")` with no
+//      return would fail with "Module code did not return exactly one value").
+//
+//   2. The loadstring-then-ModuleScript-require fallback, with the parse-error
+//      recovery hack that pulls the real diagnostic from LogService.
+//
+//   3. Return-value formatting: tables get HttpService:JSONEncode'd so the
+//      caller sees `{"x":1,"y":2}` instead of `table: 0xaddr`; primitives
+//      pass through tostring. The encode is pcall'd so cycles or
+//      non-serializable values gracefully fall back to tostring.
+//
+// Before this module existed, the client peer used a stripped-down
+// require-only execution path that lacked both the wrapper and the JSON
+// formatting, producing two well-known papercuts:
+//   - `print("hi")` (no return) failed with "Module code did not return..."
+//   - Returning a table yielded `table: 0xaddr` instead of structured data.
+
+const HttpService = game.GetService("HttpService");
+const LogService = game.GetService("LogService");
+
+interface WrapperResult {
+	ok?: boolean;
+	value?: unknown;
+	output?: defined;
+}
+
+interface ExecuteResult {
+	success: boolean;
+	returnValue?: string;
+	output?: string[];
+	error?: string;
+	message?: string;
+}
+
+const PAYLOAD_INSTANCE_NAME = "__MCPExecLuauPayload";
+const PAYLOAD_PATH_PREFIX = `Workspace.${PAYLOAD_INSTANCE_NAME}:`;
+
+// Number of lines the wrapper emits BEFORE the first line of user code.
+// Used both inside the wrapper (Luau __mcp_LINE_OFFSET) and on the TS side
+// (remapPayloadLines, for compile errors recovered from LogService) so user
+// code errors report user-relative line numbers instead of the inflated
+// "line 23" the wrapper would otherwise expose. If you reorder buildWrapper's
+// prefix lines, update this constant — there's a self-check below.
+const WRAPPER_LINE_OFFSET = 23;
+
+// Count source lines so the wrapper can filter traceback frames that fall
+// outside the user code range (the wrapper's own preamble/postamble lines).
+function countLines(s: string): number {
+	let n = 1;
+	const size = s.size();
+	for (let i = 1; i <= size; i++) {
+		if (string.sub(s, i, i) === "\n") n++;
+	}
+	return n;
+}
+
+function buildWrapper(code: string): string {
+	// If you reorder the prefix lines below, update WRAPPER_LINE_OFFSET to
+	// match the number of lines emitted BEFORE the ${code} substitution.
+	// The constant is mirrored inside the wrapper (__mcp_LINE_OFFSET) and
+	// used by remapPayloadLines on the TS side.
+	const userLines = countLines(code);
+	return `return ((function()
+\tlocal __mcp_traceback
+\tlocal __mcp_remap
+\tlocal __mcp_LINE_OFFSET = ${WRAPPER_LINE_OFFSET}
+\tlocal __mcp_USER_LINES = ${userLines}
+\tlocal __mcp_output = {}
+\tlocal __mcp_real_print = print
+\tlocal __mcp_real_warn = warn
+\tlocal print = function(...)
+\t\t__mcp_real_print(...)
+\t\tlocal args = {...}
+\t\tlocal parts = table.create(#args)
+\t\tfor i, a in ipairs(args) do parts[i] = tostring(a) end
+\t\ttable.insert(__mcp_output, table.concat(parts, "\\t"))
+\tend
+\tlocal warn = function(...)
+\t\t__mcp_real_warn(...)
+\t\tlocal args = {...}
+\t\tlocal parts = table.create(#args)
+\t\tfor i, a in ipairs(args) do parts[i] = tostring(a) end
+\t\ttable.insert(__mcp_output, "[warn] " .. table.concat(parts, "\\t"))
+\tend
+\tlocal function __mcp_run()
+${code}
+\tend
+\t__mcp_remap = function(s)
+\t\t-- Two chunk-name formats can reference our payload:
+\t\t--   * "Workspace.__MCPExecLuauPayload:N" — ModuleScript:require fallback path
+\t\t--   * "[string \\"return ((function()...\\"]:N" — loadstring() (default in plugin)
+\t\t-- Subtract LINE_OFFSET to get the user-relative number, then clamp.
+\t\t-- Clamping matters for unclosed constructs ("local x = (") where the
+\t\t-- parser keeps reading into wrapper postamble and reports a payload
+\t\t-- line past user EOF. Without clamping the message says "user_code:49"
+\t\t-- for one-line input, framing the wrapper as user code.
+\t\tlocal function __mcp_user_line(payload_n)
+\t\t\tlocal user_n = payload_n - __mcp_LINE_OFFSET
+\t\t\tif user_n < 1 then return "1" end
+\t\t\tif user_n > __mcp_USER_LINES then return tostring(__mcp_USER_LINES) .. " (at end of input)" end
+\t\t\treturn tostring(user_n)
+\t\tend
+\t\ts = string.gsub(s, "__MCPExecLuauPayload:(%d+)", function(num)
+\t\t\tlocal n = tonumber(num)
+\t\t\tif n then return "user_code:" .. __mcp_user_line(n) end
+\t\t\treturn "user_code:" .. num
+\t\tend)
+\t\ts = string.gsub(s, '%[string "[^"]+"%]:(%d+)', function(num)
+\t\t\tlocal n = tonumber(num)
+\t\t\tif n then return "user_code:" .. __mcp_user_line(n) end
+\t\t\treturn "user_code:" .. num
+\t\tend)
+\t\treturn s
+\tend
+\t__mcp_traceback = function(err)
+\t\tlocal raw = debug.traceback(tostring(err), 2)
+\t\tlocal kept = {}
+\t\tfor line in string.gmatch(raw, "[^\\n]+") do
+\t\t\t-- Extract referenced line number (either chunk-name format).
+\t\t\tlocal num_str = string.match(line, "__MCPExecLuauPayload:(%d+)")
+\t\t\t\tor string.match(line, '%[string "[^"]+"%]:(%d+)')
+\t\t\tlocal n = num_str and tonumber(num_str)
+\t\t\t-- Strip the "in function '__mcp_run'" annotation before doing
+\t\t\t-- any filtering, because user-code frames carry that suffix —
+\t\t\t-- the entire user payload is hosted inside __mcp_run, so EVERY
+\t\t\t-- user frame would otherwise match a naive "__mcp_" filter and
+\t\t\t-- get dropped. Strip first, then apply filters.
+\t\t\tline = (string.gsub(line, " in function '__mcp_run'", ""))
+\t\t\tlocal skip = string.find(line, "MCPPlugin", 1, true)
+\t\t\t\tor string.find(line, "__mcp_", 1, true)
+\t\t\t\tor string.find(line, "in function 'xpcall'", 1, true)
+\t\t\t-- Frame lines pointing at wrapper preamble/postamble (outside
+\t\t\t-- user range) are wrapper internals — drop them. Lines without
+\t\t\t-- a payload-chunk line number (the traceback header / engine
+\t\t\t-- C frames) are kept; remap is a no-op for them.
+\t\t\tif n and (n <= __mcp_LINE_OFFSET or n > __mcp_LINE_OFFSET + __mcp_USER_LINES) then
+\t\t\t\tskip = true
+\t\t\tend
+\t\t\tif not skip then
+\t\t\t\ttable.insert(kept, __mcp_remap(line))
+\t\t\tend
+\t\tend
+\t\treturn table.concat(kept, "\\n")
+\tend
+\tlocal ok, errOrValue = xpcall(__mcp_run, __mcp_traceback)
+\treturn { ok = ok, value = errOrValue, output = __mcp_output }
+end)())`;
+}
+
+// TS-side mirror of the Lua __mcp_remap. Used by runViaModuleScript when
+// pulling the real compile-error diagnostic out of LogService — that error
+// references the payload module's line number directly, and never passes
+// through the IIFE's runtime wrapper.
+function remapPayloadLines(s: string, userLines: number): string {
+	// Mirror of the Lua __mcp_remap inside the wrapper, for paths that
+	// don't pass through the IIFE (compile errors recovered from
+	// LogService, the immediate loadstring compileError surface). Same
+	// two-format coverage plus the same clamp: unclosed user constructs
+	// let the parser consume wrapper postamble, so the raw payload line
+	// is sometimes well past user EOF — clamp to [1, userLines] and
+	// annotate so the error doesn't say "user_code:49" for one-line input.
+	const userLine = (payload: number): string => {
+		const u = payload - WRAPPER_LINE_OFFSET;
+		if (u < 1) return "1";
+		if (u > userLines) return `${tostring(userLines)} (at end of input)`;
+		return tostring(u);
+	};
+	let out = s;
+	const [a] = string.gsub(out, "__MCPExecLuauPayload:(%d+)", (num: string) => {
+		const n = tonumber(num);
+		if (n !== undefined) return `user_code:${userLine(n)}`;
+		return `user_code:${num}`;
+	});
+	out = a;
+	const [b] = string.gsub(out, '%[string "[^"]+"%]:(%d+)', (num: string) => {
+		const n = tonumber(num);
+		if (n !== undefined) return `user_code:${userLine(n)}`;
+		return `user_code:${num}`;
+	});
+	out = b;
+	return out;
+}
+
+function runViaModuleScript(wrapped: string, userLines: number): WrapperResult {
+	const m = new Instance("ModuleScript");
+	m.Name = PAYLOAD_INSTANCE_NAME;
+	const [okSet, setErr] = pcall(() => {
+		(m as unknown as { Source: string }).Source = wrapped;
+	});
+	if (!okSet) {
+		m.Destroy();
+		// error(..., 0) suppresses the "user_MCPPlugin.rbxmx.MCPPlugin.modules.LuauExec:N:"
+		// prefix that error() would otherwise prepend, keeping the visible
+		// message focused on the user-actionable error rather than our path.
+		error(`ModuleScript Source set failed: ${tostring(setErr)}`, 0);
+	}
+	m.Parent = game.GetService("Workspace");
+	const [okReq, reqResult] = pcall(() => require(m));
+	m.Destroy();
+	if (!okReq) {
+		let errMsg = tostring(reqResult);
+		// pcall(require, m) collapses parse/compile failures into the canned
+		// engine string. The real diagnostic was emitted to LogService on the
+		// next engine frame — give it ~50ms to land then scan backward.
+		if (errMsg === "Requested module experienced an error while loading") {
+			task.wait(0.05);
+			const hist = LogService.GetLogHistory();
+			for (let i = hist.size() - 1; i >= 0; i--) {
+				const e = hist[i];
+				if (
+					e.messageType === Enum.MessageType.MessageError &&
+					string.sub(e.message, 1, PAYLOAD_PATH_PREFIX.size()) === PAYLOAD_PATH_PREFIX
+				) {
+					errMsg = e.message;
+					break;
+				}
+			}
+		}
+		// Compile errors reference the payload module's line number directly
+		// — remap + clamp to user-relative line numbers so `local x = 1 +`
+		// reports :1: instead of :23:, and reports the clamp annotation
+		// when the parser ran off the end of user code into wrapper code.
+		error(remapPayloadLines(errMsg, userLines), 0);
+	}
+	return reqResult as unknown as WrapperResult;
+}
+
+function isLoadstringUnavailable(err: unknown): boolean {
+	const errStr = tostring(err);
+	const [matchStart] = string.find(errStr, "not available", 1, true);
+	return matchStart !== undefined;
+}
+
+// Returns a string suitable for `returnValue`. Tables get JSON-encoded so
+// the caller sees structured data instead of "table: 0xaddr". Anything that
+// JSONEncode chokes on (cycles, Roblox userdata) falls back to tostring.
+function formatReturnValue(value: unknown): string {
+	if (value === undefined) return "";
+	if (typeIs(value, "table")) {
+		const [ok, encoded] = pcall(() => HttpService.JSONEncode(value));
+		if (ok) return encoded as string;
+	}
+	return tostring(value);
+}
+
+function execute(code: string): ExecuteResult {
+	if (!code || code === "") {
+		return { success: false, error: "code is required" };
+	}
+	const wrapped = buildWrapper(code);
+	const userLines = countLines(code);
+
+	let [success, result] = pcall(() => {
+		const [fn, compileError] = loadstring(wrapped);
+		if (!fn) {
+			if (isLoadstringUnavailable(compileError)) {
+				return runViaModuleScript(wrapped, userLines);
+			}
+			error(`Compile error: ${remapPayloadLines(tostring(compileError), userLines)}`, 0);
+		}
+		return fn() as unknown as WrapperResult;
+	});
+
+	// loadstring can throw (not return nil) when ServerScriptService.
+	// LoadStringEnabled is false; treat that as a second-chance fallback.
+	if (!success && isLoadstringUnavailable(result)) {
+		[success, result] = pcall(() => runViaModuleScript(wrapped, userLines));
+	}
+
+	if (!success) {
+		return {
+			success: false,
+			error: tostring(result),
+			output: [],
+			message: "Code execution failed",
+		};
+	}
+
+	const r = result as unknown as WrapperResult;
+	const capturedOutput = r.output as unknown as string[] | undefined;
+	const output = capturedOutput !== undefined ? capturedOutput : ([] as string[]);
+	if (r.ok === true) {
+		return {
+			success: true,
+			returnValue: r.value !== undefined ? formatReturnValue(r.value) : undefined,
+			output,
+			message: "Code executed successfully",
+		};
+	}
+	return {
+		success: false,
+		error: r.value !== undefined ? tostring(r.value) : "(unknown error)",
+		output,
+		message: "Code execution failed",
+	};
+}
+
+export = { execute };

package/studio-plugin/src/modules/RenderMonitor.ts

@@ -0,0 +1,60 @@
+// Detects whether the Studio window is actually rendering, so virtual input
+// and screenshot tools can surface a clear reason instead of silently failing.
+//
+// When a Studio window is MINIMIZED, the engine suspends the render loop AND
+// input processing, but keeps running scripts (Heartbeat keeps firing). That's
+// why simulate_*_input would return success while having zero effect, and
+// CaptureService:CaptureScreenshot would time out. Validated live: during a 3s
+// minimize, RenderStepped's max inter-frame gap was 5.08s while Heartbeat's was
+// 0.10s. So RenderStepped freshness is the reliable "is this window rendering?"
+// signal; Heartbeat is not.
+
+import { RunService } from "@rbxts/services";
+
+let lastFrame = 0;
+let connected = false;
+
+// Above this many seconds since the last rendered frame, we treat the window
+// as not rendering. RenderStepped normally fires every ~16ms; a multi-second
+// gap only happens when minimized/suspended, so 1s cleanly avoids false
+// positives from ordinary frame hitches while still catching the real case.
+const STALE_THRESHOLD = 1.0;
+
+export function start(): void {
+	if (connected) return;
+	// RenderStepped can only be connected from a client/edit render loop; it
+	// throws in the play-server DM. pcall so a server-DM call is a safe no-op
+	// (connected stays false → notRenderingReason() returns undefined there).
+	const [ok] = pcall(() => {
+		RunService.RenderStepped.Connect(() => {
+			lastFrame = tick();
+		});
+	});
+	if (ok) {
+		connected = true;
+		lastFrame = tick();
+	}
+}
+
+export function secondsSinceFrame(): number {
+	if (!connected) return 0;
+	return tick() - lastFrame;
+}
+
+// Returns a human-readable reason if the window appears minimized / not
+// rendering (so input + screenshots won't work), else undefined. Fail-open:
+// when the monitor isn't active in this DM (server peer, or connect failed) it
+// returns undefined so we never block on a false signal.
+export function notRenderingReason(): string | undefined {
+	if (!connected) return undefined;
+	const gap = secondsSinceFrame();
+	if (gap > STALE_THRESHOLD) {
+		return string.format(
+			"Studio window appears minimized or not rendering (no frame in %.1fs). " +
+				"Virtual input and screenshots only work while the window is visible — " +
+				"restore/un-minimize the Studio window and retry.",
+			gap,
+		);
+	}
+	return undefined;
+}

package/studio-plugin/src/modules/StopPlayMonitor.ts

@@ -1,32 +1,40 @@
-// Cross-DM stop_playtest signaling via plugin:SetSetting.
+// Cross-DM stop_playtest signaling via plugin:SetSetting, scoped by
+// per-instance setting key so the same Studio process can host playtests
+// for multiple places without one place's stop_playtest yanking another's.
 //
 // `plugin:SetSetting` / `plugin:GetSetting` is a per-plugin persistent store
-// that's shared across every DataModel the plugin runs in (edit, play-server,
-// play-clients). We use it as a one-bit flag for "please call EndTest in the
-// play-server DM":
+// shared across every DataModel the plugin runs in (edit DMs, play-server
+// DMs, play-client DMs). For each connected place we use a dedicated key
+// "MCP_STOP_PLAY_<instanceId>" as a single-bit mailbox:
 //
-//   * The edit DM's stopPlaytest handler writes the flag (requestStop).
-//   * A monitor loop running inside the play-server DM polls the flag at 1Hz
-//     and calls StudioTestService:EndTest when it flips true, then resets it.
-//   * The edit DM then waits up to ~2.5s for the flag to be reset, which
-//     tells us a play-server actually consumed the request (no false-positive
-//     success when nothing was running).
+//   * The edit DM's stopPlaytest handler writes `true` into its own key
+//     (computed from its placeId / ServerStorage anon UUID).
+//   * Each play-server DM's monitor loop polls the key matching its own
+//     instanceId at 0.1Hz; on `true` it clears the key and calls
+//     StudioTestService:EndTest. Play-server DMs for other places never
+//     touch this key.
+//   * The edit DM waits up to ~8s for its key to be cleared, confirming a
+//     matching play-server actually consumed the request.
 //
-// Why this is simpler than the previous edit-proxy registration:
-//   * Doesn't depend on the MCP server tracking peer roles at all.
-//   * Survives MCP server restarts: monitor loop is local to the play-server
-//     plugin lifetime, not to any HTTP/registration state.
-//   * No need for cross-DM LogService.MessageOut reflection (which we verified
-//     does not work edit -> play-server anyway).
-//
-// Pattern mirrors the official Roblox Studio MCP
-// (Roblox/studio-rust-mcp-server, plugin/src/Utils/GameStopUtil.luau).
+// Earlier versions used a single shared boolean flag, which let any
+// play-server DM in the same Studio process consume any place's stop
+// request — silently yanking teammates' playtests. The per-key scoping
+// below is the fix.
+
+import { HttpService, ServerStorage } from "@rbxts/services";
 
 const StudioTestService = game.GetService("StudioTestService");
 
-const SETTING_KEY = "MCP_STOP_PLAY_SIGNAL";
-const POLL_INTERVAL_SEC = 1;
-const WAIT_FOR_CONSUMPTION_TIMEOUT_SEC = 2.5;
+const SETTING_KEY_PREFIX = "MCP_STOP_PLAY_";
+// Monitor checks the key at this cadence. 0.1s keeps worst-case detection
+// lag tight so the consumption-confirmation window doesn't have to absorb
+// polling jitter on top of EndTest's teardown time.
+const POLL_INTERVAL_SEC = 0.1;
+// Total time we wait for the matching play-server DM to consume the
+// signal. Must cover: monitor detection (<= POLL_INTERVAL_SEC) +
+// StudioTestService:EndTest teardown (several seconds on heavier places).
+// 8s is comfortable; the tighter poll above keeps real cases well under.
+const WAIT_FOR_CONSUMPTION_TIMEOUT_SEC = 8.0;
 const WAIT_POLL_SEC = 0.1;
 
 let pluginRef: Plugin | undefined;
@@ -35,20 +43,45 @@ function init(p: Plugin): void {
 	pluginRef = p;
 }
 
+// Mirror of Communication.computeInstanceId(). Duplicated here because
+// StopPlayMonitor runs in both edit and play-server DMs, and both must
+// agree on the place identifier (published places: placeId; unpublished:
+// UUID on ServerStorage's __MCPPlaceId attribute, travels with the .rbxl
+// into the play DM).
+function computeInstanceId(): string {
+	if (game.PlaceId !== 0) {
+		return `place:${tostring(game.PlaceId)}`;
+	}
+	const existing = ServerStorage.GetAttribute("__MCPPlaceId");
+	if (typeIs(existing, "string") && existing !== "") {
+		return `anon:${existing as string}`;
+	}
+	const fresh = HttpService.GenerateGUID(false);
+	pcall(() => ServerStorage.SetAttribute("__MCPPlaceId", fresh));
+	return `anon:${fresh}`;
+}
+
+function settingKey(instanceId: string): string {
+	return SETTING_KEY_PREFIX + instanceId;
+}
+
 function startMonitor(): void {
 	if (!pluginRef) {
 		warn("[MCP] StopPlayMonitor.startMonitor called before init; skipping");
 		return;
 	}
-	// Clear any stale value left from a prior session. If a real stop request
-	// is in-flight when this runs, the requesting edit DM will set it again
-	// within its 2.5s wait window.
-	pcall(() => pluginRef!.SetSetting(SETTING_KEY, false));
+	const myKey = settingKey(computeInstanceId());
+	// Clear any stale value left from a prior session. If a real stop
+	// request is in-flight when this runs, the requesting edit DM will
+	// write again within its consumption-confirmation window.
+	pcall(() => pluginRef!.SetSetting(myKey, false));
 	task.spawn(() => {
 		while (true) {
-			const [okGet, val] = pcall(() => pluginRef!.GetSetting(SETTING_KEY));
+			const [okGet, val] = pcall(() => pluginRef!.GetSetting(myKey));
 			if (okGet && val === true) {
-				pcall(() => pluginRef!.SetSetting(SETTING_KEY, false));
+				// Consume the flag first so requestStop's
+				// waitForConsumption returns success, then end the test.
+				pcall(() => pluginRef!.SetSetting(myKey, false));
 				pcall(() => StudioTestService.EndTest("stopped_by_mcp"));
 			}
 			task.wait(POLL_INTERVAL_SEC);
@@ -58,15 +91,17 @@ function startMonitor(): void {
 
 function requestStop(): boolean {
 	if (!pluginRef) return false;
-	const [ok] = pcall(() => pluginRef!.SetSetting(SETTING_KEY, true));
+	const myKey = settingKey(computeInstanceId());
+	const [ok] = pcall(() => pluginRef!.SetSetting(myKey, true));
 	return ok;
 }
 
 function waitForConsumption(): boolean {
 	if (!pluginRef) return false;
+	const myKey = settingKey(computeInstanceId());
 	const start = tick();
 	while (tick() - start < WAIT_FOR_CONSUMPTION_TIMEOUT_SEC) {
-		const [okGet, val] = pcall(() => pluginRef!.GetSetting(SETTING_KEY));
+		const [okGet, val] = pcall(() => pluginRef!.GetSetting(myKey));
 		if (okGet && val !== true) return true;
 		task.wait(WAIT_POLL_SEC);
 	}
@@ -75,7 +110,8 @@ function waitForConsumption(): boolean {
 
 function clearPending(): void {
 	if (!pluginRef) return;
-	pcall(() => pluginRef!.SetSetting(SETTING_KEY, false));
+	const myKey = settingKey(computeInstanceId());
+	pcall(() => pluginRef!.SetSetting(myKey, false));
 }
 
 export = {

package/studio-plugin/src/modules/handlers/CaptureHandlers.ts

@@ -1,3 +1,5 @@
+import * as RenderMonitor from "../RenderMonitor";
+
 const CaptureService = game.GetService("CaptureService");
 const AssetService = game.GetService("AssetService");
 
@@ -71,7 +73,17 @@ function readPixelsTiled(img: EditableImage, w: number, h: number): buffer {
 	return fullBuf;
 }
 
-function captureScreenshotData(): unknown {
+// Triggers CaptureService:CaptureScreenshot and waits for the temporary
+// content id. Works in any DM, including the play CLIENT (where reading the
+// pixels back is blocked, but capturing is not). The returned rbxtemp:// id is
+// a process-scoped handle: it can be dereferenced from a DIFFERENT, more
+// privileged DM (the edit DM) — see captureRead.
+function doCaptureScreenshot(): { contentId: string } | { error: string } {
+	// Fast-fail with a clear reason if the window isn't rendering — otherwise
+	// CaptureScreenshot's callback never fires and we'd block for the full 10s.
+	const notRendering = RenderMonitor.notRenderingReason();
+	if (notRendering !== undefined) return { error: notRendering };
+
 	let contentId: string | undefined;
 
 	CaptureService.CaptureScreenshot((id: string) => {
@@ -82,14 +94,23 @@ function captureScreenshotData(): unknown {
 	while (contentId === undefined) {
 		if (tick() - startTime > 10) {
 			return {
-				error: "Screenshot capture timed out. Ensure the Studio viewport is visible and you are in Edit mode (not Play mode). Known Roblox bug: capture may fail if viewport renders a solid color.",
+				error: "Screenshot capture timed out (CaptureScreenshot callback never fired). The Studio window is likely minimized or occluded — restore it so the viewport renders. (Known Roblox bug: capture can also fail if the viewport renders a solid color.)",
 			};
 		}
 		task.wait(0.1);
 	}
 
+	return { contentId };
+}
+
+// Promotes a CaptureScreenshot content id into an EditableImage and reads its
+// RGBA pixels. MUST run in the edit/plugin context: the running game VM lacks
+// the privilege to create an EditableImage from a temporary texture id (errors
+// "cannot currently create editable image from temporary texture id"), while
+// the edit DM can — even for an id captured in the play client DM.
+function readContentToBase64(contentId: string): unknown {
 	const [editableOk, editableResult] = pcall(() => {
-		return AssetService.CreateEditableImageAsync(Content.fromUri(contentId!));
+		return AssetService.CreateEditableImageAsync(Content.fromUri(contentId));
 	});
 
 	if (!editableOk) {
@@ -118,11 +139,32 @@ function captureScreenshotData(): unknown {
 	return { success: true, width: w, height: h, data: base64Data };
 }
 
+// Edit-mode single shot: capture and read back in the same (edit) context.
+function captureScreenshotData(): unknown {
+	const cap = doCaptureScreenshot();
+	if ("error" in cap) return cap;
+	return readContentToBase64(cap.contentId);
+}
+
 function captureScreenshot(): unknown {
 	return captureScreenshotData();
 }
 
+// Play-mode step 1 (run on the CLIENT): capture only, return the temp id.
+function captureBegin(): unknown {
+	return doCaptureScreenshot();
+}
+
+// Play-mode step 2 (run on EDIT): read pixels from a temp id captured elsewhere.
+function captureRead(requestData: Record<string, unknown>): unknown {
+	const contentId = requestData.contentId as string | undefined;
+	if (!contentId) return { error: "contentId is required" };
+	return readContentToBase64(contentId);
+}
+
 export = {
 	captureScreenshotData,
 	captureScreenshot,
+	captureBegin,
+	captureRead,
 };