# TASK-159-03-04-03: Addon Scene Custom Property Utility Split

**Parent:** [TASK-159-03-04](./TASK-159-03-04_Addon_Scene_Creation_Visibility_And_Metadata_Utilities.md)
**Status:** ✅ Done
**Priority:** 🔴 High

## Objective

Separate custom-property read/write helpers into one focused addon utility leaf.

## Repository Touchpoints

- `blender_addon/application/handlers/scene.py`
- likely helper module such as `blender_addon/application/handlers/scene_utility_mixin.py`
- `tests/unit/tools/scene/test_scene_mcp_tools_batch.py`
- `tests/unit/tools/test_handler_rpc_alignment.py`
- `tests/unit/adapters/mcp/test_structured_contract_delivery.py`

## Current Code Anchors

- `SceneHandler.get_custom_properties(...)`
- `SceneHandler.set_custom_property(...)`

## Planned Code Shape

```python
class SceneHandler(SceneCustomPropertyUtilityMixin, ...):
    pass
```

## Runtime / Security Contract Notes

- keep custom-property read/write payloads and structured delivery stable
- no dedicated Blender-backed custom-property workflow test exists today, so
  this leaf closes on the exact unit/RPC/structured-contract lanes until such a
  runtime workflow exists

## Tests To Add/Update

- `tests/unit/tools/scene/test_scene_mcp_tools_batch.py`
- `tests/unit/tools/test_handler_rpc_alignment.py`
- `tests/unit/adapters/mcp/test_structured_contract_delivery.py`

## Validation Commands

- `PYTHONPATH=. poetry run pytest tests/unit/tools/scene/test_scene_mcp_tools_batch.py tests/unit/tools/test_handler_rpc_alignment.py tests/unit/adapters/mcp/test_structured_contract_delivery.py -q`

## Docs To Update

- inherit parent docs closeout unless custom-property ownership wording changes

## Changelog Impact

- include in the parent `TASK-159` changelog entry when shipped

## Acceptance Criteria

- custom-property helpers have a focused home
- structured delivery and payload semantics remain unchanged under the current
  unit/RPC/structured-contract proof lane

## Status / Board Update

- keep promoted tracking on parent `TASK-159`

## Completion Summary

Completed on 2026-05-04.

- moved `get_custom_properties(...)` and `set_custom_property(...)` into
  `blender_addon/application/handlers/scene_custom_property_utility_mixin.py`
- preserved structured custom-property serialization and delete/set behavior
  without changing the current RPC or structured-contract proof lane
