goldsync 0.1.16 → 0.1.31

package/assets/GoldSync.rbxmx

@@ -19,10 +19,16 @@ local ENDPOINT = "http://127.0.0.1:34873"
 local SESSION_MARKER_NAME = "__GoldSyncSession"
 local CLIENT_HEADERS = {
 	["X-GoldSync-Client"] = "studio-plugin",
+	["X-GoldSync-Tree-Roots"] = "4",
 }
 local SETTINGS_PREFIX = "GoldSync:v2:"
 local UI_SETTINGS_PREFIX = "GoldSync:ui:v1:"
-local VERSION = "0.1.16"
+local VERSION = "0.1.31"
+local startupProfile = { settings = 0, watchers = 0, reconcile = 0, downloads = 0 }
+local savedHashes = {}
+local savedHashesKey
+local hashesDirty = false
+local TreeRoots = require(script.Parent.TreeRoots)
 local REQUEST_INTERVAL_SECONDS = 0.15
 local REQUEST_RETRY_DELAYS = { 1, 2, 4 }
 
@@ -392,6 +398,12 @@ local requestWaiters = {}
 local lastRequestAt = 0
 local serverConfig
 local states = {}
+local treeDiscovery = {}
+local snapshotBatch = {}
+local configETag
+local filteringTree = false
+local filterScheduled = false
+local filterAgain = false
 local groups = {}
 local batchingStatusUpdates = false
 local splitRootConnections = {}
@@ -402,6 +414,7 @@ local refreshUnsyncedButton
 local upload
 local pull
 local deleteSnapshot
+local pathStartsWith
 local openGitConflict
 local resolveGitConflict
 local applyTreeFilter
@@ -550,10 +563,10 @@ local function responseError(response)
 	return string.format("HTTP %d · %s", response.StatusCode, tostring(response.StatusMessage))
 end
 
-local function resolveRoot(studioPath)
+local function resolveRoot(studioPath, instanceIds)
 	local current = game:GetService(studioPath[1])
 	for index = 2, #studioPath do
-		current = current:FindFirstChild(studioPath[index])
+		current = if instanceIds then TreeRoots.findChild(current, studioPath[index], instanceIds[index]) else current:FindFirstChild(studioPath[index])
 		if not current then
 			return nil
 		end
@@ -561,10 +574,10 @@ local function resolveRoot(studioPath)
 	return current
 end
 
-local function resolveParent(studioPath)
+local function resolveParent(studioPath, instanceIds)
 	local current = game:GetService(studioPath[1])
 	for index = 2, #studioPath - 1 do
-		current = current:FindFirstChild(studioPath[index])
+		current = if instanceIds then TreeRoots.findChild(current, studioPath[index], instanceIds[index]) else current:FindFirstChild(studioPath[index])
 		if not current then
 			return nil
 		end
@@ -719,21 +732,9 @@ local function addButtonHover(button)
 	Instance.new("UICorner", button).CornerRadius = UDim.new(0, 3)
 end
 
-local function findCode(root)
-	if root:IsA("BaseScript") then
-		return root
-	end
-	for _, descendant in root:GetDescendants() do
-		if descendant:IsA("BaseScript") then
-			return descendant
-		end
-	end
-	return nil
-end
-
 local function setStatus(state, text, color)
 	local statusColor = color or Color3.fromRGB(180, 180, 190)
-	local statusKind = if string.sub(text, 1, 6) == "Synced"
+	local statusKind = if string.sub(text, 1, 6) == "Synced" or string.sub(text, 1, 7) == "Deleted"
 		then "synced"
 		elseif string.find(text, "syncing")
 			or string.find(text, "Serializing")
@@ -743,18 +744,29 @@ local function setStatus(state, text, color)
 		then "working"
 		elseif string.find(text, "Rojo") and string.find(text, "offline") then "paused"
 		else "issue"
-	if state.status.Text == text and state.status.TextColor3 == statusColor and state.statusKind == statusKind then
+	if state.statusText == text and state.statusColor == statusColor and state.statusKind == statusKind then
 		return
 	end
 	local previousStatusKind = state.statusKind
-	state.status.Text = text
-	state.status.TextColor3 = statusColor
-	state.dot.TextColor3 = statusColor
+	state.statusText = text
+	state.statusColor = statusColor
+	if state.row then
+		state.status.Text = text
+		state.status.TextColor3 = statusColor
+		state.dot.TextColor3 = statusColor
+	end
 	state.searchQuery = nil
 	state.statusKind = statusKind
 	if updateGroupSummaries and not batchingStatusUpdates then
 		if previousStatusKind ~= state.statusKind then
 			updateGroupSummaries()
+			if applyTreeFilter and not filterScheduled then
+				filterScheduled = true
+				task.defer(function()
+					filterScheduled = false
+					if running then applyTreeFilter() end
+				end)
+			end
 		elseif refreshStatusSummary then
 			refreshStatusSummary()
 		end
@@ -813,6 +825,9 @@ local function getSerializedPropertyNames(className)
 				table.insert(names, property.Name)
 			end
 		end
+		if (className == "ModuleScript" or className == "Script" or className == "LocalScript") and not table.find(names, "Source") then
+			table.insert(names, "Source")
+		end
 		table.sort(names)
 	end
 	propertyNamesByClass[className] = names
@@ -850,7 +865,7 @@ local function compareConflictWorkspace(state, versions, resultRoot)
 	local generation = inspectorGeneration
 	table.clear(inspectorEntries)
 	inspectorRendered = 0
-	inspectorTitle.Text = table.concat(state.manifest.studioPath, ".")
+	inspectorTitle.Text = TreeRoots.displayPath(state.manifest.studioPath, state.manifest.instanceIds)
 	inspectorSummary.Text = "Scanning serialized properties..."
 	inspectorWidget.Enabled = true
 
@@ -1110,10 +1125,20 @@ local function watchInstance(state, instance)
 		return
 	end
 	local connections = {
-		instance.AttributeChanged:Connect(function()
+		instance.AttributeChanged:Connect(function(attribute)
 			markDirty(state)
+			if attribute == "GoldSyncId" and instance == state.root and state.manifest.treeRootId then
+				local tree = treeDiscovery[state.manifest.treeRootId]
+				if tree then tree.dirty = true end
+			end
 		end),
 	}
+	if instance == state.root and state.manifest.treeRootId then
+		table.insert(connections, instance:GetPropertyChangedSignal("Name"):Connect(function()
+			local tree = treeDiscovery[state.manifest.treeRootId]
+			if tree then tree.dirty = true end
+		end))
+	end
 	if instance:IsA("ValueBase") then
 		for _, propertyName in getSerializedPropertyNames(instance.ClassName) do
 			local connected, connection = pcall(function()
@@ -1137,9 +1162,23 @@ local function watchInstance(state, instance)
 end
 
 local function watchRoot(state, root)
+	local started = os.clock()
 	disconnectRoot(state)
 	state.root = root
 	watchInstance(state, root)
+	if state.manifest.container then
+		local tree = treeDiscovery[state.manifest.treeRootId]
+		if tree then
+			for _, signal in { root.ChildAdded, root.ChildRemoved } do
+				table.insert(state.rootConnections, signal:Connect(function()
+					tree.dirty = true
+					markDirty(state)
+				end))
+			end
+		end
+		if startupProfile then startupProfile.watchers += os.clock() - started end
+		return
+	end
 	for _, descendant in root:GetDescendants() do
 		watchInstance(state, descendant)
 	end
@@ -1158,34 +1197,86 @@ local function watchRoot(state, root)
 		markDirty(state)
 	end))
 	table.insert(state.rootConnections, root.AncestryChanged:Connect(function()
-		if not state.suppress and resolveRoot(state.manifest.studioPath) ~= root then
+		if not state.suppress and resolveRoot(state.manifest.studioPath, state.manifest.instanceIds) ~= root then
 			deleteSnapshot(state)
 		end
 	end))
+	if startupProfile then startupProfile.watchers += os.clock() - started end
+end
+
+local function saveHashes()
+	if not hashesDirty or not savedHashesKey then return end
+	plugin:SetSetting(savedHashesKey, savedHashes)
+	hashesDirty = false
 end
 
 local function rememberHash(state, hash)
 	state.lastHash = hash
-	plugin:SetSetting(
-		SETTINGS_PREFIX .. serverConfig.projectId .. ":" .. serverConfig.workspaceId .. ":" .. state.manifest.id .. ":hash",
-		hash
-	)
+	if savedHashes[state.manifest.id] == hash then return end
+	savedHashes[state.manifest.id] = hash
+	hashesDirty = true
 end
 
 local function forgetHash(state)
 	state.lastHash = nil
-	plugin:SetSetting(
-		SETTINGS_PREFIX .. serverConfig.projectId .. ":" .. serverConfig.workspaceId .. ":" .. state.manifest.id .. ":hash",
-		nil
-	)
+	if savedHashes[state.manifest.id] == nil then return end
+	savedHashes[state.manifest.id] = nil
+	hashesDirty = true
 end
 
