✨ Add gradient and image-filled text (Feature 3) (#4)

* feat: add gradient and image-filled text (Feature 3)

Adds the ability to fill text glyphs with LinearGradient, RadialGradient,
or a TextFillImage instead of a flat color.

- New `TextFillImage` model with `path` and `fit` fields
- New `fill` field on `TextLayer` and `TextPart`
- `Canvas.text()` accepts a `fill` parameter
- Per-part fill overrides layer-level fill for that segment
- Block-level fill for multiline text: gradient/image spans the entire
  text block rather than repeating per line
- Full JSON round-trip support via Pydantic discriminated union
- Effects (shadow, glow, stroke, background) compose correctly with fill
- 25 new tests covering models, JSON serialization, and rendering

https://claude.ai/code/session_01QK5iq4VqPsjWK8R9zJp1cg

* fix: resolve review bugs in gradient/image-filled text (Feature 3)

- Fix letter_spacing silently dropped when TextPart has both fill and
  letter_spacing set (_render_text_part now uses letter-spaced mask path)
- Fix letter_spacing silently dropped in multiline fill path
  (_render_multiline_text now pre-computes spaced widths for block bounds
  and draws stroke/mask character-by-character when letter_spacing is set)
- Add TextFillImage path validation in _validate_image_paths (checks layer
  fill and per-part fills before rendering)
- Add rendering tests for TextFillImage and TextPart fill+letter_spacing

https://claude.ai/code/session_01QK5iq4VqPsjWK8R9zJp1cg

* fix: exclude fill=None from TextLayer/TextPart JSON serialization

Adding fill to TextLayer and TextPart caused "fill": null to appear in
all serialized text layers, breaking existing snapshot tests. Fix by
adding a model_serializer to both classes that omits the fill key when
it is None. JSON round-trips still work because fill defaults to None
when the key is absent.

Also reverts the snapshot changes in test_canvas.py and test_text_layers.py
that were patching around the serialization noise.

https://claude.ai/code/session_01QK5iq4VqPsjWK8R9zJp1cg

* Revert "fix: exclude fill=None from TextLayer/TextPart JSON serialization"

This reverts commit 1300bf4.

* test: replace test_text_fill with rendering snapshots and validation tests

- Delete tests/test_text_fill.py (model/rendering smoke tests that were
  too trivial to be worth maintaining separately)
- Add 7 snapshot tests to test_rendering.py covering: linear gradient fill,
  radial gradient fill, image fill (TextFillImage), fill + stroke, fill +
  letter spacing, multiline block fill, and rich text per-part fill
- Add TestTextFill class to test_text_layers.py with 8 validation and
  serialization tests: JSON serialization for all 3 fill types, null fill
  serialization, JSON round-trip, TextPart fill serialization, and
  FileNotFoundError for missing TextFillImage paths (layer-level and part-level)

https://claude.ai/code/session_01QK5iq4VqPsjWK8R9zJp1cg

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sjquant

quickthumb/__init__.py

@@ -18,6 +18,7 @@
     ShapeLayer,
     Stroke,
     TextEffect,
+    TextFillImage,
     TextLayer,
     TextPart,
 )
@@ -44,6 +45,7 @@
     "ShapeLayer",
     "Stroke",
     "TextEffect",
+    "TextFillImage",
     "TextLayer",
     "TextPart",
 ]

quickthumb/canvas.py

@@ -173,6 +173,17 @@ class RadialGradient(QuickThumbModel):
     center: tuple[float, float] = (0.5, 0.5)
 
 
+class TextFillImage(QuickThumbModel):
+    type: Literal["image"] = "image"
+    path: str
+    fit: Annotated[
+        FitMode, AfterValidator(lambda v: enum_converter(FitMode)(v) if v else FitMode.COVER)
+    ] = FitMode.COVER
+
+
+TextFill = Annotated[LinearGradient | RadialGradient | TextFillImage, Discriminator("type")]
+
+
 class Stroke(QuickThumbModel):
     type: Literal["stroke"] = "stroke"
     width: PositiveInt
@@ -262,6 +273,7 @@ def validate_saturation(cls, v: float) -> float:
 class TextPart(QuickThumbModel):
     text: str
     color: HexColor | None = None
+    fill: TextFill | None = None
     effects: list[TextEffect] = []
     size: PositiveInt | None = None
     bold: bool | None = None
@@ -318,6 +330,7 @@ class TextLayer(QuickThumbModel):
     font: str | None = None
     size: PositiveInt | None = None
     color: HexColor | None = None
+    fill: TextFill | None = None
     position: tuple | None = None
     align: AlignWithHVTuple = None
     bold: bool = False