feat: Add HueEffect and HueDecorator

[s1r1m1r1]

Description

This PR adds a new
HueEffect
to the Flame effects library. This effect allows animating the hue shift of a component's paint over time.

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues

[spydon]

Docs and examples are missing, other than that it looks good!

[s1r1m1r1]

⚠️ Performance Warning: Decorators vs. Effects

This PR provides two ways to apply visual transformations: Decorators and Effects. It is crucial to understand their performance profiles:

Decorators (e.g., HueDecorator): This use canvas.saveLayer() to isolate the component's rendering and apply filters.

Pros: Highly flexible; supports complex chaining of multiple effects; works on any custom draw logic.
Cons: Significant performance overhead. Each saveLayer requires an off-screen buffer allocation and a GPU context switch. In high-density benchmarks (100+ sprites), this can be up to 20x slower than direct paint manipulation.

Effects (e.g., HueEffect): These modify the component's Paint(specifically colorFilter) directly.
Pros: Extremely fast. Hardware-accelerated directly in the fragment shader with zero memory allocation overhead.
Cons: Less flexible for complex layering; only works on components that expose a Paint.

Recommendation: Always prefer Effects for simple color/hue shifts on large numbers of units. Use Decorators only when you need complex visual composition or when targeting raw canvas drawing that isn't governed by a single

[spydon]

⚠️ Performance Warning: Decorators vs. Effects

This PR provides two ways to apply visual transformations: Decorators and Effects. It is crucial to understand their performance profiles:

Decorators (e.g., HueDecorator): This use canvas.saveLayer() to isolate the component's rendering and apply filters.

Pros: Highly flexible; supports complex chaining of multiple effects; works on any custom draw logic.
Cons: Significant performance overhead. Each saveLayer requires an off-screen buffer allocation and a GPU context switch. In high-density benchmarks (100+ sprites), this can be up to 20x slower than direct paint manipulation.

Effects (e.g., HueEffect): These modify the component's Paint(specifically colorFilter) directly.
Pros: Extremely fast. Hardware-accelerated directly in the fragment shader with zero memory allocation overhead.
Cons: Less flexible for complex layering; only works on components that expose a Paint.

Recommendation: Always prefer Effects for simple color/hue shifts on large numbers of units. Use Decorators only when you need complex visual composition or when targeting raw canvas drawing that isn't governed by a single

This should be a general comment on decorators in the docs, if it's not already in there.

[spydon]

Follow alphabetical order

[spydon]

Suggested change

	In this example we show how the `HueEffect` can be used.
	Ember will shift its hue over time.
	In this example we show how the `HueEffect` can be used.
	Ember will shift its hue over time.

[spydon]

Suggested change

	position: Vector2(size.x / 2, size.y / 2),
	position: size / 2,

[spydon]

Suggested change

	In this example we show how the `HueDecorator` can be used.
	Click anywhere to cycle through different hue shifts on Ember.
	In this example we show how the `HueDecorator` can be used.
	Click anywhere to cycle through different hue shifts on Ember.

[spydon]

It would be good to use nested components in this example to show when a decorator can be used when an effect doesn't work.

[spydon]

The main section should still be Decorators and have a description about what decorators are, it shouldn't start with a warning before the user knows what they are reading about.

[spydon]

We should probably add a new section called decorators, since we're missing examples for the rest of the decorators.

[spydon]

This will need both a To and a By effect, similar to MoveToEffect and MoveByEffect.