-deleteSnapshot = function(state)
+deleteSnapshot = function(state, explicit)
+	if state.boundary or state.coveredByBoundary then return end
+	if state.manifest.container then
+		state.conflict = true
+		setStatus(state, "Folder removed. Push to remove its saved subtree; Pull to restore it.", Color3.fromRGB(245, 106, 106))
+		if not explicit or state.deleting or not serverConfig.rojoConnected then return end
+		local expected, affected = {}, {}
+		for _, candidate in states do
+			local manifest = candidate.manifest
+			if manifest.treeRootId ~= state.manifest.treeRootId or not pathStartsWith(state.manifest.studioPath, manifest.studioPath, state.manifest.instanceIds, manifest.instanceIds) then continue end
+			if manifest.gitConflict or resolveRoot(manifest.studioPath, manifest.instanceIds) then
+				setStatus(state, "Deletion blocked: a saved descendant still exists in Studio or has a Git conflict.", Color3.fromRGB(245, 106, 106))
+				return
+			end
+			expected[manifest.id] = manifest.hash or false
+			table.insert(affected, candidate)
+		end
+		local header = HttpService:JSONEncode({ entries = {}, expected = expected })
+		local length = buffer.create(4)
+		buffer.writeu32(length, 0, #header)
+		state.deleting = true
+		local response, failure = request("PUT", "/v1/roots/" .. state.manifest.id .. "/boundary", buffer.tostring(length) .. header, { ["Content-Type"] = "application/octet-stream" })
+		state.deleting = false
+		if not response or not response.Success then
+			setStatus(state, "Deletion failed: " .. (failure or responseError(response)), Color3.fromRGB(245, 106, 106))
+			return
+		end
+		for _, candidate in affected do
+			disconnectRoot(candidate)
+			forgetHash(candidate)
+			candidate.coveredByBoundary = state.manifest.id
+			candidate.conflict = false
+			setStatus(candidate, "Deleted Studio → file", Color3.fromRGB(102, 214, 139))
+		end
+		configETag = nil
+		treeDiscovery[state.manifest.treeRootId].dirty = true
+		return
+	end
+	if not explicit and state.manifest.treeRootId then
+		local parentPath = table.clone(state.manifest.studioPath)
+		table.remove(parentPath)
+		if not resolveRoot(parentPath, state.manifest.instanceIds) then
+			state.conflict = true
+			setStatus(state, "Parent removed. Push to remove its saved subtree; Pull to restore it.", Color3.fromRGB(245, 106, 106))
+			return
+		end
+	end
 	if state.uploading or state.pulling or state.deleting then
 		return
 	end
 	state.generation += 1
 	state.dirty = false
+	if explicit then state.lastHash = state.manifest.hash end
 	if state.manifest.gitConflict or not state.lastHash then
 		state.conflict = true
 		setStatus(state, "Root removed; resolve the existing file conflict manually.", Color3.fromRGB(245, 106, 106))
@@ -1233,6 +1324,7 @@ deleteSnapshot = function(state)
 end
 
 upload = function(state, overwrite)
+	if state.coveredByBoundary then return end
 	if state.uploading or state.pulling or state.deleting then
 		return
 	end
@@ -1244,25 +1336,132 @@ upload = function(state, overwrite)
 		setStatus(state, "Paused — Rojo is offline.", Color3.fromRGB(244, 194, 92))
 		return
 	end
-	local root = resolveRoot(state.manifest.studioPath)
+	local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 	if not root then
+		if state.manifest.deleted and not state.manifest.exists then
+			state.conflict = false
+			setStatus(state, "Deleted", Color3.fromRGB(102, 214, 139))
+			return
+		end
+		if overwrite then
+			local owner = state
+			for _, candidate in states do
+				if candidate.manifest.treeRootId == state.manifest.treeRootId and candidate.manifest.container
+					and #candidate.manifest.studioPath < #owner.manifest.studioPath
+					and pathStartsWith(candidate.manifest.studioPath, state.manifest.studioPath, candidate.manifest.instanceIds, state.manifest.instanceIds)
+					and not resolveRoot(candidate.manifest.studioPath, candidate.manifest.instanceIds) then owner = candidate end
+			end
+			deleteSnapshot(owner, true)
+			return
+		end
 		state.conflict = true
 		setStatus(state, "Studio root is missing. Pull to restore it.", Color3.fromRGB(245, 106, 106))
 		return
 	end
-	local scriptInstance = findCode(root)
-	if scriptInstance then
-		state.conflict = true
-		setStatus(state, "Blocked: contains code at " .. scriptInstance:GetFullName(), Color3.fromRGB(245, 106, 106))
+	if state.manifest.treeRootId and not state.boundary then
+		for _, tree in serverConfig.treeRoots do
+			if tree.id ~= state.manifest.treeRootId then continue end
+			if TreeRoots.isContainer(root, #tree.studioPath == #state.manifest.studioPath) ~= state.manifest.container then
+				state.boundary = true
+				treeDiscovery[tree.id].dirty = true
+				setStatus(state, "Storage boundary changed. Refreshing conversion details...", Color3.fromRGB(244, 194, 92))
+				return
+			end
+		end
+	end
+	if state.boundary then
+		if not overwrite then
+			setStatus(state, "Storage boundary changed. Push to convert the saved subtree.", Color3.fromRGB(244, 194, 92))
+			return
+		end
+		state.uploading = true
+		setStatus(state, "Serializing replacement boundary...", Color3.fromRGB(115, 182, 255))
+		local success, packet = pcall(function()
+			local tree
+			for _, candidate in serverConfig.treeRoots do if candidate.id == state.manifest.treeRootId then tree = candidate break end end
+			local entries, snapshots = {}, {}
+			if root.ClassName == "Folder" then TreeRoots.discover({ id = tree.id, studioPath = state.manifest.studioPath }, root, {}, serverConfig.maxPathDepth) end
+			local expected = {}
+			for _, candidate in serverConfig.roots do
+				if candidate.id == state.manifest.id or (states[candidate.id] and states[candidate.id].coveredByBoundary == state.manifest.id) then
+					expected[candidate.id] = candidate.hash or false
+				end
+			end
+			local function visit(instance, path, ids)
+				local container = instance.ClassName == "Folder"
+				local snapshot = if container then TreeRoots.snapshot(instance, getSerializedPropertyNames) else instance
+				local bytes = SerializationService:SerializeInstancesAsync({ snapshot })
+				local restored = SerializationService:DeserializeInstancesAsync(bytes)
+				assert(#restored == 1 and TreeRoots.equal(snapshot, restored[1], getSerializedPropertyNames, container), "Replacement snapshot failed verification")
+				restored[1]:Destroy()
+				if snapshot ~= instance then snapshot:Destroy() end
+				if container and not TreeRoots.needsSnapshot(instance) then bytes = buffer.create(0) end
+				table.insert(entries, { path = path, instanceIds = ids, container = container, size = buffer.len(bytes) })
+				table.insert(snapshots, buffer.tostring(bytes))
+				if not container then return end
+				for _, child in instance:GetChildren() do
+					local childPath, childIds = table.clone(path), table.clone(ids)
+					table.insert(childPath, child.Name)
+					table.insert(childIds, child:GetAttribute("GoldSyncId") or "")
+					visit(child, childPath, childIds)
+				end
+			end
+			local relativePath, relativeIds = {}, {}
+			for depth = #tree.studioPath + 1, #state.manifest.studioPath do
+				table.insert(relativePath, state.manifest.studioPath[depth])
+				table.insert(relativeIds, state.manifest.instanceIds[depth])
+			end
+			visit(root, relativePath, relativeIds)
+			local header = HttpService:JSONEncode({ entries = entries, expected = expected })
+			local length = buffer.create(4)
+			buffer.writeu32(length, 0, #header)
+			return buffer.tostring(length) .. header .. table.concat(snapshots)
+		end)
+		if not success then
+			state.uploading = false
+			setStatus(state, "Conversion failed: " .. tostring(packet), Color3.fromRGB(245, 106, 106))
+			return
+		end
+		local response, failure = request("PUT", "/v1/roots/" .. state.manifest.id .. "/boundary", packet, { ["Content-Type"] = "application/octet-stream" })
+		state.uploading = false
+		if not response or not response.Success then
+			setStatus(state, "Conversion failed: " .. (failure or responseError(response)), Color3.fromRGB(245, 106, 106))
+			return
+		end
+		for _, manifest in HttpService:JSONDecode(response.Body).roots do
+			if manifest.id == state.manifest.id then state.manifest = manifest end
+		end
+		state.boundary = nil
+		state.conflict = false
+		state.dirty = false
+		configETag = nil
+		treeDiscovery[state.manifest.treeRootId].dirty = true
+		setStatus(state, "Synced converted boundary", Color3.fromRGB(102, 214, 139))
+		return
+	end
+
+	local plainFolder = state.manifest.container and not TreeRoots.needsSnapshot(root)
+	if plainFolder and not state.manifest.exists then
+		state.dirty = false
+		state.conflict = false
+		forgetHash(state)
+		watchRoot(state, root)
+		setStatus(state, "Synced Folder", Color3.fromRGB(102, 214, 139))
 		return
 	end
 
 	state.uploading = true
 	setStatus(state, "Serializing Studio root...", Color3.fromRGB(115, 182, 255))
 	local serialized, serializationError
+	local snapshot
 	local success, result = pcall(function()
-		return SerializationService:SerializeInstancesAsync({ root })
+		if plainFolder then return buffer.create(0) end
+		snapshot = if state.manifest.container then TreeRoots.snapshot(root, getSerializedPropertyNames) else root
+		return SerializationService:SerializeInstancesAsync({ snapshot })
 	end)
+	if snapshot and snapshot ~= root then
+		snapshot:Destroy()
+	end
 	if success then
 		serialized = result
 	else
@@ -1280,9 +1479,10 @@ upload = function(state, overwrite)
 	elseif state.lastHash then
 		expectedHash = state.lastHash
 	end
-	local response, requestError = request("PUT", "/v1/roots/" .. state.manifest.id .. "/snapshot", buffer.tostring(serialized), {
+	local response, requestError = request(if plainFolder then "DELETE" else "PUT", "/v1/roots/" .. state.manifest.id .. "/snapshot", buffer.tostring(serialized), {
 		["Content-Type"] = "application/octet-stream",
 		["If-Match"] = expectedHash,
+		["X-GoldSync-Plain-Folder"] = if plainFolder then "1" else "0",
 	})
 	state.uploading = false
 	if not response then
@@ -1308,12 +1508,13 @@ upload = function(state, overwrite)
 	state.manifest = manifest
 	state.dirty = false
 	state.conflict = false
-	rememberHash(state, manifest.hash)
+	if manifest.hash then rememberHash(state, manifest.hash) else forgetHash(state) end
 	watchRoot(state, root)
 	setStatus(state, "Synced Studio → file", Color3.fromRGB(102, 214, 139))
 end
 
-pull = function(state)
+pull = function(state, adoptOnly)
+	if state.coveredByBoundary then return end
 	if state.uploading or state.pulling or state.deleting then
 		return
 	end
@@ -1326,25 +1527,57 @@ pull = function(state)
 		return
 	end
 	if not state.manifest.exists then
+		if state.manifest.container then
+			local parent = resolveParent(state.manifest.studioPath, state.manifest.instanceIds)
+			if not parent then
+				setStatus(state, "Studio parent path is missing.", Color3.fromRGB(245, 106, 106))
+				return
+			end
+			local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
+			if root and root.ClassName ~= "Folder" then
+				setStatus(state, "Missing metadata represents a Folder. Push to keep this class.", Color3.fromRGB(245, 106, 106))
+				return
+			end
+			local snapshot = Instance.new("Folder")
+			snapshot.Name = state.manifest.studioPath[#state.manifest.studioPath]
+			local id = state.manifest.instanceIds[#state.manifest.studioPath]
+			if id ~= "" then snapshot:SetAttribute("GoldSyncId", id) end
+			if root then
+				local applied, failure = pcall(TreeRoots.applyMetadata, root, snapshot, getSerializedPropertyNames)
+				snapshot:Destroy()
+				if not applied then
+					setStatus(state, tostring(failure), Color3.fromRGB(245, 106, 106))
+					return
+				end
+			else
+				root = snapshot
+				root.Parent = parent
+			end
+			forgetHash(state)
+			watchRoot(state, root)
+			state.dirty = false
+			state.conflict = false
+			setStatus(state, "Synced Folder", Color3.fromRGB(102, 214, 139))
+			return
+		end
 		setStatus(state, "No file snapshot exists. Push Studio first.", Color3.fromRGB(245, 106, 106))
 		return
 	end
-	local parent = resolveParent(state.manifest.studioPath)
+	local parent = resolveParent(state.manifest.studioPath, state.manifest.instanceIds)
 	if not parent then
 		setStatus(state, "Studio parent path is missing.", Color3.fromRGB(245, 106, 106))
 		return
 	end
-	local currentRoot = resolveRoot(state.manifest.studioPath)
-	local currentScript = currentRoot and findCode(currentRoot)
-	if currentScript then
-		state.conflict = true
-		setStatus(state, "Blocked: Studio root contains code at " .. currentScript:GetFullName(), Color3.fromRGB(245, 106, 106))
-		return
-	end
+	local currentRoot = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 
 	state.pulling = true
 	setStatus(state, "Loading file snapshot...", Color3.fromRGB(115, 182, 255))
-	local response, requestError = request("GET", "/v1/roots/" .. state.manifest.id .. "/snapshot")
+	local response = snapshotBatch[state.manifest.id]
+	snapshotBatch[state.manifest.id] = nil
+	local requestError
+	if not response then
+		response, requestError = request("GET", "/v1/roots/" .. state.manifest.id .. "/snapshot")
+	end
 	if not response then
 		state.pulling = false
 		setStatus(state, "Daemon unavailable: " .. requestError, Color3.fromRGB(245, 106, 106))
@@ -1355,6 +1588,12 @@ pull = function(state)
 		setStatus(state, "Download failed (HTTP " .. response.StatusCode .. ")", Color3.fromRGB(245, 106, 106))
 		return
 	end
+	local downloadedHash = response.Headers and (response.Headers.ETag or response.Headers.etag)
+	if downloadedHash ~= '"' .. state.manifest.hash .. '"' then
+		state.pulling = false
+		setStatus(state, "File changed during download; waiting for the next refresh.", Color3.fromRGB(244, 194, 92))
+		return
+	end
 
 	local success, instances = pcall(function()
 		return SerializationService:DeserializeInstancesAsync(buffer.fromstring(response.Body))
@@ -1375,24 +1614,70 @@ pull = function(state)
 
 	local replacement = instances[1]
 	local expectedName = state.manifest.studioPath[#state.manifest.studioPath]
-	local scriptInstance = findCode(replacement)
-	if replacement.Name ~= expectedName or scriptInstance then
+	if state.manifest.instanceIds and (replacement:GetAttribute("GoldSyncId") or "") ~= state.manifest.instanceIds[#state.manifest.studioPath] then
+		replacement:Destroy()
+		state.pulling = false
+		setStatus(state, "Blocked: snapshot GoldSyncId does not match its file.", Color3.fromRGB(245, 106, 106))
+		return
+	end
+	if replacement.Name ~= expectedName then
 		replacement:Destroy()
 		state.pulling = false
-		if scriptInstance then
-			setStatus(state, "Blocked: file snapshot contains code.", Color3.fromRGB(245, 106, 106))
+		setStatus(state, "Blocked: root must be named " .. expectedName, Color3.fromRGB(245, 106, 106))
+		return
+	end
+	if state.manifest.treeRootId then
+		local isRoot = false
+		for _, tree in serverConfig.treeRoots do
+			if tree.id == state.manifest.treeRootId then
+				isRoot = #tree.studioPath == #state.manifest.studioPath
+				break
+			end
+		end
+		if TreeRoots.isContainer(replacement, isRoot) ~= state.manifest.container then
+			replacement:Destroy()
+			state.pulling = false
+			state.conflict = true
+			setStatus(state, "Blocked: migrate this snapshot to Folder boundaries first.", Color3.fromRGB(245, 106, 106))
+			return
+		end
+	end
+	if state.manifest.container and #replacement:GetChildren() > 0 then
+		replacement:Destroy()
+		state.pulling = false
+		setStatus(state, "Blocked: container snapshot contains children.", Color3.fromRGB(245, 106, 106))
+		return
+	end
+	if adoptOnly and currentRoot then
+		local compared, matches = pcall(TreeRoots.equal, currentRoot, replacement, getSerializedPropertyNames, state.manifest.container)
+		replacement:Destroy()
+		state.pulling = false
+		state.conflict = not compared or not matches
+		if not compared then
+			setStatus(state, "Could not compare existing instance: " .. tostring(matches), Color3.fromRGB(245, 106, 106))
+			return
+		end
+		if matches then
+			rememberHash(state, state.manifest.hash)
+			state.dirty = false
+			setStatus(state, "Synced existing Studio instance", Color3.fromRGB(102, 214, 139))
+			if state.manifest.container and not TreeRoots.needsSnapshot(currentRoot) then upload(state, false) end
 		else
-			setStatus(state, "Blocked: root must be named " .. expectedName, Color3.fromRGB(245, 106, 106))
+			setStatus(state, "Studio differs from file. Choose Push or Pull; nothing was replaced.", Color3.fromRGB(244, 194, 92))
 		end
 		return
 	end
 
 	state.suppress = true
 	disconnectRoot(state)
-	local previous = resolveRoot(state.manifest.studioPath)
+	local previous = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 	ChangeHistoryService:SetWaypoint("GoldSync before Pull")
 	local applied, applyError = pcall(function()
-		replacement.Parent = parent
+		if state.manifest.container and previous then
+			TreeRoots.applyMetadata(previous, replacement, getSerializedPropertyNames)
+		else
+			replacement.Parent = parent
+		end
 	end)
 	if not applied then
 		replacement:Destroy()
@@ -1404,7 +1689,10 @@ pull = function(state)
 		setStatus(state, "Could not apply snapshot: " .. tostring(applyError), Color3.fromRGB(245, 106, 106))
 		return
 	end
-	if previous then
+	if previous and state.manifest.container then
+		replacement:Destroy()
+		replacement = previous
+	elseif previous then
 		previous:Destroy()
 	end
 	ChangeHistoryService:SetWaypoint("GoldSync Pull " .. expectedName)
@@ -1441,10 +1729,6 @@ local function deserializeConflictStage(state, stage)
 		end
 		return nil, "snapshot must contain exactly one root"
 	end
-	if findCode(instances[1]) then
-		instances[1]:Destroy()
-		return nil, "snapshot contains code"
-	end
 	return instances[1]
 end
 
@@ -1466,9 +1750,11 @@ local function destroyConflictWorkspace(state)
 			parent:Destroy()
 		end
 	end
-	state.mergeButton.Text = "Open Merge Workspace"
-	state.mergeButton.Size = UDim2.fromScale(1, 1)
-	state.diffButton.Visible = false
+	if state.row then
+		state.mergeButton.Text = "Open Merge Workspace"
+		state.mergeButton.Size = UDim2.fromScale(1, 1)
+		state.diffButton.Visible = false
+	end
 end
 
 openGitConflict = function(state)
@@ -1574,8 +1860,12 @@ resolveGitConflict = function(state)
 	end
 	local resultRoot = resultChildren[1]
 	local expectedName = state.manifest.studioPath[#state.manifest.studioPath]
-	if resultRoot.Name ~= expectedName or findCode(resultRoot) then
-		setStatus(state, "Result must be a code-free root named " .. expectedName .. ".", Color3.fromRGB(245, 106, 106))
+	if state.manifest.instanceIds and (resultRoot:GetAttribute("GoldSyncId") or "") ~= state.manifest.instanceIds[#state.manifest.studioPath] then
+		setStatus(state, "Result GoldSyncId must match its file.", Color3.fromRGB(245, 106, 106))
+		return
+	end
+	if resultRoot.Name ~= expectedName then
+		setStatus(state, "Result must be a root named " .. expectedName .. ".", Color3.fromRGB(245, 106, 106))
 		return
 	end
 
@@ -1622,28 +1912,28 @@ local function setGroupExpanded(group, expanded)
 	group.name.Text = group.label .. group.summary
 end
 
-local function pathStartsWith(prefix, fullPath)
+pathStartsWith = function(prefix, fullPath, prefixIds, fullIds)
 	if #prefix > #fullPath then
 		return false
 	end
 	for index, segment in prefix do
-		if fullPath[index] ~= segment then
+		if fullPath[index] ~= segment or (prefixIds and prefixIds[index] or "") ~= (fullIds and fullIds[index] or "") then
 			return false
 		end
 	end
 	return true
 end
 
-local function createGroup(path, order)
-	local key = table.concat(path, "\0")
+local function createGroup(path, order, instanceIds, attention)
+	local key = (if attention then "attention:" else "") .. TreeRoots.pathKey(path, instanceIds)
 	if groups[key] then
 		return groups[key]
 	end
 	local parentGroup
-	if #path > 1 then
+	if #path > 1 and not attention then
 		local parentPath = table.clone(path)
 		table.remove(parentPath)
-		parentGroup = createGroup(parentPath, order)
+		parentGroup = createGroup(parentPath, order, instanceIds and table.move(instanceIds, 1, #parentPath, 1, {}))
 	end
 
 	local section = Instance.new("Frame")
@@ -1651,7 +1941,7 @@ local function createGroup(path, order)
 	section.BackgroundTransparency = 1
 	section.LayoutOrder = order
 	section.Size = UDim2.new(1, 0, 0, 0)
-	section.Parent = if parentGroup then parentGroup.list else rootsContainer
+	section.Parent = if attention then attentionList elseif parentGroup then parentGroup.list else rootsContainer
 
 	local sectionLayout = Instance.new("UIListLayout")
 	sectionLayout.Padding = UDim.new(0, 2)
@@ -1687,7 +1977,7 @@ local function createGroup(path, order)
 	icon.Position = UDim2.new(0, 19, 0.5, -8)
 	icon.Size = UDim2.fromOffset(16, 16)
 	icon.Parent = header
-	local parentInstance = resolveRoot(path)
+	local parentInstance = resolveRoot(path, instanceIds)
 	applyClassIcon(icon, if parentInstance then parentInstance.ClassName else "Folder")
 
 	local name = Instance.new("TextButton")
@@ -1770,8 +2060,10 @@ local function createGroup(path, order)
 
 	local group = {
 		key = key,
-		label = path[#path],
+		label = if attention then TreeRoots.displayPath(path, instanceIds) else TreeRoots.displayName(path[#path], instanceIds and instanceIds[#path]),
+		attention = attention,
 		path = table.clone(path),
+		instanceIds = instanceIds,
 		section = section,
 		header = header,
 		disclosure = disclosure,
@@ -1786,12 +2078,14 @@ local function createGroup(path, order)
 		summary = "",
 	}
 	groups[key] = group
-	setGroupExpanded(group, #path <= 2)
+	setGroupExpanded(group, attention or #path <= 2)
 	disclosure.Activated:Connect(function()
 		setGroupExpanded(group, not group.expanded)
+		applyTreeFilter()
 	end)
 	name.Activated:Connect(function()
 		setGroupExpanded(group, not group.expanded)
+		applyTreeFilter()
 	end)
 	bulkPush.Activated:Connect(function()
 		if bulkRunning then
@@ -1799,7 +2093,8 @@ local function createGroup(path, order)
 		end
 		bulkRunning = true
 		for _, state in states do
-			if pathStartsWith(group.path, state.manifest.studioPath) and not state.manifest.gitConflict then
+			if group.attention and state.statusKind ~= "issue" then continue end
+			if pathStartsWith(group.path, state.manifest.studioPath, group.instanceIds, state.manifest.instanceIds) and not state.manifest.gitConflict then
 				upload(state, true)
 			end
 		end
@@ -1811,7 +2106,8 @@ local function createGroup(path, order)
 		end
 		bulkRunning = true
 		for _, state in states do
-			if pathStartsWith(group.path, state.manifest.studioPath) and not state.manifest.gitConflict then
+			if group.attention and state.statusKind ~= "issue" then continue end
+			if pathStartsWith(group.path, state.manifest.studioPath, group.instanceIds, state.manifest.instanceIds) and not state.manifest.gitConflict then
 				pull(state)
 			end
 		end
@@ -1822,6 +2118,7 @@ end
 
 local function setRootExpanded(state, expanded)
 	state.expanded = expanded
+	if not state.row then return end
 	state.row.BackgroundTransparency = 1
 	state.file.Visible = expanded
 	state.status.Visible = expanded
@@ -1830,30 +2127,30 @@ local function setRootExpanded(state, expanded)
 end
 
 updateGroupSummaries = function()
+	local totals = {}
 	for _, group in groups do
-		local total = 0
-		local synced = 0
-		local issues = 0
-		local issueColor = Color3.fromRGB(244, 194, 92)
-		local pending = 0
-		local paused = 0
-		for _, state in states do
-			if pathStartsWith(group.path, state.manifest.studioPath) then
-				total += 1
-				if state.statusKind == "synced" then
-					synced += 1
-				elseif state.statusKind == "issue" then
-					issues += 1
-					if state.status.TextColor3 == Color3.fromRGB(245, 106, 106) then
-						issueColor = state.status.TextColor3
-					end
-				elseif state.statusKind == "paused" then
-					paused += 1
-				else
-					pending += 1
-				end
+		totals[group] = { total = 0, synced = 0, issue = 0, paused = 0, pending = 0, issueColor = Color3.fromRGB(244, 194, 92) }
+	end
+	for _, state in states do
+		if state.coveredByBoundary then continue end
+		for depth = 1, #state.manifest.studioPath do
+			local key = TreeRoots.pathKey(state.manifest.studioPath, state.manifest.instanceIds, depth)
+			local group = groups[key]
+			local counts = group and totals[group]
+			if not counts then continue end
+			counts.total += 1
+			local kind = if state.statusKind == "synced" or state.statusKind == "issue" or state.statusKind == "paused" then state.statusKind else "pending"
+			counts[kind] += 1
+			if kind == "issue" and state.statusColor == Color3.fromRGB(245, 106, 106) then
+				counts.issueColor = state.statusColor
 			end
 		end
+	end
+	for _, group in groups do
+		local counts = totals[group]
+		if group.attention then continue end
+		local total, synced, issues = counts.total, counts.synced, counts.issue
+		local pending, paused, issueColor = counts.pending, counts.paused, counts.issueColor
 		group.summary = string.format("   (%d/%d) synced", synced, total)
 		if issues > 0 then
 			group.summary ..= string.format(" · %d need attention", issues)
@@ -1882,7 +2179,7 @@ updateGroupSummaries = function()
 				else Color3.fromRGB(95, 95, 105)
 			group.bulkPush.TextColor3 = arrowColor
 			group.bulkPull.TextColor3 = arrowColor
-			setGroupExpanded(group, group.expanded or (issues > 0 and autoExpandConflicts))
+			setGroupExpanded(group, group.expanded or (issues > 0 and autoExpandConflicts and #serverConfig.roots <= 1000))
 		end
 	end
 	if refreshUnsyncedButton then
@@ -1896,7 +2193,7 @@ end
 refreshUnsyncedButton = function()
 	local unsynced = 0
 	for _, state in states do
-		if state.statusKind ~= "synced" then
+		if not state.coveredByBoundary and state.statusKind ~= "synced" then
 			unsynced += 1
 		end
 	end
@@ -1912,20 +2209,25 @@ end
 refreshStatusSummary = function()
 	local issues = {}
 	local working = {}
+	for _, group in groups do if group.attention then group.section.Visible = false end end
 	for _, state in states do
+		if state.coveredByBoundary then continue end
 		local entry = {
-			path = table.concat(state.manifest.studioPath, "."),
-			status = state.status.Text,
+			path = TreeRoots.displayPath(state.manifest.studioPath, state.manifest.instanceIds),
+			status = state.statusText,
 			state = state,
 		}
 		if state.statusKind == "issue" then
 			table.insert(issues, entry)
 		else
-			if state.row.Parent == attentionList then
+			if state.row and state.group.attention then
+				local parentPath = table.clone(state.manifest.studioPath)
+				table.remove(parentPath)
+				state.group = createGroup(parentPath, state.treeOrder, state.manifest.instanceIds)
 				state.row.Parent = state.group.list
 				state.connector.Visible = true
 				state.row.LayoutOrder = state.treeOrder
-				state.title.Text = state.manifest.studioPath[#state.manifest.studioPath]
+				state.title.Text = TreeRoots.displayName(state.manifest.studioPath[#state.manifest.studioPath], state.manifest.instanceIds and state.manifest.instanceIds[#state.manifest.studioPath])
 				setRootExpanded(state, state.expandedBeforeAttention)
 			end
 			if state.statusKind == "working" then
@@ -1955,16 +2257,21 @@ refreshStatusSummary = function()
 	for index, entry in entries do
 		if #issues > 0 then
 			local state = entry.state
-			if state.row.Parent ~= attentionList then
+			if not state.row then continue end
+			if not state.group.attention then
 				state.expandedBeforeAttention = state.expanded
-				state.row.Parent = attentionList
+				local parentPath = table.clone(state.manifest.studioPath)
+				table.remove(parentPath)
+				state.group = createGroup(parentPath, state.treeOrder, state.manifest.instanceIds, true)
+				state.row.Parent = state.group.list
 				state.connector.Visible = false
 				setRootExpanded(state, false)
 			end
+			state.group.section.Visible = true
 			state.row.LayoutOrder = index
-			state.title.Text = entry.path
+			state.title.Text = TreeRoots.displayName(state.manifest.studioPath[#state.manifest.studioPath], state.manifest.instanceIds and state.manifest.instanceIds[#state.manifest.studioPath])
 		else
-			table.insert(lines, entry.path .. " — " .. entry.status)
+			if index <= 10 then table.insert(lines, entry.path .. " — " .. entry.status) end
 		end
 	end
 	statusBanner.BackgroundColor3 = if #issues > 0
@@ -2089,6 +2396,7 @@ local function createInstanceNode(instance, parent, depth, order)
 end
 
 local function resetStateContents(state)
+	if not state.row then return end
 	for _, child in state.contentsList:GetChildren() do
 		if child ~= state.contentsLayout then
 			child:Destroy()
@@ -2098,7 +2406,7 @@ local function resetStateContents(state)
 	state.contentsExpanded = false
 	state.contents.Visible = false
 	state.contentDisclosure.Text = "▸"
-	local root = resolveRoot(state.manifest.studioPath)
+	local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 	state.contentDisclosure.Visible = visualDepth > 0 and root ~= nil and #root:GetChildren() > 0
 end
 
@@ -2124,7 +2432,7 @@ local function toggleRootContents(state)
 	if not state.contentsExpanded then
 		return
 	end
-	local root = resolveRoot(state.manifest.studioPath)
+	local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 	if not root then
 		return
 	end
@@ -2138,10 +2446,36 @@ local function toggleRootContents(state)
 	state.contentsLoaded = true
 end
 
-local function createRootRow(manifest, order)
+local function createRootState(manifest, order)
+	local started = os.clock()
+	local savedHash = savedHashes[manifest.id]
+	if startupProfile then startupProfile.settings += os.clock() - started end
+	local state = {
+		manifest = manifest,
+		treeOrder = order,
+		rootConnections = {},
+		instanceConnections = {},
+		dirty = false,
+		generation = 0,
+		suppress = false,
+		conflict = false,
+		uploading = false,
+		pulling = false,
+		deleting = false,
+		expanded = false,
+		statusText = "Checking...",
+		statusColor = Color3.fromRGB(180, 180, 190),
+		lastHash = if type(savedHash) == "string" then savedHash else nil,
+	}
+	states[manifest.id] = state
+	return state
+end
+
+local function createRootRow(state)
+	local manifest, order = state.manifest, state.treeOrder
 	local parentPath = table.clone(manifest.studioPath)
 	table.remove(parentPath)
-	local group = createGroup(parentPath, order)
+	local group = createGroup(parentPath, order, manifest.instanceIds and table.move(manifest.instanceIds, 1, #parentPath, 1, {}), state.statusKind == "issue")
 	group.hasDirectRoots = true
 	group.bulkPush.Visible = true
 	group.bulkPull.Visible = true
@@ -2197,15 +2531,15 @@ local function createRootRow(manifest, order)
 	icon.Position = UDim2.new(0, 19, 0.5, -8)
 	icon.Size = UDim2.fromOffset(16, 16)
 	icon.Parent = titleLine
-	local rootInstance = resolveRoot(manifest.studioPath)
-	applyClassIcon(icon, if rootInstance then rootInstance.ClassName else "Model")
+	local rootInstance = resolveRoot(manifest.studioPath, manifest.instanceIds)
+	if rootInstance then applyClassIcon(icon, rootInstance.ClassName) end
 
 	local title = Instance.new("TextButton")
 	title.BackgroundTransparency = 1
 	title.Font = Enum.Font.BuilderSansBold
 	title.Position = UDim2.new(0, 39, 0, 0)
 	title.Size = UDim2.new(1, -109, 1, 0)
-	title.Text = manifest.studioPath[#manifest.studioPath]
+	title.Text = TreeRoots.displayName(manifest.studioPath[#manifest.studioPath], manifest.instanceIds and manifest.instanceIds[#manifest.studioPath])
 	title.TextColor3 = Color3.fromRGB(235, 235, 240)
 	title.TextSize = 13
 	title.TextXAlignment = Enum.TextXAlignment.Left
@@ -2217,7 +2551,7 @@ local function createRootRow(manifest, order)
 	dot.Position = UDim2.new(1, -70, 0, 0)
 	dot.Size = UDim2.new(0, 12, 1, 0)
 	dot.Text = "●"
-	dot.TextColor3 = Color3.fromRGB(180, 180, 190)
+	dot.TextColor3 = state.statusColor
 	dot.TextSize = 9
 	dot.Parent = titleLine
 
@@ -2280,8 +2614,8 @@ local function createRootRow(manifest, order)
 	status.Font = Enum.Font.BuilderSans
 	status.LayoutOrder = 3
 	status.Size = UDim2.new(1, 0, 0, 18)
-	status.Text = "Checking..."
-	status.TextColor3 = Color3.fromRGB(180, 180, 190)
+	status.Text = state.statusText
+	status.TextColor3 = state.statusColor
 	status.TextSize = 12
 	status.TextWrapped = true
 	status.TextXAlignment = Enum.TextXAlignment.Left
@@ -2372,18 +2706,14 @@ local function createRootRow(manifest, order)
 		contentsGuide.Size = UDim2.fromOffset(1, contentsLayout.AbsoluteContentSize.Y)
 	end)
 
-	local savedHash = plugin:GetSetting(
-		SETTINGS_PREFIX .. serverConfig.projectId .. ":" .. serverConfig.workspaceId .. ":" .. manifest.id .. ":hash"
-	) or plugin:GetSetting(SETTINGS_PREFIX .. serverConfig.projectId .. ":" .. manifest.id .. ":hash")
-	local state = {
-		manifest = manifest,
+	state.rowFields = {}
+	for key, value in {
 		group = group,
 		row = row,
-		treeOrder = order,
 		connector = connector,
 		title = title,
 		icon = icon,
-		iconClass = if rootInstance then rootInstance.ClassName else "Model",
+		iconClass = rootInstance and rootInstance.ClassName,
 		contentDisclosure = contentDisclosure,
 		contents = contents,
 		contentsList = contentsList,
@@ -2403,21 +2733,10 @@ local function createRootRow(manifest, order)
 		pullButton = pullButton,
 		mergeButton = mergeButton,
 		diffButton = diffButton,
-		root = nil,
-		rootConnections = {},
-		instanceConnections = {},
-		dirty = false,
-		generation = 0,
-		suppress = false,
-		conflict = false,
-		uploading = false,
-		pulling = false,
-		deleting = false,
-		conflictWorkspace = nil,
-		expanded = false,
-		lastHash = if type(savedHash) == "string" then savedHash else nil,
-	}
-	states[manifest.id] = state
+	} do
+		state[key] = value
+		table.insert(state.rowFields, key)
+	end
 	contentDisclosure.Activated:Connect(function()
 		toggleRootContents(state)
 	end)
@@ -2425,7 +2744,7 @@ local function createRootRow(manifest, order)
 		setRootExpanded(state, not state.expanded)
 	end)
 	title.Activated:Connect(function()
-		local root = resolveRoot(state.manifest.studioPath)
+		local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 		if root then
 			Selection:Set({ root })
 		end
@@ -2454,42 +2773,73 @@ local function createRootRow(manifest, order)
 			inspectorWidget.Enabled = true
 		end
 	end)
+	setRootExpanded(state, state.expanded)
+	state.status.Text = state.statusText
+	state.status.TextColor3 = state.statusColor
+	state.contentDisclosure.Visible = visualDepth > 0 and rootInstance ~= nil and #rootInstance:GetChildren() > 0
+	for _, button in { pushButton, pullButton, miniPush, miniPull } do
+		button.Visible = not manifest.gitConflict
+		button.Active = serverConfig.rojoConnected
+		button.AutoButtonColor = serverConfig.rojoConnected
+	end
+	mergeButton.Visible = manifest.gitConflict == true
 	return state
 end
 
+local function destroyRootRow(state)
+	if not state.row then return end
+	state.row:Destroy()
+	for _, key in state.rowFields do state[key] = nil end
+	state.rowFields = nil
+end
+
 local function reconcile(state, manifest)
 	state.manifest = manifest
+	if state.coveredByBoundary then
+		disconnectRoot(state)
+		state.statusKind = "covered"
+		return
+	end
+	if state.boundary then
+		state.conflict = true
+		setStatus(state, "Storage boundary changed. Push to convert the saved subtree.", Color3.fromRGB(244, 194, 92))
+		return
+	end
 	if manifest.gitConflict then
 		state.conflict = true
-		state.pushButton.Visible = false
-		state.pullButton.Visible = false
-		state.miniPush.Visible = false
-		state.miniPull.Visible = false
-		state.mergeButton.Visible = true
+		if state.row then
+			state.pushButton.Visible = false
+			state.pullButton.Visible = false
+			state.miniPush.Visible = false
+			state.miniPull.Visible = false
+			state.mergeButton.Visible = true
+		end
 		setStatus(state, "Git conflict — resolve in VS Code or open the optional merge workspace.", Color3.fromRGB(245, 106, 106))
-		if autoExpandConflicts then
+		if autoExpandConflicts and state.row then
 			setGroupExpanded(state.group, true)
 			setRootExpanded(state, true)
 		end
 		return
 	end
-	state.pushButton.Visible = true
-	state.pullButton.Visible = true
-	state.miniPush.Visible = true
-	state.miniPull.Visible = true
-	state.mergeButton.Visible = false
-	state.pushButton.Active = serverConfig.rojoConnected
-	state.pullButton.Active = serverConfig.rojoConnected
-	state.miniPush.Active = serverConfig.rojoConnected
-	state.miniPull.Active = serverConfig.rojoConnected
-	state.pushButton.AutoButtonColor = serverConfig.rojoConnected
-	state.pullButton.AutoButtonColor = serverConfig.rojoConnected
-	state.miniPush.AutoButtonColor = serverConfig.rojoConnected
-	state.miniPull.AutoButtonColor = serverConfig.rojoConnected
-	state.miniPush.TextColor3 = if serverConfig.rojoConnected
-		then Color3.fromRGB(115, 182, 255)
-		else Color3.fromRGB(95, 95, 105)
-	state.miniPull.TextColor3 = state.miniPush.TextColor3
+	if state.row then
+		state.pushButton.Visible = true
+		state.pullButton.Visible = true
+		state.miniPush.Visible = true
+		state.miniPull.Visible = true
+		state.mergeButton.Visible = false
+		state.pushButton.Active = serverConfig.rojoConnected
+		state.pullButton.Active = serverConfig.rojoConnected
+		state.miniPush.Active = serverConfig.rojoConnected
+		state.miniPull.Active = serverConfig.rojoConnected
+		state.pushButton.AutoButtonColor = serverConfig.rojoConnected
+		state.pullButton.AutoButtonColor = serverConfig.rojoConnected
+		state.miniPush.AutoButtonColor = serverConfig.rojoConnected
+		state.miniPull.AutoButtonColor = serverConfig.rojoConnected
+		state.miniPush.TextColor3 = if serverConfig.rojoConnected
+			then Color3.fromRGB(115, 182, 255)
+			else Color3.fromRGB(95, 95, 105)
+		state.miniPull.TextColor3 = state.miniPush.TextColor3
+	end
 	if state.conflictWorkspace then
 		destroyConflictWorkspace(state)
 	end
@@ -2497,23 +2847,40 @@ local function reconcile(state, manifest)
 		setStatus(state, "Paused — Rojo offline; conflict viewer remains available.", Color3.fromRGB(244, 194, 92))
 		return
 	end
-	local root = resolveRoot(manifest.studioPath)
+	local root = resolveRoot(manifest.studioPath, manifest.instanceIds)
 	if state.contentRoot ~= root then
 		state.contentRoot = root
 		state.searchQuery = nil
 		resetStateContents(state)
-	elseif root then
+	elseif root and state.row then
 		state.contentDisclosure.Visible = visualDepth > 0 and #root:GetChildren() > 0
 	end
-	if root and state.iconClass ~= root.ClassName then
+	if root and state.row and state.iconClass ~= root.ClassName then
 		state.iconClass = root.ClassName
 		applyClassIcon(state.icon, root.ClassName)
 	end
 	if root and state.root ~= root then
 		watchRoot(state, root)
 	end
+	if not root and manifest.treeRootId then
+		if manifest.deleted then
+			state.conflict = false
+			setStatus(state, "Deleted", Color3.fromRGB(102, 214, 139))
+			return
+		end
+		state.conflict = true
+		setStatus(state, "Studio root is missing. Push to remove saved files; Pull to restore it.", Color3.fromRGB(245, 106, 106))
+		return
+	end
 
 	if not manifest.exists then
+		if manifest.container and root and not TreeRoots.needsSnapshot(root) then
+			forgetHash(state)
+			state.conflict = false
+			state.dirty = false
+			setStatus(state, "Synced Folder", Color3.fromRGB(102, 214, 139))
+			return
+		end
 		if manifest.deleted and not root then
 			state.conflict = false
 			setStatus(state, "Deleted", Color3.fromRGB(102, 214, 139))
@@ -2535,6 +2902,12 @@ local function reconcile(state, manifest)
 		return
 	end
 	if not state.lastHash then
+		if manifest.treeRootId then
+			if not state.conflict then
+				pull(state, true)
+			end
+			return
+		end
 		state.conflict = true
 		setStatus(state, "First sync needs Push or Pull once.", Color3.fromRGB(244, 194, 92))
 		return
@@ -2562,15 +2935,32 @@ local function refreshSettingsLabels()
 end
 
 applyTreeFilter = function()
+	if filteringTree then
+		filterAgain = true
+		return
+	end
+	filteringTree = true
 	local query = string.lower(searchBox.Text)
+	local visibleGroups = {}
+	local orderedStates = {}
+	local parentsWithChildren = {}
 	for _, state in states do
+		table.insert(orderedStates, state)
+		local manifest = state.manifest
+		parentsWithChildren[TreeRoots.pathKey(manifest.studioPath, manifest.instanceIds, #manifest.studioPath - 1)] = true
+	end
+	table.sort(orderedStates, function(left, right) return left.treeOrder < right.treeOrder end)
+	local previousBatching = batchingStatusUpdates
+	batchingStatusUpdates = true
+	local sliceStarted = os.clock()
+	for _, state in orderedStates do
 		if state.searchQuery ~= query then
 			local searchable = string.lower(
-				table.concat(state.manifest.studioPath, ".") .. " " .. state.manifest.file .. " " .. state.status.Text
+				table.concat(state.manifest.studioPath, ".") .. " " .. state.manifest.file .. " " .. state.statusText
 			)
 			local matches = query == "" or string.find(searchable, query, 1, true) ~= nil
-			if not matches then
-				local root = resolveRoot(state.manifest.studioPath)
+			if not matches and not state.manifest.container then
+				local root = resolveRoot(state.manifest.studioPath, state.manifest.instanceIds)
 				if root then
 					for _, descendant in root:GetDescendants() do
 						if string.find(string.lower(descendant.Name .. " " .. descendant.ClassName), query, 1, true) then
@@ -2583,21 +2973,43 @@ applyTreeFilter = function()
 			state.searchQuery = query
 			state.searchMatches = matches
 		end
-		state.row.Visible = state.searchMatches and (showSynced or state.statusKind ~= "synced")
-	end
-	for _, group in groups do
-		local hasVisibleDescendant = false
-		for _, state in states do
-			if state.row.Visible and pathStartsWith(group.path, state.manifest.studioPath) then
-				hasVisibleDescendant = true
-				break
+		local visible = not state.coveredByBoundary and state.searchMatches and (showSynced or state.statusKind ~= "synced")
+		local needsAttention = state.statusKind == "issue"
+		local folderGroup = state.manifest.container and parentsWithChildren[TreeRoots.pathKey(state.manifest.studioPath, state.manifest.instanceIds)]
+		if visible and not needsAttention then
+			for depth = 1, #state.manifest.studioPath - (if folderGroup then 0 else 1) do
+				local parentPath = table.move(state.manifest.studioPath, 1, depth, 1, {})
+				local group = createGroup(parentPath, state.treeOrder, state.manifest.instanceIds and table.move(state.manifest.instanceIds, 1, depth, 1, {}))
+				visibleGroups[group] = true
+				if not group.expanded then
+					visible = false
+					break
+				end
 			end
+			if folderGroup then visible = false end
 		end
-		group.section.Visible = hasVisibleDescendant
-		if query ~= "" and hasVisibleDescendant then
-			setGroupExpanded(group, true)
+		if visible and not state.row then
+			createRootRow(state)
+		elseif not visible and state.row and not state.conflictWorkspace then
+			destroyRootRow(state)
+		end
+		if state.row then state.row.Visible = visible end
+		if os.clock() - sliceStarted >= 0.004 then
+			task.wait()
+			sliceStarted = os.clock()
 		end
 	end
+	updateGroupSummaries()
+	for _, group in groups do
+		if not group.attention then group.section.Visible = visibleGroups[group] == true end
+	end
+	batchingStatusUpdates = previousBatching
+	refreshStatusSummary()
+	filteringTree = false
+	if filterAgain then
+		filterAgain = false
+		task.defer(applyTreeFilter)
+	end
 end
 
 addButtonHover(settingsButton)
@@ -2667,12 +3079,16 @@ local function manifestChanged(previous, current)
 		or previous.conflictToken ~= current.conflictToken
 		or previous.file ~= current.file
 		or previous.splitRootId ~= current.splitRootId
-		or table.concat(previous.studioPath, "\0") ~= table.concat(current.studioPath, "\0")
+		or previous.treeRootId ~= current.treeRootId
+		or previous.container ~= current.container
+		or TreeRoots.pathKey(previous.studioPath, previous.instanceIds) ~= TreeRoots.pathKey(current.studioPath, current.instanceIds)
 end
 
 refreshConfig = function()
-	local response, requestError = request("GET", "/v1/config")
-	if not response or not response.Success then
+	local refreshStarted = os.clock()
+	local response, requestError = request("GET", "/v1/config", nil, if configETag then { ["If-None-Match"] = configETag } else nil)
+	if not response or (not response.Success and response.StatusCode ~= 304) then
+		configETag = nil
 		local reason = requestError or (if response then responseError(response) else nil) or "connect Rojo to start syncing"
 		if serverConfig then
 			serverConfig.rojoConnected = false
@@ -2683,18 +3099,29 @@ refreshConfig = function()
 		return false
 	end
 
-	local decoded = HttpService:JSONDecode(response.Body)
+	local decoded = if response.StatusCode == 304 then serverConfig else HttpService:JSONDecode(response.Body)
+	configETag = response.Headers.ETag or response.Headers.etag
 	local projectChanged = serverConfig
 		and (serverConfig.projectId ~= decoded.projectId or serverConfig.workspaceId ~= decoded.workspaceId)
 	local connectionChanged = serverConfig and serverConfig.rojoConnected ~= decoded.rojoConnected
+	local hashesKey = SETTINGS_PREFIX .. decoded.projectId .. ":" .. decoded.workspaceId .. ":hashes"
+	if savedHashesKey ~= hashesKey then
+		saveHashes()
+		local settingsStarted = os.clock()
+		local stored = plugin:GetSetting(hashesKey)
+		if startupProfile then startupProfile.settings += os.clock() - settingsStarted end
+		savedHashes = if type(stored) == "table" then stored else {}
+		savedHashesKey = hashesKey
+	end
 	if projectChanged then
 		for _, state in states do
 			disconnectRoot(state)
 			destroyConflictWorkspace(state)
-			state.row:Destroy()
+			destroyRootRow(state)
 		end
 		disconnectSplitRoots()
 		table.clear(states)
+		table.clear(treeDiscovery)
 		for _, child in rootsContainer:GetChildren() do
 			if child ~= rootsLayout then
 				child:Destroy()
@@ -2711,6 +3138,49 @@ refreshConfig = function()
 		connectionStatus.TextColor3 = Color3.fromRGB(244, 194, 92)
 	end
 	connectionDot.TextColor3 = connectionStatus.TextColor3
+	if decoded.rojoConnected then
+		for _, tree in decoded.treeRoots or {} do
+			local root = resolveRoot(tree.studioPath)
+			if not root then
+				continue
+			end
+			local discovery = treeDiscovery[tree.id]
+			if not discovery or discovery.root ~= root then
+				discovery = { root = root, dirty = true, nextScan = 0 }
+				treeDiscovery[tree.id] = discovery
+			end
+			if not discovery.dirty and os.clock() < discovery.nextScan then
+				continue
+			end
+			discovery.dirty = false
+			local instancesById = {}
+			for id, state in states do instancesById[id] = state.root end
+			local discovered, entries = pcall(TreeRoots.discover, tree, root, decoded.roots, decoded.maxPathDepth, instancesById)
+			if not discovered then
+				discovery.dirty = true
+				connectionStatus.Text = "Tree discovery paused: " .. tostring(entries)
+				return false
+			end
+			discovery.boundaries = {}
+			local additions = {}
+			for _, entry in entries do
+				if entry.boundaryId then discovery.boundaries[entry.boundaryId] = true else table.insert(additions, entry) end
+			end
+			entries = additions
+			for first = 1, #entries, 1000 do
+				local batch = table.move(entries, first, math.min(first + 999, #entries), 1, {})
+				local discoveryResponse, discoveryError = request("POST", "/v1/trees/" .. tree.id .. "/discover", HttpService:JSONEncode({ entries = batch }), {
+					["Content-Type"] = "application/json",
+				})
+				if not discoveryResponse or not discoveryResponse.Success then
+					discovery.dirty = true
+					connectionStatus.Text = "Tree discovery paused: " .. (discoveryError or responseError(discoveryResponse))
+					return false
+				end
+			end
+			discovery.nextScan = os.clock() + 30
+		end
+	end
 
 	local currentSplitRootIds = {}
 	for _, splitRoot in decoded.splitRoots do
@@ -2727,25 +3197,77 @@ refreshConfig = function()
 		disconnectSplitRoot(id)
 	end
 
+	local boundaryPaths = {}
+	for _, manifest in decoded.roots do
+		local discovery = treeDiscovery[manifest.treeRootId]
+		if discovery and discovery.boundaries and discovery.boundaries[manifest.id] then boundaryPaths[manifest.id] = manifest end
+	end
+	local affectedBoundaries = {}
+	for _, manifest in decoded.roots do
+		for id, boundary in boundaryPaths do
+			if pathStartsWith(boundary.studioPath, manifest.studioPath, boundary.instanceIds, manifest.instanceIds) then affectedBoundaries[manifest.id] = id break end
+		end
+	end
 	local treeChanged = projectChanged == true or connectionChanged == true
 	batchingStatusUpdates = true
+	local sliceStarted = os.clock()
 	for order, manifest in decoded.roots do
+		if decoded.version == 2 and (order - 1) % 50 == 0 then
+			table.clear(snapshotBatch)
+			local ids = {}
+			for index = order, math.min(order + 49, #decoded.roots) do
+				local candidate = decoded.roots[index]
+				local previous = states[candidate.id]
+				local knownHash = if previous then previous.lastHash else savedHashes[candidate.id]
+				if not affectedBoundaries[candidate.id] and candidate.exists and not candidate.gitConflict and knownHash ~= candidate.hash and (not previous or (not previous.dirty and not previous.conflict)) then
+					table.insert(ids, candidate.id)
+				end
+			end
+			if #ids > 0 and decoded.rojoConnected then
+				local downloadStarted = os.clock()
+				local response = request("POST", "/v1/snapshots", HttpService:JSONEncode(ids), { ["Content-Type"] = "application/json" })
+				if startupProfile then startupProfile.downloads += os.clock() - downloadStarted end
+				if response and response.Success then
+					local bytes = buffer.fromstring(response.Body)
+					local offset = 0
+					while offset < buffer.len(bytes) do
+						local length = buffer.readu32(bytes, offset)
+						offset += 4
+						local header = HttpService:JSONDecode(buffer.readstring(bytes, offset, length))
+						offset += length
+						snapshotBatch[header.id] = { Success = true, Body = buffer.readstring(bytes, offset, header.size), Headers = { ETag = '"' .. header.hash .. '"' } }
+						offset += header.size
+					end
+				end
+			end
+		end
 		local state = states[manifest.id]
 		local created = state == nil
 		if created then
-			state = createRootRow(manifest, order)
+			state = createRootState(manifest, order)
 		end
-		local resolvedRoot = resolveRoot(manifest.studioPath)
+		local owner = affectedBoundaries[manifest.id]
+		local boundaryChanged = state.boundary ~= (owner == manifest.id) or state.coveredByBoundary ~= (if owner ~= manifest.id then owner else nil)
+		state.boundary = owner == manifest.id
+		state.coveredByBoundary = if owner ~= manifest.id then owner else nil
+		local resolvedRoot = resolveRoot(manifest.studioPath, manifest.instanceIds)
 		local rootChanged = state.observedRoot ~= resolvedRoot
 		state.observedRoot = resolvedRoot
-		if created or connectionChanged or rootChanged or manifestChanged(state.manifest, manifest) then
+		if created or connectionChanged or rootChanged or boundaryChanged or manifestChanged(state.manifest, manifest) then
+			local reconcileStarted = os.clock()
 			reconcile(state, manifest)
+			if startupProfile then startupProfile.reconcile += os.clock() - reconcileStarted end
 			treeChanged = true
 		else
 			state.manifest = manifest
 		end
+		if os.clock() - sliceStarted >= 0.004 then
+			task.wait()
+			sliceStarted = os.clock()
+		end
 	end
 	local currentIds = {}
+	table.clear(snapshotBatch)
 	for _, manifest in decoded.roots do
 		currentIds[manifest.id] = true
 	end
@@ -2759,7 +3281,7 @@ refreshConfig = function()
 		local state = states[id]
 		disconnectRoot(state)
 		destroyConflictWorkspace(state)
-		state.row:Destroy()
+		destroyRootRow(state)
 		states[id] = nil
 		treeChanged = true
 	end
@@ -2768,6 +3290,11 @@ refreshConfig = function()
 		updateGroupSummaries()
 		applyTreeFilter()
 	end
+	saveHashes()
+	if startupProfile and decoded.rojoConnected and #decoded.roots > 0 then
+		print(string.format("[GoldSync startup] total=%.3fs settings=%.3fs watchers=%.3fs reconciliationIncludingWatchers=%.3fs batchDownloads=%.3fs roots=%d", os.clock() - refreshStarted, startupProfile.settings, startupProfile.watchers, startupProfile.reconcile, startupProfile.downloads, #decoded.roots))
+		startupProfile = nil
+	end
 	return true
 end
 
@@ -2783,6 +3310,7 @@ end)
 
 plugin.Unloading:Connect(function()
 	running = false
+	saveHashes()
 	disconnectSplitRoots()
 	for _, state in states do
 		disconnectRoot(state)
@@ -2796,6 +3324,290 @@ task.spawn(function()
 		task.wait((serverConfig and serverConfig.pollIntervalMs or 750) / 1000)
 	end
 end)
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="2">
+      <Properties>
+        <string name="Name">TreeRoots</string>
+        <string name="Source"><![CDATA[local TreeRoots = {}
+
+local function getInstanceId(instance)
+	local id = instance:GetAttribute("GoldSyncId")
+	if id ~= nil and not (type(id) == "string" and ((#id <= 9 and string.match(id, "^[1-9]%d*$")) or (#id == 32 and string.match(id, "^[0-9a-f]+$")))) then
+		error("Invalid GoldSyncId on " .. instance:GetFullName())
+	end
+	return id or ""
+end
+
+function TreeRoots.pathKey(path, instanceIds, depth)
+	local segments = {}
+	for index = 1, depth or #path do
+		local name = path[index]
+		segments[index] = #name .. ":" .. name .. ":" .. (instanceIds and instanceIds[index] or "")
+	end
+	return table.concat(segments, "/")
+end
+
+function TreeRoots.displayName(name, id)
+	return if id and id ~= "" then name .. " (" .. id .. ")" else name
+end
+
+function TreeRoots.displayPath(path, instanceIds)
+	local names = {}
+	for index, name in path do
+		names[index] = TreeRoots.displayName(name, instanceIds and instanceIds[index])
+	end
+	return table.concat(names, ".")
+end
+
+function TreeRoots.findChild(parent, name, id)
+	local first = parent:FindFirstChild(name)
+	if not first or (first:GetAttribute("GoldSyncId") or "") == id then return first end
+	for _, child in parent:GetChildren() do
+		if child.Name == name and (child:GetAttribute("GoldSyncId") or "") == id then return child end
+	end
+	return nil
+end
+
+function TreeRoots.isContainer(instance, isRoot)
+	return isRoot or instance.ClassName == "Folder"
+end
+
+function TreeRoots.needsSnapshot(instance)
+	return instance.ClassName ~= "Folder" or not instance.Archivable
+		or next(instance:GetAttributes()) ~= nil or #instance:GetTags() > 0
+		or #instance:GetChildren() == 0
+end
+
+function TreeRoots.discover(tree, root, manifests, maxDepth, instancesById)
+	local known = {}
+	local reservedNumbers = {}
+	for _, manifest in manifests do
+		if manifest.treeRootId == tree.id then
+			known[TreeRoots.pathKey(manifest.studioPath, manifest.instanceIds)] = manifest
+			for depth = #tree.studioPath + 1, #manifest.studioPath do
+				local id = manifest.instanceIds and manifest.instanceIds[depth] or ""
+				if #id > 9 or not string.match(id, "^[1-9]%d*$") then continue end
+				local parentKey = TreeRoots.pathKey(manifest.studioPath, manifest.instanceIds, depth - 1)
+				local numbers = reservedNumbers[parentKey] or {}
+				reservedNumbers[parentKey] = numbers
+				local name = string.lower(manifest.studioPath[depth])
+				numbers[name] = math.max(numbers[name] or 1, tonumber(id) + 1)
+			end
+		end
+	end
+	local entries = {}
+	local function visit(instance, relativePath, relativeIds)
+		assert(#tree.studioPath + #relativePath <= maxDepth, "Tree exceeds maxPathDepth")
+		local fullPath = table.clone(tree.studioPath)
+		local fullIds = table.create(#tree.studioPath, "")
+		for _, segment in relativePath do
+			table.insert(fullPath, segment)
+		end
+		for _, id in relativeIds do table.insert(fullIds, id) end
+		local existing = known[TreeRoots.pathKey(fullPath, fullIds)]
+		local container = TreeRoots.isContainer(instance, #relativePath == 0)
+		if existing and existing.container ~= container then
+			table.insert(entries, { path = relativePath, instanceIds = relativeIds, container = container, boundaryId = existing.id })
+			return
+		end
+		if not existing then
+			table.insert(entries, { path = relativePath, instanceIds = relativeIds, container = container })
+		end
+		if not container then
+			return
+		end
+		local children = instance:GetChildren()
+		local owners = {}
+		local nextNumbers = table.clone(reservedNumbers[TreeRoots.pathKey(fullPath, fullIds)] or {})
+		for _, child in children do
+			local id = getInstanceId(child)
+			local name = string.lower(child.Name)
+			local number = if #id <= 9 and string.match(id, "^[1-9]%d*$") then tonumber(id) else nil
+			nextNumbers[name] = math.max(nextNumbers[name] or 1, if number then number + 1 else 1)
+			local key = string.lower(child.Name) .. "\0" .. id
+			local childPath, childIds = table.clone(fullPath), table.clone(fullIds)
+			table.insert(childPath, child.Name)
+			table.insert(childIds, id)
+			local manifest = known[TreeRoots.pathKey(childPath, childIds)]
+			if not owners[key] or (manifest and instancesById and instancesById[manifest.id] == child) then
+				owners[key] = child
+			end
+		end
+		for _, child in children do
+			local id = getInstanceId(child)
+			if owners[string.lower(child.Name) .. "\0" .. id] ~= child then
+				local name = string.lower(child.Name)
+				assert(nextNumbers[name] <= 999999999, "Duplicate number limit reached: " .. child:GetFullName())
+				id = tostring(nextNumbers[name])
+				nextNumbers[name] += 1
+				child:SetAttribute("GoldSyncId", id)
+			end
+			local childPath = table.clone(relativePath)
+			local childIds = table.clone(relativeIds)
+			table.insert(childPath, child.Name)
+			table.insert(childIds, id)
+			visit(child, childPath, childIds)
+		end
+	end
+	visit(root, {}, {})
+	return entries
+end
+
+local function propertiesEqual(left, right, propertyNames, counterparts)
+	local leftAttributes, rightAttributes = left:GetAttributes(), right:GetAttributes()
+	for key, value in leftAttributes do
+		if rightAttributes[key] ~= value then
+			return false
+		end
+	end
+	for key in rightAttributes do
+		if leftAttributes[key] == nil then
+			return false
+		end
+	end
+	if #left:GetTags() ~= #right:GetTags() then
+		return false
+	end
+	for _, tag in left:GetTags() do
+		if not right:HasTag(tag) then
+			return false
+		end
+	end
+	for _, name in propertyNames(left.ClassName) do
+		if name == "Parent" then
+			continue
+		end
+		local leftReadable, leftValue = pcall(function() return left[name] end)
+		local rightReadable, rightValue = pcall(function() return right[name] end)
+		if leftReadable ~= rightReadable then
+			return false
+		end
+		if not leftReadable then
+			continue
+		end
+		if typeof(leftValue) == "Instance" or typeof(rightValue) == "Instance" then
+			if not counterparts then continue end
+			leftValue = counterparts[leftValue] or leftValue
+		elseif typeof(leftValue) == "buffer" and typeof(rightValue) == "buffer" then
+			leftValue, rightValue = buffer.tostring(leftValue), buffer.tostring(rightValue)
+		end
+		if leftValue ~= rightValue then
+			if typeof(leftValue) == "CFrame" and typeof(rightValue) == "CFrame" and leftValue.Position == rightValue.Position then
+				local leftComponents = { leftValue:GetComponents() }
+				local rightComponents = { rightValue:GetComponents() }
+				for index = 4, 12 do
+					if not (math.abs(leftComponents[index] - rightComponents[index]) <= 2 ^ -23) then return false end
+				end
+				continue
+			end
+			return false
+		end
+	end
+	return true
+end
+
+function TreeRoots.equal(first, second, propertyNames, container)
+	local pairsToCompare = {}
+	local counterparts = {}
+	local function pair(left, right)
+		if left.ClassName ~= right.ClassName or left.Name ~= right.Name then return false end
+		if not propertiesEqual(left, right, propertyNames) then return false end
+		counterparts[left] = right
+		table.insert(pairsToCompare, { left, right })
+		if container then return true end
+		local childrenByName = {}
+		local remaining = 0
+		for _, child in right:GetChildren() do
+			if child.ClassName == "TouchTransmitter" then continue end
+			remaining += 1
+			local key = child.ClassName .. "\0" .. child.Name
+			local bucket = childrenByName[key] or {}
+			childrenByName[key] = bucket
+			table.insert(bucket, child)
+		end
+		for _, child in left:GetChildren() do
+			if child.ClassName == "TouchTransmitter" then continue end
+			local bucket = childrenByName[child.ClassName .. "\0" .. child.Name]
+			if not bucket then return false end
+			local matched = false
+			for index, candidate in bucket do
+				local previousCount = #pairsToCompare
+				if pair(child, candidate) then
+					table.remove(bucket, index)
+					remaining -= 1
+					matched = true
+					break
+				end
+				for rollback = #pairsToCompare, previousCount + 1, -1 do
+					counterparts[pairsToCompare[rollback][1]] = nil
+					pairsToCompare[rollback] = nil
+				end
+			end
+			if not matched then return false end
+		end
+		return remaining == 0
+	end
+	if not pair(first, second) then return false end
+	for _, instances in pairsToCompare do
+		if not propertiesEqual(instances[1], instances[2], propertyNames, counterparts) then return false end
+	end
+	return true
+end
+
+local function copyMetadata(target, snapshot, propertyNames)
+	local previous = {}
+	local applied, failure = pcall(function()
+		for _, name in propertyNames(target.ClassName) do
+			if name == "Parent" or name == "Name" then
+				continue
+			end
+			local readable, value, original = pcall(function() return snapshot[name], target[name] end)
+			if readable and value ~= original then
+				previous[name] = { value = original }
+				target[name] = value
+			end
+		end
+	end)
+	if not applied then
+		for name, original in previous do
+			pcall(function() target[name] = original.value end)
+		end
+		error(failure)
+	end
+	for name in target:GetAttributes() do
+		target:SetAttribute(name, nil)
+	end
+	for name, value in snapshot:GetAttributes() do
+		target:SetAttribute(name, value)
+	end
+	for _, tag in target:GetTags() do
+		target:RemoveTag(tag)
+	end
+	for _, tag in snapshot:GetTags() do
+		target:AddTag(tag)
+	end
+end
+
+function TreeRoots.snapshot(root, propertyNames)
+	local snapshot = Instance.new(root.ClassName)
+	snapshot.Name = root.Name
+	local success, failure = pcall(copyMetadata, snapshot, root, propertyNames)
+	if not success then
+		snapshot:Destroy()
+		error(failure)
+	end
+	return snapshot
+end
+
+function TreeRoots.applyMetadata(target, snapshot, propertyNames)
+	assert(target.ClassName == snapshot.ClassName, "Container class changed; resolve manually to preserve children")
+	assert(#snapshot:GetChildren() == 0, "Container snapshot must not contain children")
+	copyMetadata(target, snapshot, propertyNames)
+end
+
+return TreeRoots
 ]]></string>
       </Properties>
     </Item>