@el4cteo/rbx-studio-mcp 0.7.7 → 0.7.8

package/plugin/src/handlers/Perf.luau

@@ -1,889 +1,913 @@
---!strict
---[[
-	Output and performance: the Developer Console and Script Performance windows,
-	readable by an agent.
-
-	These are the panels a developer opens when something is slow or broken, and
-	no other Studio MCP server exposes them. Being able to say "which script is
-	eating the frame" without the user reading a graph and describing it back is
-	the difference between diagnosing a problem and guessing at one.
-
-	`Stats` time properties are in seconds and reported here in milliseconds,
-	because every frame budget a developer reasons about is quoted in ms.
-]]
-
-local ScriptContext = game:GetService("ScriptContext")
-local RunService = game:GetService("RunService")
-local SceneAnalysisService = game:GetService("SceneAnalysisService")
-local ScriptProfilerService = game:GetService("ScriptProfilerService")
-local Stats = game:GetService("Stats")
-
-local Dispatch = require(script.Parent.Parent.Dispatch)
-local LogBuffer = require(script.Parent.Parent.LogBuffer)
-local Paths = require(script.Parent.Parent.Paths)
-local Scope = require(script.Parent.Parent.Scope)
-
--- The log holds thousands of lines in a busy session; an unbounded tail would
--- swamp any context window.
-local MAX_LOG_ENTRIES = 500
-local DEFAULT_LOG_ENTRIES = 100
-
--- Profiling is a blocking wait, so the ceiling is what a caller will sit through
--- rather than what the profiler can manage.
-local MAX_PROFILE_SECONDS = 30
-local DEFAULT_PROFILE_SECONDS = 5
-local PROFILE_DATA_TIMEOUT = 5
-
--- Uncovered line numbers are listed, not just counted, but a script that never
--- ran at all would otherwise list every line it has.
-local MAX_UNCOVERED_LINES = 50
-
-local Perf = {}
-
-local function round(value: number, places: number): number
-	local scale = 10 ^ places
-	return math.floor(value * scale + 0.5) / scale
-end
-
---[[
-	Reads a Stats property without assuming it exists. The set has changed across
-	engine versions, and one missing counter should not fail the whole snapshot.
-]]
-local function stat(name: string): number?
-	local ok, value = pcall(function()
-		return (Stats :: any)[name]
-	end)
-	if ok and typeof(value) == "number" then
-		return value
-	end
-	return nil
-end
-
-local function millis(name: string): number?
-	local seconds = stat(name)
-	return if seconds then round(seconds * 1000, 3) else nil
-end
-
-local function flag(name: string): boolean?
-	local ok, value = pcall(function()
-		return (Stats :: any)[name]
-	end)
-	if ok and typeof(value) == "boolean" then
-		return value
-	end
-	return nil
-end
-
-local function rounded(name: string, places: number): number?
-	local value = stat(name)
-	return if value then round(value, places) else nil
-end
-
---[[
-	The output log, newest last.
-
-	Ordering matters: an agent reading a tail wants the most recent lines at the
-	bottom, the same way the Output window reads, so an error and the lines that
-	led to it stay in the order they happened.
-]]
-function Perf.console(params: { [string]: any }): { [string]: any }
-	local limit = math.clamp(tonumber(params.limit) or DEFAULT_LOG_ENTRIES, 1, MAX_LOG_ENTRIES)
-	local level = params.level
-	local pattern = params.pattern
-
-	-- Read from our own buffer, not LogService:GetLogHistory(). See LogBuffer for
-	-- why: the engine's history stops growing after startup in an editor session
-	-- and is empty outright in a playtest, without reporting either as a failure.
-	local history, evicted = LogBuffer.all()
-
-	local entries: { { [string]: any } } = {}
-	local matched = 0
-
-	for _, item in history do
-		local kind = item.level
-		if level and kind ~= level then
-			continue
-		end
-
-		local message = item.message
-		if pattern then
-			-- An invalid pattern raises rather than failing to match, so it is
-			-- reported as a pattern problem instead of an empty result.
-			local valid, position = pcall(string.find, message, pattern)
-			if not valid then
-				Dispatch.fail(
-					"BAD_PATTERN",
-					string.format("%s is not a valid Lua pattern: %s", pattern, tostring(position)),
-					"Lua patterns escape with %, not backslash. Omit `pattern` to see everything."
-				)
-			end
-			if position == nil then
-				continue
-			end
-		end
-
-		matched += 1
-		table.insert(entries, {
-			level = kind,
-			message = message,
-			timestamp = item.timestamp,
-			stack = item.stack,
-			source = item.source,
-		})
-	end
-
-	-- Trimmed from the front: the newest lines are the ones worth keeping.
-	local dropped = 0
-	if #entries > limit then
-		dropped = #entries - limit
-		entries = table.move(entries, dropped + 1, #entries, 1, {})
-	end
-
-	return {
-		items = entries,
-		total = matched,
-		dropped = dropped,
-		-- Lines lost to the buffer's own capacity, as opposed to ones trimmed to
-		-- satisfy this call's limit. Only the first is a reason to worry.
-		evicted = if evicted > 0 then evicted else nil,
-		recordingSeconds = LogBuffer.recordingSeconds(),
-	}
-end
-
---[[
-	A snapshot of the engine's own counters -- what the Developer Console shows on
-	its Performance and Memory tabs.
-]]
-function Perf.snapshot(): { [string]: any }
-	--[[
-		Read one tag at a time, not with `GetMemoryUsageMbAllCategories`.
-
-		The aggregate call is the obvious one and is closed to us: it now requires
-		the InternalTest capability, so from a plugin it only ever raises "the
-		current thread cannot call 'GetMemoryUsageMbAllCategories'". Measured, not
-		assumed -- and the same refusal comes back in an editor session and in a
-		playtest, so there is no context in which waiting for it pays off.
-
-		`GetMemoryUsageMbForTag` carries no such restriction, and walking
-		`Enum.DeveloperMemoryTag` reaches every category the Developer Console's
-		Memory tab shows. Zero-valued tags are dropped so the list stays readable.
-	]]
-	local memory: { { [string]: any } } = {}
-	local memoryProblem: string? = nil
-
-	for _, tag in Enum.DeveloperMemoryTag:GetEnumItems() do
-		local ok, value = pcall(function()
-			return Stats:GetMemoryUsageMbForTag(tag)
-		end)
-		if not ok then
-			-- One refusal means the whole route is shut, not that this tag is
-			-- special; stop rather than repeat the same failure for every item.
-			memoryProblem = string.format("Stats refused the call: %s", tostring(value))
-			break
-		end
-		if typeof(value) == "number" and value > 0 then
-			table.insert(memory, { category = tag.Name, megabytes = round(value, 2) })
-		end
-	end
-
-	table.sort(memory, function(a, b)
-		return a.megabytes > b.megabytes
-	end)
-
-	local okTotal, total = pcall(function()
-		return Stats:GetTotalMemoryUsageMb()
-	end)
-
-	--[[
-		A playtest server has no renderer, so every drawing counter reads zero --
-		zero draw calls, zero triangles, no frame time. Left unexplained that is
-		the most flattering possible misreading of a place's performance, so the
-		snapshot says outright that those numbers are absent rather than good.
-	]]
-	local headless = RunService:IsRunning() and RunService:IsServer() and not RunService:IsClient()
-
-	return {
-		renderless = headless or nil,
-		frame = {
-			frameTimeMs = millis("FrameTime"),
-			heartbeatTimeMs = millis("HeartbeatTime"),
-			physicsStepTimeMs = millis("PhysicsStepTime"),
-			renderCpuMs = millis("RenderCPUFrameTime"),
-			renderGpuMs = millis("RenderGPUFrameTime"),
-		},
-		scene = {
-			instances = stat("InstanceCount"),
-			parts = stat("PrimitivesCount"),
-			movingParts = stat("MovingPrimitivesCount"),
-			contacts = stat("ContactsCount"),
-			drawcalls = stat("SceneDrawcallCount"),
-			triangles = stat("SceneTriangleCount"),
-		},
-		network = {
-			receiveKbps = rounded("DataReceiveKbps", 1),
-			sendKbps = rounded("DataSendKbps", 1),
-		},
-		memory = {
-			totalMb = if okTotal and typeof(total) == "number" then round(total, 1) else nil,
-			-- Studio only accumulates the per-category breakdown while this is on,
-			-- so an empty list means "not measured" rather than "nothing used".
-			trackingEnabled = flag("MemoryTrackingEnabled"),
-			categories = memory,
-			problem = if #memory == 0 then memoryProblem else nil,
-		},
-	}
-end
-
---[[
-	Runs the script profiler for a while and returns what it collected.
-
-	This is the Script Performance window. The profiler samples at `frequency` Hz
-	and reports back through an event rather than a return value, so the call
-	starts it, waits, asks for the data, and stops -- blocking for the duration,
-	which is why the ceiling is short.
-
-	The payload's shape is Roblox's own and undocumented, so it is passed through
-	rather than reshaped into something that might quietly misreport which script
-	is expensive.
-]]
-function Perf.profile(params: { [string]: any }): { [string]: any }
-	local seconds = math.clamp(
-		tonumber(params.seconds) or DEFAULT_PROFILE_SECONDS,
-		1,
-		MAX_PROFILE_SECONDS
-	)
-	local frequency = math.clamp(tonumber(params.frequency) or 1000, 100, 10000)
-
-	local received: string? = nil
-	local connection = ScriptProfilerService.OnNewData:Connect(function(_player, jsonString)
-		received = jsonString
-	end)
-
-	local started, startError = pcall(function()
-		ScriptProfilerService:ServerStart(frequency)
-	end)
-	if not started then
-		connection:Disconnect()
-		Dispatch.fail(
-			"PROFILER_UNAVAILABLE",
-			string.format("Could not start the script profiler: %s", tostring(startError)),
-			"The profiler is only available in Studio, and only one session at a time."
-		)
-	end
-
-	task.wait(seconds)
-
-	pcall(function()
-		ScriptProfilerService:ServerRequestData()
-	end)
-
-	-- The data arrives on the event, so the request is followed by a bounded wait
-	-- rather than assuming it has already landed.
-	local deadline = os.clock() + PROFILE_DATA_TIMEOUT
-	while received == nil and os.clock() < deadline do
-		task.wait(0.1)
-	end
-
-	pcall(function()
-		ScriptProfilerService:ServerStop()
-	end)
-	connection:Disconnect()
-
-	if received == nil then
-		Dispatch.fail(
-			"NO_PROFILE_DATA",
-			string.format("The profiler ran for %ds but returned no data.", seconds),
-			"Nothing ran during the sample. Start a playtest first, or profile for longer."
-		)
-	end
-
-	local okParse, parsed = pcall(function()
-		return ScriptProfilerService:DeserializeJSON(received)
-	end)
-
-	return {
-		seconds = seconds,
-		frequency = frequency,
-		data = if okParse then parsed else nil,
-		raw = if okParse then nil else received,
-	}
-end
-
---[[
-	Which scripts to instrument the moment a session starts.
-
-	`EnableCoverage` applies to the DataModel it is called in, and a playtest is a
-	different DataModel, built when Play is pressed. So enabling from the editor
-	and then playing -- the sequence this tool used to instruct -- instruments the
-	editor and measures the playtest, which is why it reported nothing at all: the
-	editor never ran the code, and the playtest was never instrumented.
-
-	Nothing can be enabled from outside in time either, because a playtest's
-	scripts start with the DataModel. The request has to be waiting before the
-	session exists, so it is remembered here and replayed by whichever session
-	loads next.
-
-	Kept per place. Plugin settings live in one file shared by every Studio
-	process, so a path remembered while working on one game would otherwise be
-	resolved against a different one.
-]]
-local COVERAGE_SETTING = "coverageTargets"
-local pluginRef: Plugin? = nil
-local carriedOver: { string } = {}
-local carriedFailed: { { [string]: any } } = {}
-
-local function rememberCoverage(paths: { string })
-	local host = pluginRef
-	if host == nil then
-		return
-	end
-	pcall(function()
-		(host :: Plugin):SetSetting(COVERAGE_SETTING, {
-			placeId = game.PlaceId,
-			paths = paths,
-		})
-	end)
-end
-
-local function rememberedCoverage(): { string }
-	local host = pluginRef
-	if host == nil then
-		return {}
-	end
-	local ok, stored = pcall(function()
-		return (host :: Plugin):GetSetting(COVERAGE_SETTING)
-	end)
-	if not ok or typeof(stored) ~= "table" then
-		return {}
-	end
-	local record = stored :: { [string]: any }
-	if record.placeId ~= game.PlaceId or typeof(record.paths) ~= "table" then
-		return {}
-	end
-	return record.paths :: { string }
-end
-
---[[
-	Line coverage: which lines of which scripts actually ran.
-
-	Coverage has to be switched on for a script before that script executes, so a
-	call that only reads the stats reports nothing on a first run. `enable` turns
-	it on for named scripts and remembers them for the next session to switch on
-	for itself; the caller then plays, and reads back from the playtest.
-]]
-function Perf.coverage(params: { [string]: any }): { [string]: any }
-	local enabled: { string } = {}
-	-- Distinguished from absent on purpose: an explicit empty list is how a
-	-- caller stops instrumenting every future session for this place.
-	local requested = params.enable
-	for _, path in (requested or {}) :: { string } do
-		local target = Paths.resolve(path)
-		local ok = pcall(function()
-			ScriptContext:EnableCoverage(target)
-		end)
-		if ok then
-			table.insert(enabled, Paths.of(target))
-		end
-	end
-	if requested ~= nil then
-		rememberCoverage(enabled)
-	end
-
-	local ok, stats = pcall(function()
-		return ScriptContext:GetCoverageStats()
-	end)
-	if not ok or typeof(stats) ~= "table" then
-		return { enabled = enabled, scripts = {}, problem = tostring(stats) }
-	end
-
-	--[[
-		The payload is undocumented, so this is the shape measured from a real
-		capture rather than a guess: each entry is `{ Script = Instance, GetHits =
-		function }`, and `GetHits()` returns an array indexed by line number.
-
-		The values carry three distinct meanings, and conflating them is what an
-		earlier attempt here did:
-		  -1  the line cannot be instrumented at all -- blank, a comment, an `end`
-		   0  instrumented and never executed: the lines worth reporting
-		  >0  the number of times it ran
-
-		Counting every element as instrumented drags the denominator up by every
-		blank line and comment in the file, which understates coverage on exactly
-		the well-commented code most likely to be measured.
-	]]
-	local scripts: { { [string]: any } } = {}
-	local unrecognised: any = nil
-
-	for _, entry in stats :: { any } do
-		if typeof(entry) ~= "table" then
-			unrecognised = stats
-			break
-		end
-
-		local record = entry :: { [string]: any }
-		local target = record.Script or record.script
-		local getHits = record.GetHits
-
-		if typeof(getHits) ~= "function" then
-			unrecognised = stats
-			break
-		end
-
-		local gotHits, hits = pcall(getHits, record)
-		if not gotHits or typeof(hits) ~= "table" then
-			unrecognised = stats
-			break
-		end
-
-		local instrumented = 0
-		local covered = 0
-		-- The lines that never ran are the entire point of asking, so they are
-		-- named rather than left to be inferred from a percentage.
-		local missed: { number } = {}
-
-		for line, count in hits :: { number } do
-			if typeof(count) ~= "number" or count < 0 then
-				continue
-			end
-			instrumented += 1
-			if count > 0 then
-				covered += 1
-			elseif #missed < MAX_UNCOVERED_LINES then
-				table.insert(missed, line)
-			end
-		end
-
-		table.sort(missed)
-
-		--[[
-			A destroyed script keeps its coverage record for the life of the
-			session, and `Paths.of` on something with no ancestry returns a bare
-			name -- so the report named "MCPProbeB" with no path, for a script
-			that no longer existed and could not be looked up. Measured by
-			destroying an instrumented ModuleScript and reading coverage back:
-			the row was still there, and still there on the call after it.
-
-			Dropped rather than flagged. Coverage answers "which lines of my code
-			ran", and a script that is gone has no lines anyone can go and read.
-		]]
-		if typeof(target) == "Instance" and not (target :: Instance):IsDescendantOf(game) then
-			continue
-		end
-
-		table.insert(scripts, {
-			path = if typeof(target) == "Instance" then Paths.of(target) else tostring(target),
-			instrumentedLines = instrumented,
-			coveredLines = covered,
-			uncoveredLines = missed,
-			percent = if instrumented > 0
-				then math.floor(covered / instrumented * 1000 + 0.5) / 10
-				else 0,
-			--[[
-				Zero instrumented lines is not "already compiled when coverage
-				was switched on". That was the earlier reading here and it is
-				wrong: probed against ScriptContext, a script that ran before
-				being enabled gets NO record at all and never reaches this loop.
-
-				What it IS has not been pinned down. The session that produced
-				0-line records could not be made to produce them again -- the
-				same create/enable/require sequence instrumented 6 of 6 lines on
-				the next attempt -- so no cause is claimed here. The flag exists
-				because 0/0 and 0/many render identically and mean opposite
-				things: no data, versus nothing ran.
-			]]
-			notMeasurable = if instrumented == 0 then true else nil,
-		})
-	end
-
-	return {
-		enabled = enabled,
-		scripts = scripts,
-		raw = unrecognised,
-		-- What this session switched on for itself as it loaded, which is the
-		-- only thing that can instrument code running at startup.
-		carriedOver = if #carriedOver > 0 then carriedOver else nil,
-		carriedFailed = if #carriedFailed > 0 then carriedFailed else nil,
-		remembered = rememberedCoverage(),
-	}
-end
-
---[[
-	Every reference in the place that points at nothing.
-
-	A dead asset id is the quietest failure Roblox has. A Sound whose id was
-	deleted, made private, or mistyped plays silence; a Decal shows nothing; an
-	Animation does nothing. None of them errors, none of them warns, and the
-	instance looks perfectly healthy in the Explorer -- the id is a string, and
-	it is still a string. The only way to find them today is to play the game and
-	notice something missing, which nobody does reliably for the twentieth sound
-	effect.
-
-	`ContentProvider:PreloadAsync` settles it. Measured: a real id came back
-	`IsLoaded=true, TimeLength=0.632`, a dead one `IsLoaded=false, TimeLength=0`.
-	So this collects every asset-bearing property in the place, asks the engine
-	to fetch them, and reports the ones that did not arrive.
-
-	One honest cost: preloading a dead id writes a line to Studio's Output
-	window. That is the engine talking, not this tool, and it corroborates the
-	finding rather than contradicting it -- but it is the user's Output window,
-	so the tool says up front that it will happen.
-]]
-
---[[
-	Assets fetched in one audit.
-
-	Preloading is network work, and a place with two thousand sounds would spend
-	minutes on it while Studio sat still. The cap is generous enough to cover
-	most places whole and small enough that the worst case is seconds, and the
-	reply says when it stopped short rather than implying it checked everything.
-]]
-local MAX_ASSETS = 200
-
---[[
-	How long the whole fetch may take before this gives up on it.
-
-	Long enough for two hundred ordinary assets over a slow connection, short
-	enough that a stuck fetch is a slow answer rather than a hung Studio.
-]]
-local PRELOAD_SECONDS = 20
-
---[[
-	Which property on which class holds a content id.
-
-	Written out rather than discovered from the API dump, because "a string
-	property whose name sounds like an asset" catches `Name` and misses
-	`MeshContent`. The list is short, and being wrong here means reporting a
-	healthy place as broken.
-]]
-local ASSET_FIELDS: { { className: string, property: string } } = {
-	{ className = "Sound", property = "SoundId" },
-	{ className = "Decal", property = "Texture" },
-	{ className = "Texture", property = "Texture" },
-	{ className = "ImageLabel", property = "Image" },
-	{ className = "ImageButton", property = "Image" },
-	{ className = "Animation", property = "AnimationId" },
-	{ className = "Sky", property = "SkyboxUp" },
-	{ className = "ParticleEmitter", property = "Texture" },
-	{ className = "Beam", property = "Texture" },
-	{ className = "Trail", property = "Texture" },
-}
-
-function Perf.audit(params: { [string]: any }): { [string]: any }
-	local ContentProvider = game:GetService("ContentProvider")
-
-	local unset: { { [string]: any } } = {}
-	local candidates: { { instance: Instance, id: string, property: string } } = {}
-	local disabled: { string } = {}
-	local duplicates: { string } = {}
-
-	local seenNames: { [string]: boolean } = {}
-
-	for _, descendant in game:GetDescendants() do
-		if Scope.isNoisy(descendant) then
-			continue
-		end
-
-		for _, field in ASSET_FIELDS do
-			if not descendant:IsA(field.className) then
-				continue
-			end
-			local ok, value = pcall(function()
-				return (descendant :: any)[field.property]
-			end)
-			if not ok or typeof(value) ~= "string" then
-				continue
-			end
-			if value == "" then
-				table.insert(unset, { path = Paths.of(descendant), property = field.property })
-			elseif #candidates < MAX_ASSETS then
-				table.insert(candidates, { instance = descendant, id = value, property = field.property })
-			end
-			break
-		end
-
-		--[[
-			`Disabled` exists on BaseScript, not on ModuleScript -- reading it off
-			the wrong one throws, which is how this check failed the first time it
-			was written. Narrowed to the class that has it.
-		]]
-		if descendant:IsA("BaseScript") and (descendant :: any).Disabled == true then
-			if #disabled < 25 then
-				table.insert(disabled, Paths.of(descendant))
-			end
-		end
-
-		--[[
-			Same-named siblings, which is what breaks `WaitForChild`: it returns
-			whichever one the engine reaches first, and that is not stable.
-
-			Geometry is excluded, and that exclusion is the whole value of the
-			check. Measured on a real place: the first version reported 25
-			duplicates and every one of them was a wall bar, a bench or a table
-			leg in a blockout -- decorative parts nobody ever looks up by name.
-			The real findings were buried under them.
-
-			A duplicated script, RemoteEvent, value or GUI element is a different
-			matter: those exist to be found by name, and two of them means code
-			somewhere is reaching for whichever the engine happened to index
-			first.
-		]]
-		local parent = descendant.Parent
-		if parent ~= nil and not descendant:IsA("BasePart") and not descendant:IsA("Attachment") then
-			local key = tostring(parent:GetDebugId(8)) .. "/" .. descendant.Name
-			if seenNames[key] and #duplicates < 25 then
-				table.insert(duplicates, Paths.of(descendant))
-			end
-			seenNames[key] = true
-		end
-	end
-
-	--[[
-		Preloaded in one call rather than one per asset.
-
-		`PreloadAsync` takes the whole list and fetches in parallel; asking for
-		them one at a time would serialise two hundred network round trips into
-		something that looks like a hang.
-	]]
-	local toLoad: { Instance } = {}
-	for _, entry in candidates do
-		table.insert(toLoad, entry.instance)
-	end
-	--[[
-		Given a deadline, because `PreloadAsync` has none of its own.
-
-		It blocks until every id in the list resolves, and an id that resolves
-		slowly -- or a network that has stopped answering -- blocks it for as
-		long as that takes. Measured: an audit against a running playtest sat
-		still long enough for the request to time out and the playtest to end
-		with it. A tool that can stop Studio responding is worse than one that
-		reports less.
-
-		Run on its own thread and waited on here, so the wait can end without
-		the work being cancelled -- there is no way to cancel it, and pretending
-		otherwise would leave a thread writing into a finished request.
-	]]
-	local preloaded = true
-	if #toLoad > 0 then
-		local done = false
-		task.spawn(function()
-			pcall(function()
-				ContentProvider:PreloadAsync(toLoad)
-			end)
-			done = true
-		end)
-
-		local waited = 0
-		while not done and waited < PRELOAD_SECONDS do
-			waited += task.wait(0.05)
-		end
-		preloaded = done
-	end
-
-	local dead: { { [string]: any } } = {}
-	for _, entry in candidates do
-		local instance = entry.instance
-		local loaded = true
-		if instance:IsA("Sound") then
-			-- A Sound that fetched has a length; one that did not is still zero.
-			loaded = (instance :: Sound).TimeLength > 0
-		else
-			local ok, value = pcall(function()
-				return (instance :: any).IsLoaded
-			end)
-			if ok and typeof(value) == "boolean" then
-				loaded = value
-			end
-		end
-		--[[
-			Nothing is called dead once the fetch has been abandoned.
-
-			An id that simply had not arrived yet is indistinguishable here from
-			one that points at nothing, and "this sound is broken" about a sound
-			that is fine is the one answer this check must never give.
-		]]
-		if not loaded and not preloaded then
-			continue
-		end
-		if not loaded and #dead < 50 then
-			table.insert(dead, {
-				path = Paths.of(instance),
-				property = entry.property,
-				id = entry.id,
-			})
-		end
-	end
-
-	return {
-		checked = #candidates,
-		-- Reported beside the fetched count, because "3 checked" on a place with
-		-- fourteen blank ids reads as if the audit barely ran. A blank id needs
-		-- no fetch to be judged; it is still a reference that points nowhere.
-		scanned = #candidates + #unset,
-		truncated = #candidates >= MAX_ASSETS,
-		-- Said out loud, because an empty `dead` list from an abandoned fetch
-		-- reads exactly like a clean place.
-		incomplete = if not preloaded then true else nil,
-		dead = dead,
-		deadCount = #dead,
-		unset = unset,
-		unsetCount = #unset,
-		disabledScripts = disabled,
-		duplicateNames = duplicates,
-	}
-end
-
-function Perf.register(host: Plugin?)
-	pluginRef = host
-
-	--[[
-		Applied at load, which is the only moment early enough to matter. A
-		playtest's scripts run as its DataModel starts, so a session that waited
-		for a tool call to tell it what to instrument would already have missed
-		the run it was meant to measure.
-
-		Paths that no longer resolve are skipped rather than reported: the set is
-		remembered across sessions, and a script deleted in between is a stale
-		entry, not a failure worth surfacing here.
-	]]
-	for _, path in rememberedCoverage() do
-		local ok, err = pcall(function()
-			ScriptContext:EnableCoverage(Paths.resolve(path))
-		end)
-		if ok then
-			table.insert(carriedOver, path)
-		else
-			-- Reported rather than swallowed. When this silently did nothing the
-			-- symptom was identical to the bug it was written to fix -- an empty
-			-- coverage read -- and there was no way to tell which half had failed.
-			table.insert(carriedFailed, { path = path, error = tostring(err) })
-		end
-	end
-
---[[
-	What this place is made of, and where its weight sits.
-
-	`SceneAnalysisService` answers questions the counters cannot. A snapshot says
-	memory is 2.4GB; this says which assets hold it and which instances are
-	responsible, broken down by category rather than by process.
-
-	The return shapes are undocumented -- the reference page lists the six
-	methods and names their result types without describing a single field -- so
-	what follows was read off a live session. Every one of them returns the same
-	recursive node: `{ Name, Size, Children }`, with two exceptions.
-	`GetTriangleCompositionAsync` carries `Sizes`, a dictionary of Triangles and
-	Drawcalls, in place of the single `Size`; and animation nodes add `AssetId`
-	and `Owners`, each owner being `{ Name, ClassName }`.
-
-	Sizes are counts for instance composition and bytes for the memory readings,
-	which the engine does not label either -- so this file labels them.
-]]
-local function flatten(node: any, depth: number, into: { { [string]: any } })
-	if typeof(node) ~= "table" then
-		return
-	end
-	local children = (node :: any).Children
-	if typeof(children) ~= "table" then
-		return
-	end
-	for _, child in children do
-		local entry: { [string]: any } = {
-			name = tostring((child :: any).Name),
-			depth = depth,
-		}
-		local size = (child :: any).Size
-		if typeof(size) == "number" then
-			entry.size = size
-		end
-		local sizes = (child :: any).Sizes
-		if typeof(sizes) == "table" then
-			for key, value in sizes :: { [string]: any } do
-				entry[string.lower(tostring(key))] = value
-			end
-		end
-		local assetId = (child :: any).AssetId
-		if assetId ~= nil then
-			entry.assetId = tostring(assetId)
-		end
-		local owners = (child :: any).Owners
-		if typeof(owners) == "table" then
-			local names: { string } = {}
-			for _, owner in owners :: { any } do
-				if typeof(owner) == "table" then
-					table.insert(names, string.format("%s (%s)", tostring(owner.Name), tostring(owner.ClassName)))
-				end
-			end
-			entry.owners = names
-		end
-		table.insert(into, entry)
-
-		-- Two levels is the useful depth: "3D Objects -> MeshPart" answers the
-		-- question, while a third level is per-instance detail that `find` gives
-		-- better and on demand.
-		if depth < 2 then
-			flatten(child, depth + 1, into)
-		end
-	end
-end
-
-local SCENE_SECTIONS = {
-	{ key = "composition", method = "GetInstanceCompositionAsync", unit = "instances" },
-	{ key = "triangles", method = "GetTriangleCompositionAsync", unit = "triangles" },
-	{ key = "scriptMemory", method = "GetScriptMemoryAsync", unit = "bytes" },
-	{ key = "animationMemory", method = "GetAnimationMemoryAsync", unit = "bytes" },
-	{ key = "audioMemory", method = "GetAudioMemoryAsync", unit = "bytes" },
-	{ key = "unparented", method = "GetUnparentedInstancesAsync", unit = "instances" },
-}
-
-function Perf.scene(params: { [string]: any }): { [string]: any }
-	local only = if typeof(params.section) == "string" and params.section ~= "" then params.section else nil
-	local sections: { [string]: any } = {}
-
-	for _, spec in SCENE_SECTIONS do
-		if only ~= nil and only ~= spec.key then
-			continue
-		end
-		local ok, root = pcall(function()
-			return (SceneAnalysisService :: any)[spec.method](SceneAnalysisService)
-		end)
-		if not ok then
-			sections[spec.key] = { error = tostring(root) }
-			continue
-		end
-
-		local rows: { { [string]: any } } = {}
-		flatten(root, 1, rows)
-
-		local total = (root :: any).Size
-		local totals = (root :: any).Sizes
-		sections[spec.key] = {
-			total = if typeof(total) == "number" then total else nil,
-			totals = if typeof(totals) == "table" then totals else nil,
-			unit = spec.unit,
-			entries = rows,
-		}
-	end
-
-	if only ~= nil and sections[only] == nil then
-		Dispatch.fail(
-			"BAD_PARAMS",
-			string.format("unknown scene section %q", only),
-			"Sections are: composition, triangles, scriptMemory, animationMemory, audioMemory, unparented."
-		)
-	end
-
-	return sections
-end
-
-	Dispatch.registerAll("perf", {
-		audit = Perf.audit,
-		console = Perf.console,
-		snapshot = function()
-			return Perf.snapshot()
-		end,
-		profile = Perf.profile,
-		coverage = Perf.coverage,
-		scene = Perf.scene,
-	})
-end
-
-return Perf
+--!strict
+--[[
+	Output and performance: the Developer Console and Script Performance windows,
+	readable by an agent.
+
+	These are the panels a developer opens when something is slow or broken, and
+	no other Studio MCP server exposes them. Being able to say "which script is
+	eating the frame" without the user reading a graph and describing it back is
+	the difference between diagnosing a problem and guessing at one.
+
+	`Stats` time properties are in seconds and reported here in milliseconds,
+	because every frame budget a developer reasons about is quoted in ms.
+]]
+
+local ScriptContext = game:GetService("ScriptContext")
+local RunService = game:GetService("RunService")
+local SceneAnalysisService = game:GetService("SceneAnalysisService")
+local ScriptProfilerService = game:GetService("ScriptProfilerService")
+local Stats = game:GetService("Stats")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local ClientRelay = require(script.Parent.Parent.ClientRelay)
+local LogBuffer = require(script.Parent.Parent.LogBuffer)
+local Paths = require(script.Parent.Parent.Paths)
+local Scope = require(script.Parent.Parent.Scope)
+
+-- The log holds thousands of lines in a busy session; an unbounded tail would
+-- swamp any context window.
+local MAX_LOG_ENTRIES = 500
+local DEFAULT_LOG_ENTRIES = 100
+
+-- Profiling is a blocking wait, so the ceiling is what a caller will sit through
+-- rather than what the profiler can manage.
+local MAX_PROFILE_SECONDS = 30
+local DEFAULT_PROFILE_SECONDS = 5
+local PROFILE_DATA_TIMEOUT = 5
+
+-- Uncovered line numbers are listed, not just counted, but a script that never
+-- ran at all would otherwise list every line it has.
+local MAX_UNCOVERED_LINES = 50
+
+local Perf = {}
+
+local function round(value: number, places: number): number
+	local scale = 10 ^ places
+	return math.floor(value * scale + 0.5) / scale
+end
+
+--[[
+	Reads a Stats property without assuming it exists. The set has changed across
+	engine versions, and one missing counter should not fail the whole snapshot.
+]]
+local function stat(name: string): number?
+	local ok, value = pcall(function()
+		return (Stats :: any)[name]
+	end)
+	if ok and typeof(value) == "number" then
+		return value
+	end
+	return nil
+end
+
+local function millis(name: string): number?
+	local seconds = stat(name)
+	return if seconds then round(seconds * 1000, 3) else nil
+end
+
+local function flag(name: string): boolean?
+	local ok, value = pcall(function()
+		return (Stats :: any)[name]
+	end)
+	if ok and typeof(value) == "boolean" then
+		return value
+	end
+	return nil
+end
+
+local function rounded(name: string, places: number): number?
+	local value = stat(name)
+	return if value then round(value, places) else nil
+end
+
+--[[
+	The output log, newest last.
+
+	Ordering matters: an agent reading a tail wants the most recent lines at the
+	bottom, the same way the Output window reads, so an error and the lines that
+	led to it stay in the order they happened.
+]]
+function Perf.console(params: { [string]: any }): { [string]: any }
+	local limit = math.clamp(tonumber(params.limit) or DEFAULT_LOG_ENTRIES, 1, MAX_LOG_ENTRIES)
+	local level = params.level
+	local pattern = params.pattern
+	local target = params.target or "studio"
+	if target ~= "studio" and target ~= "client" then Dispatch.fail("BAD_PARAMS", "target must be studio or client") end
+	local player = if target == "client" then ClientRelay.playerFor(params.player) else nil
+
+	-- Read from our own buffer, not LogService:GetLogHistory(). See LogBuffer for
+	-- why: the engine's history stops growing after startup in an editor session
+	-- and is empty outright in a playtest, without reporting either as a failure.
+	local history, evicted, token, latest, recordingSeconds = LogBuffer.stream(player)
+	local since: number? = nil
+	if params.since ~= nil then
+		local supplied = params.since
+		local cursorToken: string? = nil
+		local cursorSequence: string? = nil
+		if typeof(supplied) == "string" then
+			cursorToken, cursorSequence = string.match(supplied, "^([^:]+):(%d+)$")
+		end
+		local parsed = tonumber(cursorSequence)
+		if cursorToken ~= token or parsed == nil or parsed > latest then
+			Dispatch.fail("BAD_CURSOR", "This console cursor belongs to another session or is invalid.", "Start a fresh read without `since`.")
+		end
+		since = parsed
+	end
+	local oldest = if #history > 0 then history[1].sequence or 1 else latest + 1
+	local missed = if since ~= nil then math.max(0, oldest - since - 1) else 0
+
+	local entries: { { [string]: any } } = {}
+	local matched = 0
+
+	for _, item in history do
+		if since ~= nil and (item.sequence or 0) <= since then continue end
+		local kind = item.level
+		if level and kind ~= level then
+			continue
+		end
+
+		local message = item.message
+		if pattern then
+			-- An invalid pattern raises rather than failing to match, so it is
+			-- reported as a pattern problem instead of an empty result.
+			local valid, position = pcall(string.find, message, pattern)
+			if not valid then
+				Dispatch.fail(
+					"BAD_PATTERN",
+					string.format("%s is not a valid Lua pattern: %s", pattern, tostring(position)),
+					"Lua patterns escape with %, not backslash. Omit `pattern` to see everything."
+				)
+			end
+			if position == nil then
+				continue
+			end
+		end
+
+		matched += 1
+		table.insert(entries, {
+			level = kind,
+			message = message,
+			timestamp = item.timestamp,
+			stack = item.stack,
+			source = item.source,
+		})
+	end
+
+	-- Trimmed from the front: the newest lines are the ones worth keeping.
+	local dropped = 0
+	if #entries > limit then
+		dropped = #entries - limit
+		entries = table.move(entries, dropped + 1, #entries, 1, {})
+	end
+
+	return {
+		items = entries,
+		total = matched,
+		dropped = dropped,
+		-- Lines lost to the buffer's own capacity, as opposed to ones trimmed to
+		-- satisfy this call's limit. Only the first is a reason to worry.
+		evicted = if since ~= nil then (if missed > 0 then missed else nil) else (if evicted > 0 then evicted else nil),
+		recordingSeconds = recordingSeconds,
+		nextCursor = token .. ":" .. tostring(latest),
+		player = if player then player.Name else nil,
+		capturing = if player then LogBuffer.clientReady(player) else true,
+	}
+end
+
+--[[
+	A snapshot of the engine's own counters -- what the Developer Console shows on
+	its Performance and Memory tabs.
+]]
+function Perf.snapshot(): { [string]: any }
+	--[[
+		Read one tag at a time, not with `GetMemoryUsageMbAllCategories`.
+
+		The aggregate call is the obvious one and is closed to us: it now requires
+		the InternalTest capability, so from a plugin it only ever raises "the
+		current thread cannot call 'GetMemoryUsageMbAllCategories'". Measured, not
+		assumed -- and the same refusal comes back in an editor session and in a
+		playtest, so there is no context in which waiting for it pays off.
+
+		`GetMemoryUsageMbForTag` carries no such restriction, and walking
+		`Enum.DeveloperMemoryTag` reaches every category the Developer Console's
+		Memory tab shows. Zero-valued tags are dropped so the list stays readable.
+	]]
+	local memory: { { [string]: any } } = {}
+	local memoryProblem: string? = nil
+
+	for _, tag in Enum.DeveloperMemoryTag:GetEnumItems() do
+		local ok, value = pcall(function()
+			return Stats:GetMemoryUsageMbForTag(tag)
+		end)
+		if not ok then
+			-- One refusal means the whole route is shut, not that this tag is
+			-- special; stop rather than repeat the same failure for every item.
+			memoryProblem = string.format("Stats refused the call: %s", tostring(value))
+			break
+		end
+		if typeof(value) == "number" and value > 0 then
+			table.insert(memory, { category = tag.Name, megabytes = round(value, 2) })
+		end
+	end
+
+	table.sort(memory, function(a, b)
+		return a.megabytes > b.megabytes
+	end)
+
+	local okTotal, total = pcall(function()
+		return Stats:GetTotalMemoryUsageMb()
+	end)
+
+	--[[
+		A playtest server has no renderer, so every drawing counter reads zero --
+		zero draw calls, zero triangles, no frame time. Left unexplained that is
+		the most flattering possible misreading of a place's performance, so the
+		snapshot says outright that those numbers are absent rather than good.
+	]]
+	local headless = RunService:IsRunning() and RunService:IsServer() and not RunService:IsClient()
+
+	return {
+		renderless = headless or nil,
+		frame = {
+			frameTimeMs = millis("FrameTime"),
+			heartbeatTimeMs = millis("HeartbeatTime"),
+			physicsStepTimeMs = millis("PhysicsStepTime"),
+			renderCpuMs = millis("RenderCPUFrameTime"),
+			renderGpuMs = millis("RenderGPUFrameTime"),
+		},
+		scene = {
+			instances = stat("InstanceCount"),
+			parts = stat("PrimitivesCount"),
+			movingParts = stat("MovingPrimitivesCount"),
+			contacts = stat("ContactsCount"),
+			drawcalls = stat("SceneDrawcallCount"),
+			triangles = stat("SceneTriangleCount"),
+		},
+		network = {
+			receiveKbps = rounded("DataReceiveKbps", 1),
+			sendKbps = rounded("DataSendKbps", 1),
+		},
+		memory = {
+			totalMb = if okTotal and typeof(total) == "number" then round(total, 1) else nil,
+			-- Studio only accumulates the per-category breakdown while this is on,
+			-- so an empty list means "not measured" rather than "nothing used".
+			trackingEnabled = flag("MemoryTrackingEnabled"),
+			categories = memory,
+			problem = if #memory == 0 then memoryProblem else nil,
+		},
+	}
+end
+
+--[[
+	Runs the script profiler for a while and returns what it collected.
+
+	This is the Script Performance window. The profiler samples at `frequency` Hz
+	and reports back through an event rather than a return value, so the call
+	starts it, waits, asks for the data, and stops -- blocking for the duration,
+	which is why the ceiling is short.
+
+	The payload's shape is Roblox's own and undocumented, so it is passed through
+	rather than reshaped into something that might quietly misreport which script
+	is expensive.
+]]
+function Perf.profile(params: { [string]: any }): { [string]: any }
+	local seconds = math.clamp(
+		tonumber(params.seconds) or DEFAULT_PROFILE_SECONDS,
+		1,
+		MAX_PROFILE_SECONDS
+	)
+	local frequency = math.clamp(tonumber(params.frequency) or 1000, 100, 10000)
+
+	local received: string? = nil
+	local connection = ScriptProfilerService.OnNewData:Connect(function(_player, jsonString)
+		received = jsonString
+	end)
+
+	local started, startError = pcall(function()
+		ScriptProfilerService:ServerStart(frequency)
+	end)
+	if not started then
+		connection:Disconnect()
+		Dispatch.fail(
+			"PROFILER_UNAVAILABLE",
+			string.format("Could not start the script profiler: %s", tostring(startError)),
+			"The profiler is only available in Studio, and only one session at a time."
+		)
+	end
+
+	task.wait(seconds)
+
+	pcall(function()
+		ScriptProfilerService:ServerRequestData()
+	end)
+
+	-- The data arrives on the event, so the request is followed by a bounded wait
+	-- rather than assuming it has already landed.
+	local deadline = os.clock() + PROFILE_DATA_TIMEOUT
+	while received == nil and os.clock() < deadline do
+		task.wait(0.1)
+	end
+
+	pcall(function()
+		ScriptProfilerService:ServerStop()
+	end)
+	connection:Disconnect()
+
+	if received == nil then
+		Dispatch.fail(
+			"NO_PROFILE_DATA",
+			string.format("The profiler ran for %ds but returned no data.", seconds),
+			"Nothing ran during the sample. Start a playtest first, or profile for longer."
+		)
+	end
+
+	local okParse, parsed = pcall(function()
+		return ScriptProfilerService:DeserializeJSON(received)
+	end)
+
+	return {
+		seconds = seconds,
+		frequency = frequency,
+		data = if okParse then parsed else nil,
+		raw = if okParse then nil else received,
+	}
+end
+
+--[[
+	Which scripts to instrument the moment a session starts.
+
+	`EnableCoverage` applies to the DataModel it is called in, and a playtest is a
+	different DataModel, built when Play is pressed. So enabling from the editor
+	and then playing -- the sequence this tool used to instruct -- instruments the
+	editor and measures the playtest, which is why it reported nothing at all: the
+	editor never ran the code, and the playtest was never instrumented.
+
+	Nothing can be enabled from outside in time either, because a playtest's
+	scripts start with the DataModel. The request has to be waiting before the
+	session exists, so it is remembered here and replayed by whichever session
+	loads next.
+
+	Kept per place. Plugin settings live in one file shared by every Studio
+	process, so a path remembered while working on one game would otherwise be
+	resolved against a different one.
+]]
+local COVERAGE_SETTING = "coverageTargets"
+local pluginRef: Plugin? = nil
+local carriedOver: { string } = {}
+local carriedFailed: { { [string]: any } } = {}
+
+local function rememberCoverage(paths: { string })
+	local host = pluginRef
+	if host == nil then
+		return
+	end
+	pcall(function()
+		(host :: Plugin):SetSetting(COVERAGE_SETTING, {
+			placeId = game.PlaceId,
+			paths = paths,
+		})
+	end)
+end
+
+local function rememberedCoverage(): { string }
+	local host = pluginRef
+	if host == nil then
+		return {}
+	end
+	local ok, stored = pcall(function()
+		return (host :: Plugin):GetSetting(COVERAGE_SETTING)
+	end)
+	if not ok or typeof(stored) ~= "table" then
+		return {}
+	end
+	local record = stored :: { [string]: any }
+	if record.placeId ~= game.PlaceId or typeof(record.paths) ~= "table" then
+		return {}
+	end
+	return record.paths :: { string }
+end
+
+--[[
+	Line coverage: which lines of which scripts actually ran.
+
+	Coverage has to be switched on for a script before that script executes, so a
+	call that only reads the stats reports nothing on a first run. `enable` turns
+	it on for named scripts and remembers them for the next session to switch on
+	for itself; the caller then plays, and reads back from the playtest.
+]]
+function Perf.coverage(params: { [string]: any }): { [string]: any }
+	local enabled: { string } = {}
+	-- Distinguished from absent on purpose: an explicit empty list is how a
+	-- caller stops instrumenting every future session for this place.
+	local requested = params.enable
+	for _, path in (requested or {}) :: { string } do
+		local target = Paths.resolve(path)
+		local ok = pcall(function()
+			ScriptContext:EnableCoverage(target)
+		end)
+		if ok then
+			table.insert(enabled, Paths.of(target))
+		end
+	end
+	if requested ~= nil then
+		rememberCoverage(enabled)
+	end
+
+	local ok, stats = pcall(function()
+		return ScriptContext:GetCoverageStats()
+	end)
+	if not ok or typeof(stats) ~= "table" then
+		return { enabled = enabled, scripts = {}, problem = tostring(stats) }
+	end
+
+	--[[
+		The payload is undocumented, so this is the shape measured from a real
+		capture rather than a guess: each entry is `{ Script = Instance, GetHits =
+		function }`, and `GetHits()` returns an array indexed by line number.
+
+		The values carry three distinct meanings, and conflating them is what an
+		earlier attempt here did:
+		  -1  the line cannot be instrumented at all -- blank, a comment, an `end`
+		   0  instrumented and never executed: the lines worth reporting
+		  >0  the number of times it ran
+
+		Counting every element as instrumented drags the denominator up by every
+		blank line and comment in the file, which understates coverage on exactly
+		the well-commented code most likely to be measured.
+	]]
+	local scripts: { { [string]: any } } = {}
+	local unrecognised: any = nil
+
+	for _, entry in stats :: { any } do
+		if typeof(entry) ~= "table" then
+			unrecognised = stats
+			break
+		end
+
+		local record = entry :: { [string]: any }
+		local target = record.Script or record.script
+		local getHits = record.GetHits
+
+		if typeof(getHits) ~= "function" then
+			unrecognised = stats
+			break
+		end
+
+		local gotHits, hits = pcall(getHits, record)
+		if not gotHits or typeof(hits) ~= "table" then
+			unrecognised = stats
+			break
+		end
+
+		local instrumented = 0
+		local covered = 0
+		-- The lines that never ran are the entire point of asking, so they are
+		-- named rather than left to be inferred from a percentage.
+		local missed: { number } = {}
+
+		for line, count in hits :: { number } do
+			if typeof(count) ~= "number" or count < 0 then
+				continue
+			end
+			instrumented += 1
+			if count > 0 then
+				covered += 1
+			elseif #missed < MAX_UNCOVERED_LINES then
+				table.insert(missed, line)
+			end
+		end
+
+		table.sort(missed)
+
+		--[[
+			A destroyed script keeps its coverage record for the life of the
+			session, and `Paths.of` on something with no ancestry returns a bare
+			name -- so the report named "MCPProbeB" with no path, for a script
+			that no longer existed and could not be looked up. Measured by
+			destroying an instrumented ModuleScript and reading coverage back:
+			the row was still there, and still there on the call after it.
+
+			Dropped rather than flagged. Coverage answers "which lines of my code
+			ran", and a script that is gone has no lines anyone can go and read.
+		]]
+		if typeof(target) == "Instance" and not (target :: Instance):IsDescendantOf(game) then
+			continue
+		end
+
+		table.insert(scripts, {
+			path = if typeof(target) == "Instance" then Paths.of(target) else tostring(target),
+			instrumentedLines = instrumented,
+			coveredLines = covered,
+			uncoveredLines = missed,
+			percent = if instrumented > 0
+				then math.floor(covered / instrumented * 1000 + 0.5) / 10
+				else 0,
+			--[[
+				Zero instrumented lines is not "already compiled when coverage
+				was switched on". That was the earlier reading here and it is
+				wrong: probed against ScriptContext, a script that ran before
+				being enabled gets NO record at all and never reaches this loop.
+
+				What it IS has not been pinned down. The session that produced
+				0-line records could not be made to produce them again -- the
+				same create/enable/require sequence instrumented 6 of 6 lines on
+				the next attempt -- so no cause is claimed here. The flag exists
+				because 0/0 and 0/many render identically and mean opposite
+				things: no data, versus nothing ran.
+			]]
+			notMeasurable = if instrumented == 0 then true else nil,
+		})
+	end
+
+	return {
+		enabled = enabled,
+		scripts = scripts,
+		raw = unrecognised,
+		-- What this session switched on for itself as it loaded, which is the
+		-- only thing that can instrument code running at startup.
+		carriedOver = if #carriedOver > 0 then carriedOver else nil,
+		carriedFailed = if #carriedFailed > 0 then carriedFailed else nil,
+		remembered = rememberedCoverage(),
+	}
+end
+
+--[[
+	Every reference in the place that points at nothing.
+
+	A dead asset id is the quietest failure Roblox has. A Sound whose id was
+	deleted, made private, or mistyped plays silence; a Decal shows nothing; an
+	Animation does nothing. None of them errors, none of them warns, and the
+	instance looks perfectly healthy in the Explorer -- the id is a string, and
+	it is still a string. The only way to find them today is to play the game and
+	notice something missing, which nobody does reliably for the twentieth sound
+	effect.
+
+	`ContentProvider:PreloadAsync` settles it. Measured: a real id came back
+	`IsLoaded=true, TimeLength=0.632`, a dead one `IsLoaded=false, TimeLength=0`.
+	So this collects every asset-bearing property in the place, asks the engine
+	to fetch them, and reports the ones that did not arrive.
+
+	One honest cost: preloading a dead id writes a line to Studio's Output
+	window. That is the engine talking, not this tool, and it corroborates the
+	finding rather than contradicting it -- but it is the user's Output window,
+	so the tool says up front that it will happen.
+]]
+
+--[[
+	Assets fetched in one audit.
+
+	Preloading is network work, and a place with two thousand sounds would spend
+	minutes on it while Studio sat still. The cap is generous enough to cover
+	most places whole and small enough that the worst case is seconds, and the
+	reply says when it stopped short rather than implying it checked everything.
+]]
+local MAX_ASSETS = 200
+
+--[[
+	How long the whole fetch may take before this gives up on it.
+
+	Long enough for two hundred ordinary assets over a slow connection, short
+	enough that a stuck fetch is a slow answer rather than a hung Studio.
+]]
+local PRELOAD_SECONDS = 20
+
+--[[
+	Which property on which class holds a content id.
+
+	Written out rather than discovered from the API dump, because "a string
+	property whose name sounds like an asset" catches `Name` and misses
+	`MeshContent`. The list is short, and being wrong here means reporting a
+	healthy place as broken.
+]]
+local ASSET_FIELDS: { { className: string, property: string } } = {
+	{ className = "Sound", property = "SoundId" },
+	{ className = "Decal", property = "Texture" },
+	{ className = "Texture", property = "Texture" },
+	{ className = "ImageLabel", property = "Image" },
+	{ className = "ImageButton", property = "Image" },
+	{ className = "Animation", property = "AnimationId" },
+	{ className = "Sky", property = "SkyboxUp" },
+	{ className = "ParticleEmitter", property = "Texture" },
+	{ className = "Beam", property = "Texture" },
+	{ className = "Trail", property = "Texture" },
+}
+
+function Perf.audit(params: { [string]: any }): { [string]: any }
+	local ContentProvider = game:GetService("ContentProvider")
+
+	local unset: { { [string]: any } } = {}
+	local candidates: { { instance: Instance, id: string, property: string } } = {}
+	local disabled: { string } = {}
+	local duplicates: { string } = {}
+
+	local seenNames: { [string]: boolean } = {}
+
+	for _, descendant in game:GetDescendants() do
+		if Scope.isNoisy(descendant) then
+			continue
+		end
+
+		for _, field in ASSET_FIELDS do
+			if not descendant:IsA(field.className) then
+				continue
+			end
+			local ok, value = pcall(function()
+				return (descendant :: any)[field.property]
+			end)
+			if not ok or typeof(value) ~= "string" then
+				continue
+			end
+			if value == "" then
+				table.insert(unset, { path = Paths.of(descendant), property = field.property })
+			elseif #candidates < MAX_ASSETS then
+				table.insert(candidates, { instance = descendant, id = value, property = field.property })
+			end
+			break
+		end
+
+		--[[
+			`Disabled` exists on BaseScript, not on ModuleScript -- reading it off
+			the wrong one throws, which is how this check failed the first time it
+			was written. Narrowed to the class that has it.
+		]]
+		if descendant:IsA("BaseScript") and (descendant :: any).Disabled == true then
+			if #disabled < 25 then
+				table.insert(disabled, Paths.of(descendant))
+			end
+		end
+
+		--[[
+			Same-named siblings, which is what breaks `WaitForChild`: it returns
+			whichever one the engine reaches first, and that is not stable.
+
+			Geometry is excluded, and that exclusion is the whole value of the
+			check. Measured on a real place: the first version reported 25
+			duplicates and every one of them was a wall bar, a bench or a table
+			leg in a blockout -- decorative parts nobody ever looks up by name.
+			The real findings were buried under them.
+
+			A duplicated script, RemoteEvent, value or GUI element is a different
+			matter: those exist to be found by name, and two of them means code
+			somewhere is reaching for whichever the engine happened to index
+			first.
+		]]
+		local parent = descendant.Parent
+		if parent ~= nil and not descendant:IsA("BasePart") and not descendant:IsA("Attachment") then
+			local key = tostring(parent:GetDebugId(8)) .. "/" .. descendant.Name
+			if seenNames[key] and #duplicates < 25 then
+				table.insert(duplicates, Paths.of(descendant))
+			end
+			seenNames[key] = true
+		end
+	end
+
+	--[[
+		Preloaded in one call rather than one per asset.
+
+		`PreloadAsync` takes the whole list and fetches in parallel; asking for
+		them one at a time would serialise two hundred network round trips into
+		something that looks like a hang.
+	]]
+	local toLoad: { Instance } = {}
+	for _, entry in candidates do
+		table.insert(toLoad, entry.instance)
+	end
+	--[[
+		Given a deadline, because `PreloadAsync` has none of its own.
+
+		It blocks until every id in the list resolves, and an id that resolves
+		slowly -- or a network that has stopped answering -- blocks it for as
+		long as that takes. Measured: an audit against a running playtest sat
+		still long enough for the request to time out and the playtest to end
+		with it. A tool that can stop Studio responding is worse than one that
+		reports less.
+
+		Run on its own thread and waited on here, so the wait can end without
+		the work being cancelled -- there is no way to cancel it, and pretending
+		otherwise would leave a thread writing into a finished request.
+	]]
+	local preloaded = true
+	if #toLoad > 0 then
+		local done = false
+		task.spawn(function()
+			pcall(function()
+				ContentProvider:PreloadAsync(toLoad)
+			end)
+			done = true
+		end)
+
+		local waited = 0
+		while not done and waited < PRELOAD_SECONDS do
+			waited += task.wait(0.05)
+		end
+		preloaded = done
+	end
+
+	local dead: { { [string]: any } } = {}
+	for _, entry in candidates do
+		local instance = entry.instance
+		local loaded = true
+		if instance:IsA("Sound") then
+			-- A Sound that fetched has a length; one that did not is still zero.
+			loaded = (instance :: Sound).TimeLength > 0
+		else
+			local ok, value = pcall(function()
+				return (instance :: any).IsLoaded
+			end)
+			if ok and typeof(value) == "boolean" then
+				loaded = value
+			end
+		end
+		--[[
+			Nothing is called dead once the fetch has been abandoned.
+
+			An id that simply had not arrived yet is indistinguishable here from
+			one that points at nothing, and "this sound is broken" about a sound
+			that is fine is the one answer this check must never give.
+		]]
+		if not loaded and not preloaded then
+			continue
+		end
+		if not loaded and #dead < 50 then
+			table.insert(dead, {
+				path = Paths.of(instance),
+				property = entry.property,
+				id = entry.id,
+			})
+		end
+	end
+
+	return {
+		checked = #candidates,
+		-- Reported beside the fetched count, because "3 checked" on a place with
+		-- fourteen blank ids reads as if the audit barely ran. A blank id needs
+		-- no fetch to be judged; it is still a reference that points nowhere.
+		scanned = #candidates + #unset,
+		truncated = #candidates >= MAX_ASSETS,
+		-- Said out loud, because an empty `dead` list from an abandoned fetch
+		-- reads exactly like a clean place.
+		incomplete = if not preloaded then true else nil,
+		dead = dead,
+		deadCount = #dead,
+		unset = unset,
+		unsetCount = #unset,
+		disabledScripts = disabled,
+		duplicateNames = duplicates,
+	}
+end
+
+function Perf.register(host: Plugin?)
+	pluginRef = host
+
+	--[[
+		Applied at load, which is the only moment early enough to matter. A
+		playtest's scripts run as its DataModel starts, so a session that waited
+		for a tool call to tell it what to instrument would already have missed
+		the run it was meant to measure.
+
+		Paths that no longer resolve are skipped rather than reported: the set is
+		remembered across sessions, and a script deleted in between is a stale
+		entry, not a failure worth surfacing here.
+	]]
+	for _, path in rememberedCoverage() do
+		local ok, err = pcall(function()
+			ScriptContext:EnableCoverage(Paths.resolve(path))
+		end)
+		if ok then
+			table.insert(carriedOver, path)
+		else
+			-- Reported rather than swallowed. When this silently did nothing the
+			-- symptom was identical to the bug it was written to fix -- an empty
+			-- coverage read -- and there was no way to tell which half had failed.
+			table.insert(carriedFailed, { path = path, error = tostring(err) })
+		end
+	end
+
+--[[
+	What this place is made of, and where its weight sits.
+
+	`SceneAnalysisService` answers questions the counters cannot. A snapshot says
+	memory is 2.4GB; this says which assets hold it and which instances are
+	responsible, broken down by category rather than by process.
+
+	The return shapes are undocumented -- the reference page lists the six
+	methods and names their result types without describing a single field -- so
+	what follows was read off a live session. Every one of them returns the same
+	recursive node: `{ Name, Size, Children }`, with two exceptions.
+	`GetTriangleCompositionAsync` carries `Sizes`, a dictionary of Triangles and
+	Drawcalls, in place of the single `Size`; and animation nodes add `AssetId`
+	and `Owners`, each owner being `{ Name, ClassName }`.
+
+	Sizes are counts for instance composition and bytes for the memory readings,
+	which the engine does not label either -- so this file labels them.
+]]
+local function flatten(node: any, depth: number, into: { { [string]: any } })
+	if typeof(node) ~= "table" then
+		return
+	end
+	local children = (node :: any).Children
+	if typeof(children) ~= "table" then
+		return
+	end
+	for _, child in children do
+		local entry: { [string]: any } = {
+			name = tostring((child :: any).Name),
+			depth = depth,
+		}
+		local size = (child :: any).Size
+		if typeof(size) == "number" then
+			entry.size = size
+		end
+		local sizes = (child :: any).Sizes
+		if typeof(sizes) == "table" then
+			for key, value in sizes :: { [string]: any } do
+				entry[string.lower(tostring(key))] = value
+			end
+		end
+		local assetId = (child :: any).AssetId
+		if assetId ~= nil then
+			entry.assetId = tostring(assetId)
+		end
+		local owners = (child :: any).Owners
+		if typeof(owners) == "table" then
+			local names: { string } = {}
+			for _, owner in owners :: { any } do
+				if typeof(owner) == "table" then
+					table.insert(names, string.format("%s (%s)", tostring(owner.Name), tostring(owner.ClassName)))
+				end
+			end
+			entry.owners = names
+		end
+		table.insert(into, entry)
+
+		-- Two levels is the useful depth: "3D Objects -> MeshPart" answers the
+		-- question, while a third level is per-instance detail that `find` gives
+		-- better and on demand.
+		if depth < 2 then
+			flatten(child, depth + 1, into)
+		end
+	end
+end
+
+local SCENE_SECTIONS = {
+	{ key = "composition", method = "GetInstanceCompositionAsync", unit = "instances" },
+	{ key = "triangles", method = "GetTriangleCompositionAsync", unit = "triangles" },
+	{ key = "scriptMemory", method = "GetScriptMemoryAsync", unit = "bytes" },
+	{ key = "animationMemory", method = "GetAnimationMemoryAsync", unit = "bytes" },
+	{ key = "audioMemory", method = "GetAudioMemoryAsync", unit = "bytes" },
+	{ key = "unparented", method = "GetUnparentedInstancesAsync", unit = "instances" },
+}
+
+function Perf.scene(params: { [string]: any }): { [string]: any }
+	local only = if typeof(params.section) == "string" and params.section ~= "" then params.section else nil
+	local sections: { [string]: any } = {}
+
+	for _, spec in SCENE_SECTIONS do
+		if only ~= nil and only ~= spec.key then
+			continue
+		end
+		local ok, root = pcall(function()
+			return (SceneAnalysisService :: any)[spec.method](SceneAnalysisService)
+		end)
+		if not ok then
+			sections[spec.key] = { error = tostring(root) }
+			continue
+		end
+
+		local rows: { { [string]: any } } = {}
+		flatten(root, 1, rows)
+
+		local total = (root :: any).Size
+		local totals = (root :: any).Sizes
+		sections[spec.key] = {
+			total = if typeof(total) == "number" then total else nil,
+			totals = if typeof(totals) == "table" then totals else nil,
+			unit = spec.unit,
+			entries = rows,
+		}
+	end
+
+	if only ~= nil and sections[only] == nil then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("unknown scene section %q", only),
+			"Sections are: composition, triangles, scriptMemory, animationMemory, audioMemory, unparented."
+		)
+	end
+
+	return sections
+end
+
+	Dispatch.registerAll("perf", {
+		audit = Perf.audit,
+		console = Perf.console,
+		snapshot = function()
+			return Perf.snapshot()
+		end,
+		profile = Perf.profile,
+		coverage = Perf.coverage,
+		scene = Perf.scene,
+	})
+end
+
+return Perf