mcpforunityserver 9.3.0b20260128055651__py3-none-any.whl → 9.3.0b20260129121506__py3-none-any.whl

services/tools/manage_material.py

@@ -9,44 +9,11 @@ from mcp.types import ToolAnnotations
 
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
-from services.tools.utils import parse_json_payload, coerce_int, normalize_properties
+from services.tools.utils import parse_json_payload, coerce_int, normalize_properties, normalize_color
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 
 
-def _normalize_color(value: Any) -> tuple[list[float] | None, str | None]:
-    """
-    Normalize color parameter to [r, g, b] or [r, g, b, a] format.
-    Returns (parsed_color, error_message).
-    """
-    if value is None:
-        return None, None
-
-    # Already a list - validate
-    if isinstance(value, (list, tuple)):
-        if len(value) in (3, 4):
-            try:
-                return [float(c) for c in value], None
-            except (ValueError, TypeError):
-                return None, f"color values must be numbers, got {value}"
-        return None, f"color must have 3 or 4 components, got {len(value)}"
-
-    # Try parsing as string
-    if isinstance(value, str):
-        if value in ("[object Object]", "undefined", "null", ""):
-            return None, f"color received invalid value: '{value}'. Expected [r, g, b] or [r, g, b, a]"
-
-        parsed = parse_json_payload(value)
-        if isinstance(parsed, (list, tuple)) and len(parsed) in (3, 4):
-            try:
-                return [float(c) for c in parsed], None
-            except (ValueError, TypeError):
-                return None, f"color values must be numbers, got {parsed}"
-        return None, f"Failed to parse color string: {value}"
-
-    return None, f"color must be a list or JSON string, got {type(value).__name__}"
-
-
 @mcp_for_unity_tool(
     description="Manages Unity materials (set properties, colors, shaders, etc). Read-only actions: ping, get_material_info. Modifying actions: create, set_material_shader_property, set_material_color, assign_material_to_renderer, set_renderer_color.",
     annotations=ToolAnnotations(
@@ -82,8 +49,8 @@ async def manage_material(
                      "Value to set (color array, float, texture path/instruction)"] | None = None,
 
     # set_material_color / set_renderer_color
-    color: Annotated[list[float] | str,
-                     "Color as [r, g, b] or [r, g, b, a] array (list or JSON string)."] | None = None,
+    color: Annotated[list[float] | dict[str, float] | str,
+                     "Color as [r, g, b] or [r, g, b, a] array, {r, g, b, a} object, or JSON string."] | None = None,
 
     # assign_material_to_renderer / set_renderer_color
     target: Annotated[str,
@@ -98,7 +65,7 @@ async def manage_material(
     unity_instance = get_unity_instance_from_context(ctx)
 
     # --- Normalize color with validation ---
-    color, color_error = _normalize_color(color)
+    color, color_error = normalize_color(color, output_range="float")
     if color_error:
         return {"success": False, "message": color_error}
 

services/tools/manage_prefabs.py

@@ -5,7 +5,7 @@ from mcp.types import ToolAnnotations
 
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
-from services.tools.utils import coerce_bool
+from services.tools.utils import coerce_bool, normalize_vector3
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.preflight import preflight
@@ -25,6 +25,10 @@ REQUIRED_PARAMS = {
         "Manages Unity Prefab assets via headless operations (no UI, no prefab stages). "
         "Actions: get_info, get_hierarchy, create_from_gameobject, modify_contents. "
         "Use modify_contents for headless prefab editing - ideal for automated workflows. "
+        "Use create_child parameter with modify_contents to add child GameObjects to a prefab "
+        "(single object or array for batch creation in one save). "
+        "Example: create_child=[{\"name\": \"Child1\", \"primitive_type\": \"Sphere\", \"position\": [1,0,0]}, "
+        "{\"name\": \"Child2\", \"primitive_type\": \"Cube\", \"parent\": \"Child1\"}]. "
         "Use manage_asset action=search filterType=Prefab to list prefabs."
     ),
     annotations=ToolAnnotations(
@@ -49,9 +53,9 @@ async def manage_prefabs(
     search_inactive: Annotated[bool, "Include inactive GameObjects in search."] | None = None,
     unlink_if_instance: Annotated[bool, "Unlink from existing prefab before creating new one."] | None = None,
     # modify_contents parameters
-    position: Annotated[list[float], "New local position [x, y, z] for modify_contents."] | None = None,
-    rotation: Annotated[list[float], "New local rotation (euler angles) [x, y, z] for modify_contents."] | None = None,
-    scale: Annotated[list[float], "New local scale [x, y, z] for modify_contents."] | None = None,
+    position: Annotated[list[float] | dict[str, float] | str, "New local position [x, y, z] or {x, y, z} for modify_contents."] | None = None,
+    rotation: Annotated[list[float] | dict[str, float] | str, "New local rotation (euler angles) [x, y, z] or {x, y, z} for modify_contents."] | None = None,
+    scale: Annotated[list[float] | dict[str, float] | str, "New local scale [x, y, z] or {x, y, z} for modify_contents."] | None = None,
     name: Annotated[str, "New name for the target object in modify_contents."] | None = None,
     tag: Annotated[str, "New tag for the target object in modify_contents."] | None = None,
     layer: Annotated[str, "New layer name for the target object in modify_contents."] | None = None,
@@ -59,6 +63,7 @@ async def manage_prefabs(
     parent: Annotated[str, "New parent object name/path within prefab for modify_contents."] | None = None,
     components_to_add: Annotated[list[str], "Component types to add in modify_contents."] | None = None,
     components_to_remove: Annotated[list[str], "Component types to remove in modify_contents."] | None = None,
+    create_child: Annotated[dict[str, Any] | list[dict[str, Any]], "Create child GameObject(s) in the prefab. Single object or array of objects, each with: name (required), parent (optional, defaults to target), primitive_type (optional: Cube, Sphere, Capsule, Cylinder, Plane, Quad), position, rotation, scale, components_to_add, tag, layer, set_active."] | None = None,
 ) -> dict[str, Any]:
     # Back-compat: map 'name' → 'target' for create_from_gameobject (Unity accepts both)
     if action == "create_from_gameobject" and target is None and name is not None:
@@ -114,11 +119,20 @@ async def manage_prefabs(
 
         # modify_contents parameters
         if position is not None:
-            params["position"] = position
+            position_value, position_error = normalize_vector3(position, "position")
+            if position_error:
+                return {"success": False, "message": position_error}
+            params["position"] = position_value
         if rotation is not None:
-            params["rotation"] = rotation
+            rotation_value, rotation_error = normalize_vector3(rotation, "rotation")
+            if rotation_error:
+                return {"success": False, "message": rotation_error}
+            params["rotation"] = rotation_value
         if scale is not None:
-            params["scale"] = scale
+            scale_value, scale_error = normalize_vector3(scale, "scale")
+            if scale_error:
+                return {"success": False, "message": scale_error}
+            params["scale"] = scale_value
         if name is not None:
             params["name"] = name
         if tag is not None:
@@ -134,6 +148,36 @@ async def manage_prefabs(
             params["componentsToAdd"] = components_to_add
         if components_to_remove is not None:
             params["componentsToRemove"] = components_to_remove
+        if create_child is not None:
+            # Normalize vector fields within create_child (handles single object or array)
+            def normalize_child_params(child: Any, index: int | None = None) -> tuple[dict | None, str | None]:
+                prefix = f"create_child[{index}]" if index is not None else "create_child"
+                if not isinstance(child, dict):
+                    return None, f"{prefix} must be a dict with child properties (name, primitive_type, position, etc.), got {type(child).__name__}"
+                child_params = dict(child)
+                for vec_field in ("position", "rotation", "scale"):
+                    if vec_field in child_params and child_params[vec_field] is not None:
+                        vec_val, vec_err = normalize_vector3(child_params[vec_field], f"{prefix}.{vec_field}")
+                        if vec_err:
+                            return None, vec_err
+                        child_params[vec_field] = vec_val
+                return child_params, None
+
+            if isinstance(create_child, list):
+                # Array of children
+                normalized_children = []
+                for i, child in enumerate(create_child):
+                    child_params, err = normalize_child_params(child, i)
+                    if err:
+                        return {"success": False, "message": err}
+                    normalized_children.append(child_params)
+                params["createChild"] = normalized_children
+            else:
+                # Single child object
+                child_params, err = normalize_child_params(create_child)
+                if err:
+                    return {"success": False, "message": err}
+                params["createChild"] = child_params
 
         # Send command to Unity
         response = await send_with_unity_instance(

services/tools/manage_script.py

@@ -613,7 +613,7 @@ async def manage_script_capabilities(ctx: Context) -> dict[str, Any]:
 
 
 @mcp_for_unity_tool(
-    description="Get SHA256 and basic metadata for a Unity C# script without returning file contents",
+    description="Get SHA256 and basic metadata for a Unity C# script without returning file contents. Requires uri (script path under Assets/ or mcpforunity://path/Assets/... or file://...).",
     annotations=ToolAnnotations(
         title="Get SHA",
         readOnlyHint=True,

services/tools/manage_texture.py

@@ -10,41 +10,12 @@ from mcp.types import ToolAnnotations
 
 from services.registry import mcp_for_unity_tool
 from services.tools import get_unity_instance_from_context
-from services.tools.utils import parse_json_payload, coerce_bool, coerce_int
+from services.tools.utils import parse_json_payload, coerce_bool, coerce_int, normalize_color
 from transport.unity_transport import send_with_unity_instance
 from transport.legacy.unity_connection import async_send_command_with_retry
 from services.tools.preflight import preflight
 
 
-def _is_normalized_color(values: list) -> bool:
-    """
-    Check if color values appear to be in normalized 0.0-1.0 range.
-    Returns True if all values are <= 1.0 and at least one is a float or between 0-1 exclusive.
-    """
-    if not values:
-        return False
-    
-    try:
-        numeric_values = [float(v) for v in values]
-    except (TypeError, ValueError):
-        return False
-
-    # Check if all values are <= 1.0
-    all_small = all(0 <= v <= 1.0 for v in numeric_values)
-    if not all_small:
-        return False
-    
-    # If any non-zero value is less than 1, it's likely normalized (e.g., 0.5)
-    has_fractional = any(0 < v < 1 for v in numeric_values)
-    
-    # If all values are 0 or 1, and they're all integers, could be either format
-    # In this ambiguous case (like [1, 0, 0, 1]), assume normalized since that's
-    # what graphics programmers typically use
-    all_binary = all(v in (0, 1, 0.0, 1.0) for v in numeric_values)
-    
-    return has_fractional or all_binary
-
-
 def _normalize_dimension(value: Any, name: str, default: int = 64) -> tuple[int | None, str | None]:
     if value is None:
         return default, None
@@ -65,66 +36,9 @@ def _normalize_positive_int(value: Any, name: str) -> tuple[int | None, str | No
     return coerced, None
 
 
-def _normalize_color(value: Any) -> tuple[list[int] | None, str | None]:
-    """
-    Normalize color parameter to [r, g, b, a] format (0-255).
-    Auto-detects normalized float colors (0.0-1.0) and converts to 0-255.
-    Returns (parsed_color, error_message).
-    """
-    if value is None:
-        return None, None
-
-    # Already a list - validate
-    if isinstance(value, (list, tuple)):
-        if len(value) == 3:
-            value = list(value) + [1.0 if _is_normalized_color(value) else 255]
-        if len(value) == 4:
-            try:
-                # Check if values appear to be normalized (0.0-1.0 range)
-                if _is_normalized_color(value):
-                    # Convert from 0.0-1.0 to 0-255
-                    return [int(round(float(c) * 255)) for c in value], None
-                else:
-                    # Already in 0-255 range
-                    return [int(c) for c in value], None
-            except (ValueError, TypeError):
-                return None, f"color values must be numeric, got {value}"
-        return None, f"color must have 3 or 4 components, got {len(value)}"
-
-    # Try parsing as string
-    if isinstance(value, str):
-        if value in ("[object Object]", "undefined", "null", ""):
-            return None, f"color received invalid value: '{value}'. Expected [r, g, b] or [r, g, b, a]"
-
-        # Handle Hex Colors
-        if value.startswith("#"):
-            h = value.lstrip("#")
-            try:
-                if len(h) == 6:
-                    return [int(h[i:i+2], 16) for i in (0, 2, 4)] + [255], None
-                elif len(h) == 8:
-                    return [int(h[i:i+2], 16) for i in (0, 2, 4, 6)], None
-            except ValueError:
-                return None, f"Invalid hex color: {value}"
-
-        parsed = parse_json_payload(value)
-        if isinstance(parsed, (list, tuple)):
-            if len(parsed) == 3:
-                parsed = list(parsed) + [1.0 if _is_normalized_color(parsed) else 255]
-            if len(parsed) == 4:
-                try:
-                    # Check if values appear to be normalized (0.0-1.0 range)
-                    if _is_normalized_color(parsed):
-                        # Convert from 0.0-1.0 to 0-255
-                        return [int(round(float(c) * 255)) for c in parsed], None
-                    else:
-                        # Already in 0-255 range
-                        return [int(c) for c in parsed], None
-                except (ValueError, TypeError):
-                    return None, f"color values must be numeric, got {parsed}"
-        return None, f"Failed to parse color string: {value}"
-
-    return None, f"color must be a list or JSON string, got {type(value).__name__}"
+def _normalize_color_int(value: Any) -> tuple[list[int] | None, str | None]:
+    """Thin wrapper for normalize_color with int output for texture operations."""
+    return normalize_color(value, output_range="int")
 
 
 def _normalize_palette(value: Any) -> tuple[list[list[int]] | None, str | None]:
@@ -146,7 +60,7 @@ def _normalize_palette(value: Any) -> tuple[list[list[int]] | None, str | None]:
 
     normalized = []
     for i, color in enumerate(value):
-        parsed, error = _normalize_color(color)
+        parsed, error = _normalize_color_int(color)
         if error:
             return None, f"palette[{i}]: {error}"
         normalized.append(parsed)
@@ -181,7 +95,7 @@ def _normalize_pixels(value: Any, width: int, height: int) -> tuple[list[list[in
 
         normalized = []
         for i, pixel in enumerate(value):
-            parsed, error = _normalize_color(pixel)
+            parsed, error = _normalize_color_int(pixel)
             if error:
                 return None, f"pixels[{i}]: {error}"
             normalized.append(parsed)
@@ -482,8 +396,8 @@ async def manage_texture(
     height: Annotated[int, "Texture height in pixels (default: 64)"] | None = None,
 
     # Solid fill (accepts both 0-255 integers and 0.0-1.0 normalized floats)
-    fill_color: Annotated[list[int | float],
-                          "Fill color as [r, g, b] or [r, g, b, a]. Accepts both 0-255 range (e.g., [255, 0, 0]) or 0.0-1.0 normalized range (e.g., [1.0, 0, 0])"] | None = None,
+    fill_color: Annotated[list[int | float] | dict[str, int | float] | str,
+                          "Fill color as [r, g, b] or [r, g, b, a] array, {r, g, b, a} object, or hex string. Accepts both 0-255 range (e.g., [255, 0, 0]) or 0.0-1.0 normalized range (e.g., [1.0, 0, 0])"] | None = None,
 
     # Pattern-based generation
     pattern: Annotated[Literal[
@@ -544,7 +458,7 @@ async def manage_texture(
         return gate.model_dump()
 
     # --- Normalize parameters ---
-    fill_color, fill_error = _normalize_color(fill_color)
+    fill_color, fill_error = _normalize_color_int(fill_color)
     if fill_error:
         return {"success": False, "message": fill_error}
 
@@ -613,7 +527,7 @@ async def manage_texture(
 
         set_pixels_normalized = set_pixels.copy()
         if "color" in set_pixels_normalized:
-            color, error = _normalize_color(set_pixels_normalized["color"])
+            color, error = _normalize_color_int(set_pixels_normalized["color"])
             if error:
                 return {"success": False, "message": f"set_pixels.color: {error}"}
             set_pixels_normalized["color"] = color

services/tools/run_tests.py

@@ -16,11 +16,58 @@ from services.tools import get_unity_instance_from_context
 from services.tools.preflight import preflight
 import transport.unity_transport as unity_transport
 from transport.legacy.unity_connection import async_send_command_with_retry
-from utils.focus_nudge import nudge_unity_focus, should_nudge
+from transport.plugin_hub import PluginHub
+from utils.focus_nudge import nudge_unity_focus, should_nudge, reset_nudge_backoff
 
 logger = logging.getLogger(__name__)
 
 
+async def _get_unity_project_path(unity_instance: str | None) -> str | None:
+    """Get the project root path for a Unity instance (for focus nudging).
+
+    Args:
+        unity_instance: Unity instance hash or "Name@hash" format or None
+
+    Returns:
+        Project root path (e.g., "/Users/name/project"), or falls back to project_name if path unavailable
+    """
+    if not unity_instance:
+        return None
+
+    try:
+        registry = PluginHub._registry
+        if not registry:
+            return None
+
+        # Parse Name@hash format if present (middleware stores instances as "Name@hash")
+        target_hash = unity_instance
+        if "@" in target_hash:
+            _, _, target_hash = target_hash.rpartition("@")
+        if not target_hash:
+            return None
+
+        # Get session by hash
+        session_id = await registry.get_session_id_by_hash(target_hash)
+        if not session_id:
+            return None
+
+        session = await registry.get_session(session_id)
+        if not session:
+            return None
+
+    except Exception as e:
+        # Re-raise cancellation errors so task cancellation propagates
+        if isinstance(e, asyncio.CancelledError):
+            raise
+        logger.debug(f"Could not get Unity project path: {e}")
+        return None
+    else:
+        # Return full path if available, otherwise fall back to project name
+        if session.project_path:
+            return session.project_path
+        return session.project_name if session.project_name else None
+
+
 class RunTestsSummary(BaseModel):
     total: int
     passed: int
@@ -200,6 +247,10 @@ async def get_test_job(
     if wait_timeout and wait_timeout > 0:
         deadline = asyncio.get_event_loop().time() + wait_timeout
         poll_interval = 2.0  # Poll Unity every 2 seconds
+        prev_last_update_unix_ms = None
+
+        # Get project path once for focus nudging (multi-instance support)
+        project_path = await _get_unity_project_path(unity_instance)
 
         while True:
             response = await _fetch_status()
@@ -216,12 +267,20 @@ async def get_test_job(
             if status in ("succeeded", "failed", "cancelled"):
                 return GetTestJobResponse(**response)
 
+            # Detect progress and reset exponential backoff
+            last_update_unix_ms = data.get("last_update_unix_ms")
+            if prev_last_update_unix_ms is not None and last_update_unix_ms != prev_last_update_unix_ms:
+                # Progress detected - reset exponential backoff for next potential stall
+                reset_nudge_backoff()
+                logger.debug(f"Test job {job_id} made progress - reset nudge backoff")
+            prev_last_update_unix_ms = last_update_unix_ms
+
             # Check if Unity needs a focus nudge to make progress
             # This handles OS-level throttling (e.g., macOS App Nap) that can
             # stall PlayMode tests when Unity is in the background.
+            # Uses exponential backoff: 1s, 2s, 4s, 8s, 10s max between nudges.
             progress = data.get("progress", {})
             editor_is_focused = progress.get("editor_is_focused", True)
-            last_update_unix_ms = data.get("last_update_unix_ms")
             current_time_ms = int(time.time() * 1000)
 
             if should_nudge(
@@ -229,10 +288,14 @@ async def get_test_job(
                 editor_is_focused=editor_is_focused,
                 last_update_unix_ms=last_update_unix_ms,
                 current_time_ms=current_time_ms,
-                stall_threshold_ms=10_000,  # 10 seconds without progress
+                # Use default stall_threshold_ms (3s)
             ):
                 logger.info(f"Test job {job_id} appears stalled (unfocused Unity), attempting nudge...")
-                nudged = await nudge_unity_focus(focus_duration_s=0.5)
+                # Lazily resolve project path if not yet available (registry may have become ready)
+                if project_path is None:
+                    project_path = await _get_unity_project_path(unity_instance)
+                # Pass project path for multi-instance support
+                nudged = await nudge_unity_focus(unity_project_path=project_path)
                 if nudged:
                     logger.info(f"Test job {job_id} nudge completed")
 

services/tools/utils.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import math
 from typing import Any
 
 _TRUTHY = {"true", "1", "yes", "on"}
@@ -129,3 +130,219 @@ def normalize_properties(value: Any) -> tuple[dict[str, Any] | None, str | None]
         return None, f"properties must be a JSON object (dict), got string that parsed to {type(parsed).__name__}"
 
     return None, f"properties must be a dict or JSON string, got {type(value).__name__}"
+
+
+def normalize_vector3(value: Any, param_name: str = "vector") -> tuple[list[float] | None, str | None]:
+    """
+    Normalize a vector parameter to [x, y, z] format.
+
+    Handles various input formats from MCP clients/LLMs:
+    - None -> (None, None)
+    - list/tuple [x, y, z] -> ([x, y, z], None)
+    - dict {x, y, z} -> ([x, y, z], None)
+    - JSON string "[x, y, z]" or "{x, y, z}" -> parsed and normalized
+    - comma-separated string "x, y, z" -> ([x, y, z], None)
+
+    Returns:
+        Tuple of (parsed_vector, error_message). If error_message is set, parsed_vector is None.
+    """
+    if value is None:
+        return None, None
+
+    # Handle dict with x/y/z keys (e.g., {"x": 0, "y": 1, "z": 2})
+    if isinstance(value, dict):
+        if all(k in value for k in ("x", "y", "z")):
+            try:
+                vec = [float(value["x"]), float(value["y"]), float(value["z"])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {value}"
+            except (ValueError, TypeError, KeyError):
+                return None, f"{param_name} dict values must be numbers, got {value}"
+        return None, f"{param_name} dict must have 'x', 'y', 'z' keys, got {list(value.keys())}"
+
+    # If already a list/tuple with 3 elements, convert to floats
+    if isinstance(value, (list, tuple)) and len(value) == 3:
+        try:
+            vec = [float(value[0]), float(value[1]), float(value[2])]
+            if all(math.isfinite(n) for n in vec):
+                return vec, None
+            return None, f"{param_name} values must be finite numbers, got {value}"
+        except (ValueError, TypeError):
+            return None, f"{param_name} values must be numbers, got {value}"
+
+    # Try parsing as string
+    if isinstance(value, str):
+        # Check for obviously invalid values
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"{param_name} received invalid value: '{value}'. Expected [x, y, z] array or {{x, y, z}} object"
+
+        parsed = parse_json_payload(value)
+
+        # Handle parsed dict
+        if isinstance(parsed, dict):
+            return normalize_vector3(parsed, param_name)
+
+        # Handle parsed list
+        if isinstance(parsed, list) and len(parsed) == 3:
+            try:
+                vec = [float(parsed[0]), float(parsed[1]), float(parsed[2])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {parsed}"
+            except (ValueError, TypeError):
+                return None, f"{param_name} values must be numbers, got {parsed}"
+
+        # Handle comma-separated strings "1,2,3", "[1,2,3]", or "(1,2,3)"
+        s = value.strip()
+        if (s.startswith("[") and s.endswith("]")) or (s.startswith("(") and s.endswith(")")):
+            s = s[1:-1]
+        parts = [p.strip() for p in (s.split(",") if "," in s else s.split())]
+        if len(parts) == 3:
+            try:
+                vec = [float(parts[0]), float(parts[1]), float(parts[2])]
+                if all(math.isfinite(n) for n in vec):
+                    return vec, None
+                return None, f"{param_name} values must be finite numbers, got {value}"
+            except (ValueError, TypeError):
+                return None, f"{param_name} values must be numbers, got {value}"
+
+        return None, f"{param_name} must be a [x, y, z] array or {{x, y, z}} object, got: {value}"
+
+    return None, f"{param_name} must be a list, dict, or string, got {type(value).__name__}"
+
+
+def normalize_color(value: Any, output_range: str = "float") -> tuple[list[float] | None, str | None]:
+    """
+    Normalize a color parameter to [r, g, b, a] format.
+
+    Handles various input formats from MCP clients/LLMs:
+    - None -> (None, None)
+    - list/tuple [r, g, b] or [r, g, b, a] -> normalized with optional alpha
+    - dict {r, g, b} or {r, g, b, a} -> converted to list
+    - hex string "#RGB", "#RRGGBB", "#RRGGBBAA" -> parsed to [r, g, b, a]
+    - JSON string -> parsed and normalized
+
+    Args:
+        value: The color value to normalize
+        output_range: "float" for 0.0-1.0 range, "int" for 0-255 range
+
+    Returns:
+        Tuple of (parsed_color, error_message). If error_message is set, parsed_color is None.
+    """
+    if value is None:
+        return None, None
+
+    def _to_output_range(components: list[float], from_hex: bool = False) -> list:
+        """Convert color components to the requested output range."""
+        if output_range == "int":
+            if from_hex:
+                # Already 0-255 from hex parsing
+                return [int(c) for c in components]
+            # Check if input is normalized (0-1) or already 0-255
+            if all(0 <= c <= 1 for c in components):
+                return [int(round(c * 255)) for c in components]
+            return [int(c) for c in components]
+        else:  # float
+            if from_hex:
+                # Convert 0-255 to 0-1
+                return [c / 255.0 for c in components]
+            if any(c > 1 for c in components):
+                return [c / 255.0 for c in components]
+            return [float(c) for c in components]
+
+    # Handle dict with r/g/b keys
+    if isinstance(value, dict):
+        if all(k in value for k in ("r", "g", "b")):
+            try:
+                color = [float(value["r"]), float(value["g"]), float(value["b"])]
+                if "a" in value:
+                    color.append(float(value["a"]))
+                else:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError, KeyError):
+                return None, f"color dict values must be numbers, got {value}"
+        return None, f"color dict must have 'r', 'g', 'b' keys, got {list(value.keys())}"
+
+    # Already a list/tuple - validate
+    if isinstance(value, (list, tuple)):
+        if len(value) in (3, 4):
+            try:
+                color = [float(c) for c in value]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {value}"
+        return None, f"color must have 3 or 4 components, got {len(value)}"
+
+    # Try parsing as string
+    if isinstance(value, str):
+        if value in ("[object Object]", "undefined", "null", ""):
+            return None, f"color received invalid value: '{value}'. Expected [r, g, b, a] or {{r, g, b, a}}"
+
+        # Handle hex colors
+        if value.startswith("#"):
+            h = value.lstrip("#")
+            try:
+                if len(h) == 3:
+                    # Short form #RGB -> expand to #RRGGBB
+                    components = [int(c + c, 16) for c in h] + [255]
+                    return _to_output_range(components, from_hex=True), None
+                elif len(h) == 6:
+                    components = [int(h[i:i+2], 16) for i in (0, 2, 4)] + [255]
+                    return _to_output_range(components, from_hex=True), None
+                elif len(h) == 8:
+                    components = [int(h[i:i+2], 16) for i in (0, 2, 4, 6)]
+                    return _to_output_range(components, from_hex=True), None
+            except ValueError:
+                return None, f"Invalid hex color: {value}"
+            return None, f"Invalid hex color length: {value}"
+
+        # Try parsing as JSON
+        parsed = parse_json_payload(value)
+
+        # Handle parsed dict
+        if isinstance(parsed, dict):
+            return normalize_color(parsed, output_range)
+
+        # Handle parsed list
+        if isinstance(parsed, (list, tuple)) and len(parsed) in (3, 4):
+            try:
+                color = [float(c) for c in parsed]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                return None, f"color values must be numbers, got {parsed}"
+
+        # Handle tuple-style strings "(r, g, b)" or "(r, g, b, a)"
+        s = value.strip()
+        if (s.startswith("[") and s.endswith("]")) or (s.startswith("(") and s.endswith(")")):
+            s = s[1:-1]
+        parts = [p.strip() for p in s.split(",")]
+        if len(parts) in (3, 4):
+            try:
+                color = [float(p) for p in parts]
+                if len(color) == 3:
+                    if output_range == "int" and all(0 <= c <= 1 for c in color):
+                        color.append(1.0)
+                    else:
+                        color.append(1.0 if output_range == "float" else 255)
+                return _to_output_range(color), None
+            except (ValueError, TypeError):
+                pass  # Fall through to error message
+
+        return None, f"Failed to parse color string: {value}"
+
+    return None, f"color must be a list, dict, hex string, or JSON string, got {type(value).__name__}"