dominus-cli 0.6.0 → 2.1.0

package/plugin/src/Properties.lua

@@ -1,725 +1,859 @@
---[[
-	Properties module: read/write instance properties
-	Uses ReflectionService to determine expected types for smart coercion.
-]]
-
-local Explorer = require(script.Parent.Explorer)
-local ReflectionService = game:GetService("ReflectionService")
-
-local Properties = {}
-
-local IGNORED_PROPERTIES = {
-	Parent = true,
-	ClassName = true,
-	Archivable = true,
-}
-
--- Properties that are read-only / computed / redundant — strip in compact mode
-local COMPACT_SKIP = {
-	-- Read-only computed
-	AbsolutePosition = true,
-	AbsoluteSize = true,
-	AbsoluteRotation = true,
-	AbsoluteCanvasSize = true,
-	TextBounds = true,
-	TextFits = true,
-	IsLoaded = true,
-	ContentText = true,
-	LocalizedText = true,
-	GuiState = true,
-	-- Deprecated / redundant (BrickColor duplicates Color3, Font duplicates FontFace)
-	BackgroundColor = true,
-	BorderColor = true,
-	TextColor = true,
-	Font = true,
-	FontSize = true,
-	-- Internal / security
-	Capabilities = true,
-	Sandboxed = true,
-	archivable = true,
-	className = true,
-	Localize = true,
-	-- Selection navigation (almost always nil/default)
-	NextSelectionDown = true,
-	NextSelectionLeft = true,
-	NextSelectionRight = true,
-	NextSelectionUp = true,
-	SelectionBehaviorDown = true,
-	SelectionBehaviorLeft = true,
-	SelectionBehaviorRight = true,
-	SelectionBehaviorUp = true,
-	SelectionGroup = true,
-	SelectionOrder = true,
-	SelectionImageObject = true,
-	-- Rarely useful defaults
-	Draggable = true,
-	InputSink = true,
-	RootLocalizationTable = true,
-	AutoLocalize = true,
-	OpenTypeFeatures = true,
-	OpenTypeFeaturesError = true,
-	Interactable = true,
-	Style = true,
-	BorderMode = true,
-	SizeConstraint = true,
-}
-
--- Default values that are not worth reporting in compact mode
-local COMPACT_DEFAULT_VALUES = {
-	["0"] = true,
-	["1"] = true,
-	["false"] = true,
-	["nil"] = true,
-	[""] = true,
-	["Enum.AutomaticSize.None"] = true,
-	["Enum.TextTruncate.None"] = true,
-	["Enum.TextDirection.Auto"] = true,
-	["Enum.ResamplerMode.Default"] = true,
-	["Enum.ScaleType.Stretch"] = true,
-}
-
--- Cache property type maps per class to avoid repeated reflection calls
-local typeCache = {}
-
-local function getPropertyTypeMap(className)
-	if typeCache[className] then
-		return typeCache[className]
-	end
-
-	local typeMap = {}
-	local ok, props = pcall(function()
-		return ReflectionService:GetPropertiesOfClass(className)
-	end)
-	if ok and props then
-		for _, prop in props do
-			if prop.ValueType then
-				typeMap[prop.Name] = tostring(prop.ValueType)
-			end
-		end
-	end
-	typeCache[className] = typeMap
-	return typeMap
-end
-
-function Properties.get(path, compact)
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	local properties = {}
-
-	local ok, apiData = pcall(function()
-		local info = {}
-		local propData = ReflectionService:GetPropertiesOfClass(instance.ClassName)
-		for _, prop in propData do
-			if not IGNORED_PROPERTIES[prop.Name] then
-				if compact and COMPACT_SKIP[prop.Name] then
-					continue
-				end
-				local valueOk, value = pcall(function()
-					return instance[prop.Name]
-				end)
-				if valueOk then
-					local valueStr = tostring(value)
-					if compact and valueStr == "nil" then
-						continue
-					end
-					table.insert(info, {
-						name = prop.Name,
-						value = valueStr,
-						type = prop.ValueType and tostring(prop.ValueType) or typeof(value),
-						category = prop.Category or "Other",
-					})
-				end
-			end
-		end
-		return info
-	end)
-
-	if ok then
-		properties = apiData
-	else
-		local commonProps =
-			{ "Name", "Position", "Size", "Color", "Material", "Transparency", "Anchored", "CanCollide" }
-		for _, propName in commonProps do
-			local valOk, val = pcall(function()
-				return instance[propName]
-			end)
-			if valOk and val ~= nil then
-				table.insert(properties, {
-					name = propName,
-					value = tostring(val),
-					type = typeof(val),
-				})
-			end
-		end
-	end
-
-	return { properties = properties }
-end
-
-function Properties.getDescendants(path, compact)
-	local rootInstance = Explorer.resolveInstance(path)
-	if not rootInstance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	-- In compact mode, skip noisy/default properties to reduce payload size
-	local shouldSkip = compact
-			and function(propName, valueStr)
-				if COMPACT_SKIP[propName] then
-					return true
-				end
-				-- Skip nil-valued properties
-				if valueStr == "nil" then
-					return true
-				end
-				return false
-			end
-		or function()
-			return false
-		end
-
-	-- Extra compact filter: skip properties that are clearly defaults and non-informative
-	local isBoringDefault = compact
-			and function(propName, valueStr)
-				-- These specific properties at default values are noise
-				local boringAtDefault = {
-					Active = "false",
-					Selectable = "false",
-					ClipsDescendants = "false",
-					TextWrap = "false",
-					TextWrapped = "false",
-					RichText = "false",
-					TextScaled = "false",
-					Rotation = "0",
-					LayoutOrder = "0",
-					MaxVisibleGraphemes = "-1",
-					SliceScale = "1",
-					LineHeight = "1",
-					BorderSizePixel = "1",
-					Visible = "true",
-				}
-				return boringAtDefault[propName] == valueStr
-			end
-		or function()
-			return false
-		end
-
-	local function getProps(instance)
-		local properties = {}
-
-		local ok, apiData = pcall(function()
-			local info = {}
-			local propData = ReflectionService:GetPropertiesOfClass(instance.ClassName)
-			for _, prop in propData do
-				if not IGNORED_PROPERTIES[prop.Name] and not shouldSkip(prop.Name, "") then
-					local valueOk, value = pcall(function()
-						return instance[prop.Name]
-					end)
-					if valueOk then
-						local valueStr = tostring(value)
-						if not shouldSkip(prop.Name, valueStr) and not isBoringDefault(prop.Name, valueStr) then
-							table.insert(info, {
-								name = prop.Name,
-								value = valueStr,
-								type = prop.ValueType and tostring(prop.ValueType) or typeof(value),
-								category = prop.Category or "Other",
-							})
-						end
-					end
-				end
-			end
-			return info
-		end)
-
-		if ok then
-			properties = apiData
-		else
-			local commonProps =
-				{ "Name", "Position", "Size", "Color", "Material", "Transparency", "Anchored", "CanCollide" }
-			for _, propName in commonProps do
-				local valOk, val = pcall(function()
-					return instance[propName]
-				end)
-				if valOk and val ~= nil then
-					table.insert(properties, {
-						name = propName,
-						value = tostring(val),
-						type = typeof(val),
-					})
-				end
-			end
-		end
-
-		return properties
-	end
-
-	local results = {}
-
-	-- Include the root instance itself
-	table.insert(results, {
-		name = rootInstance.Name,
-		className = rootInstance.ClassName,
-		path = Explorer.getPath(rootInstance),
-		properties = getProps(rootInstance),
-	})
-
-	for _, descendant in rootInstance:GetDescendants() do
-		table.insert(results, {
-			name = descendant.Name,
-			className = descendant.ClassName,
-			path = Explorer.getPath(descendant),
-			properties = getProps(descendant),
-		})
-	end
-
-	return { success = true, descendants = results }
-end
-
---[[
-	Smart type coercion: converts JSON-friendly values into Roblox types.
-	Uses the expected property type from ReflectionService when available.
-]]
-local function coerceValue(instance, key, value)
-	local expectedType = nil
-	local typeMap = getPropertyTypeMap(instance.ClassName)
-	expectedType = typeMap[key]
-
-	-- If we don't know the expected type, try reading the current value
-	if not expectedType then
-		local curOk, curVal = pcall(function()
-			return instance[key]
-		end)
-		if curOk and curVal ~= nil then
-			expectedType = typeof(curVal)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- UDim2 (GUI Size, Position, etc.)
-	-- ═══════════════════════════════════════════
-	if expectedType == "UDim2" then
-		if type(value) == "table" then
-			-- {xScale, xOffset, yScale, yOffset} or named keys
-			if value.XScale or value.xScale or value.X then
-				return UDim2.new(
-					value.XScale or value.xScale or value.X and value.X.Scale or 0,
-					value.XOffset or value.xOffset or value.X and value.X.Offset or 0,
-					value.YScale or value.yScale or value.Y and value.Y.Scale or 0,
-					value.YOffset or value.yOffset or value.Y and value.Y.Offset or 0
-				)
-			end
-			-- {X = {Scale, Offset}, Y = {Scale, Offset}}
-			if value.X and type(value.X) == "table" then
-				return UDim2.new(
-					value.X.Scale or value.X[1] or 0,
-					value.X.Offset or value.X[2] or 0,
-					value.Y and (value.Y.Scale or value.Y[1]) or 0,
-					value.Y and (value.Y.Offset or value.Y[2]) or 0
-				)
-			end
-			-- Array: {xScale, xOffset, yScale, yOffset}
-			if value[1] ~= nil then
-				return UDim2.new(value[1] or 0, value[2] or 0, value[3] or 0, value[4] or 0)
-			end
-			-- fromScale shorthand: {scale_x, scale_y} when only 2 elements
-			return UDim2.new(0, 0, 0, 0)
-		end
-		if type(value) == "string" then
-			-- "0.5, 0, 0.5, 0" format
-			local a, b, c, d = value:match("([%d%.%-]+)%s*,%s*([%d%.%-]+)%s*,%s*([%d%.%-]+)%s*,%s*([%d%.%-]+)")
-			if a then
-				return UDim2.new(tonumber(a), tonumber(b), tonumber(c), tonumber(d))
-			end
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- UDim
-	-- ═══════════════════════════════════════════
-	if expectedType == "UDim" then
-		if type(value) == "table" then
-			return UDim.new(value.Scale or value[1] or 0, value.Offset or value[2] or 0)
-		end
-		if type(value) == "number" then
-			return UDim.new(value, 0)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Vector3
-	-- ═══════════════════════════════════════════
-	if expectedType == "Vector3" then
-		if type(value) == "table" then
-			return Vector3.new(
-				value.X or value.x or value[1] or 0,
-				value.Y or value.y or value[2] or 0,
-				value.Z or value.z or value[3] or 0
-			)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Vector2
-	-- ═══════════════════════════════════════════
-	if expectedType == "Vector2" then
-		if type(value) == "table" then
-			return Vector2.new(value.X or value.x or value[1] or 0, value.Y or value.y or value[2] or 0)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Color3
-	-- ═══════════════════════════════════════════
-	if expectedType == "Color3" then
-		if type(value) == "string" then
-			if value:sub(1, 1) == "#" then
-				return Color3.fromHex(value)
-			end
-			if value:match("^rgb") then
-				local r, g, b = value:match("(%d+)%D+(%d+)%D+(%d+)")
-				if r then
-					return Color3.fromRGB(tonumber(r), tonumber(g), tonumber(b))
-				end
-			end
-			local ok, bc = pcall(BrickColor.new, value)
-			if ok then
-				return bc.Color
-			end
-		end
-		if type(value) == "table" then
-			-- {R, G, B} 0-1 or {r, g, b}
-			if value.R or value.r then
-				return Color3.new(value.R or value.r or 0, value.G or value.g or 0, value.B or value.b or 0)
-			end
-			-- {red, green, blue} 0-255
-			if value.red or value.Red then
-				return Color3.fromRGB(
-					value.red or value.Red or 0,
-					value.green or value.Green or 0,
-					value.blue or value.Blue or 0
-				)
-			end
-			-- Array [r, g, b]
-			if value[1] then
-				if value[1] > 1 or value[2] > 1 or value[3] > 1 then
-					return Color3.fromRGB(value[1], value[2], value[3])
-				end
-				return Color3.new(value[1], value[2], value[3])
-			end
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- BrickColor
-	-- ═══════════════════════════════════════════
-	if expectedType == "BrickColor" then
-		if type(value) == "string" then
-			return BrickColor.new(value)
-		end
-		if type(value) == "number" then
-			return BrickColor.new(value)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- CFrame
-	-- ═══════════════════════════════════════════
-	if expectedType == "CFrame" then
-		if type(value) == "table" then
-			if value.Position or value.position then
-				local pos = value.Position or value.position
-				local cf = CFrame.new(
-					pos.x or pos.X or pos[1] or 0,
-					pos.y or pos.Y or pos[2] or 0,
-					pos.z or pos.Z or pos[3] or 0
-				)
-				if value.Rotation or value.rotation then
-					local rot = value.Rotation or value.rotation
-					cf = cf
-						* CFrame.Angles(
-							math.rad(rot.x or rot.X or rot[1] or 0),
-							math.rad(rot.y or rot.Y or rot[2] or 0),
-							math.rad(rot.z or rot.Z or rot[3] or 0)
-						)
-				end
-				return cf
-			end
-			-- Simple {x, y, z}
-			if value[1] then
-				return CFrame.new(value[1], value[2] or 0, value[3] or 0)
-			end
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Rect (for GUI ImageRectOffset, etc.)
-	-- ═══════════════════════════════════════════
-	if expectedType == "Rect" then
-		if type(value) == "table" then
-			return Rect.new(
-				value[1] or value.Min and value.Min[1] or 0,
-				value[2] or value.Min and value.Min[2] or 0,
-				value[3] or value.Max and value.Max[1] or 0,
-				value[4] or value.Max and value.Max[2] or 0
-			)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- NumberRange
-	-- ═══════════════════════════════════════════
-	if expectedType == "NumberRange" then
-		if type(value) == "table" then
-			return NumberRange.new(value.Min or value[1] or 0, value.Max or value[2] or 1)
-		end
-		if type(value) == "number" then
-			return NumberRange.new(value)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- NumberSequence (for transparency gradients, etc.)
-	-- ═══════════════════════════════════════════
-	if expectedType == "NumberSequence" then
-		if type(value) == "table" then
-			if value[1] and type(value[1]) == "table" then
-				local keypoints = {}
-				for _, kp in value do
-					table.insert(
-						keypoints,
-						NumberSequenceKeypoint.new(
-							kp.Time or kp[1] or 0,
-							kp.Value or kp[2] or 0,
-							kp.Envelope or kp[3] or 0
-						)
-					)
-				end
-				return NumberSequence.new(keypoints)
-			end
-			if #value == 2 and type(value[1]) == "number" then
-				return NumberSequence.new(value[1], value[2])
-			end
-		end
-		if type(value) == "number" then
-			return NumberSequence.new(value)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- ColorSequence
-	-- ═══════════════════════════════════════════
-	if expectedType == "ColorSequence" then
-		if type(value) == "table" then
-			if value[1] and type(value[1]) == "table" then
-				local keypoints = {}
-				for _, kp in value do
-					local color = Color3.new(1, 1, 1)
-					if kp.Color then
-						if type(kp.Color) == "string" and kp.Color:sub(1, 1) == "#" then
-							color = Color3.fromHex(kp.Color)
-						elseif type(kp.Color) == "table" then
-							color = Color3.new(kp.Color[1] or 0, kp.Color[2] or 0, kp.Color[3] or 0)
-						end
-					end
-					table.insert(keypoints, ColorSequenceKeypoint.new(kp.Time or kp[1] or 0, color))
-				end
-				return ColorSequence.new(keypoints)
-			end
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Font
-	-- ═══════════════════════════════════════════
-	if expectedType == "Font" then
-		if type(value) == "table" then
-			local family = value.Family or value.family or "rbxasset://fonts/families/SourceSansPro.json"
-			local weight = Enum.FontWeight.Regular
-			local style = Enum.FontStyle.Normal
-			if value.Weight or value.weight then
-				pcall(function()
-					weight = Enum.FontWeight[value.Weight or value.weight]
-				end)
-			end
-			if value.Style or value.style then
-				pcall(function()
-					style = Enum.FontStyle[value.Style or value.style]
-				end)
-			end
-			return Font.new(family, weight, style)
-		end
-		if type(value) == "string" then
-			return Font.new(value)
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- EnumItem (any enum property)
-	-- ═══════════════════════════════════════════
-	if type(value) == "string" then
-		local currentVal = nil
-		pcall(function()
-			currentVal = instance[key]
-		end)
-		if typeof(currentVal) == "EnumItem" then
-			local enumType = tostring(currentVal.EnumType)
-			local enumOk, enumVal = pcall(function()
-				return Enum[enumType][value]
-			end)
-			if enumOk then
-				return enumVal
-			end
-		end
-	end
-
-	-- ═══════════════════════════════════════════
-	-- Fallback: type-agnostic guesses (no expectedType known)
-	-- ═══════════════════════════════════════════
-	if type(value) == "table" and not expectedType then
-		-- UDim2 guess: has XScale/YScale keys
-		if value.XScale or value.xScale then
-			return UDim2.new(
-				value.XScale or value.xScale or 0,
-				value.XOffset or value.xOffset or 0,
-				value.YScale or value.yScale or 0,
-				value.YOffset or value.yOffset or 0
-			)
-		end
-		-- Vector3 guess: 3 number elements or X/Y/Z keys
-		if (value.X or value.x) and (value.Y or value.y) and (value.Z or value.z) then
-			return Vector3.new(value.X or value.x, value.Y or value.y, value.Z or value.z)
-		end
-		if value[1] and value[2] and value[3] and not value[4] then
-			return Vector3.new(value[1], value[2], value[3])
-		end
-		-- Color3 guess: R/G/B keys
-		if value.R or value.r then
-			return Color3.new(value.R or value.r or 0, value.G or value.g or 0, value.B or value.b or 0)
-		end
-		-- Vector2 guess: 2 number elements
-		if value[1] and value[2] and not value[3] then
-			return Vector2.new(value[1], value[2])
-		end
-	end
-
-	-- String-based color on color properties (fallback)
-	if type(value) == "string" and (key == "Color" or key == "Color3" or key:match("Color$")) then
-		if value:sub(1, 1) == "#" then
-			return Color3.fromHex(value)
-		end
-		local ok, bc = pcall(BrickColor.new, value)
-		if ok then
-			return bc.Color
-		end
-	end
-
-	if type(value) == "string" and key == "BrickColor" then
-		return BrickColor.new(value)
-	end
-
-	return value
-end
-
-function Properties.set(path, propertiesToSet)
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	local errors = {}
-	local set = {}
-
-	for key, value in propertiesToSet do
-		local coerced = coerceValue(instance, key, value)
-		local ok, err = pcall(function()
-			instance[key] = coerced
-		end)
-		if ok then
-			table.insert(set, key)
-		else
-			table.insert(errors, key .. ": " .. tostring(err))
-		end
-	end
-
-	if #errors > 0 then
-		return { success = false, error = table.concat(errors, "; "), set = set }
-	end
-
-	return { success = true, set = set }
-end
-
-function Properties.bulkSet(spec)
-	local ChangeHistoryService = game:GetService("ChangeHistoryService")
-	local recording = ChangeHistoryService:TryBeginRecording("Dominus: Bulk set properties")
-
-	local modified = 0
-	local errors = {}
-
-	if spec.targets and type(spec.targets) == "table" then
-		-- Explicit mode: array of {path, properties}
-		for _, target in ipairs(spec.targets) do
-			local instance = Explorer.resolveInstance(target.path)
-			if not instance then
-				table.insert(errors, "Not found: " .. tostring(target.path))
-			else
-				for key, value in target.properties do
-					local coerced = coerceValue(instance, key, value)
-					local ok, err = pcall(function()
-						instance[key] = coerced
-					end)
-					if not ok then
-						table.insert(errors, target.path .. "." .. key .. ": " .. tostring(err))
-					end
-				end
-				modified = modified + 1
-			end
-		end
-	elseif spec.root and spec.properties then
-		-- Filter mode: apply to all matching descendants
-		local root = Explorer.resolveInstance(spec.root)
-		if not root then
-			if recording then
-				ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
-			end
-			return { success = false, error = "Root not found: " .. tostring(spec.root) }
-		end
-
-		local function processInstance(inst)
-			if spec.className and inst.ClassName ~= spec.className then
-				return
-			end
-			for key, value in spec.properties do
-				local coerced = coerceValue(inst, key, value)
-				local ok, err = pcall(function()
-					inst[key] = coerced
-				end)
-				if not ok then
-					table.insert(errors, Explorer.getPath(inst) .. "." .. key .. ": " .. tostring(err))
-				end
-			end
-			modified = modified + 1
-		end
-
-		-- Include root itself if it matches
-		processInstance(root)
-		for _, desc in root:GetDescendants() do
-			processInstance(desc)
-		end
-	else
-		if recording then
-			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
-		end
-		return { success = false, error = "Provide either 'targets' array or 'root' + 'properties'" }
-	end
-
-	if recording then
-		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
-	end
-
-	return { success = true, modified = modified, errors = errors }
-end
-
-return Properties
+--[[
+	Properties module: read/write instance properties
+	Uses ReflectionService to determine expected types for smart coercion.
+]]
+
+local Explorer = require(script.Parent.Explorer)
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local Reflection = require(script.Parent.Reflection)
+local ValueCodec = require(script.Parent.ValueCodec)
+local ReflectionService = game:GetService("ReflectionService")
+
+local Properties = {}
+
+local IGNORED_PROPERTIES = {
+	Parent = true,
+	ClassName = true,
+	Archivable = true,
+}
+
+-- Properties that are read-only / computed / redundant — strip in compact mode
+local COMPACT_SKIP = {
+	-- Read-only computed
+	AbsolutePosition = true,
+	AbsoluteSize = true,
+	AbsoluteRotation = true,
+	AbsoluteCanvasSize = true,
+	TextBounds = true,
+	TextFits = true,
+	IsLoaded = true,
+	ContentText = true,
+	LocalizedText = true,
+	GuiState = true,
+	-- Deprecated / redundant (BrickColor duplicates Color3, Font duplicates FontFace)
+	BackgroundColor = true,
+	BorderColor = true,
+	TextColor = true,
+	Font = true,
+	FontSize = true,
+	-- Internal / security
+	Capabilities = true,
+	Sandboxed = true,
+	archivable = true,
+	className = true,
+	Localize = true,
+	-- Selection navigation (almost always nil/default)
+	NextSelectionDown = true,
+	NextSelectionLeft = true,
+	NextSelectionRight = true,
+	NextSelectionUp = true,
+	SelectionBehaviorDown = true,
+	SelectionBehaviorLeft = true,
+	SelectionBehaviorRight = true,
+	SelectionBehaviorUp = true,
+	SelectionGroup = true,
+	SelectionOrder = true,
+	SelectionImageObject = true,
+	-- Rarely useful defaults
+	Draggable = true,
+	InputSink = true,
+	RootLocalizationTable = true,
+	AutoLocalize = true,
+	OpenTypeFeatures = true,
+	OpenTypeFeaturesError = true,
+	Interactable = true,
+	Style = true,
+	BorderMode = true,
+	SizeConstraint = true,
+}
+
+-- Default values that are not worth reporting in compact mode
+local COMPACT_DEFAULT_VALUES = {
+	["0"] = true,
+	["1"] = true,
+	["false"] = true,
+	["nil"] = true,
+	[""] = true,
+	["Enum.AutomaticSize.None"] = true,
+	["Enum.TextTruncate.None"] = true,
+	["Enum.TextDirection.Auto"] = true,
+	["Enum.ResamplerMode.Default"] = true,
+	["Enum.ScaleType.Stretch"] = true,
+}
+
+-- Cache property type maps per class to avoid repeated reflection calls
+local typeCache = {}
+
+local function getPropertyTypeMap(className)
+	if typeCache[className] then
+		return typeCache[className]
+	end
+
+	local typeMap = {}
+	local ok, props = pcall(function()
+		return ReflectionService:GetPropertiesOfClass(className)
+	end)
+	if ok and props then
+		for _, prop in props do
+			if prop.Type then
+				typeMap[prop.Name] = tostring(prop.Type)
+			end
+		end
+	end
+	typeCache[className] = typeMap
+	return typeMap
+end
+
+function Properties.get(path, compact)
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	local properties = {}
+
+	local ok, apiData = pcall(function()
+		local info = {}
+		local propData = ReflectionService:GetPropertiesOfClass(instance.ClassName)
+		for _, prop in propData do
+			if not IGNORED_PROPERTIES[prop.Name] then
+				if compact and COMPACT_SKIP[prop.Name] then
+					continue
+				end
+				local valueOk, value = pcall(function()
+					return instance[prop.Name]
+				end)
+				if valueOk then
+					local valueStr = tostring(value)
+					if compact and valueStr == "nil" then
+						continue
+					end
+					table.insert(info, {
+						name = prop.Name,
+						value = valueStr,
+						type = prop.Type and tostring(prop.Type) or typeof(value),
+						category = prop.Display and prop.Display.Category or "Other",
+					})
+				end
+			end
+		end
+		return info
+	end)
+
+	if ok then
+		properties = apiData
+	else
+		local commonProps =
+			{ "Name", "Position", "Size", "Color", "Material", "Transparency", "Anchored", "CanCollide" }
+		for _, propName in commonProps do
+			local valOk, val = pcall(function()
+				return instance[propName]
+			end)
+			if valOk and val ~= nil then
+				table.insert(properties, {
+					name = propName,
+					value = tostring(val),
+					type = typeof(val),
+				})
+			end
+		end
+	end
+
+	return { properties = properties }
+end
+
+function Properties.getDescendants(path, compact)
+	local rootInstance = Explorer.resolveInstance(path)
+	if not rootInstance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	-- In compact mode, skip noisy/default properties to reduce payload size
+	local shouldSkip = compact
+			and function(propName, valueStr)
+				if COMPACT_SKIP[propName] then
+					return true
+				end
+				-- Skip nil-valued properties
+				if valueStr == "nil" then
+					return true
+				end
+				return false
+			end
+		or function()
+			return false
+		end
+
+	-- Extra compact filter: skip properties that are clearly defaults and non-informative
+	local isBoringDefault = compact
+			and function(propName, valueStr)
+				-- These specific properties at default values are noise
+				local boringAtDefault = {
+					Active = "false",
+					Selectable = "false",
+					ClipsDescendants = "false",
+					TextWrap = "false",
+					TextWrapped = "false",
+					RichText = "false",
+					TextScaled = "false",
+					Rotation = "0",
+					LayoutOrder = "0",
+					MaxVisibleGraphemes = "-1",
+					SliceScale = "1",
+					LineHeight = "1",
+					BorderSizePixel = "1",
+					Visible = "true",
+				}
+				return boringAtDefault[propName] == valueStr
+			end
+		or function()
+			return false
+		end
+
+	local function getProps(instance)
+		local properties = {}
+
+		local ok, apiData = pcall(function()
+			local info = {}
+			local propData = ReflectionService:GetPropertiesOfClass(instance.ClassName)
+			for _, prop in propData do
+				if not IGNORED_PROPERTIES[prop.Name] and not shouldSkip(prop.Name, "") then
+					local valueOk, value = pcall(function()
+						return instance[prop.Name]
+					end)
+					if valueOk then
+						local valueStr = tostring(value)
+						if not shouldSkip(prop.Name, valueStr) and not isBoringDefault(prop.Name, valueStr) then
+							table.insert(info, {
+								name = prop.Name,
+								value = valueStr,
+								type = prop.Type and tostring(prop.Type) or typeof(value),
+								category = prop.Display and prop.Display.Category or "Other",
+							})
+						end
+					end
+				end
+			end
+			return info
+		end)
+
+		if ok then
+			properties = apiData
+		else
+			local commonProps =
+				{ "Name", "Position", "Size", "Color", "Material", "Transparency", "Anchored", "CanCollide" }
+			for _, propName in commonProps do
+				local valOk, val = pcall(function()
+					return instance[propName]
+				end)
+				if valOk and val ~= nil then
+					table.insert(properties, {
+						name = propName,
+						value = tostring(val),
+						type = typeof(val),
+					})
+				end
+			end
+		end
+
+		return properties
+	end
+
+	local results = {}
+
+	-- Include the root instance itself
+	table.insert(results, {
+		name = rootInstance.Name,
+		className = rootInstance.ClassName,
+		path = Explorer.getPath(rootInstance),
+		properties = getProps(rootInstance),
+	})
+
+	for _, descendant in rootInstance:GetDescendants() do
+		table.insert(results, {
+			name = descendant.Name,
+			className = descendant.ClassName,
+			path = Explorer.getPath(descendant),
+			properties = getProps(descendant),
+		})
+	end
+
+	return { success = true, descendants = results }
+end
+
+--[[
+	Smart type coercion: converts JSON-friendly values into Roblox types.
+	Uses the expected property type from ReflectionService when available.
+]]
+local function coerceValue(instance, key, value)
+	local expectedType = nil
+	local typeMap = getPropertyTypeMap(instance.ClassName)
+	expectedType = typeMap[key]
+
+	-- If we don't know the expected type, try reading the current value
+	if not expectedType then
+		local curOk, curVal = pcall(function()
+			return instance[key]
+		end)
+		if curOk and curVal ~= nil then
+			expectedType = typeof(curVal)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- UDim2 (GUI Size, Position, etc.)
+	-- ═══════════════════════════════════════════
+	if expectedType == "UDim2" then
+		if type(value) == "table" then
+			-- {xScale, xOffset, yScale, yOffset} or named keys
+			if value.XScale or value.xScale or value.X then
+				return UDim2.new(
+					value.XScale or value.xScale or value.X and value.X.Scale or 0,
+					value.XOffset or value.xOffset or value.X and value.X.Offset or 0,
+					value.YScale or value.yScale or value.Y and value.Y.Scale or 0,
+					value.YOffset or value.yOffset or value.Y and value.Y.Offset or 0
+				)
+			end
+			-- {X = {Scale, Offset}, Y = {Scale, Offset}}
+			if value.X and type(value.X) == "table" then
+				return UDim2.new(
+					value.X.Scale or value.X[1] or 0,
+					value.X.Offset or value.X[2] or 0,
+					value.Y and (value.Y.Scale or value.Y[1]) or 0,
+					value.Y and (value.Y.Offset or value.Y[2]) or 0
+				)
+			end
+			-- Array: {xScale, xOffset, yScale, yOffset}
+			if value[1] ~= nil then
+				return UDim2.new(value[1] or 0, value[2] or 0, value[3] or 0, value[4] or 0)
+			end
+			-- fromScale shorthand: {scale_x, scale_y} when only 2 elements
+			return UDim2.new(0, 0, 0, 0)
+		end
+		if type(value) == "string" then
+			-- "0.5, 0, 0.5, 0" format
+			local a, b, c, d = value:match("([%d%.%-]+)%s*,%s*([%d%.%-]+)%s*,%s*([%d%.%-]+)%s*,%s*([%d%.%-]+)")
+			if a then
+				return UDim2.new(tonumber(a), tonumber(b), tonumber(c), tonumber(d))
+			end
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- UDim
+	-- ═══════════════════════════════════════════
+	if expectedType == "UDim" then
+		if type(value) == "table" then
+			return UDim.new(value.Scale or value[1] or 0, value.Offset or value[2] or 0)
+		end
+		if type(value) == "number" then
+			return UDim.new(value, 0)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Vector3
+	-- ═══════════════════════════════════════════
+	if expectedType == "Vector3" then
+		if type(value) == "table" then
+			return Vector3.new(
+				value.X or value.x or value[1] or 0,
+				value.Y or value.y or value[2] or 0,
+				value.Z or value.z or value[3] or 0
+			)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Vector2
+	-- ═══════════════════════════════════════════
+	if expectedType == "Vector2" then
+		if type(value) == "table" then
+			return Vector2.new(value.X or value.x or value[1] or 0, value.Y or value.y or value[2] or 0)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Color3
+	-- ═══════════════════════════════════════════
+	if expectedType == "Color3" then
+		if type(value) == "string" then
+			if value:sub(1, 1) == "#" then
+				return Color3.fromHex(value)
+			end
+			if value:match("^rgb") then
+				local r, g, b = value:match("(%d+)%D+(%d+)%D+(%d+)")
+				if r then
+					return Color3.fromRGB(tonumber(r), tonumber(g), tonumber(b))
+				end
+			end
+			local ok, bc = pcall(BrickColor.new, value)
+			if ok then
+				return bc.Color
+			end
+		end
+		if type(value) == "table" then
+			-- {R, G, B} 0-1 or {r, g, b}
+			if value.R or value.r then
+				return Color3.new(value.R or value.r or 0, value.G or value.g or 0, value.B or value.b or 0)
+			end
+			-- {red, green, blue} 0-255
+			if value.red or value.Red then
+				return Color3.fromRGB(
+					value.red or value.Red or 0,
+					value.green or value.Green or 0,
+					value.blue or value.Blue or 0
+				)
+			end
+			-- Array [r, g, b]
+			if value[1] then
+				if value[1] > 1 or value[2] > 1 or value[3] > 1 then
+					return Color3.fromRGB(value[1], value[2], value[3])
+				end
+				return Color3.new(value[1], value[2], value[3])
+			end
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- BrickColor
+	-- ═══════════════════════════════════════════
+	if expectedType == "BrickColor" then
+		if type(value) == "string" then
+			return BrickColor.new(value)
+		end
+		if type(value) == "number" then
+			return BrickColor.new(value)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- CFrame
+	-- ═══════════════════════════════════════════
+	if expectedType == "CFrame" then
+		if type(value) == "table" then
+			if value.Position or value.position then
+				local pos = value.Position or value.position
+				local cf = CFrame.new(
+					pos.x or pos.X or pos[1] or 0,
+					pos.y or pos.Y or pos[2] or 0,
+					pos.z or pos.Z or pos[3] or 0
+				)
+				if value.Rotation or value.rotation then
+					local rot = value.Rotation or value.rotation
+					cf = cf
+						* CFrame.Angles(
+							math.rad(rot.x or rot.X or rot[1] or 0),
+							math.rad(rot.y or rot.Y or rot[2] or 0),
+							math.rad(rot.z or rot.Z or rot[3] or 0)
+						)
+				end
+				return cf
+			end
+			-- Simple {x, y, z}
+			if value[1] then
+				return CFrame.new(value[1], value[2] or 0, value[3] or 0)
+			end
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Rect (for GUI ImageRectOffset, etc.)
+	-- ═══════════════════════════════════════════
+	if expectedType == "Rect" then
+		if type(value) == "table" then
+			return Rect.new(
+				value[1] or value.Min and value.Min[1] or 0,
+				value[2] or value.Min and value.Min[2] or 0,
+				value[3] or value.Max and value.Max[1] or 0,
+				value[4] or value.Max and value.Max[2] or 0
+			)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- NumberRange
+	-- ═══════════════════════════════════════════
+	if expectedType == "NumberRange" then
+		if type(value) == "table" then
+			return NumberRange.new(value.Min or value[1] or 0, value.Max or value[2] or 1)
+		end
+		if type(value) == "number" then
+			return NumberRange.new(value)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- NumberSequence (for transparency gradients, etc.)
+	-- ═══════════════════════════════════════════
+	if expectedType == "NumberSequence" then
+		if type(value) == "table" then
+			if value[1] and type(value[1]) == "table" then
+				local keypoints = {}
+				for _, kp in value do
+					table.insert(
+						keypoints,
+						NumberSequenceKeypoint.new(
+							kp.Time or kp[1] or 0,
+							kp.Value or kp[2] or 0,
+							kp.Envelope or kp[3] or 0
+						)
+					)
+				end
+				return NumberSequence.new(keypoints)
+			end
+			if #value == 2 and type(value[1]) == "number" then
+				return NumberSequence.new(value[1], value[2])
+			end
+		end
+		if type(value) == "number" then
+			return NumberSequence.new(value)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- ColorSequence
+	-- ═══════════════════════════════════════════
+	if expectedType == "ColorSequence" then
+		if type(value) == "table" then
+			if value[1] and type(value[1]) == "table" then
+				local keypoints = {}
+				for _, kp in value do
+					local color = Color3.new(1, 1, 1)
+					if kp.Color then
+						if type(kp.Color) == "string" and kp.Color:sub(1, 1) == "#" then
+							color = Color3.fromHex(kp.Color)
+						elseif type(kp.Color) == "table" then
+							color = Color3.new(kp.Color[1] or 0, kp.Color[2] or 0, kp.Color[3] or 0)
+						end
+					end
+					table.insert(keypoints, ColorSequenceKeypoint.new(kp.Time or kp[1] or 0, color))
+				end
+				return ColorSequence.new(keypoints)
+			end
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Font
+	-- ═══════════════════════════════════════════
+	if expectedType == "Font" then
+		if type(value) == "table" then
+			local family = value.Family or value.family or "rbxasset://fonts/families/SourceSansPro.json"
+			local weight = Enum.FontWeight.Regular
+			local style = Enum.FontStyle.Normal
+			if value.Weight or value.weight then
+				pcall(function()
+					weight = Enum.FontWeight[value.Weight or value.weight]
+				end)
+			end
+			if value.Style or value.style then
+				pcall(function()
+					style = Enum.FontStyle[value.Style or value.style]
+				end)
+			end
+			return Font.new(family, weight, style)
+		end
+		if type(value) == "string" then
+			return Font.new(value)
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- EnumItem (any enum property)
+	-- ═══════════════════════════════════════════
+	if type(value) == "string" then
+		local currentVal = nil
+		pcall(function()
+			currentVal = instance[key]
+		end)
+		if typeof(currentVal) == "EnumItem" then
+			local enumType = tostring(currentVal.EnumType)
+			local enumOk, enumVal = pcall(function()
+				return Enum[enumType][value]
+			end)
+			if enumOk then
+				return enumVal
+			end
+		end
+	end
+
+	-- ═══════════════════════════════════════════
+	-- Fallback: type-agnostic guesses (no expectedType known)
+	-- ═══════════════════════════════════════════
+	if type(value) == "table" and not expectedType then
+		-- UDim2 guess: has XScale/YScale keys
+		if value.XScale or value.xScale then
+			return UDim2.new(
+				value.XScale or value.xScale or 0,
+				value.XOffset or value.xOffset or 0,
+				value.YScale or value.yScale or 0,
+				value.YOffset or value.yOffset or 0
+			)
+		end
+		-- Vector3 guess: 3 number elements or X/Y/Z keys
+		if (value.X or value.x) and (value.Y or value.y) and (value.Z or value.z) then
+			return Vector3.new(value.X or value.x, value.Y or value.y, value.Z or value.z)
+		end
+		if value[1] and value[2] and value[3] and not value[4] then
+			return Vector3.new(value[1], value[2], value[3])
+		end
+		-- Color3 guess: R/G/B keys
+		if value.R or value.r then
+			return Color3.new(value.R or value.r or 0, value.G or value.g or 0, value.B or value.b or 0)
+		end
+		-- Vector2 guess: 2 number elements
+		if value[1] and value[2] and not value[3] then
+			return Vector2.new(value[1], value[2])
+		end
+	end
+
+	-- String-based color on color properties (fallback)
+	if type(value) == "string" and (key == "Color" or key == "Color3" or key:match("Color$")) then
+		if value:sub(1, 1) == "#" then
+			return Color3.fromHex(value)
+		end
+		local ok, bc = pcall(BrickColor.new, value)
+		if ok then
+			return bc.Color
+		end
+	end
+
+	if type(value) == "string" and key == "BrickColor" then
+		return BrickColor.new(value)
+	end
+
+	return value
+end
+
+function Properties.set(path, propertiesToSet)
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	local errors = {}
+	local set = {}
+
+	for key, value in propertiesToSet do
+		local coerced = coerceValue(instance, key, value)
+		local ok, err = pcall(function()
+			instance[key] = coerced
+		end)
+		if ok then
+			table.insert(set, key)
+		else
+			table.insert(errors, key .. ": " .. tostring(err))
+		end
+	end
+
+	if #errors > 0 then
+		return { success = false, error = table.concat(errors, "; "), set = set }
+	end
+
+	return { success = true, set = set }
+end
+
+function Properties.bulkSet(spec)
+	local ChangeHistoryService = game:GetService("ChangeHistoryService")
+	local recording = ChangeHistoryService:TryBeginRecording("Dominus: Bulk set properties")
+
+	local modified = 0
+	local errors = {}
+
+	if spec.targets and type(spec.targets) == "table" then
+		-- Explicit mode: array of {path, properties}
+		for _, target in ipairs(spec.targets) do
+			local instance = Explorer.resolveInstance(target.path)
+			if not instance then
+				table.insert(errors, "Not found: " .. tostring(target.path))
+			else
+				for key, value in target.properties do
+					local coerced = coerceValue(instance, key, value)
+					local ok, err = pcall(function()
+						instance[key] = coerced
+					end)
+					if not ok then
+						table.insert(errors, target.path .. "." .. key .. ": " .. tostring(err))
+					end
+				end
+				modified = modified + 1
+			end
+		end
+	elseif spec.root and (spec.properties or spec.addChildren) then
+		-- Filter mode: apply to all matching descendants
+		local root = Explorer.resolveInstance(spec.root)
+		if not root then
+			if recording then
+				ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+			end
+			return { success = false, error = "Root not found: " .. tostring(spec.root) }
+		end
+
+		local function processInstance(inst)
+			if spec.className and inst.ClassName ~= spec.className then
+				return
+			end
+			if spec.properties then
+				for key, value in spec.properties do
+					local coerced = coerceValue(inst, key, value)
+					local ok, err = pcall(function()
+						inst[key] = coerced
+					end)
+					if not ok then
+						table.insert(errors, Explorer.getPath(inst) .. "." .. key .. ": " .. tostring(err))
+					end
+				end
+			end
+			-- addChildren: insert new child instances (e.g. UIStroke, UICorner)
+			if spec.addChildren and type(spec.addChildren) == "table" then
+				for _, childSpec in ipairs(spec.addChildren) do
+					local childClass = childSpec.ClassName or childSpec.className
+					if childClass then
+						-- Skip if child of this class already exists (idempotent)
+						local skipIfExists = childSpec.skipIfExists ~= false
+						if skipIfExists then
+							local existing = inst:FindFirstChildOfClass(childClass)
+							if existing then
+								continue
+							end
+						end
+						local ok2, child = pcall(Instance.new, childClass)
+						if ok2 and child then
+							if childSpec.Name or childSpec.name then
+								child.Name = childSpec.Name or childSpec.name
+							end
+							-- Set props on the new child
+							local props = childSpec.properties
+								or childSpec.Properties
+								or childSpec.props
+								or childSpec.Props
+								or {}
+							-- Also check flattened keys
+							for k, v in childSpec do
+								if
+									k ~= "ClassName"
+									and k ~= "className"
+									and k ~= "Name"
+									and k ~= "name"
+									and k ~= "properties"
+									and k ~= "Properties"
+									and k ~= "props"
+									and k ~= "Props"
+									and k ~= "skipIfExists"
+									and k ~= "Children"
+									and k ~= "children"
+								then
+									props[k] = v
+								end
+							end
+							for pk, pv in props do
+								local coerced = coerceValue(child, pk, pv)
+								pcall(function()
+									child[pk] = coerced
+								end)
+							end
+							child.Parent = inst
+						else
+							table.insert(
+								errors,
+								Explorer.getPath(inst) .. ": failed to create " .. tostring(childClass)
+							)
+						end
+					end
+				end
+			end
+			modified = modified + 1
+		end
+
+		-- Include root itself if it matches
+		processInstance(root)
+		for _, desc in root:GetDescendants() do
+			processInstance(desc)
+		end
+	else
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		end
+		return { success = false, error = "Provide either 'targets' array or 'root' + 'properties'/'addChildren'" }
+	end
+
+	if recording then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	end
+
+	return { success = true, modified = modified, errors = errors }
+end
+
+function Properties.inspectV2(spec)
+	if type(spec.targets) ~= "table" or #spec.targets == 0 then
+		return { success = false, error = "targets must contain at least one instance reference" }
+	end
+	if #spec.targets > 20 then
+		return { success = false, error = "At most 20 instances can be inspected at once" }
+	end
+	local compact = spec.compact ~= false
+	local results = {}
+
+	for index, targetRef in spec.targets do
+		local instance, err = InstanceRegistry.resolve(targetRef)
+		if not instance then
+			table.insert(results, { success = false, index = index, error = err })
+			continue
+		end
+
+		local metadata = Reflection.getPropertyMetadata(instance.ClassName)
+		local propertyNames = {}
+		for propertyName in metadata do
+			if not IGNORED_PROPERTIES[propertyName] and (not compact or not COMPACT_SKIP[propertyName]) then
+				table.insert(propertyNames, propertyName)
+			end
+		end
+		table.sort(propertyNames)
+
+		local properties = {}
+		for _, propertyName in propertyNames do
+			local readOk, value = pcall(function()
+				return instance[propertyName]
+			end)
+			if readOk and value ~= nil then
+				table.insert(properties, {
+					name = propertyName,
+					type = metadata[propertyName].type,
+					category = metadata[propertyName].category,
+					writable = metadata[propertyName].writable,
+					value = ValueCodec.encode(value),
+				})
+			end
+		end
+
+		local children = instance:GetChildren()
+		table.sort(children, function(a, b)
+			if a.Name == b.Name then
+				return a.ClassName < b.ClassName
+			end
+			return a.Name < b.Name
+		end)
+		local childRefs = {}
+		for _, child in children do
+			table.insert(childRefs, {
+				name = child.Name,
+				className = child.ClassName,
+				ref = InstanceRegistry.toRef(child),
+			})
+		end
+
+		table.insert(results, {
+			success = true,
+			name = instance.Name,
+			className = instance.ClassName,
+			ref = InstanceRegistry.toRef(instance),
+			properties = properties,
+			children = childRefs,
+		})
+	end
+
+	return { success = true, results = results }
+end
+
+return Properties