Add external renderer layer for generated dancers

[mikeharv]

Summary

Introduce a pluggable “external dancer” rendering layer that Dance Party can composite between sprites and foreground effects. This allows the main code-dot-org repo to supply its own renderer (e.g., a Lottie-based dancer preview) without adding that dependency to Dance Party.

The external renderer layer is shown below as bull dancer that is provided by a Lottie renderer introduced with code-dot-org/code-dot-org#68250

2025-09-09.15-37-31.2025-09-09.15_38_01.mp4

We have multiple surfaces that need to render the same generated dancer JSON (Dance Party canvas, a Dancer Editor, and a Music Lab view). Centralizing the rendering logic in the main repo keeps Dance Party lean and lets other surfaces reuse the same renderer.

What changed

• New adapter: ExternalDancerLayer (p5 adapter that owns a p5.Graphics buffer and hands its 2D context to an external renderer).
• New injection point: DanceParty now accepts an optional externalRendererFactory (constructor option). If provided, setup() creates an ExternalDancerLayer.
• New helper: setExternalLayerSource(dancerName) updates the external layer’s source JSON (or clears it).
• Draw order: When the external layer is present, we split sprite rendering around it (low-depth sprites → external layer → high-depth sprites) to preserve the intended depth illusion.
• Reset/teardown: Resets clear or dispose the external layer cleanly.

Behavioral notes

• If no externalRendererFactory is provided, no behavior change: sprites and effects render as before.
• Timing for the external layer is driven by the current song measure, so it stays in sync with sprites.
• This code does not change any behavior for the standalone DanceParty package, unless a compatible external renderer is provided.

Deployment strategy

Pairs with code-dot-org/code-dot-org#68250 (adds the concrete Lottie renderer and passes the factory into DanceParty).

Testing story

• Verified dancer renders inside the Dance Party canvas and respects layout (fit/center/scale).
• Confirmed sprite split rendering shows “in front of”/“behind” correctly.
• Verified sync with song beat and sprite timing.
• Resizing and disposal don’t leak canvases.

[breville]

nit: periods at end of sentences in comments.

[breville]

Out of curiosity, would it be possible to create a regular Sprite but override its draw function to call the custom renderer at the right time?

[sanchitmalhotra126]

Mind explaining what this is for?