docs: update API reference and JSON schema for gradient/image-filled text

- docs/api/text.md: add `fill` parameter to signature and params table,
  add `fill` to TextPart table, add "Gradient and image fills" examples
  section, add fill validation rules
- docs/api/enums.md: add TextFillImage reference with params and examples
- docs/api/index.md: add TextFillImage to public imports and pages table
- docs/json-schema.md: add gradient-filled and image-filled text JSON
  examples with discriminator values documented

https://claude.ai/code/session_01QK5iq4VqPsjWK8R9zJp1cg

Author: claude

docs/api/enums.md

@@ -192,3 +192,52 @@ canvas.background(
     ),
 )
 ```
+
+---
+
+## TextFillImage
+
+An image used as a fill for text glyphs. The image is scaled to the text bounding box and masked to the glyph shapes.
+
+```python
+from quickthumb import TextFillImage
+
+TextFillImage(
+    path="fire_texture.jpg",
+    fit="cover",
+)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `path` | `str` | **required** | Local file path or remote URL for the fill image. |
+| `fit` | `str \| FitMode` | `"cover"` | How the image is scaled to the text bounding box. `"cover"`, `"contain"`, or `"fill"`. |
+
+### Examples
+
+```python
+from quickthumb import Canvas, TextFillImage
+
+# Local file
+canvas.text(
+    content="FIRE",
+    size=140,
+    fill=TextFillImage(path="assets/fire_texture.jpg", fit="cover"),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Remote URL
+canvas.text(
+    content="MARBLE",
+    size=140,
+    fill=TextFillImage(
+        path="https://example.com/textures/marble.jpg",
+        fit="cover",
+    ),
+    position=("50%", "50%"),
+    align="center",
+)
+```
+
+Pass `TextFillImage` to the `fill` parameter of `.text()` or `TextPart`. See [Gradient and image fills](text.md#gradient-and-image-fills) for usage in context.

docs/api/index.md

@@ -17,6 +17,7 @@ from quickthumb import (
     RadialGradient,
     Shadow,
     Stroke,
+    TextFillImage,
     TextPart,
     ValidationError,
 )
@@ -33,7 +34,7 @@ from quickthumb import (
 | [Shape](shape.md) | `.shape()` — rectangles and ellipses |
 | [Outline](outline.md) | `.outline()` — canvas border |
 | [Effects](effects.md) | `Stroke`, `Shadow`, `Glow`, `Filter`, `Background` |
-| [Enums & Gradients](enums.md) | `Align`, `BlendMode`, `FitMode`, `LinearGradient`, `RadialGradient` |
+| [Enums & Gradients](enums.md) | `Align`, `BlendMode`, `FitMode`, `LinearGradient`, `RadialGradient`, `TextFillImage` |
 
 ## Error types
 

docs/api/text.md

@@ -10,6 +10,7 @@ canvas.text(
     font=None,
     size=None,
     color=None,
+    fill=None,
     position=None,
     align=None,
     bold=False,
@@ -33,6 +34,7 @@ canvas.text(
 | `font` | `str \| None` | `None` | Font family name, local file path, or remote webfont URL. |
 | `size` | `int \| None` | `None` | Font size in pixels. Must be a positive integer. |
 | `color` | `str \| None` | `None` | Default text color. Hex string (`"#RRGGBB"` or `"#RRGGBBAA"`). |
+| `fill` | `LinearGradient \| RadialGradient \| TextFillImage \| None` | `None` | Gradient or image fill applied to the text glyphs. Takes visual precedence over `color` when set. See [Gradient and image fills](#gradient-and-image-fills). |
 | `position` | `tuple \| None` | `None` | `(x, y)` position. Values can be integers (px) or percentage strings (`"50%"`). |
 | `align` | `str \| Align \| tuple \| None` | `None` | Alignment of the text block. See [Align values](#align-values). |
 | `bold` | `bool` | `False` | Bold flag. Mutually exclusive with `weight`. |
@@ -151,6 +153,53 @@ canvas.text(
 !!! note "Webfont URLs"
     When `font` is a URL, `bold`, `italic`, and `weight` are ignored — the URL already points to a specific variant. Download separate URLs for bold/italic versions.
 
+### Gradient and image fills
+
+Fill text glyphs with a gradient or image instead of a flat color. Pass a `LinearGradient`, `RadialGradient`, or `TextFillImage` to `fill`.
+
+```python
+from quickthumb import Canvas, LinearGradient, RadialGradient, TextFillImage, TextPart
+
+# Linear gradient headline
+canvas.text(
+    content="GRADIENT",
+    size=120,
+    fill=LinearGradient(angle=90, stops=[("#FF6B6B", 0.0), ("#4ECDC4", 1.0)]),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Image-filled text
+canvas.text(
+    content="TEXTURE",
+    size=140,
+    fill=TextFillImage(path="fire_texture.jpg", fit="cover"),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Per-segment fills using TextPart
+canvas.text(
+    content=[
+        TextPart(
+            text="HOT ",
+            fill=LinearGradient(angle=45, stops=[("#FF4500", 0.0), ("#FFD700", 1.0)]),
+            weight=900,
+        ),
+        TextPart(
+            text="COLD",
+            fill=LinearGradient(angle=45, stops=[("#00BFFF", 0.0), ("#8A2BE2", 1.0)]),
+            weight=900,
+        ),
+    ],
+    size=110,
+    position=("50%", "50%"),
+    align="center",
+)
+```
+
+`fill` on a `TextPart` overrides the layer-level `fill` for that segment only. `fill` and `color` are independent; when `fill` is set it takes visual precedence. See [TextFillImage](enums.md#textfillimage) for image fill options.
+
 ## TextPart
 
 `TextPart` enables per-segment styling within a text layer.
@@ -161,6 +210,7 @@ from quickthumb import Stroke, TextPart
 TextPart(
     text="HOT",
     color="#FF3B30",
+    fill=None,
     size=56,
     font="Impact",
     weight=900,
@@ -175,6 +225,7 @@ TextPart(
 | --- | --- | --- | --- |
 | `text` | `str` | **required** | The text segment. Cannot be empty. |
 | `color` | `str \| None` | `None` | Hex color override for this segment. |
+| `fill` | `LinearGradient \| RadialGradient \| TextFillImage \| None` | `None` | Gradient or image fill for this segment. Overrides the layer-level `fill` for this segment only. |
 | `size` | `int \| None` | `None` | Font size override for this segment. |
 | `font` | `str \| None` | `None` | Font override for this segment. |
 | `bold` | `bool \| None` | `None` | Bold override. Mutually exclusive with `weight`. |
@@ -192,3 +243,5 @@ TextPart(
 - `auto_scale=True` requires `max_width` to also be set.
 - `max_width` must be a positive integer or a positive percentage string like `"60%"`.
 - Percentage strings in `position` must match the pattern `-?N%` (negative percentages are valid).
+- `fill` and `color` are independent fields; `fill` takes visual precedence when both are set.
+- `TextFillImage.path` supports local file paths and remote URLs; missing local files raise `FileNotFoundError` at render time.

docs/json-schema.md

@@ -132,6 +132,44 @@ Only include the fields you need — unspecified fields use their defaults.
 }
 ```
 
+**Gradient-filled text:**
+
+```json
+{
+  "type": "text",
+  "content": "GRADIENT",
+  "size": 120,
+  "fill": {
+    "type": "linear_gradient",
+    "angle": 90,
+    "stops": [["#FF6B6B", 0.0], ["#4ECDC4", 1.0]]
+  },
+  "position": ["50%", "50%"],
+  "align": "center",
+  "effects": []
+}
+```
+
+**Image-filled text:**
+
+```json
+{
+  "type": "text",
+  "content": "TEXTURE",
+  "size": 140,
+  "fill": {
+    "type": "image",
+    "path": "fire_texture.jpg",
+    "fit": "cover"
+  },
+  "position": ["50%", "50%"],
+  "align": "center",
+  "effects": []
+}
+```
+
+`fill` discriminator values: `"linear_gradient"`, `"radial_gradient"`, `"image"`. `fill` can also be set per `TextPart` entry using the same discriminated object.
+
 **Align values:** `"center"`, `"left"`, `"right"`, `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, `"bottom-right"`
 
 ---