dominus-cli 0.6.0 → 2.1.0

package/plugin/src/UIBuilder.lua

@@ -1,727 +1,857 @@
---[[
-	UIBuilder: create entire UI trees from a declarative JSON spec in one call.
-	Handles all type coercion natively in Luau — no round trips needed.
-]]
-
-local Explorer = require(script.Parent.Explorer)
-local Reflection = require(script.Parent.Reflection)
-
-local UIBuilder = {}
-
--- Cache property type maps per ClassName to avoid repeated reflection calls
-local propertyTypeCache = {}
-local function getPropertyType(className, propName)
-	if not propertyTypeCache[className] then
-		propertyTypeCache[className] = Reflection.getPropertyTypes(className)
-	end
-	return propertyTypeCache[className][propName]
-end
-
-local function resolveColor(value)
-	if type(value) == "string" then
-		if value:sub(1, 1) == "#" then
-			return Color3.fromHex(value)
-		end
-		local r, g, b = value:match("rgb%s*%((%d+)%D+(%d+)%D+(%d+)%)")
-		if r then
-			return Color3.fromRGB(tonumber(r), tonumber(g), tonumber(b))
-		end
-		local ok, bc = pcall(BrickColor.new, value)
-		if ok then
-			return bc.Color
-		end
-	end
-	if type(value) == "table" then
-		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
-		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
-	end
-	return Color3.new(1, 1, 1)
-end
-
-local function resolveUDim2(value)
-	if type(value) == "table" then
-		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
-		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
-		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
-	end
-	if type(value) == "string" then
-		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
-	return UDim2.new(0, 0, 0, 0)
-end
-
-local function resolveUDim(value)
-	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(0, value)
-	end
-	return UDim.new(0, 0)
-end
-
-local function resolveVector2(value)
-	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
-	return Vector2.new(0, 0)
-end
-
-local function resolveEnum(instance, key, value)
-	if type(value) ~= "string" then
-		return value
-	end
-	local curOk, curVal = pcall(function()
-		return instance[key]
-	end)
-	if curOk and typeof(curVal) == "EnumItem" then
-		local enumType = tostring(curVal.EnumType)
-		local ok, enumVal = pcall(function()
-			return Enum[enumType][value]
-		end)
-		if ok then
-			return enumVal
-		end
-	end
-	return value
-end
-
-local function resolveFont(value)
-	if type(value) == "string" then
-		local ok, font = pcall(function()
-			return Enum.Font[value]
-		end)
-		if ok then
-			return font
-		end
-	end
-	return value
-end
-
-local UDIM2_PROPS = {
-	Size = true,
-	Position = true,
-	CellSize = true,
-	CellPadding = true,
-}
-
-local COLOR3_PROPS = {
-	BackgroundColor3 = true,
-	BorderColor3 = true,
-	TextColor3 = true,
-	ImageColor3 = true,
-	PlaceholderColor3 = true,
-	TextStrokeColor3 = true,
-	ScrollBarImageColor3 = true,
-}
-
-local function resolveColorSequence(value)
-	if type(value) == "table" then
-		-- Array of keypoints: {{time, color}, ...}
-		if type(value[1]) == "table" then
-			local keypoints = {}
-			for _, kp in ipairs(value) do
-				local t = kp[1] or kp.Time or 0
-				local c = resolveColor(kp[2] or kp.Color or kp)
-				table.insert(keypoints, ColorSequenceKeypoint.new(t, c))
-			end
-			return ColorSequence.new(keypoints)
-		end
-		-- Single color as array [r,g,b] → uniform ColorSequence
-		if type(value[1]) == "number" and #value == 3 then
-			local c = resolveColor(value)
-			return ColorSequence.new(c)
-		end
-	end
-	-- String hex/rgb → uniform ColorSequence
-	if type(value) == "string" then
-		return ColorSequence.new(resolveColor(value))
-	end
-	return ColorSequence.new(Color3.new(1, 1, 1))
-end
-
-local function resolveNumberSequence(value)
-	if type(value) == "table" then
-		-- Array of keypoints: {{time, value, envelope?}, ...}
-		if type(value[1]) == "table" then
-			local keypoints = {}
-			for _, kp in ipairs(value) do
-				local t = kp[1] or kp.Time or 0
-				local v = kp[2] or kp.Value or 0
-				local e = kp[3] or kp.Envelope or 0
-				table.insert(keypoints, NumberSequenceKeypoint.new(t, v, e))
-			end
-			return NumberSequence.new(keypoints)
-		end
-	end
-	if type(value) == "number" then
-		return NumberSequence.new(value)
-	end
-	return NumberSequence.new(0)
-end
-
-local VECTOR2_PROPS = {
-	AnchorPoint = true,
-	CanvasSize_v2 = true,
-	AbsoluteSize = true,
-	AbsolutePosition = true,
-}
-
-local UDIM_PROPS = {
-	CornerRadius = true,
-	Padding = true,
-	PaddingTop = true,
-	PaddingBottom = true,
-	PaddingLeft = true,
-	PaddingRight = true,
-	FillDirection = false, -- not UDim
-}
-
-local NUMBER_RANGE_PROPS = {
-	Range = true,
-	RotationRange = true,
-	Size_NR = true, -- particle size range alias
-}
-
-local RECT_PROPS = {
-	SliceCenter = true,
-	ImageRectOffset_Rect = true,
-}
-
-local function resolveNumberRange(value)
-	if type(value) == "table" then
-		return NumberRange.new(value[1] or 0, value[2] or value[1] or 0)
-	end
-	if type(value) == "number" then
-		return NumberRange.new(value)
-	end
-	return NumberRange.new(0)
-end
-
-local function resolveRect(value)
-	if type(value) == "table" then
-		if #value == 4 then
-			return Rect.new(value[1], value[2], value[3], value[4])
-		end
-		return Rect.new(
-			value.Min and value.Min[1] or value.MinX or 0,
-			value.Min and value.Min[2] or value.MinY or 0,
-			value.Max and value.Max[1] or value.MaxX or 0,
-			value.Max and value.Max[2] or value.MaxY or 0
-		)
-	end
-	return Rect.new(0, 0, 0, 0)
-end
-
--- Disambiguate 2-element arrays: check actual property type on the instance
-local function resolve2ElementArray(instance, key, value)
-	-- First, check our known lookup tables
-	if VECTOR2_PROPS[key] then
-		return resolveVector2(value)
-	end
-	if UDIM_PROPS[key] then
-		return resolveUDim(value)
-	end
-	if NUMBER_RANGE_PROPS[key] then
-		return resolveNumberRange(value)
-	end
-	-- Fall back to runtime type introspection
-	local ok, curVal = pcall(function()
-		return instance[key]
-	end)
-	if ok and curVal ~= nil then
-		local t = typeof(curVal)
-		if t == "Vector2" then
-			return resolveVector2(value)
-		end
-		if t == "UDim" then
-			return resolveUDim(value)
-		end
-		if t == "NumberRange" then
-			return resolveNumberRange(value)
-		end
-	end
-	-- Default: assume UDim for 2-element (more common in UI)
-	return resolveUDim(value)
-end
-
-local function applyProperty(instance, key, value)
-	-- Special handling by property name
-	if key == "Size" or key == "Position" then
-		if instance:IsA("GuiObject") or instance:IsA("UIBase") then
-			instance[key] = resolveUDim2(value)
-			return
-		end
-	end
-
-	if key == "AnchorPoint" then
-		if instance:IsA("GuiObject") then
-			instance[key] = resolveVector2(value)
-			return
-		end
-	end
-
-	if key == "CanvasSize" and instance:IsA("ScrollingFrame") then
-		instance[key] = resolveUDim2(value)
-		return
-	end
-
-	if UDIM_PROPS[key] then
-		instance[key] = resolveUDim(value)
-		return
-	end
-
-	-- Use reflection to distinguish Color3 vs ColorSequence, NumberSequence, etc.
-	local propType = getPropertyType(instance.ClassName, key)
-
-	if propType == "ColorSequence" then
-		instance[key] = resolveColorSequence(value)
-		return
-	end
-
-	if propType == "NumberSequence" then
-		instance[key] = resolveNumberSequence(value)
-		return
-	end
-
-	if COLOR3_PROPS[key] or propType == "Color3" then
-		instance[key] = resolveColor(value)
-		return
-	end
-
-	-- Reflection-based coercion for types not in hardcoded tables
-	if propType == "UDim2" and type(value) == "table" then
-		instance[key] = resolveUDim2(value)
-		return
-	end
-	if propType == "UDim" then
-		instance[key] = resolveUDim(value)
-		return
-	end
-	if propType == "Vector2" then
-		instance[key] = resolveVector2(value)
-		return
-	end
-	if propType == "NumberRange" then
-		instance[key] = resolveNumberRange(value)
-		return
-	end
-	if propType == "Rect" then
-		instance[key] = resolveRect(value)
-		return
-	end
-
-	-- Rect properties (4-element arrays like SliceCenter)
-	if RECT_PROPS[key] then
-		instance[key] = resolveRect(value)
-		return
-	end
-
-	-- NumberRange properties
-	if NUMBER_RANGE_PROPS[key] then
-		instance[key] = resolveNumberRange(value)
-		return
-	end
-
-	if key == "Font" and instance:IsA("TextLabel") or instance:IsA("TextButton") or instance:IsA("TextBox") then
-		instance[key] = resolveFont(value)
-		return
-	end
-
-	if key == "FontFace" then
-		if type(value) == "table" then
-			local family = value.Family or "rbxasset://fonts/families/SourceSansPro.json"
-			local weight = Enum.FontWeight.Regular
-			local style = Enum.FontStyle.Normal
-			pcall(function()
-				weight = Enum.FontWeight[value.Weight or "Regular"]
-			end)
-			pcall(function()
-				style = Enum.FontStyle[value.Style or "Normal"]
-			end)
-			instance.FontFace = Font.new(family, weight, style)
-		end
-		return
-	end
-
-	-- Enum properties (string values)
-	if type(value) == "string" then
-		local resolved = resolveEnum(instance, key, value)
-		local ok, err = pcall(function()
-			instance[key] = resolved
-		end)
-		if not ok then
-			-- Maybe it's a direct value
-			pcall(function()
-				instance[key] = value
-			end)
-		end
-		return
-	end
-
-	if UDIM2_PROPS[key] then
-		pcall(function()
-			instance[key] = resolveUDim2(value)
-		end)
-		return
-	end
-
-	-- Smart disambiguation for 2-element table arrays
-	if type(value) == "table" and #value == 2 then
-		local resolved = resolve2ElementArray(instance, key, value)
-		pcall(function()
-			instance[key] = resolved
-		end)
-		return
-	end
-
-	-- 4-element table arrays: try Rect if not already handled as UDim2
-	if type(value) == "table" and #value == 4 then
-		-- Check actual property type
-		local ok, curVal = pcall(function()
-			return instance[key]
-		end)
-		if ok and curVal ~= nil then
-			local t = typeof(curVal)
-			if t == "Rect" then
-				pcall(function()
-					instance[key] = resolveRect(value)
-				end)
-				return
-			elseif t == "UDim2" then
-				pcall(function()
-					instance[key] = resolveUDim2(value)
-				end)
-				return
-			end
-		end
-		-- Default 4-element to UDim2
-		pcall(function()
-			instance[key] = resolveUDim2(value)
-		end)
-		return
-	end
-
-	-- Direct assignment for numbers, booleans, etc.
-	pcall(function()
-		instance[key] = value
-	end)
-end
-
-local RESERVED_KEYS = {
-	ClassName = true,
-	className = true,
-	Name = true,
-	name = true,
-	Children = true,
-	children = true,
-	properties = true,
-	Properties = true,
-	props = true,
-	Props = true,
-}
-
-local function buildNode(spec, parent, animate)
-	local className = spec.ClassName or spec.className or "Frame"
-	local name = spec.Name or spec.name or className
-
-	local instance = Instance.new(className)
-	instance.Name = name
-
-	-- Apply flattened top-level properties
-	for key, value in spec do
-		if not RESERVED_KEYS[key] then
-			applyProperty(instance, key, value)
-		end
-	end
-
-	-- Also accept a nested "properties" / "Properties" / "props" bag for convenience.
-	-- This lets callers group properties explicitly without the key being misread
-	-- as an instance property name.
-	local propBag = spec.properties or spec.Properties or spec.props or spec.Props
-	if type(propBag) == "table" then
-		for key, value in propBag do
-			if not RESERVED_KEYS[key] then
-				applyProperty(instance, key, value)
-			end
-		end
-	end
-
-	-- Set parent after properties to avoid unnecessary layout computations
-	instance.Parent = parent
-
-	-- Build children recursively
-	local children = spec.Children or spec.children
-	if children then
-		for _, childSpec in children do
-			if animate then
-				task.wait(0.05)
-			end
-			buildNode(childSpec, instance, animate)
-		end
-	end
-
-	return instance
-end
-
-function UIBuilder.build(spec)
-	local parentPath = spec.parent or "StarterGui"
-	local parent = Explorer.resolveInstance(parentPath)
-	if not parent then
-		-- Try as a service
-		local ok
-		ok, parent = pcall(function()
-			return game:GetService(parentPath)
-		end)
-		if not ok then
-			return { success = false, error = "Parent not found: " .. parentPath }
-		end
-	end
-
-	-- Clean up existing instance with same name
-	local existingName = spec.tree and (spec.tree.Name or spec.tree.name) or nil
-	if existingName then
-		local existing = parent:FindFirstChild(existingName)
-		if existing then
-			existing:Destroy()
-		end
-	end
-
-	local tree = spec.tree
-	if not tree then
-		return { success = false, error = "No 'tree' provided in spec" }
-	end
-
-	local animate = false
-	if spec.animate ~= nil then
-		animate = spec.animate
-	end
-
-	local ok, result = pcall(function()
-		return buildNode(tree, parent, animate)
-	end)
-
-	if not ok then
-		return { success = false, error = "Build failed: " .. tostring(result) }
-	end
-
-	local path = Explorer.getPath(result)
-	local count = 0
-	local function countDescendants(inst)
-		count = count + 1
-		for _, child in inst:GetChildren() do
-			countDescendants(child)
-		end
-	end
-	countDescendants(result)
-
-	return { success = true, path = path, instanceCount = count }
-end
-
---[[
-	Serialize: convert an existing instance tree into create_ui-compatible JSON.
-	Reads properties via ReflectionService, converts Roblox types to JSON-friendly values,
-	and skips default/unchanged values to keep output minimal.
-]]
-
-local Reflection = require(script.Parent.Reflection)
-local ReflectionService = game:GetService("ReflectionService")
-
--- Convert a Roblox value to a JSON-friendly representation
-local function valueToJson(value, propType)
-	local t = typeof(value)
-
-	if t == "UDim2" then
-		return { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset }
-	end
-	if t == "UDim" then
-		return { value.Scale, value.Offset }
-	end
-	if t == "Vector2" then
-		return { value.X, value.Y }
-	end
-	if t == "Vector3" then
-		return { value.X, value.Y, value.Z }
-	end
-	if t == "Color3" then
-		return "#" .. value:ToHex()
-	end
-	if t == "BrickColor" then
-		return value.Name
-	end
-	if t == "ColorSequence" then
-		local kps = {}
-		for _, kp in value.Keypoints do
-			table.insert(kps, { kp.Time, "#" .. kp.Value:ToHex() })
-		end
-		return kps
-	end
-	if t == "NumberSequence" then
-		local kps = {}
-		for _, kp in value.Keypoints do
-			table.insert(kps, { kp.Time, kp.Value, kp.Envelope })
-		end
-		return kps
-	end
-	if t == "NumberRange" then
-		return { value.Min, value.Max }
-	end
-	if t == "Rect" then
-		return { value.Min.X, value.Min.Y, value.Max.X, value.Max.Y }
-	end
-	if t == "CFrame" then
-		return { value:GetComponents() }
-	end
-	if t == "EnumItem" then
-		return value.Name
-	end
-	if t == "Font" then
-		return {
-			Family = value.Family,
-			Weight = value.Weight.Name,
-			Style = value.Style.Name,
-		}
-	end
-	if t == "boolean" or t == "number" or t == "string" then
-		return value
-	end
-	-- Fallback: tostring
-	return tostring(value)
-end
-
-local SERIALIZE_SKIP = {
-	Parent = true,
-	ClassName = true,
-	Name = true,
-	Archivable = true,
-	AbsolutePosition = true,
-	AbsoluteSize = true,
-	AbsoluteRotation = true,
-	IsLoaded = true,
-}
-
-local function serializeNode(instance, maxDepth, depth)
-	if depth > maxDepth then
-		return nil
-	end
-
-	local node = {
-		ClassName = instance.ClassName,
-		Name = instance.Name,
-	}
-
-	-- Get non-default properties via reflection
-	local ok, propData = pcall(function()
-		return ReflectionService:GetPropertiesOfClass(instance.ClassName)
-	end)
-
-	if ok and propData then
-		-- Create a default instance to compare against
-		local defaultInstance = nil
-		pcall(function()
-			defaultInstance = Instance.new(instance.ClassName)
-		end)
-
-		for _, prop in propData do
-			if not SERIALIZE_SKIP[prop.Name] and not prop.Name:match("^Absolute") then
-				local valOk, value = pcall(function()
-					return instance[prop.Name]
-				end)
-				if valOk and value ~= nil then
-					-- Skip default values
-					local isDefault = false
-					if defaultInstance then
-						local defOk, defVal = pcall(function()
-							return defaultInstance[prop.Name]
-						end)
-						if defOk and defVal == value then
-							isDefault = true
-						end
-					end
-
-					if not isDefault then
-						local jsonVal = valueToJson(value, prop.ValueType and tostring(prop.ValueType))
-						if jsonVal ~= nil then
-							node[prop.Name] = jsonVal
-						end
-					end
-				end
-			end
-		end
-
-		if defaultInstance then
-			pcall(function()
-				defaultInstance:Destroy()
-			end)
-		end
-	end
-
-	-- Serialize children
-	local children = instance:GetChildren()
-	if #children > 0 then
-		node.Children = {}
-		for _, child in children do
-			local childNode = serializeNode(child, maxDepth, depth + 1)
-			if childNode then
-				table.insert(node.Children, childNode)
-			end
-		end
-		if #node.Children == 0 then
-			node.Children = nil
-		end
-	end
-
-	return node
-end
-
-function UIBuilder.serialize(spec)
-	local path = spec.path
-	if not path then
-		return { success = false, error = "Missing 'path' parameter" }
-	end
-
-	local instance = Explorer.resolveInstance(path)
-	if not instance then
-		return { success = false, error = "Instance not found: " .. path }
-	end
-
-	local maxDepth = spec.maxDepth or 50
-
-	local ok, tree = pcall(function()
-		return serializeNode(instance, maxDepth, 0)
-	end)
-
-	if not ok then
-		return { success = false, error = "Serialization failed: " .. tostring(tree) }
-	end
-
-	return { success = true, tree = tree }
-end
-
-return UIBuilder
+--[[
+	UIBuilder: create entire UI trees from a declarative JSON spec in one call.
+	Handles all type coercion natively in Luau — no round trips needed.
+]]
+
+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 ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+local UIBuilder = {}
+
+-- Cache property type maps per ClassName to avoid repeated reflection calls
+local propertyTypeCache = {}
+local function getPropertyType(className, propName)
+	if not propertyTypeCache[className] then
+		propertyTypeCache[className] = Reflection.getPropertyTypes(className)
+	end
+	return propertyTypeCache[className][propName]
+end
+
+local function resolveColor(value)
+	if type(value) == "string" then
+		if value:sub(1, 1) == "#" then
+			return Color3.fromHex(value)
+		end
+		local r, g, b = value:match("rgb%s*%((%d+)%D+(%d+)%D+(%d+)%)")
+		if r then
+			return Color3.fromRGB(tonumber(r), tonumber(g), tonumber(b))
+		end
+		local ok, bc = pcall(BrickColor.new, value)
+		if ok then
+			return bc.Color
+		end
+	end
+	if type(value) == "table" then
+		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
+		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
+	end
+	return Color3.new(1, 1, 1)
+end
+
+local function resolveUDim2(value)
+	if type(value) == "table" then
+		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
+		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
+		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
+	end
+	if type(value) == "string" then
+		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
+	return UDim2.new(0, 0, 0, 0)
+end
+
+local function resolveUDim(value)
+	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(0, value)
+	end
+	return UDim.new(0, 0)
+end
+
+local function resolveVector2(value)
+	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
+	return Vector2.new(0, 0)
+end
+
+local function resolveEnum(instance, key, value)
+	if type(value) ~= "string" then
+		return value
+	end
+	local curOk, curVal = pcall(function()
+		return instance[key]
+	end)
+	if curOk and typeof(curVal) == "EnumItem" then
+		local enumType = tostring(curVal.EnumType)
+		local ok, enumVal = pcall(function()
+			return Enum[enumType][value]
+		end)
+		if ok then
+			return enumVal
+		end
+	end
+	return value
+end
+
+local function resolveFont(value)
+	if type(value) == "string" then
+		local ok, font = pcall(function()
+			return Enum.Font[value]
+		end)
+		if ok then
+			return font
+		end
+	end
+	return value
+end
+
+local UDIM2_PROPS = {
+	Size = true,
+	Position = true,
+	CellSize = true,
+	CellPadding = true,
+}
+
+local COLOR3_PROPS = {
+	BackgroundColor3 = true,
+	BorderColor3 = true,
+	TextColor3 = true,
+	ImageColor3 = true,
+	PlaceholderColor3 = true,
+	TextStrokeColor3 = true,
+	ScrollBarImageColor3 = true,
+}
+
+local function resolveColorSequence(value)
+	if type(value) == "table" then
+		-- Array of keypoints: {{time, color}, ...}
+		if type(value[1]) == "table" then
+			local keypoints = {}
+			for _, kp in ipairs(value) do
+				local t = kp[1] or kp.Time or 0
+				local c = resolveColor(kp[2] or kp.Color or kp)
+				table.insert(keypoints, ColorSequenceKeypoint.new(t, c))
+			end
+			return ColorSequence.new(keypoints)
+		end
+		-- Single color as array [r,g,b] → uniform ColorSequence
+		if type(value[1]) == "number" and #value == 3 then
+			local c = resolveColor(value)
+			return ColorSequence.new(c)
+		end
+	end
+	-- String hex/rgb → uniform ColorSequence
+	if type(value) == "string" then
+		return ColorSequence.new(resolveColor(value))
+	end
+	return ColorSequence.new(Color3.new(1, 1, 1))
+end
+
+local function resolveNumberSequence(value)
+	if type(value) == "table" then
+		-- Array of keypoints: {{time, value, envelope?}, ...}
+		if type(value[1]) == "table" then
+			local keypoints = {}
+			for _, kp in ipairs(value) do
+				local t = kp[1] or kp.Time or 0
+				local v = kp[2] or kp.Value or 0
+				local e = kp[3] or kp.Envelope or 0
+				table.insert(keypoints, NumberSequenceKeypoint.new(t, v, e))
+			end
+			return NumberSequence.new(keypoints)
+		end
+	end
+	if type(value) == "number" then
+		return NumberSequence.new(value)
+	end
+	return NumberSequence.new(0)
+end
+
+local VECTOR2_PROPS = {
+	AnchorPoint = true,
+	CanvasSize_v2 = true,
+	AbsoluteSize = true,
+	AbsolutePosition = true,
+}
+
+local UDIM_PROPS = {
+	CornerRadius = true,
+	Padding = true,
+	PaddingTop = true,
+	PaddingBottom = true,
+	PaddingLeft = true,
+	PaddingRight = true,
+	FillDirection = false, -- not UDim
+}
+
+local NUMBER_RANGE_PROPS = {
+	Range = true,
+	RotationRange = true,
+	Size_NR = true, -- particle size range alias
+}
+
+local RECT_PROPS = {
+	SliceCenter = true,
+	ImageRectOffset_Rect = true,
+}
+
+local function resolveNumberRange(value)
+	if type(value) == "table" then
+		return NumberRange.new(value[1] or 0, value[2] or value[1] or 0)
+	end
+	if type(value) == "number" then
+		return NumberRange.new(value)
+	end
+	return NumberRange.new(0)
+end
+
+local function resolveRect(value)
+	if type(value) == "table" then
+		if #value == 4 then
+			return Rect.new(value[1], value[2], value[3], value[4])
+		end
+		return Rect.new(
+			value.Min and value.Min[1] or value.MinX or 0,
+			value.Min and value.Min[2] or value.MinY or 0,
+			value.Max and value.Max[1] or value.MaxX or 0,
+			value.Max and value.Max[2] or value.MaxY or 0
+		)
+	end
+	return Rect.new(0, 0, 0, 0)
+end
+
+-- Disambiguate 2-element arrays: check actual property type on the instance
+local function resolve2ElementArray(instance, key, value)
+	-- First, check our known lookup tables
+	if VECTOR2_PROPS[key] then
+		return resolveVector2(value)
+	end
+	if UDIM_PROPS[key] then
+		return resolveUDim(value)
+	end
+	if NUMBER_RANGE_PROPS[key] then
+		return resolveNumberRange(value)
+	end
+	-- Fall back to runtime type introspection
+	local ok, curVal = pcall(function()
+		return instance[key]
+	end)
+	if ok and curVal ~= nil then
+		local t = typeof(curVal)
+		if t == "Vector2" then
+			return resolveVector2(value)
+		end
+		if t == "UDim" then
+			return resolveUDim(value)
+		end
+		if t == "NumberRange" then
+			return resolveNumberRange(value)
+		end
+	end
+	-- Default: assume UDim for 2-element (more common in UI)
+	return resolveUDim(value)
+end
+
+local function applyProperty(instance, key, value)
+	-- Special handling by property name
+	if key == "Size" or key == "Position" then
+		if instance:IsA("GuiObject") or instance:IsA("UIBase") then
+			instance[key] = resolveUDim2(value)
+			return
+		end
+	end
+
+	if key == "AnchorPoint" then
+		if instance:IsA("GuiObject") then
+			instance[key] = resolveVector2(value)
+			return
+		end
+	end
+
+	if key == "CanvasSize" and instance:IsA("ScrollingFrame") then
+		instance[key] = resolveUDim2(value)
+		return
+	end
+
+	if UDIM_PROPS[key] then
+		instance[key] = resolveUDim(value)
+		return
+	end
+
+	-- Use reflection to distinguish Color3 vs ColorSequence, NumberSequence, etc.
+	local propType = getPropertyType(instance.ClassName, key)
+
+	if propType == "ColorSequence" then
+		instance[key] = resolveColorSequence(value)
+		return
+	end
+
+	if propType == "NumberSequence" then
+		instance[key] = resolveNumberSequence(value)
+		return
+	end
+
+	if COLOR3_PROPS[key] or propType == "Color3" then
+		instance[key] = resolveColor(value)
+		return
+	end
+
+	-- Reflection-based coercion for types not in hardcoded tables
+	if propType == "UDim2" and type(value) == "table" then
+		instance[key] = resolveUDim2(value)
+		return
+	end
+	if propType == "UDim" then
+		instance[key] = resolveUDim(value)
+		return
+	end
+	if propType == "Vector2" then
+		instance[key] = resolveVector2(value)
+		return
+	end
+	if propType == "NumberRange" then
+		instance[key] = resolveNumberRange(value)
+		return
+	end
+	if propType == "Rect" then
+		instance[key] = resolveRect(value)
+		return
+	end
+
+	-- Rect properties (4-element arrays like SliceCenter)
+	if RECT_PROPS[key] then
+		instance[key] = resolveRect(value)
+		return
+	end
+
+	-- NumberRange properties
+	if NUMBER_RANGE_PROPS[key] then
+		instance[key] = resolveNumberRange(value)
+		return
+	end
+
+	if key == "Font" and (instance:IsA("TextLabel") or instance:IsA("TextButton") or instance:IsA("TextBox")) then
+		instance[key] = resolveFont(value)
+		return
+	end
+
+	if key == "FontFace" then
+		if type(value) == "table" then
+			local family = value.Family or "rbxasset://fonts/families/SourceSansPro.json"
+			local weight = Enum.FontWeight.Regular
+			local style = Enum.FontStyle.Normal
+			pcall(function()
+				weight = Enum.FontWeight[value.Weight or "Regular"]
+			end)
+			pcall(function()
+				style = Enum.FontStyle[value.Style or "Normal"]
+			end)
+			instance.FontFace = Font.new(family, weight, style)
+		end
+		return
+	end
+
+	-- Enum properties (string values)
+	if type(value) == "string" then
+		local resolved = resolveEnum(instance, key, value)
+		local ok, err = pcall(function()
+			instance[key] = resolved
+		end)
+		if not ok then
+			-- Maybe it's a direct value
+			pcall(function()
+				instance[key] = value
+			end)
+		end
+		return
+	end
+
+	if UDIM2_PROPS[key] then
+		pcall(function()
+			instance[key] = resolveUDim2(value)
+		end)
+		return
+	end
+
+	-- Smart disambiguation for 2-element table arrays
+	if type(value) == "table" and #value == 2 then
+		local resolved = resolve2ElementArray(instance, key, value)
+		pcall(function()
+			instance[key] = resolved
+		end)
+		return
+	end
+
+	-- 4-element table arrays: try Rect if not already handled as UDim2
+	if type(value) == "table" and #value == 4 then
+		-- Check actual property type
+		local ok, curVal = pcall(function()
+			return instance[key]
+		end)
+		if ok and curVal ~= nil then
+			local t = typeof(curVal)
+			if t == "Rect" then
+				pcall(function()
+					instance[key] = resolveRect(value)
+				end)
+				return
+			elseif t == "UDim2" then
+				pcall(function()
+					instance[key] = resolveUDim2(value)
+				end)
+				return
+			end
+		end
+		-- Default 4-element to UDim2
+		pcall(function()
+			instance[key] = resolveUDim2(value)
+		end)
+		return
+	end
+
+	-- Direct assignment for numbers, booleans, etc.
+	pcall(function()
+		instance[key] = value
+	end)
+end
+
+local RESERVED_KEYS = {
+	ClassName = true,
+	className = true,
+	Name = true,
+	name = true,
+	Children = true,
+	children = true,
+	properties = true,
+	Properties = true,
+	props = true,
+	Props = true,
+}
+
+local function buildNode(spec, parent, animate)
+	local className = spec.ClassName or spec.className or "Frame"
+	local name = spec.Name or spec.name or className
+
+	local instance = Instance.new(className)
+	instance.Name = name
+
+	-- Apply flattened top-level properties
+	for key, value in spec do
+		if not RESERVED_KEYS[key] then
+			applyProperty(instance, key, value)
+		end
+	end
+
+	-- Also accept a nested "properties" / "Properties" / "props" bag for convenience.
+	-- This lets callers group properties explicitly without the key being misread
+	-- as an instance property name.
+	local propBag = spec.properties or spec.Properties or spec.props or spec.Props
+	if type(propBag) == "table" then
+		for key, value in propBag do
+			if not RESERVED_KEYS[key] then
+				applyProperty(instance, key, value)
+			end
+		end
+	end
+
+	-- Set parent after properties to avoid unnecessary layout computations
+	instance.Parent = parent
+
+	-- Build children recursively
+	local children = spec.Children or spec.children
+	if children then
+		for _, childSpec in children do
+			if animate then
+				task.wait(0.05)
+			end
+			buildNode(childSpec, instance, animate)
+		end
+	end
+
+	return instance
+end
+
+function UIBuilder.build(spec)
+	local parentPath = spec.parent or "StarterGui"
+	local parent = Explorer.resolveInstance(parentPath)
+	if not parent then
+		-- Try as a service
+		local ok
+		ok, parent = pcall(function()
+			return game:GetService(parentPath)
+		end)
+		if not ok then
+			return { success = false, error = "Parent not found: " .. parentPath }
+		end
+	end
+
+	-- Clean up existing instance with same name
+	local existingName = spec.tree and (spec.tree.Name or spec.tree.name) or nil
+	if existingName then
+		local existing = parent:FindFirstChild(existingName)
+		if existing then
+			existing:Destroy()
+		end
+	end
+
+	local tree = spec.tree
+	if not tree then
+		return { success = false, error = "No 'tree' provided in spec" }
+	end
+
+	local animate = false
+	if spec.animate ~= nil then
+		animate = spec.animate
+	end
+
+	local ok, result = pcall(function()
+		return buildNode(tree, parent, animate)
+	end)
+
+	if not ok then
+		return { success = false, error = "Build failed: " .. tostring(result) }
+	end
+
+	local path = Explorer.getPath(result)
+	local count = 0
+	local function countDescendants(inst)
+		count = count + 1
+		for _, child in inst:GetChildren() do
+			countDescendants(child)
+		end
+	end
+	countDescendants(result)
+
+	return { success = true, path = path, instanceCount = count }
+end
+
+--[[
+	Serialize: convert an existing instance tree into create_ui-compatible JSON.
+	Reads properties via ReflectionService, converts Roblox types to JSON-friendly values,
+	and skips default/unchanged values to keep output minimal.
+]]
+
+local Reflection = require(script.Parent.Reflection)
+local ReflectionService = game:GetService("ReflectionService")
+
+-- Convert a Roblox value to a JSON-friendly representation
+local function valueToJson(value, propType)
+	local t = typeof(value)
+
+	if t == "UDim2" then
+		return { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset }
+	end
+	if t == "UDim" then
+		return { value.Scale, value.Offset }
+	end
+	if t == "Vector2" then
+		return { value.X, value.Y }
+	end
+	if t == "Vector3" then
+		return { value.X, value.Y, value.Z }
+	end
+	if t == "Color3" then
+		return "#" .. value:ToHex()
+	end
+	if t == "BrickColor" then
+		return value.Name
+	end
+	if t == "ColorSequence" then
+		local kps = {}
+		for _, kp in value.Keypoints do
+			table.insert(kps, { kp.Time, "#" .. kp.Value:ToHex() })
+		end
+		return kps
+	end
+	if t == "NumberSequence" then
+		local kps = {}
+		for _, kp in value.Keypoints do
+			table.insert(kps, { kp.Time, kp.Value, kp.Envelope })
+		end
+		return kps
+	end
+	if t == "NumberRange" then
+		return { value.Min, value.Max }
+	end
+	if t == "Rect" then
+		return { value.Min.X, value.Min.Y, value.Max.X, value.Max.Y }
+	end
+	if t == "CFrame" then
+		return { value:GetComponents() }
+	end
+	if t == "EnumItem" then
+		return value.Name
+	end
+	if t == "Font" then
+		return {
+			Family = value.Family,
+			Weight = value.Weight.Name,
+			Style = value.Style.Name,
+		}
+	end
+	if t == "boolean" or t == "number" or t == "string" then
+		return value
+	end
+	-- Fallback: tostring
+	return tostring(value)
+end
+
+local SERIALIZE_SKIP = {
+	Parent = true,
+	ClassName = true,
+	Name = true,
+	Archivable = true,
+	AbsolutePosition = true,
+	AbsoluteSize = true,
+	AbsoluteRotation = true,
+	IsLoaded = true,
+}
+
+local function serializeNode(instance, maxDepth, depth)
+	if depth > maxDepth then
+		return nil
+	end
+
+	local node = {
+		ClassName = instance.ClassName,
+		Name = instance.Name,
+	}
+
+	-- Get non-default properties via reflection
+	local ok, propData = pcall(function()
+		return ReflectionService:GetPropertiesOfClass(instance.ClassName)
+	end)
+
+	if ok and propData then
+		-- Create a default instance to compare against
+		local defaultInstance = nil
+		pcall(function()
+			defaultInstance = Instance.new(instance.ClassName)
+		end)
+
+		for _, prop in propData do
+			if not SERIALIZE_SKIP[prop.Name] and not prop.Name:match("^Absolute") then
+				local valOk, value = pcall(function()
+					return instance[prop.Name]
+				end)
+				if valOk and value ~= nil then
+					-- Skip default values
+					local isDefault = false
+					if defaultInstance then
+						local defOk, defVal = pcall(function()
+							return defaultInstance[prop.Name]
+						end)
+						if defOk and defVal == value then
+							isDefault = true
+						end
+					end
+
+					if not isDefault then
+						local jsonVal = valueToJson(value, prop.Type and tostring(prop.Type))
+						if jsonVal ~= nil then
+							node[prop.Name] = jsonVal
+						end
+					end
+				end
+			end
+		end
+
+		if defaultInstance then
+			pcall(function()
+				defaultInstance:Destroy()
+			end)
+		end
+	end
+
+	-- Serialize children
+	local children = instance:GetChildren()
+	if #children > 0 then
+		node.Children = {}
+		for _, child in children do
+			local childNode = serializeNode(child, maxDepth, depth + 1)
+			if childNode then
+				table.insert(node.Children, childNode)
+			end
+		end
+		if #node.Children == 0 then
+			node.Children = nil
+		end
+	end
+
+	return node
+end
+
+function UIBuilder.serialize(spec)
+	local path = spec.path
+	if not path then
+		return { success = false, error = "Missing 'path' parameter" }
+	end
+
+	local instance = Explorer.resolveInstance(path)
+	if not instance then
+		return { success = false, error = "Instance not found: " .. path }
+	end
+
+	local maxDepth = spec.maxDepth or 50
+
+	local ok, tree = pcall(function()
+		return serializeNode(instance, maxDepth, 0)
+	end)
+
+	if not ok then
+		return { success = false, error = "Serialization failed: " .. tostring(tree) }
+	end
+
+	return { success = true, tree = tree }
+end
+
+local function buildStrictNode(spec, state, depth)
+	assert(type(spec) == "table", "Every UI node must be an object")
+	if depth > state.maxDepth then
+		error("UI tree exceeds maximum depth of " .. state.maxDepth)
+	end
+	state.count += 1
+	if state.count > state.maxNodes then
+		error("UI tree exceeds maximum node count of " .. state.maxNodes)
+	end
+
+	local className = spec.ClassName or spec.className
+	assert(type(className) == "string", "Every UI node requires ClassName")
+	local instance = Instance.new(className)
+	instance.Name = spec.Name or spec.name or className
+
+	for key, value in spec do
+		if not RESERVED_KEYS[key] then
+			ValueCodec.setProperty(instance, key, value)
+		end
+	end
+	local properties = spec.properties or spec.Properties or spec.props or spec.Props
+	if properties ~= nil then
+		assert(type(properties) == "table", "UI node properties must be an object")
+		for key, value in properties do
+			ValueCodec.setProperty(instance, key, value)
+		end
+	end
+
+	local children = spec.Children or spec.children
+	if children ~= nil then
+		assert(type(children) == "table", "UI node Children must be an array")
+		for _, childSpec in children do
+			local child = buildStrictNode(childSpec, state, depth + 1)
+			child.Parent = instance
+		end
+	end
+	return instance
+end
+
+function UIBuilder.buildV2(spec)
+	if type(spec.tree) ~= "table" then
+		return { success = false, error = "tree is required" }
+	end
+	local parentRef = spec.parent or { pathSegments = { "StarterGui" } }
+	local parent, parentErr = InstanceRegistry.resolve(parentRef)
+	if not parent then
+		return { success = false, error = "Parent: " .. tostring(parentErr) }
+	end
+
+	local state = {
+		count = 0,
+		maxDepth = math.clamp(spec.maxDepth or 30, 1, 50),
+		maxNodes = math.clamp(spec.maxNodes or 1000, 1, 3000),
+	}
+	local builtOk, rootOrError = pcall(function()
+		return buildStrictNode(spec.tree, state, 0)
+	end)
+	if not builtOk then
+		return { success = false, error = "UI validation failed: " .. tostring(rootOrError) }
+	end
+	local root = rootOrError
+
+	local existing = nil
+	local duplicateCount = 0
+	for _, child in parent:GetChildren() do
+		if child.Name == root.Name then
+			existing = child
+			duplicateCount += 1
+		end
+	end
+	if duplicateCount > 1 then
+		root:Destroy()
+		return {
+			success = false,
+			error = "Replacement target is ambiguous because multiple children share the name " .. root.Name,
+		}
+	end
+	if existing and spec.replaceExisting ~= true then
+		root:Destroy()
+		return {
+			success = false,
+			error = "A child named " .. root.Name .. " already exists; set replaceExisting=true to replace it",
+		}
+	end
+
+	local recording = ChangeHistoryService:TryBeginRecording("Dominus 2: Build UI " .. root.Name)
+	if not recording then
+		root:Destroy()
+		return { success = false, error = "Another plugin recording is already active" }
+	end
+	local commitOk, commitErr = pcall(function()
+		if existing then
+			existing:Destroy()
+		end
+		root.Parent = parent
+	end)
+	if not commitOk then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		if root.Parent == nil then
+			root:Destroy()
+		end
+		return { success = false, error = "UI commit failed: " .. tostring(commitErr), rolledBack = true }
+	end
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	return {
+		success = true,
+		root = InstanceRegistry.toRef(root),
+		instanceCount = state.count,
+		replaced = existing ~= nil,
+	}
+end
+
+function UIBuilder.snapshotV2(spec)
+	local instance, err = InstanceRegistry.resolve(spec.target)
+	if not instance then
+		return { success = false, error = err }
+	end
+	local maxDepth = math.clamp(spec.maxDepth or 30, 0, 50)
+	local ok, tree = pcall(function()
+		return serializeNode(instance, maxDepth, 0)
+	end)
+	if not ok then
+		return { success = false, error = "UI serialization failed: " .. tostring(tree) }
+	end
+	return { success = true, target = InstanceRegistry.toRef(instance), tree = tree }
+end
+
+return UIBuilder