@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

package/plugin/src/handlers/Capture.luau

@@ -1,809 +1,818 @@
---!strict
---[[
-	Screenshots, so an agent can look at the place instead of inferring it.
-
-	Everything else this server exposes reads the data model: names, properties,
-	numbers. None of that answers "does it look right", which for a 3D medium is
-	most of the question. A part can sit at the correct position, anchored, the
-	right size, and still be inside a wall.
-
-	The path is four steps, none of them optional. `CaptureService` hands back a
-	temporary content id rather than pixels; `AssetService` turns that id into an
-	EditableImage; the image gives up raw RGBA; and PNG and base64 are written by
-	hand because the engine has neither. See Png.luau.
-]]
-
-local AssetService = game:GetService("AssetService")
-local CaptureService = game:GetService("CaptureService")
-local EncodingService = game:GetService("EncodingService")
-local Players = game:GetService("Players")
-local RunService = game:GetService("RunService")
-
-local Dispatch = require(script.Parent.Parent.Dispatch)
-local Emulation = require(script.Parent.Parent.Emulation)
-local Paths = require(script.Parent.Parent.Paths)
-local Png = require(script.Parent.Parent.Png)
-
--- Wide enough to read a GUI label, small enough that the encode stays quick and
--- the reply does not dominate the conversation it is part of.
-local DEFAULT_WIDTH = 800
-local MAX_WIDTH = 1600
-local MIN_WIDTH = 160
-
--- The callback has never taken close to this. It exists so a capture that never
--- calls back fails with something an agent can act on rather than hanging the
--- session until the request deadline.
-local CAPTURE_TIMEOUT = 10
-
--- Zstd level. 3 is its default and already gets most of the win on screen
--- content; the higher levels cost Studio's main thread for a few percent.
-local COMPRESSION_LEVEL = 3
-
-local Capture = {}
-
---[[
-	How far two channel values may differ and still count as the same colour.
-
-	Generous, because a surface that looks flat is not mathematically flat: PNG
-	round-tripping and Studio's own subtle gradients move a byte or two.
-]]
-local FLAT_SPREAD = 6
-
---[[
-	Fraction of sampled pixels that must match before the frame counts as empty.
-
-	Not 100%. This is the number two wrong versions of this check were missing:
-	a viewport showing nothing is never perfectly uniform -- Studio leaves its
-	settings gear and a loading mark in the corner, and those few hundred pixels
-	were enough to make an "is every pixel the same" test answer no. 99% leaves
-	room for that furniture while still being far below anything with a scene in
-	it: a horizon, a part, a skybox gradient or a GUI all move well past 1%.
-]]
-local FLAT_SHARE = 0.99
-
---[[
-	Every Nth pixel is looked at, not every pixel.
-
-	A 1656x674 capture is 1.1M pixels, and walking all of them in Luau to answer
-	a yes/no question costs more than the screenshot did. Sampling one in 16 is
-	11000 samples over a full frame -- far more than enough to notice that
-	something is drawn, and it cannot miss a scene, because a scene is not 16
-	pixels.
-]]
-local SAMPLE_STRIDE = 16
-
---[[
-	Whether the capture is empty: one colour, give or take the corner furniture.
-
-	Two earlier versions of this got it wrong in the same direction, and both
-	shipped a picture of nothing described as a picture of something.
-
-	The first asked "is every pixel black". Studio only returns pure black when
-	it is not rendering at all; when the 3D view is simply not the active tab,
-	the capture is the script editor's background -- a dark navy around 26-35 --
-	which sailed past a threshold of 8.
-
-	The second asked "is every pixel the same colour". Closer, and still no: the
-	empty viewport keeps Studio's settings gear in the top-right corner, so a
-	handful of pixels differ and the answer came back no again. The picture was
-	99% one colour and the test wanted 100%.
-
-	So the question is a proportion, not an absolute. What is being detected is
-	"nothing was drawn into this", and a frame with anything in it -- a part, a
-	horizon, a midnight skybox, a GUI -- puts far more than 1% of its pixels
-	somewhere else.
-]]
-local function isFlat(rgb: buffer): boolean
-	local length = buffer.len(rgb)
-	if length < 3 then
-		return true
-	end
-
-	local red = buffer.readu8(rgb, 0)
-	local green = buffer.readu8(rgb, 1)
-	local blue = buffer.readu8(rgb, 2)
-
-	local step = 3 * SAMPLE_STRIDE
-	local samples = 0
-	local matches = 0
-	for offset = 0, length - 3, step do
-		samples += 1
-		if
-			math.abs(buffer.readu8(rgb, offset) - red) <= FLAT_SPREAD
-			and math.abs(buffer.readu8(rgb, offset + 1) - green) <= FLAT_SPREAD
-			and math.abs(buffer.readu8(rgb, offset + 2) - blue) <= FLAT_SPREAD
-		then
-			matches += 1
-		end
-	end
-
-	return samples > 0 and (matches / samples) >= FLAT_SHARE
-end
-
--- Only a content id comes back over the remote, so this is the time to start a
--- LocalScript and take one shot, not to move any pixels.
-local CLIENT_TIMEOUT = 25
-
---[[
-	Screenshots during a playtest, taken by the client because only the client
-	may take them.
-
-	`CaptureService:CaptureScreenshot` refuses outright in the playtest's server
-	session -- "can only be called on the client" -- and the edit session, which
-	could call it, has stopped rendering its own data model and times out. Both
-	sessions this plugin can reach are therefore the wrong one, and for a long
-	time that was written down here as "screenshots are impossible mid-playtest".
-
-	They are not. The client is reachable the same way `input` reaches it: parent
-	a LocalScript into the player's PlayerGui and let it report back over a
-	RemoteEvent. The client cannot make HTTP requests, but it does not need to --
-	the server session it replicates to already holds an open bridge.
-
-	The client only takes the shot. It cannot read it: `CaptureService` hands
-	back a temporary texture id, and `CreateEditableImageAsync` refuses those at
-	script identity -- "cannot currently create editable image from temporary
-	texture id" -- which no amount of client-side code gets around.
-
-	The id is not client-local, though. It names a texture in the Studio
-	process, and the *editor* session's plugin runs there with plugin identity,
-	where the same call opens it without complaint. So the picture is taken in
-	one session and read in the other, and the pixels never cross a RemoteEvent
-	at all -- which also removes the size ceiling that a client-side encode had
-	to stay under. See `Capture.playtestId` and `Capture.decode`; `screenshot`
-	in the MCP server drives both halves.
-]]
-local CLIENT_SOURCE = [==[
-local CaptureService = game:GetService("CaptureService")
-local RunService = game:GetService("RunService")
-
-local relay = script
-local report = relay:WaitForChild("Report", 10)
-if report == nil then
-	return
-end
-
--- One rendered frame before the shot. The RemoteEvent is already a child of
--- this script when it lands, so `WaitForChild` returns at once and the capture
--- would otherwise happen on the frame the relay arrived -- which is the frame
--- least likely to have finished drawing. Roblox's own working repro for
--- CaptureService waits on PreRender first, and it costs a sixtieth of a second.
-pcall(function()
-	RunService.PreRender:Wait()
-end)
-
-local contentId = nil
-local okShot, shotErr = pcall(function()
-	CaptureService:CaptureScreenshot(function(id)
-		contentId = id
-	end)
-end)
-if not okShot then
-	report:FireServer({ ok = false, reason = tostring(shotErr) })
-	return
-end
-
-local waited = 0
-while contentId == nil and waited < 12 do
-	task.wait(0.05)
-	waited += 0.05
-end
-if contentId == nil then
-	report:FireServer({ ok = false, reason = "the client did not produce a screenshot within 12s" })
-	return
-end
-
-report:FireServer({ ok = true, contentId = contentId })
-]==]
-
---[[
-	Takes the shot and waits for the id.
-
-	`CaptureService:CaptureScreenshot` answers through a callback rather than
-	yielding, so this bridges the two: the handler is already running on its own
-	task and is free to wait.
-]]
-local function takeScreenshot(): string
-	local contentId: string? = nil
-	local failed: string? = nil
-
-	local ok, err = pcall(function()
-		CaptureService:CaptureScreenshot(function(id: string)
-			contentId = id
-		end)
-	end)
-	if not ok then
-		failed = tostring(err)
-	end
-
-	if failed ~= nil then
-		Dispatch.fail(
-			"CAPTURE_REFUSED",
-			string.format("Studio refused to take a screenshot: %s", failed)
-		)
-	end
-
-	--[[
-		A frame at a time to begin with, then a slower poll.
-
-		The callback normally fires within a frame or two, and a flat 0.05s wait
-		billed that to the agent as up to 50ms of doing nothing -- on a call
-		whose whole point is that it is taken often. `task.wait()` resumes on the
-		next heartbeat, so the common case now costs a frame; after a quarter of
-		a second the shot is clearly not coming back promptly and the poll drops
-		to the cheap interval for the rest of the timeout.
-	]]
-	local waited = 0
-	while contentId == nil and waited < CAPTURE_TIMEOUT do
-		waited += if waited < 0.25 then task.wait() else task.wait(0.05)
-	end
-
-	if contentId == nil then
-		Dispatch.fail(
-			"CAPTURE_TIMEOUT",
-			string.format("Studio did not return a screenshot within %ds.", CAPTURE_TIMEOUT),
-			"The viewport may be hidden or Studio may be busy; try again."
-		)
-	end
-
-	return contentId :: any
-end
-
---[[
-	Half a playtest screenshot: the client takes the shot, this returns its id.
-
-	Deliberately does not try to read it. The editor session does that, because
-	only plugin identity may -- see the note on CLIENT_SOURCE.
-]]
-function Capture.playtestId(_params: { [string]: any }): { [string]: any }
-	if RunService:IsEdit() or not RunService:IsRunning() then
-		Dispatch.fail(
-			"NOT_RUNNING",
-			"This is not a running playtest session, so there is no client to capture from.",
-			"Address this at the playtest's studioId from `list_studios`."
-		)
-	end
-
-	local players = Players:GetPlayers()
-	if #players == 0 then
-		Dispatch.fail(
-			"NO_PLAYER",
-			"No player is in this session, so there is no client to capture from.",
-			"Start a playtest with a character using `playtest op=\"play\"`."
-		)
-	end
-	local player = players[1]
-	local playerGui = player:FindFirstChildOfClass("PlayerGui")
-	if playerGui == nil then
-		Dispatch.fail("NO_PLAYER", string.format("%s has no PlayerGui yet.", player.Name))
-	end
-
-	local remote = Instance.new("RemoteEvent")
-	remote.Name = "Report"
-
-	local relay = Instance.new("LocalScript")
-	relay.Name = "MCPCaptureRelay"
-	relay.Source = CLIENT_SOURCE
-	remote.Parent = relay
-
-	local answer: { [string]: any }? = nil
-	local connection = remote.OnServerEvent:Connect(function(_from, payload)
-		if typeof(payload) == "table" then
-			answer = payload :: { [string]: any }
-		end
-	end)
-
-	-- Parented last, for the same reason as the input relay: the script runs the
-	-- instant it lands and immediately waits on the RemoteEvent.
-	relay.Parent = playerGui
-
-	local deadline = os.clock() + CLIENT_TIMEOUT
-	while answer == nil and os.clock() < deadline do
-		task.wait(0.05)
-	end
-
-	connection:Disconnect()
-	relay:Destroy()
-
-	if answer == nil then
-		Dispatch.fail(
-			"CAPTURE_TIMEOUT",
-			string.format("The client did not answer within %ds.", CLIENT_TIMEOUT),
-			"The client may still be loading; try again once the character has spawned."
-		)
-	end
-
-	local result = answer :: { [string]: any }
-	if result.ok ~= true then
-		Dispatch.fail("CAPTURE_REFUSED", string.format("The client could not capture: %s", tostring(result.reason)))
-	end
-
-	return { contentId = tostring(result.contentId), device = Emulation.deviceId() }
-end
-
---[[
-	Widest image the engine will create for us.
-
-	`AssetService:CreateEditableImage` caps at 1024 on either axis, and the
-	`width` parameter goes to 1600. Above the cap there is no destination to draw
-	into, so those calls fall back to the Luau loop rather than failing -- a
-	slower big screenshot, not a missing one.
-]]
-local ENGINE_SCALE_LIMIT = 1024
-
---[[
-	Drops alpha. RGBA in, RGB out, no scaling.
-
-	A screenshot has no alpha worth keeping and carrying it would add a quarter
-	to every byte that follows, so the channel goes here rather than on the wire.
-
-	Copied a word at a time rather than a byte at a time. Each 32-bit read takes
-	a whole pixel and each write lands three bytes further on, so the alpha byte
-	spills one place into the next pixel's slot -- where the next iteration
-	overwrites it. Only the final pixel has nothing following it, which is what
-	the one byte of slack on the buffer is for; the result is then trimmed to
-	the exact length so nothing downstream has to know about it.
-
-	Worth the trick: measured on a 799x359 frame, 16ms a byte at a time against
-	6-10ms this way, for output verified identical. That is most of what the
-	engine-side downscale costs, on a call agents make constantly.
-]]
-local function stripAlpha(rgba: buffer, width: number, height: number): buffer
-	local pixels = width * height
-	local length = pixels * 3
-
-	local wide = buffer.create(length + 1)
-	for index = 0, pixels - 1 do
-		buffer.writeu32(wide, index * 3, buffer.readu32(rgba, index * 4))
-	end
-
-	local out = buffer.create(length)
-	buffer.copy(out, 0, wide, 0, length)
-	return out
-end
-
---[[
-	Downscales on the engine's side instead of in Luau.
-
-	This is about the picture, not the clock. `SamplingMode` defaults to bilinear,
-	so a 2x reduction averages the pixels it merges; the Luau loop it replaces
-	took every other row and column and dropped the rest, which is how one-pixel
-	GUI text and thin edges vanished from screenshots that existed to answer
-	"does this look right".
-
-	It was written expecting to be faster too, and it is not -- that guess is
-	recorded here because the measurement is the useful part. On a 1370x616 frame
-	scaled to 799: the old full-resolution read costs about 1ms, not the large
-	number the 4.4MB of RGBA suggests, and the Luau downscale that follows runs
-	in 19-22ms all in. `DrawImageTransformed` alone is 16-17ms of engine time.
-	With `stripAlpha` doing the rest a word at a time, this path lands around
-	23ms -- a couple of milliseconds behind, on a call whose round trip is
-	measured in hundreds. Paying that for legible text is the trade; pretending
-	it was free would have been the mistake.
-
-	Returns nil when the engine cannot do it -- an older Studio without
-	`CreateEditableImage`, or a target past ENGINE_SCALE_LIMIT -- and the caller
-	falls back.
-]]
-local function resample(
-	source: any,
-	sourceWidth: number,
-	sourceHeight: number,
-	targetWidth: number
-): (buffer?, number, number)
-	local scale = math.min(1, targetWidth / sourceWidth)
-	local outWidth = math.max(1, math.floor(sourceWidth * scale))
-	local outHeight = math.max(1, math.floor(sourceHeight * scale))
-
-	if outWidth > ENGINE_SCALE_LIMIT or outHeight > ENGINE_SCALE_LIMIT then
-		return nil, 0, 0
-	end
-
-	local ok, rgb = pcall(function()
-		local canvas = (AssetService :: any):CreateEditableImage({
-			Size = Vector2.new(outWidth, outHeight),
-		})
-		--[[
-			Position is the centre, not the corner: `DrawImageTransformed` places
-			the source's PIVOT at the position given, and the pivot defaults to
-			the middle of the source image. Passing Vector2.zero here puts three
-			quarters of the frame off-canvas.
-		]]
-		local okDraw = pcall(function()
-			canvas:DrawImageTransformed(
-				Vector2.new(outWidth / 2, outHeight / 2),
-				Vector2.new(scale, scale),
-				0,
-				source,
-				{
-					CombineType = Enum.ImageCombineType.Overwrite,
-					SamplingMode = Enum.ResamplerMode.Default,
-				}
-			)
-		end)
-		if not okDraw then
-			canvas:Destroy()
-			error("draw failed", 0)
-		end
-
-		local pixels = canvas:ReadPixelsBuffer(Vector2.zero, canvas.Size)
-		-- Freed here rather than left to the collector: an EditableImage holds
-		-- its pixels outside Luau's heap, and a screenshot every few seconds
-		-- would otherwise pile them up for as long as Studio stays open.
-		canvas:Destroy()
-		return stripAlpha(pixels, outWidth, outHeight)
-	end)
-
-	if not ok then
-		return nil, 0, 0
-	end
-	return rgb :: buffer, outWidth, outHeight
-end
-
---[[
-	Turns a content id into pixels on the wire.
-
-	Split out from `screenshot` because a playtest shot is taken in one session
-	and read in another: the id is all that travels, and this is the reading
-	half, which needs plugin identity and therefore an editor session.
-]]
--- In capture pixels, or in viewport pixels when `viewportWidth` says so.
-export type Region = { x: number, y: number, width: number, height: number, viewportWidth: number? }
-
---[[
-	The full-resolution path: the captured pixels themselves, cropped to `region`
-	when one is given, compressed for the wire and scaled down in Node.
-
-	The engine resample below is bilinear, which only averages the pixels it
-	merges at exactly 2x -- beyond that it skips source pixels, and a 1661-wide
-	viewport scaled to 800 lost thin edges and broke small GUI text apart. Node
-	scales with a box filter instead, where every source pixel counts. Measured
-	cost of sending the full frame: ~60ms of a ~550ms call, most of which is the
-	engine's own capture.
-
-	Returns nil when this Studio cannot do it (no EncodingService), so the caller
-	falls back to the engine resample.
-]]
-local function encodeFull(
-	image: any,
-	sourceWidth: number,
-	sourceHeight: number,
-	width: number,
-	context: string,
-	region: Region?
-): { [string]: any }?
-	local x, y, w, h = 0, 0, sourceWidth, sourceHeight
-	if region then
-		-- Viewport and capture pixels differ under display scaling.
-		local ratio = if region.viewportWidth then sourceWidth / region.viewportWidth else 1
-		region = {
-			x = region.x * ratio,
-			y = region.y * ratio,
-			width = region.width * ratio,
-			height = region.height * ratio,
-		}
-		x = math.clamp(math.floor(region.x), 0, sourceWidth)
-		y = math.clamp(math.floor(region.y), 0, sourceHeight)
-		w = math.min(math.ceil(region.width), sourceWidth - x)
-		h = math.min(math.ceil(region.height), sourceHeight - y)
-		if w < 1 or h < 1 then
-			Dispatch.fail(
-				"REGION_OFFSCREEN",
-				string.format(
-					"The region (%d, %d, %d x %d) is outside the %d x %d viewport.",
-					region.x,
-					region.y,
-					region.width,
-					region.height,
-					sourceWidth,
-					sourceHeight
-				),
-				"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
-			)
-		end
-	end
-
-	local ok, result = pcall(function()
-		local rgba = image:ReadPixelsBuffer(Vector2.new(x, y), Vector2.new(w, h))
-		local rgb = stripAlpha(rgba, w, h)
-		local compressed = (EncodingService :: any):CompressBuffer(
-			rgb,
-			(Enum :: any).CompressionAlgorithm.Zstd,
-			COMPRESSION_LEVEL
-		)
-		return {
-			rgb = rgb,
-			packed = buffer.tostring((EncodingService :: any):Base64Encode(compressed)),
-		}
-	end)
-	if not ok then
-		return nil
-	end
-
-	return {
-		encoding = "zstd-rgb",
-		data = result.packed,
-		width = w,
-		height = h,
-		-- Node scales to this with a box filter; see above.
-		scaleTo = width,
-		sourceWidth = sourceWidth,
-		sourceHeight = sourceHeight,
-		region = if region then { x = x, y = y, width = w, height = h } else nil,
-		rawBytes = buffer.len(result.rgb),
-		bytes = #result.packed,
-		context = context,
-		black = isFlat(result.rgb),
-		device = Emulation.deviceId(),
-	}
-end
-
-local function encode(contentId: string, width: number, context: string, region: Region?): { [string]: any }
-	local okImage, image = pcall(function()
-		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
-	end)
-	if not okImage then
-		Dispatch.fail(
-			"CAPTURE_UNREADABLE",
-			string.format("The screenshot could not be opened for reading: %s", tostring(image))
-		)
-	end
-
-	local size = (image :: any).Size
-	local sourceWidth = math.floor(size.X)
-	local sourceHeight = math.floor(size.Y)
-
-	local full = encodeFull(image, sourceWidth, sourceHeight, width, context, region)
-	if full then
-		pcall(function()
-			(image :: any):Destroy()
-		end)
-		return full
-	end
-	if region then
-		Dispatch.fail(
-			"REGION_UNSUPPORTED",
-			"This Studio build cannot crop a screenshot (EncodingService is missing).",
-			"Take the full screenshot instead, or update Studio."
-		)
-	end
-
-	local rgb, outWidth, outHeight = resample(image, sourceWidth, sourceHeight, width)
-
-	if rgb == nil then
-		--[[
-			Both arguments are required. Called with none it reports "expects 2
-			arguments" rather than defaulting to the whole image, which is worth
-			stating because every other read on this object takes none.
-		]]
-		local okPixels, pixels = pcall(function()
-			return (image :: any):ReadPixelsBuffer(Vector2.zero, size)
-		end)
-		if not okPixels then
-			Dispatch.fail(
-				"CAPTURE_UNREADABLE",
-				string.format("The screenshot's pixels could not be read: %s", tostring(pixels))
-			)
-		end
-		rgb, outWidth, outHeight = Png.downscaleToRgb(pixels, sourceWidth, sourceHeight, width)
-	end
-
-	-- On the scaled image, not the source: the question is whether anything was
-	-- drawn, which survives the downscale, and it is a quarter of the pixels to
-	-- walk.
-	local black = isFlat(rgb :: buffer)
-
-	--[[
-		Raw pixels, compressed by the engine, assembled into a PNG by Node.
-
-		The plugin used to write the whole PNG itself, and could only write a bad
-		one: Studio has no deflate, so `Png.encode` emitted zlib *stored* blocks
-		-- the format's "compression not applied" escape hatch -- and every
-		screenshot travelled and landed at full uncompressed size. It was also
-		base64-ing by hand, a table lookup per byte in Luau.
-
-		`EncodingService` has both, natively. Zstd is the only algorithm the
-		engine exposes and PNG cannot use it, so the split is: the plugin
-		compresses the pixels for the wire, and Node -- which has real zlib --
-		decompresses and writes a properly deflated PNG. The side with the
-		compressor does the compressing.
-
-		Guarded rather than assumed: EncodingService is recent, and a Studio
-		without it should cost a bigger screenshot, not a failed one.
-	]]
-	local okPacked, packed = pcall(function()
-		local compressed = (EncodingService :: any):CompressBuffer(
-			rgb :: buffer,
-			(Enum :: any).CompressionAlgorithm.Zstd,
-			COMPRESSION_LEVEL
-		)
-		return buffer.tostring((EncodingService :: any):Base64Encode(compressed))
-	end)
-
-	if okPacked then
-		return {
-			encoding = "zstd-rgb",
-			data = packed,
-			width = outWidth,
-			height = outHeight,
-			sourceWidth = sourceWidth,
-			sourceHeight = sourceHeight,
-			rawBytes = buffer.len(rgb :: buffer),
-			bytes = #(packed :: string),
-			context = context,
-			black = black,
-			device = Emulation.deviceId(),
-		}
-	end
-
-	local png = Png.encode(rgb :: buffer, outWidth, outHeight)
-
-	return {
-		encoding = "png",
-		data = Png.base64(png),
-		width = outWidth,
-		height = outHeight,
-		sourceWidth = sourceWidth,
-		sourceHeight = sourceHeight,
-		bytes = buffer.len(png),
-		context = context,
-		black = black,
-		device = Emulation.deviceId(),
-	}
-end
-
--- Room left around a zoomed subject, as a share of its size, so its edges are
--- visible rather than cut exactly at the frame.
-local REGION_PADDING = 0.08
-
---[[
-	Where on screen a GUI element or a piece of the world is, in viewport pixels.
-
-	GUI positions leave out the top inset, so it is added back; a 3D subject is
-	the screen box around its bounding box's eight corners. A subject partly
-	behind the camera has no honest box, so that is refused with the fix.
-]]
-local function boundsOf(target: Instance): (Vector2, Vector2)
-	if target:IsA("GuiObject") then
-		local inset = game:GetService("GuiService"):GetGuiInset()
-		return target.AbsolutePosition + inset, target.AbsolutePosition + target.AbsoluteSize + inset
-	end
-
-	local cframe: CFrame, size: Vector3
-	if target:IsA("BasePart") then
-		cframe, size = target.CFrame, target.Size
-	elseif target:IsA("Model") then
-		cframe, size = target:GetBoundingBox()
-	else
-		local low, high = Vector3.one * math.huge, -Vector3.one * math.huge
-		local counted = 0
-		for _, descendant in target:GetDescendants() do
-			if descendant:IsA("BasePart") then
-				local half = descendant.Size / 2
-				for _, corner in { Vector3.new(-1, -1, -1), Vector3.new(1, 1, 1), Vector3.new(-1, 1, -1), Vector3.new(1, -1, 1) } do
-					local point = descendant.CFrame:PointToWorldSpace(half * corner)
-					low, high = low:Min(point), high:Max(point)
-				end
-				counted += 1
-				if counted >= 2000 then
-					break
-				end
-			end
-		end
-		if counted == 0 then
-			Dispatch.fail(
-				"NOT_VISUAL",
-				string.format("%s has no GUI or parts to zoom to.", target:GetFullName()),
-				"Zoom to a GuiObject, a BasePart, a Model, or a folder containing parts."
-			)
-		end
-		cframe, size = CFrame.new((low + high) / 2), high - low
-	end
-
-	local camera = workspace.CurrentCamera
-	local low, high = Vector2.one * math.huge, -Vector2.one * math.huge
-	for _, sx in { -1, 1 } do
-		for _, sy in { -1, 1 } do
-			for _, sz in { -1, 1 } do
-				local point, _ = camera:WorldToViewportPoint(cframe:PointToWorldSpace(size / 2 * Vector3.new(sx, sy, sz)))
-				if point.Z <= 0 then
-					Dispatch.fail(
-						"REGION_OFFSCREEN",
-						string.format("%s is partly behind the camera.", target:GetFullName()),
-						"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
-					)
-				end
-				local flat = Vector2.new(point.X, point.Y)
-				low, high = low:Min(flat), high:Max(flat)
-			end
-		end
-	end
-	return low, high
-end
-
---[[
-	The part of the capture to keep, in capture pixels.
-
-	`path` zooms to an instance; `rect` is "x, y, width, height" in the pixels of
-	the full-resolution capture, which every screenshot caption states. A path
-	is resolved before the capture, so a bad one fails without taking it.
-]]
-local function regionFor(params: { [string]: any }): Region?
-	if typeof(params.rect) == "string" and params.rect ~= "" then
-		local numbers = {}
-		for token in string.gmatch(params.rect, "-?[%d%.]+") do
-			table.insert(numbers, tonumber(token))
-		end
-		if #numbers ~= 4 or numbers[3] <= 0 or numbers[4] <= 0 then
-			Dispatch.fail("BAD_PARAMS", 'rect must be "x, y, width, height", e.g. "400, 200, 320, 180".')
-		end
-		return { x = numbers[1], y = numbers[2], width = numbers[3], height = numbers[4] }
-	end
-
-	if typeof(params.path) ~= "string" or params.path == "" then
-		return nil
-	end
-	local target = Paths.resolve(params.path)
-	local low, high = boundsOf(target)
-	local extent = high - low
-	local pad = Vector2.new(math.max(8, extent.X * REGION_PADDING), math.max(8, extent.Y * REGION_PADDING))
-	low, high = low - pad, high + pad
-	return {
-		x = low.X,
-		y = low.Y,
-		width = high.X - low.X,
-		height = high.Y - low.Y,
-		viewportWidth = workspace.CurrentCamera.ViewportSize.X,
-	}
-end
-
-function Capture.screenshot(params: { [string]: any }): { [string]: any }
-	--[[
-		Refused rather than half-done. A playtest screenshot needs two sessions
-		and only the MCP server can see both, so failing here with the reason is
-		better than returning the editor's own idle viewport, which looks like a
-		valid answer to "what does the player see".
-	]]
-	if RunService:IsRunning() and not RunService:IsEdit() then
-		Dispatch.fail(
-			"NEEDS_EDITOR_SESSION",
-			"A playtest screenshot is taken on the client and read in the editor session, "
-				.. "so it cannot be served from the playtest server alone.",
-			"Use the `screenshot` tool, which drives both halves. It needs the editor "
-				.. "session for the same place to still be connected."
-		)
-	end
-
-	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
-	-- Before the capture, so a path that does not resolve costs no screenshot.
-	local region = regionFor(params)
-	return encode(takeScreenshot(), width, if RunService:IsEdit() then "edit" else "playtest", region)
-end
-
---[[
-	Reads a content id someone else captured.
-
-	Only the editor session can do this, and only because the temporary texture
-	is owned by the Studio process rather than by the session that made it.
-]]
-function Capture.decode(params: { [string]: any }): { [string]: any }
-	local contentId = params.contentId
-	if typeof(contentId) ~= "string" or contentId == "" then
-		Dispatch.fail("BAD_PARAMS", "decode needs a `contentId`.")
-	end
-
-	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
-	local context = if typeof(params.context) == "string" then params.context else "playtest client"
-	-- Only `rect` here: a path would have to be resolved in the client's view.
-	local region = if typeof(params.rect) == "string" then regionFor({ rect = params.rect }) else nil
-	return encode(contentId :: string, width, context, region)
-end
-
-function Capture.register()
-	Dispatch.registerAll("capture", {
-		screenshot = Capture.screenshot,
-		playtestId = Capture.playtestId,
-		decode = Capture.decode,
-	})
-end
-
-return Capture
+--!strict
+--[[
+	Screenshots, so an agent can look at the place instead of inferring it.
+
+	Everything else this server exposes reads the data model: names, properties,
+	numbers. None of that answers "does it look right", which for a 3D medium is
+	most of the question. A part can sit at the correct position, anchored, the
+	right size, and still be inside a wall.
+
+	The path is four steps, none of them optional. `CaptureService` hands back a
+	temporary content id rather than pixels; `AssetService` turns that id into an
+	EditableImage; the image gives up raw RGBA; and PNG and base64 are written by
+	hand because the engine has neither. See Png.luau.
+]]
+
+local AssetService = game:GetService("AssetService")
+local CaptureService = game:GetService("CaptureService")
+local EncodingService = game:GetService("EncodingService")
+local Players = game:GetService("Players")
+local RunService = game:GetService("RunService")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Emulation = require(script.Parent.Parent.Emulation)
+local Paths = require(script.Parent.Parent.Paths)
+local Png = require(script.Parent.Parent.Png)
+
+-- Wide enough to read a GUI label, small enough that the encode stays quick and
+-- the reply does not dominate the conversation it is part of.
+local DEFAULT_WIDTH = 800
+local MAX_WIDTH = 1600
+local MIN_WIDTH = 160
+
+-- The callback has never taken close to this. It exists so a capture that never
+-- calls back fails with something an agent can act on rather than hanging the
+-- session until the request deadline.
+local CAPTURE_TIMEOUT = 10
+
+-- Zstd level. 3 is its default and already gets most of the win on screen
+-- content; the higher levels cost Studio's main thread for a few percent.
+local COMPRESSION_LEVEL = 3
+
+local Capture = {}
+
+--[[
+	How far two channel values may differ and still count as the same colour.
+
+	Generous, because a surface that looks flat is not mathematically flat: PNG
+	round-tripping and Studio's own subtle gradients move a byte or two.
+]]
+local FLAT_SPREAD = 6
+
+--[[
+	Fraction of sampled pixels that must match before the frame counts as empty.
+
+	Not 100%. This is the number two wrong versions of this check were missing:
+	a viewport showing nothing is never perfectly uniform -- Studio leaves its
+	settings gear and a loading mark in the corner, and those few hundred pixels
+	were enough to make an "is every pixel the same" test answer no. 99% leaves
+	room for that furniture while still being far below anything with a scene in
+	it: a horizon, a part, a skybox gradient or a GUI all move well past 1%.
+]]
+local FLAT_SHARE = 0.99
+
+--[[
+	Every Nth pixel is looked at, not every pixel.
+
+	A 1656x674 capture is 1.1M pixels, and walking all of them in Luau to answer
+	a yes/no question costs more than the screenshot did. Sampling one in 16 is
+	11000 samples over a full frame -- far more than enough to notice that
+	something is drawn, and it cannot miss a scene, because a scene is not 16
+	pixels.
+]]
+local SAMPLE_STRIDE = 16
+
+--[[
+	Whether the capture is empty: one colour, give or take the corner furniture.
+
+	Two earlier versions of this got it wrong in the same direction, and both
+	shipped a picture of nothing described as a picture of something.
+
+	The first asked "is every pixel black". Studio only returns pure black when
+	it is not rendering at all; when the 3D view is simply not the active tab,
+	the capture is the script editor's background -- a dark navy around 26-35 --
+	which sailed past a threshold of 8.
+
+	The second asked "is every pixel the same colour". Closer, and still no: the
+	empty viewport keeps Studio's settings gear in the top-right corner, so a
+	handful of pixels differ and the answer came back no again. The picture was
+	99% one colour and the test wanted 100%.
+
+	So the question is a proportion, not an absolute. What is being detected is
+	"nothing was drawn into this", and a frame with anything in it -- a part, a
+	horizon, a midnight skybox, a GUI -- puts far more than 1% of its pixels
+	somewhere else.
+]]
+local function isFlat(rgb: buffer): boolean
+	local length = buffer.len(rgb)
+	if length < 3 then
+		return true
+	end
+
+	local red = buffer.readu8(rgb, 0)
+	local green = buffer.readu8(rgb, 1)
+	local blue = buffer.readu8(rgb, 2)
+
+	local step = 3 * SAMPLE_STRIDE
+	local samples = 0
+	local matches = 0
+	for offset = 0, length - 3, step do
+		samples += 1
+		if
+			math.abs(buffer.readu8(rgb, offset) - red) <= FLAT_SPREAD
+			and math.abs(buffer.readu8(rgb, offset + 1) - green) <= FLAT_SPREAD
+			and math.abs(buffer.readu8(rgb, offset + 2) - blue) <= FLAT_SPREAD
+		then
+			matches += 1
+		end
+	end
+
+	return samples > 0 and (matches / samples) >= FLAT_SHARE
+end
+
+-- Only a content id comes back over the remote, so this is the time to start a
+-- LocalScript and take one shot, not to move any pixels.
+local CLIENT_TIMEOUT = 25
+
+--[[
+	Screenshots during a playtest, taken by the client because only the client
+	may take them.
+
+	`CaptureService:CaptureScreenshot` refuses outright in the playtest's server
+	session -- "can only be called on the client" -- and the edit session, which
+	could call it, has stopped rendering its own data model and times out. Both
+	sessions this plugin can reach are therefore the wrong one, and for a long
+	time that was written down here as "screenshots are impossible mid-playtest".
+
+	They are not. The client is reachable the same way `input` reaches it: parent
+	a LocalScript into the player's PlayerGui and let it report back over a
+	RemoteEvent. The client cannot make HTTP requests, but it does not need to --
+	the server session it replicates to already holds an open bridge.
+
+	The client only takes the shot. It cannot read it: `CaptureService` hands
+	back a temporary texture id, and `CreateEditableImageAsync` refuses those at
+	script identity -- "cannot currently create editable image from temporary
+	texture id" -- which no amount of client-side code gets around.
+
+	The id is not client-local, though. It names a texture in the Studio
+	process, and the *editor* session's plugin runs there with plugin identity,
+	where the same call opens it without complaint. So the picture is taken in
+	one session and read in the other, and the pixels never cross a RemoteEvent
+	at all -- which also removes the size ceiling that a client-side encode had
+	to stay under. See `Capture.playtestId` and `Capture.decode`; `screenshot`
+	in the MCP server drives both halves.
+]]
+local CLIENT_SOURCE = [==[
+local CaptureService = game:GetService("CaptureService")
+local RunService = game:GetService("RunService")
+
+local relay = script
+local report = relay:WaitForChild("Report", 10)
+if report == nil then
+	return
+end
+
+-- One rendered frame before the shot. The RemoteEvent is already a child of
+-- this script when it lands, so `WaitForChild` returns at once and the capture
+-- would otherwise happen on the frame the relay arrived -- which is the frame
+-- least likely to have finished drawing. Roblox's own working repro for
+-- CaptureService waits on PreRender first, and it costs a sixtieth of a second.
+pcall(function()
+	RunService.PreRender:Wait()
+end)
+
+local contentId = nil
+local okShot, shotErr = pcall(function()
+	CaptureService:CaptureScreenshot(function(id)
+		contentId = id
+	end)
+end)
+if not okShot then
+	report:FireServer({ ok = false, reason = tostring(shotErr) })
+	return
+end
+
+local waited = 0
+while contentId == nil and waited < 12 do
+	task.wait(0.05)
+	waited += 0.05
+end
+if contentId == nil then
+	report:FireServer({ ok = false, reason = "the client did not produce a screenshot within 12s" })
+	return
+end
+
+report:FireServer({ ok = true, contentId = contentId })
+]==]
+
+--[[
+	Takes the shot and waits for the id.
+
+	`CaptureService:CaptureScreenshot` answers through a callback rather than
+	yielding, so this bridges the two: the handler is already running on its own
+	task and is free to wait.
+]]
+local function takeScreenshot(): string
+	local contentId: string? = nil
+	local failed: string? = nil
+
+	local ok, err = pcall(function()
+		CaptureService:CaptureScreenshot(function(id: string)
+			contentId = id
+		end)
+	end)
+	if not ok then
+		failed = tostring(err)
+	end
+
+	if failed ~= nil then
+		Dispatch.fail(
+			"CAPTURE_REFUSED",
+			string.format("Studio refused to take a screenshot: %s", failed)
+		)
+	end
+
+	--[[
+		A frame at a time to begin with, then a slower poll.
+
+		The callback normally fires within a frame or two, and a flat 0.05s wait
+		billed that to the agent as up to 50ms of doing nothing -- on a call
+		whose whole point is that it is taken often. `task.wait()` resumes on the
+		next heartbeat, so the common case now costs a frame; after a quarter of
+		a second the shot is clearly not coming back promptly and the poll drops
+		to the cheap interval for the rest of the timeout.
+	]]
+	local waited = 0
+	while contentId == nil and waited < CAPTURE_TIMEOUT do
+		waited += if waited < 0.25 then task.wait() else task.wait(0.05)
+	end
+
+	if contentId == nil then
+		Dispatch.fail(
+			"CAPTURE_TIMEOUT",
+			string.format("Studio did not return a screenshot within %ds.", CAPTURE_TIMEOUT),
+			"The viewport may be hidden or Studio may be busy; try again."
+		)
+	end
+
+	return contentId :: any
+end
+
+--[[
+	Half a playtest screenshot: the client takes the shot, this returns its id.
+
+	Deliberately does not try to read it. The editor session does that, because
+	only plugin identity may -- see the note on CLIENT_SOURCE.
+]]
+function Capture.playtestId(params: { [string]: any }): { [string]: any }
+	if RunService:IsEdit() or not RunService:IsRunning() then
+		Dispatch.fail(
+			"NOT_RUNNING",
+			"This is not a running playtest session, so there is no client to capture from.",
+			"Address this at the playtest's studioId from `list_studios`."
+		)
+	end
+
+	local players = Players:GetPlayers()
+	if #players == 0 then
+		Dispatch.fail(
+			"NO_PLAYER",
+			"No player is in this session, so there is no client to capture from.",
+			"Start a playtest with a character using `playtest op=\"play\"`."
+		)
+	end
+	local player: Player? = nil
+	if params.player then
+		for _, candidate in players do if candidate.Name == params.player then player = candidate end end
+		if not player then Dispatch.fail("NO_PLAYER", "No player named " .. tostring(params.player)) end
+	elseif #players == 1 then
+		player = players[1]
+	else
+		Dispatch.fail("AMBIGUOUS_PLAYER", "Select a screenshot player by name.")
+	end
+	player = player :: Player
+	local playerGui = player:FindFirstChildOfClass("PlayerGui")
+	if playerGui == nil then
+		Dispatch.fail("NO_PLAYER", string.format("%s has no PlayerGui yet.", player.Name))
+	end
+
+	local remote = Instance.new("RemoteEvent")
+	remote.Name = "Report"
+
+	local relay = Instance.new("LocalScript")
+	relay.Name = "MCPCaptureRelay"
+	relay.Source = CLIENT_SOURCE
+	remote.Parent = relay
+
+	local answer: { [string]: any }? = nil
+	local connection = remote.OnServerEvent:Connect(function(_from, payload)
+		if typeof(payload) == "table" then
+			answer = payload :: { [string]: any }
+		end
+	end)
+
+	-- Parented last, for the same reason as the input relay: the script runs the
+	-- instant it lands and immediately waits on the RemoteEvent.
+	relay.Parent = playerGui
+
+	local deadline = os.clock() + CLIENT_TIMEOUT
+	while answer == nil and os.clock() < deadline do
+		task.wait(0.05)
+	end
+
+	connection:Disconnect()
+	relay:Destroy()
+
+	if answer == nil then
+		Dispatch.fail(
+			"CAPTURE_TIMEOUT",
+			string.format("The client did not answer within %ds.", CLIENT_TIMEOUT),
+			"The client may still be loading; try again once the character has spawned."
+		)
+	end
+
+	local result = answer :: { [string]: any }
+	if result.ok ~= true then
+		Dispatch.fail("CAPTURE_REFUSED", string.format("The client could not capture: %s", tostring(result.reason)))
+	end
+
+	return { contentId = tostring(result.contentId), device = Emulation.deviceId() }
+end
+
+--[[
+	Widest image the engine will create for us.
+
+	`AssetService:CreateEditableImage` caps at 1024 on either axis, and the
+	`width` parameter goes to 1600. Above the cap there is no destination to draw
+	into, so those calls fall back to the Luau loop rather than failing -- a
+	slower big screenshot, not a missing one.
+]]
+local ENGINE_SCALE_LIMIT = 1024
+
+--[[
+	Drops alpha. RGBA in, RGB out, no scaling.
+
+	A screenshot has no alpha worth keeping and carrying it would add a quarter
+	to every byte that follows, so the channel goes here rather than on the wire.
+
+	Copied a word at a time rather than a byte at a time. Each 32-bit read takes
+	a whole pixel and each write lands three bytes further on, so the alpha byte
+	spills one place into the next pixel's slot -- where the next iteration
+	overwrites it. Only the final pixel has nothing following it, which is what
+	the one byte of slack on the buffer is for; the result is then trimmed to
+	the exact length so nothing downstream has to know about it.
+
+	Worth the trick: measured on a 799x359 frame, 16ms a byte at a time against
+	6-10ms this way, for output verified identical. That is most of what the
+	engine-side downscale costs, on a call agents make constantly.
+]]
+local function stripAlpha(rgba: buffer, width: number, height: number): buffer
+	local pixels = width * height
+	local length = pixels * 3
+
+	local wide = buffer.create(length + 1)
+	for index = 0, pixels - 1 do
+		buffer.writeu32(wide, index * 3, buffer.readu32(rgba, index * 4))
+	end
+
+	local out = buffer.create(length)
+	buffer.copy(out, 0, wide, 0, length)
+	return out
+end
+
+--[[
+	Downscales on the engine's side instead of in Luau.
+
+	This is about the picture, not the clock. `SamplingMode` defaults to bilinear,
+	so a 2x reduction averages the pixels it merges; the Luau loop it replaces
+	took every other row and column and dropped the rest, which is how one-pixel
+	GUI text and thin edges vanished from screenshots that existed to answer
+	"does this look right".
+
+	It was written expecting to be faster too, and it is not -- that guess is
+	recorded here because the measurement is the useful part. On a 1370x616 frame
+	scaled to 799: the old full-resolution read costs about 1ms, not the large
+	number the 4.4MB of RGBA suggests, and the Luau downscale that follows runs
+	in 19-22ms all in. `DrawImageTransformed` alone is 16-17ms of engine time.
+	With `stripAlpha` doing the rest a word at a time, this path lands around
+	23ms -- a couple of milliseconds behind, on a call whose round trip is
+	measured in hundreds. Paying that for legible text is the trade; pretending
+	it was free would have been the mistake.
+
+	Returns nil when the engine cannot do it -- an older Studio without
+	`CreateEditableImage`, or a target past ENGINE_SCALE_LIMIT -- and the caller
+	falls back.
+]]
+local function resample(
+	source: any,
+	sourceWidth: number,
+	sourceHeight: number,
+	targetWidth: number
+): (buffer?, number, number)
+	local scale = math.min(1, targetWidth / sourceWidth)
+	local outWidth = math.max(1, math.floor(sourceWidth * scale))
+	local outHeight = math.max(1, math.floor(sourceHeight * scale))
+
+	if outWidth > ENGINE_SCALE_LIMIT or outHeight > ENGINE_SCALE_LIMIT then
+		return nil, 0, 0
+	end
+
+	local ok, rgb = pcall(function()
+		local canvas = (AssetService :: any):CreateEditableImage({
+			Size = Vector2.new(outWidth, outHeight),
+		})
+		--[[
+			Position is the centre, not the corner: `DrawImageTransformed` places
+			the source's PIVOT at the position given, and the pivot defaults to
+			the middle of the source image. Passing Vector2.zero here puts three
+			quarters of the frame off-canvas.
+		]]
+		local okDraw = pcall(function()
+			canvas:DrawImageTransformed(
+				Vector2.new(outWidth / 2, outHeight / 2),
+				Vector2.new(scale, scale),
+				0,
+				source,
+				{
+					CombineType = Enum.ImageCombineType.Overwrite,
+					SamplingMode = Enum.ResamplerMode.Default,
+				}
+			)
+		end)
+		if not okDraw then
+			canvas:Destroy()
+			error("draw failed", 0)
+		end
+
+		local pixels = canvas:ReadPixelsBuffer(Vector2.zero, canvas.Size)
+		-- Freed here rather than left to the collector: an EditableImage holds
+		-- its pixels outside Luau's heap, and a screenshot every few seconds
+		-- would otherwise pile them up for as long as Studio stays open.
+		canvas:Destroy()
+		return stripAlpha(pixels, outWidth, outHeight)
+	end)
+
+	if not ok then
+		return nil, 0, 0
+	end
+	return rgb :: buffer, outWidth, outHeight
+end
+
+--[[
+	Turns a content id into pixels on the wire.
+
+	Split out from `screenshot` because a playtest shot is taken in one session
+	and read in another: the id is all that travels, and this is the reading
+	half, which needs plugin identity and therefore an editor session.
+]]
+-- In capture pixels, or in viewport pixels when `viewportWidth` says so.
+export type Region = { x: number, y: number, width: number, height: number, viewportWidth: number? }
+
+--[[
+	The full-resolution path: the captured pixels themselves, cropped to `region`
+	when one is given, compressed for the wire and scaled down in Node.
+
+	The engine resample below is bilinear, which only averages the pixels it
+	merges at exactly 2x -- beyond that it skips source pixels, and a 1661-wide
+	viewport scaled to 800 lost thin edges and broke small GUI text apart. Node
+	scales with a box filter instead, where every source pixel counts. Measured
+	cost of sending the full frame: ~60ms of a ~550ms call, most of which is the
+	engine's own capture.
+
+	Returns nil when this Studio cannot do it (no EncodingService), so the caller
+	falls back to the engine resample.
+]]
+local function encodeFull(
+	image: any,
+	sourceWidth: number,
+	sourceHeight: number,
+	width: number,
+	context: string,
+	region: Region?
+): { [string]: any }?
+	local x, y, w, h = 0, 0, sourceWidth, sourceHeight
+	if region then
+		-- Viewport and capture pixels differ under display scaling.
+		local ratio = if region.viewportWidth then sourceWidth / region.viewportWidth else 1
+		region = {
+			x = region.x * ratio,
+			y = region.y * ratio,
+			width = region.width * ratio,
+			height = region.height * ratio,
+		}
+		x = math.clamp(math.floor(region.x), 0, sourceWidth)
+		y = math.clamp(math.floor(region.y), 0, sourceHeight)
+		w = math.min(math.ceil(region.width), sourceWidth - x)
+		h = math.min(math.ceil(region.height), sourceHeight - y)
+		if w < 1 or h < 1 then
+			Dispatch.fail(
+				"REGION_OFFSCREEN",
+				string.format(
+					"The region (%d, %d, %d x %d) is outside the %d x %d viewport.",
+					region.x,
+					region.y,
+					region.width,
+					region.height,
+					sourceWidth,
+					sourceHeight
+				),
+				"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
+			)
+		end
+	end
+
+	local ok, result = pcall(function()
+		local rgba = image:ReadPixelsBuffer(Vector2.new(x, y), Vector2.new(w, h))
+		local rgb = stripAlpha(rgba, w, h)
+		local compressed = (EncodingService :: any):CompressBuffer(
+			rgb,
+			(Enum :: any).CompressionAlgorithm.Zstd,
+			COMPRESSION_LEVEL
+		)
+		return {
+			rgb = rgb,
+			packed = buffer.tostring((EncodingService :: any):Base64Encode(compressed)),
+		}
+	end)
+	if not ok then
+		return nil
+	end
+
+	return {
+		encoding = "zstd-rgb",
+		data = result.packed,
+		width = w,
+		height = h,
+		-- Node scales to this with a box filter; see above.
+		scaleTo = width,
+		sourceWidth = sourceWidth,
+		sourceHeight = sourceHeight,
+		region = if region then { x = x, y = y, width = w, height = h } else nil,
+		rawBytes = buffer.len(result.rgb),
+		bytes = #result.packed,
+		context = context,
+		black = isFlat(result.rgb),
+		device = Emulation.deviceId(),
+	}
+end
+
+local function encode(contentId: string, width: number, context: string, region: Region?): { [string]: any }
+	local okImage, image = pcall(function()
+		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
+	end)
+	if not okImage then
+		Dispatch.fail(
+			"CAPTURE_UNREADABLE",
+			string.format("The screenshot could not be opened for reading: %s", tostring(image))
+		)
+	end
+
+	local size = (image :: any).Size
+	local sourceWidth = math.floor(size.X)
+	local sourceHeight = math.floor(size.Y)
+
+	local full = encodeFull(image, sourceWidth, sourceHeight, width, context, region)
+	if full then
+		pcall(function()
+			(image :: any):Destroy()
+		end)
+		return full
+	end
+	if region then
+		Dispatch.fail(
+			"REGION_UNSUPPORTED",
+			"This Studio build cannot crop a screenshot (EncodingService is missing).",
+			"Take the full screenshot instead, or update Studio."
+		)
+	end
+
+	local rgb, outWidth, outHeight = resample(image, sourceWidth, sourceHeight, width)
+
+	if rgb == nil then
+		--[[
+			Both arguments are required. Called with none it reports "expects 2
+			arguments" rather than defaulting to the whole image, which is worth
+			stating because every other read on this object takes none.
+		]]
+		local okPixels, pixels = pcall(function()
+			return (image :: any):ReadPixelsBuffer(Vector2.zero, size)
+		end)
+		if not okPixels then
+			Dispatch.fail(
+				"CAPTURE_UNREADABLE",
+				string.format("The screenshot's pixels could not be read: %s", tostring(pixels))
+			)
+		end
+		rgb, outWidth, outHeight = Png.downscaleToRgb(pixels, sourceWidth, sourceHeight, width)
+	end
+
+	-- On the scaled image, not the source: the question is whether anything was
+	-- drawn, which survives the downscale, and it is a quarter of the pixels to
+	-- walk.
+	local black = isFlat(rgb :: buffer)
+
+	--[[
+		Raw pixels, compressed by the engine, assembled into a PNG by Node.
+
+		The plugin used to write the whole PNG itself, and could only write a bad
+		one: Studio has no deflate, so `Png.encode` emitted zlib *stored* blocks
+		-- the format's "compression not applied" escape hatch -- and every
+		screenshot travelled and landed at full uncompressed size. It was also
+		base64-ing by hand, a table lookup per byte in Luau.
+
+		`EncodingService` has both, natively. Zstd is the only algorithm the
+		engine exposes and PNG cannot use it, so the split is: the plugin
+		compresses the pixels for the wire, and Node -- which has real zlib --
+		decompresses and writes a properly deflated PNG. The side with the
+		compressor does the compressing.
+
+		Guarded rather than assumed: EncodingService is recent, and a Studio
+		without it should cost a bigger screenshot, not a failed one.
+	]]
+	local okPacked, packed = pcall(function()
+		local compressed = (EncodingService :: any):CompressBuffer(
+			rgb :: buffer,
+			(Enum :: any).CompressionAlgorithm.Zstd,
+			COMPRESSION_LEVEL
+		)
+		return buffer.tostring((EncodingService :: any):Base64Encode(compressed))
+	end)
+
+	if okPacked then
+		return {
+			encoding = "zstd-rgb",
+			data = packed,
+			width = outWidth,
+			height = outHeight,
+			sourceWidth = sourceWidth,
+			sourceHeight = sourceHeight,
+			rawBytes = buffer.len(rgb :: buffer),
+			bytes = #(packed :: string),
+			context = context,
+			black = black,
+			device = Emulation.deviceId(),
+		}
+	end
+
+	local png = Png.encode(rgb :: buffer, outWidth, outHeight)
+
+	return {
+		encoding = "png",
+		data = Png.base64(png),
+		width = outWidth,
+		height = outHeight,
+		sourceWidth = sourceWidth,
+		sourceHeight = sourceHeight,
+		bytes = buffer.len(png),
+		context = context,
+		black = black,
+		device = Emulation.deviceId(),
+	}
+end
+
+-- Room left around a zoomed subject, as a share of its size, so its edges are
+-- visible rather than cut exactly at the frame.
+local REGION_PADDING = 0.08
+
+--[[
+	Where on screen a GUI element or a piece of the world is, in viewport pixels.
+
+	GUI positions leave out the top inset, so it is added back; a 3D subject is
+	the screen box around its bounding box's eight corners. A subject partly
+	behind the camera has no honest box, so that is refused with the fix.
+]]
+local function boundsOf(target: Instance): (Vector2, Vector2)
+	if target:IsA("GuiObject") then
+		local inset = game:GetService("GuiService"):GetGuiInset()
+		return target.AbsolutePosition + inset, target.AbsolutePosition + target.AbsoluteSize + inset
+	end
+
+	local cframe: CFrame, size: Vector3
+	if target:IsA("BasePart") then
+		cframe, size = target.CFrame, target.Size
+	elseif target:IsA("Model") then
+		cframe, size = target:GetBoundingBox()
+	else
+		local low, high = Vector3.one * math.huge, -Vector3.one * math.huge
+		local counted = 0
+		for _, descendant in target:GetDescendants() do
+			if descendant:IsA("BasePart") then
+				local half = descendant.Size / 2
+				for _, corner in { Vector3.new(-1, -1, -1), Vector3.new(1, 1, 1), Vector3.new(-1, 1, -1), Vector3.new(1, -1, 1) } do
+					local point = descendant.CFrame:PointToWorldSpace(half * corner)
+					low, high = low:Min(point), high:Max(point)
+				end
+				counted += 1
+				if counted >= 2000 then
+					break
+				end
+			end
+		end
+		if counted == 0 then
+			Dispatch.fail(
+				"NOT_VISUAL",
+				string.format("%s has no GUI or parts to zoom to.", target:GetFullName()),
+				"Zoom to a GuiObject, a BasePart, a Model, or a folder containing parts."
+			)
+		end
+		cframe, size = CFrame.new((low + high) / 2), high - low
+	end
+
+	local camera = workspace.CurrentCamera
+	local low, high = Vector2.one * math.huge, -Vector2.one * math.huge
+	for _, sx in { -1, 1 } do
+		for _, sy in { -1, 1 } do
+			for _, sz in { -1, 1 } do
+				local point, _ = camera:WorldToViewportPoint(cframe:PointToWorldSpace(size / 2 * Vector3.new(sx, sy, sz)))
+				if point.Z <= 0 then
+					Dispatch.fail(
+						"REGION_OFFSCREEN",
+						string.format("%s is partly behind the camera.", target:GetFullName()),
+						"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
+					)
+				end
+				local flat = Vector2.new(point.X, point.Y)
+				low, high = low:Min(flat), high:Max(flat)
+			end
+		end
+	end
+	return low, high
+end
+
+--[[
+	The part of the capture to keep, in capture pixels.
+
+	`path` zooms to an instance; `rect` is "x, y, width, height" in the pixels of
+	the full-resolution capture, which every screenshot caption states. A path
+	is resolved before the capture, so a bad one fails without taking it.
+]]
+local function regionFor(params: { [string]: any }): Region?
+	if typeof(params.rect) == "string" and params.rect ~= "" then
+		local numbers = {}
+		for token in string.gmatch(params.rect, "-?[%d%.]+") do
+			table.insert(numbers, tonumber(token))
+		end
+		if #numbers ~= 4 or numbers[3] <= 0 or numbers[4] <= 0 then
+			Dispatch.fail("BAD_PARAMS", 'rect must be "x, y, width, height", e.g. "400, 200, 320, 180".')
+		end
+		return { x = numbers[1], y = numbers[2], width = numbers[3], height = numbers[4] }
+	end
+
+	if typeof(params.path) ~= "string" or params.path == "" then
+		return nil
+	end
+	local target = Paths.resolve(params.path)
+	local low, high = boundsOf(target)
+	local extent = high - low
+	local pad = Vector2.new(math.max(8, extent.X * REGION_PADDING), math.max(8, extent.Y * REGION_PADDING))
+	low, high = low - pad, high + pad
+	return {
+		x = low.X,
+		y = low.Y,
+		width = high.X - low.X,
+		height = high.Y - low.Y,
+		viewportWidth = workspace.CurrentCamera.ViewportSize.X,
+	}
+end
+
+function Capture.screenshot(params: { [string]: any }): { [string]: any }
+	--[[
+		Refused rather than half-done. A playtest screenshot needs two sessions
+		and only the MCP server can see both, so failing here with the reason is
+		better than returning the editor's own idle viewport, which looks like a
+		valid answer to "what does the player see".
+	]]
+	if RunService:IsRunning() and not RunService:IsEdit() then
+		Dispatch.fail(
+			"NEEDS_EDITOR_SESSION",
+			"A playtest screenshot is taken on the client and read in the editor session, "
+				.. "so it cannot be served from the playtest server alone.",
+			"Use the `screenshot` tool, which drives both halves. It needs the editor "
+				.. "session for the same place to still be connected."
+		)
+	end
+
+	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
+	-- Before the capture, so a path that does not resolve costs no screenshot.
+	local region = regionFor(params)
+	return encode(takeScreenshot(), width, if RunService:IsEdit() then "edit" else "playtest", region)
+end
+
+--[[
+	Reads a content id someone else captured.
+
+	Only the editor session can do this, and only because the temporary texture
+	is owned by the Studio process rather than by the session that made it.
+]]
+function Capture.decode(params: { [string]: any }): { [string]: any }
+	local contentId = params.contentId
+	if typeof(contentId) ~= "string" or contentId == "" then
+		Dispatch.fail("BAD_PARAMS", "decode needs a `contentId`.")
+	end
+
+	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
+	local context = if typeof(params.context) == "string" then params.context else "playtest client"
+	-- Only `rect` here: a path would have to be resolved in the client's view.
+	local region = if typeof(params.rect) == "string" then regionFor({ rect = params.rect }) else nil
+	return encode(contentId :: string, width, context, region)
+end
+
+function Capture.register()
+	Dispatch.registerAll("capture", {
+		screenshot = Capture.screenshot,
+		playtestId = Capture.playtestId,
+		decode = Capture.decode,
+	})
+end
+
+return Capture