open-wc/coordination/claims/M03-RND-M2-ANIMATED-INSTANCE-MATERIALIZER-001.md

M03-RND-M2-ANIMATED-INSTANCE-MATERIALIZER-001

Owner

• Agent ID: sindo-main-codex
• Target: M03 Renderer Facade and Safe Extraction
• Branch: work/sindo-main-codex/m03-m2-animated-instance-materializer
• Worktree: C:\Users\sindo\open-wc-worktrees\m03-m2-animated-instance-materializer

Outcome

Extract main-thread animated M2 instance duplication, render-property application, playback startup and batch attachment from StreamingWorldLoader.

Non-goals

• Change build-job cursors, budgets, prototype selection or animation eligibility.
• Change animation selection, phase, native animator behavior or diagnostic text.
• Own Editor scene persistence, static MultiMesh materialization or tile cleanup.
• Change visible transforms, visibility ranges, shadows or placement ordering.

Paths

• Exclusive: src/render/m2/m2_animated_instance_materializer.gd, src/tools/verify_m2_animated_instance_materializer.gd, docs/modules/m2-animated-instance-materializer.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, M2 animation playback/finalizer/build/facade/internal-access/manifest verifiers and specs, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated resources/caches and proprietary corpus

Contracts and data

• Duplicate flags, names, transforms and input order remain unchanged.
• Visibility end/margin and shadow mode are applied recursively before attachment.
• Playback data copy/start delegates to the accepted playback controller contract.
• The batch is attached only when at least one duplicate succeeds.
• Loader retains diagnostic formatting/path normalization and Editor ownership.

Dependencies

• Requires: accepted playback package on master 5b2d9f2
• Blocks: further animated M2 build orchestration extraction
• External state: Godot Node duplication and SceneTree attachment remain main-thread APIs

Verification

• Commands: dedicated duplication/order/render/playback/empty/source/timing verifier; M2 animated pipeline/finalizer/playback/prototype/build/shutdown/material/facade/ internal-access/manifest regressions; docs/coordination/dry-run gates
• Fixtures: synthetic prototype trees with geometry, AnimationPlayer and native animator
• Fidelity evidence: exact transforms, flags, render settings, playback delegation and order
• Performance budget: 1,000 synthetic instances under 1 second

Documentation deliverables

• Inline API docs
• Module spec with inputs/outputs, ownership and source map
• Data-flow, lifecycle/state, sequence and dependency diagrams
• Adjacent playback/finalizer/build/world-renderer/module-registry/RENDER updates

Simplicity and naming

• Important name introduced: M2AnimatedInstanceMaterializer
• Simplest solution: synchronous main-thread RefCounted returning batch diagnostics
• Rejected complexity: signals, async queue, callbacks and generic scene factory
• Unavoidable complexity: imported AnimationPlayer and native animator paths coexist
• Measured optimization evidence: bounded synthetic batch materialization

Status

• State: active
• Done: contract and ownership boundary
• Next: implementation, verification and documentation
• Blocked by:

Handoff

• Commit:
• Results:
• Remaining risks:
• Documentation updated: