reactor-advanced

# Reactor Advanced Use this skill when adding immediate-mode Win2D drawing through `Microsoft.UI.Reactor.Advanced`. The full guide is `docs/guide/win2d-canvas.md`; the performance sample is `samples/apps/particle-storm/`. ## Pick the right canvas | Workload | Use | Why | |---|---|---| | Static or data-driven drawing that changes after state updates | `Win2DCanvas.Of(onDraw, redrawKey)` | Manual invalidation; pass a changing `RedrawKey` for every value the draw callback reads. | | Game loop, physics, particles, visualizers, steady FPS | `Win2DAnimatedCanvas.Of(onUpdate, onDraw, drawState, isPaused)` | Win2D owns the tick and calls update/draw on the game thread. | | Huge scrollable or tiled surfaces | `Win2DVirtualCanvas.Of(onRegionDraw, contentSize)` | Draws only invalidated visible regions; update tiles by changing `InvalidateRegions`. | ## Threading cheat sheet | Callback | Thread | Rule | |---|---|---| | `Win2DCanvas.OnDraw` | UI thread | Safe to read Reactor state captured by render. | | `Win2DAnimatedCanvas.OnUpdate` / `.OnDraw` | Win2D game thread | Do **not** touch WinUI controls. Use thread-safe data or `UseState(threadSafe: true)` for UI handoff. | | `Win2DVirtualCanvas.OnRegionDraw` | UI thread | Keep work bounded to the invalidated region. | | `UseCanvasResources` factory | Worker/game thread | Create device resources and return a disposable/recreatable object. | Treat `Ref.Current` from `UseDrawState` like a volatile field. Re-read it and make the referenced object safe for any cross-thread mutation. Debug builds add a sentinel that appends `docs/guide/win2d-canvas.md#threading` to likely WinUI thread-affinity exceptions from animated callbacks. ## Reference graph model Element refs are reactive cells. `.Ref(cell)` writes the mounted `FrameworkElement` into the cell and writes `null` on unmount. Reference properties (`TeachingTip.Target`, `.LabeledBy`, `.DescribedBy`, `.FlowsTo`, `.FlowsFrom`, `.XYFocus*`, and custom descriptor `.Reference` / `.ReferenceList`) subscribe to those cells instead of sampling `.Current`. Resolution is one-way and push-based: cells enqueue dirty reference edges during commit, then Reactor flushes the dirty set after the tree is stable. Cycles are allowed because each property slot is a one-way edge. List references preserve author declaration order and omit unresolved targets. Advanced authors should use `descriptor.Reference` for regular controls and `binding.Reference` only as the bridge for hand-coded handlers. ## Hooks and recipes ```csharp var state = ctx.UseDrawState(() => new ParticleField(20_000)); var sprite = ctx.UseCanvasResources<CanvasBitmap>(async device => await CanvasBitmap.LoadAsync(device, "Assets/particle.png")); var draw = ctx.UseDrawCommand(model, static (session, args, m) => m.Render(session), deps: [model.Version]); ``` `UseCanvasResources` is the device-loss recipe: allocate from the supplied `CanvasDevice`, draw only when the returned ref is non-null, and let the hook dispose/recreate after `CanvasDevice.DeviceLost`. ## Performance proof The Particle Storm sample (`samples/apps/particle-storm/`) is the canonical pattern: pure Reactor chrome controls parameters; `Win2DAnimatedCanvas` renders the hot particle path; `UseDrawState` holds the particle buffers; `UseCanvasResources` owns sprites and other device resources.