quickthumb 0.3.1__tar.gz → 0.5.0__tar.gz

quickthumb-0.5.0/.claude/skills/next-task/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: next-task
+description: Read TASKS.md and begin working on the next TODO task in order.
+disable-model-invocation: true
+---
+
+Read @specs/TASKS.md and begin working on the next [TODO] task.
+
+- TODO → DOING when starting
+- Continue to the next task if the total is < 200 lines. Set to [REVIEW] once finished.
+- If code changes exceed ~200 lines: stop and set status to [REVIEW]
+- Wait for user confirmation
+- After confirmation: set status to [DONE] **before** committing or pushing
+
+Do not reorder tasks. Only update the status.

{quickthumb-0.3.1 → quickthumb-0.5.0}/.claude/skills/tdd/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: tdd
-description: Implement features or fix bugs using the TDD cycle. Use when you're about to add a new feature or fix a bug—start here before writing implementation code.
-disable-model-invocation: true
+description: Follow the TDD cycle. Use this before writing any implementation code, whether fixing a bug, adding a feature, or making any code change.
 ---
 
 ## Workflow

{quickthumb-0.3.1 → quickthumb-0.5.0}/.github/workflows/docs.yml

@@ -4,6 +4,10 @@ on:
   push:
     tags:
       - "v*.*.*"
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
   workflow_dispatch:
 
 permissions:

{quickthumb-0.3.1 → quickthumb-0.5.0}/.github/workflows/publish.yaml

@@ -23,7 +23,7 @@ jobs:
 
       - name: Test
         run: |
-          uv run pytest tests/ --ignore=tests/test_rendering.py
+          uv run --extra cli pytest tests/ --ignore=tests/test_rendering.py
 
       - name: Determine Version Change
         id: version_check

{quickthumb-0.3.1 → quickthumb-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickthumb
-Version: 0.3.1
+Version: 0.5.0
 Summary: Programmatic thumbnail and social image generation with layered Python and JSON APIs
 Project-URL: Homepage, https://github.com/sjquant/quickthumb
 Project-URL: Repository, https://github.com/sjquant/quickthumb
@@ -24,14 +24,17 @@ Requires-Python: >=3.10
 Requires-Dist: pillow<11.0.0,>=10.4.0
 Requires-Dist: pydantic<3.0.0,>=2.12.5
 Requires-Dist: typing-extensions<5.0.0,>=4.15.0
+Provides-Extra: cli
+Requires-Dist: typer<1.0,>=0.24.1; extra == 'cli'
+Requires-Dist: watchfiles<2.0.0,>=1.0.0; extra == 'cli'
 Provides-Extra: rembg
 Requires-Dist: onnxruntime<2.0.0,>=1.24.1; extra == 'rembg'
 Requires-Dist: rembg<3.0.0,>=2.0.50; extra == 'rembg'
 Description-Content-Type: text/markdown
 
-# QuickThumb
+# quickthumb
 
-QuickThumb is a Python library for programmatic thumbnail, social card, and promo image generation.
+quickthumb is a Python library for programmatic thumbnail, social card, and promo image generation.
 It is designed for code-first and JSON-first workflows, with a layer-based API that works well for human-authored scripts and AI-generated specs.
 
 ## Gallery
@@ -44,7 +47,7 @@ It is designed for code-first and JSON-first workflows, with a layer-based API t
 | --- | --- | --- |
 | ![Talking head thumbnail example](examples/youtube_talking_head.png) | ![Reaction thumbnail example](examples/youtube_reaction.png) | ![Tutorial thumbnail example](examples/youtube_tutorial_explainer.png) |
 
-## Why QuickThumb
+## Why quickthumb
 
 - Built for thumbnails and social graphics, not just generic image composition
 - Works with Python method chaining and JSON serialization/deserialization
@@ -156,6 +159,56 @@ canvas = Canvas(1280, 720).text(
 )
 ```
 
+### Gradient and image-filled text
+
+Fill text with a gradient or image instead of a flat color. Works on the whole text layer or per `TextPart`.
+
+```python
+from quickthumb import Canvas, LinearGradient, RadialGradient, TextFillImage, TextPart
+
+# Gradient headline
+canvas = Canvas(1280, 720).text(
+    content="GRADIENT TITLE",
+    size=120,
+    fill=LinearGradient(
+        angle=90,
+        stops=[("#FF6B6B", 0.0), ("#FFE66D", 0.5), ("#4ECDC4", 1.0)],
+    ),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Image-filled text
+canvas = Canvas(1280, 720).text(
+    content="TEXTURE",
+    size=140,
+    fill=TextFillImage(path="fire_texture.jpg", fit="cover"),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Per-segment fills using TextPart
+canvas = Canvas(1280, 720).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` accepts `LinearGradient`, `RadialGradient`, or `TextFillImage`. It is mutually independent of `color` — when `fill` is set it takes visual precedence. A `fill` on a `TextPart` overrides the layer-level `fill` for that segment only.
+
 ### Image layers
 
 ```python
@@ -194,6 +247,42 @@ canvas = Canvas(1280, 720).shape(
 )
 ```
 
+### Grain / noise effect
+
+Add film-grain noise to background or image layers via `effects=[Grain(...)]`.
+
+```python
+from quickthumb import Canvas, Grain
+
+canvas = (
+    Canvas(1280, 720)
+    .background(
+        color="#1A1A2E",
+        effects=[Grain(intensity=0.12, monochrome=True)],
+    )
+    .image(
+        path="portrait.png",
+        position=("70%", "50%"),
+        width=400,
+        height=500,
+        align=("center", "middle"),
+        effects=[Grain(intensity=0.08, monochrome=False, blend_mode="overlay", opacity=0.6)],
+    )
+)
+```
+
+`Grain` parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intensity` | `float` | required | Noise amplitude, `0.0`–`1.0` |
+| `monochrome` | `bool` | `True` | `True` = luminance noise; `False` = per-channel color noise |
+| `blend_mode` | `str` | `"overlay"` | `"overlay"`, `"screen"`, `"multiply"`, or `"normal"` |
+| `opacity` | `float` | `1.0` | Overall grain strength, `0.0`–`1.0` |
+| `seed` | `int \| None` | `None` | Optional RNG seed for deterministic output |
+
+`Grain` is valid in `effects` on **background** and **image** layers. It is serialized with `"type": "grain"` in JSON.
+
 ### Export helpers
 
 ```python
@@ -204,7 +293,7 @@ canvas.render("output.webp", format="WEBP", quality=90)
 
 ## JSON-First Workflow
 
-QuickThumb can round-trip most canvases through JSON:
+quickthumb can round-trip most canvases through JSON:
 
 ```python
 from quickthumb import Canvas
@@ -220,7 +309,7 @@ config = """
     },
     {
       "type": "text",
-      "content": "Hello QuickThumb",
+      "content": "Hello quickthumb",
       "size": 72,
       "color": "#FFFFFF",
       "align": "center",
@@ -244,17 +333,17 @@ serialized = canvas.to_json()
 Notes:
 
 - JSON uses top-level `width`, `height`, and `layers`
-- Custom layers added with `canvas.custom(fn)` are not JSON-serializable
+- Named custom layers added with `canvas.custom(fn, name="...", kwargs={...})` are JSON-serializable via the registry; unnamed custom layers are not
 - Enum-like values such as `blend_mode`, `fit`, and `align` can be passed as strings
 
 ## AI-Friendly Workflows
 
-QuickThumb is a good target when you want an LLM to generate image specs that are deterministic and easy to validate.
+quickthumb is a good target when you want an LLM to generate image specs that are deterministic and easy to validate.
 
 Prompt pattern for Python generation:
 
 ```text
-Generate QuickThumb Python code for a 1280x720 YouTube thumbnail.
+Generate quickthumb Python code for a 1280x720 YouTube thumbnail.
 Use layered composition only.
 Keep text on the left, subject image on the right, and use high-contrast typography.
 Return runnable code that ends with canvas.render("thumbnail.png").
@@ -263,20 +352,20 @@ Return runnable code that ends with canvas.render("thumbnail.png").
 Prompt pattern for JSON generation:
 
 ```text
-Generate a QuickThumb JSON config with top-level width, height, and layers.
+Generate a quickthumb JSON config with top-level width, height, and layers.
 Use one background image layer, one dark overlay background layer, two text layers, and one outline layer.
-Only use valid QuickThumb layer types and effect names.
+Only use valid quickthumb layer types and effect names.
 ```
 
 Recommended workflow:
 
-1. Have the model produce QuickThumb Python or JSON.
+1. Have the model produce quickthumb Python or JSON.
 2. Validate or render it locally.
 3. Adjust only the content, colors, and assets instead of rewriting layout logic from scratch.
 
 ## Environment Variables
 
-QuickThumb looks for fonts using these environment variables:
+quickthumb looks for fonts using these environment variables:
 
 - `QUICKTHUMB_FONT_DIR`: directory that contains font files
 - `QUICKTHUMB_DEFAULT_FONT`: default font family/name to use when `font` is omitted
@@ -299,13 +388,15 @@ os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
 | Background controls | Opacity, blend modes, fit modes, blur, brightness, contrast, saturation |
 | Text | Positioning, alignment, wrapping, letter spacing, line height, rotation, auto-scale |
 | Rich text | Per-segment `TextPart` styling |
+| Text fills | Gradient (`LinearGradient`, `RadialGradient`) and image (`TextFillImage`) fills; per-`TextPart` override |
 | Text effects | Stroke, shadow, glow, background fill |
 | Fonts | Local fonts, CSS-style weights, italic/bold flags, webfont URLs, fallback mapping |
 | Images | Local/remote images, sizing, fit modes, alignment, opacity, rotation |
 | Image effects | Stroke, shadow, glow, filter effects, border radius, background removal |
+| Grain / noise | Per-layer `Grain` effect on background and image layers; monochrome or color noise |
 | Shapes | Rectangle and ellipse primitives with stroke/shadow/glow support |
 | Export | PNG, JPEG, WebP, file output, base64, data URLs |
-| Serialization | `to_json()` / `from_json()` for built-in layer types |
+| Serialization | `to_json()` / `from_json()` for built-in layer types and named custom layers |
 
 ## Real Example Scripts
 
@@ -320,7 +411,10 @@ See the shipped examples in [`examples/README.md`](examples/README.md):
 - `weight` and `bold=True` are mutually exclusive on text layers and `TextPart`
 - `auto_scale=True` requires `max_width`
 - `position` percentage values must be strings like `"50%"`
-- `canvas.custom(fn)` runs during render order and cannot be serialized to JSON
+- `fill` and `color` are independent fields; when `fill` is set it takes visual precedence over `color`
+- `canvas.custom(fn)` without a `name` runs during render order but cannot be serialized to JSON; pass `name=` and register the function with `Canvas.register_layer_fn()` to enable serialization
+- `Grain` is valid only on background and image layer `effects`; it is not a valid text or shape effect
+- `Grain(intensity=0.0)` is a no-op (no noise is generated or composited)
 
 ## Development
 
@@ -333,5 +427,4 @@ uv run ty quickthumb/
 
 ## Reference
 
-- Design notes: [DESIGN.md](DESIGN.md)
 - License: [LICENSE](LICENSE)

{quickthumb-0.3.1 → quickthumb-0.5.0}/README.md

@@ -1,6 +1,6 @@
-# QuickThumb
+# quickthumb
 
-QuickThumb is a Python library for programmatic thumbnail, social card, and promo image generation.
+quickthumb is a Python library for programmatic thumbnail, social card, and promo image generation.
 It is designed for code-first and JSON-first workflows, with a layer-based API that works well for human-authored scripts and AI-generated specs.
 
 ## Gallery
@@ -13,7 +13,7 @@ It is designed for code-first and JSON-first workflows, with a layer-based API t
 | --- | --- | --- |
 | ![Talking head thumbnail example](examples/youtube_talking_head.png) | ![Reaction thumbnail example](examples/youtube_reaction.png) | ![Tutorial thumbnail example](examples/youtube_tutorial_explainer.png) |
 
-## Why QuickThumb
+## Why quickthumb
 
 - Built for thumbnails and social graphics, not just generic image composition
 - Works with Python method chaining and JSON serialization/deserialization
@@ -125,6 +125,56 @@ canvas = Canvas(1280, 720).text(
 )
 ```
 
+### Gradient and image-filled text
+
+Fill text with a gradient or image instead of a flat color. Works on the whole text layer or per `TextPart`.
+
+```python
+from quickthumb import Canvas, LinearGradient, RadialGradient, TextFillImage, TextPart
+
+# Gradient headline
+canvas = Canvas(1280, 720).text(
+    content="GRADIENT TITLE",
+    size=120,
+    fill=LinearGradient(
+        angle=90,
+        stops=[("#FF6B6B", 0.0), ("#FFE66D", 0.5), ("#4ECDC4", 1.0)],
+    ),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Image-filled text
+canvas = Canvas(1280, 720).text(
+    content="TEXTURE",
+    size=140,
+    fill=TextFillImage(path="fire_texture.jpg", fit="cover"),
+    position=("50%", "50%"),
+    align="center",
+)
+
+# Per-segment fills using TextPart
+canvas = Canvas(1280, 720).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` accepts `LinearGradient`, `RadialGradient`, or `TextFillImage`. It is mutually independent of `color` — when `fill` is set it takes visual precedence. A `fill` on a `TextPart` overrides the layer-level `fill` for that segment only.
+
 ### Image layers
 
 ```python
@@ -163,6 +213,42 @@ canvas = Canvas(1280, 720).shape(
 )
 ```
 
+### Grain / noise effect
+
+Add film-grain noise to background or image layers via `effects=[Grain(...)]`.
+
+```python
+from quickthumb import Canvas, Grain
+
+canvas = (
+    Canvas(1280, 720)
+    .background(
+        color="#1A1A2E",
+        effects=[Grain(intensity=0.12, monochrome=True)],
+    )
+    .image(
+        path="portrait.png",
+        position=("70%", "50%"),
+        width=400,
+        height=500,
+        align=("center", "middle"),
+        effects=[Grain(intensity=0.08, monochrome=False, blend_mode="overlay", opacity=0.6)],
+    )
+)
+```
+
+`Grain` parameters:
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intensity` | `float` | required | Noise amplitude, `0.0`–`1.0` |
+| `monochrome` | `bool` | `True` | `True` = luminance noise; `False` = per-channel color noise |
+| `blend_mode` | `str` | `"overlay"` | `"overlay"`, `"screen"`, `"multiply"`, or `"normal"` |
+| `opacity` | `float` | `1.0` | Overall grain strength, `0.0`–`1.0` |
+| `seed` | `int \| None` | `None` | Optional RNG seed for deterministic output |
+
+`Grain` is valid in `effects` on **background** and **image** layers. It is serialized with `"type": "grain"` in JSON.
+
 ### Export helpers
 
 ```python
@@ -173,7 +259,7 @@ canvas.render("output.webp", format="WEBP", quality=90)
 
 ## JSON-First Workflow
 
-QuickThumb can round-trip most canvases through JSON:
+quickthumb can round-trip most canvases through JSON:
 
 ```python
 from quickthumb import Canvas
@@ -189,7 +275,7 @@ config = """
     },
     {
       "type": "text",
-      "content": "Hello QuickThumb",
+      "content": "Hello quickthumb",
       "size": 72,
       "color": "#FFFFFF",
       "align": "center",
@@ -213,17 +299,17 @@ serialized = canvas.to_json()
 Notes:
 
 - JSON uses top-level `width`, `height`, and `layers`
-- Custom layers added with `canvas.custom(fn)` are not JSON-serializable
+- Named custom layers added with `canvas.custom(fn, name="...", kwargs={...})` are JSON-serializable via the registry; unnamed custom layers are not
 - Enum-like values such as `blend_mode`, `fit`, and `align` can be passed as strings
 
 ## AI-Friendly Workflows
 
-QuickThumb is a good target when you want an LLM to generate image specs that are deterministic and easy to validate.
+quickthumb is a good target when you want an LLM to generate image specs that are deterministic and easy to validate.
 
 Prompt pattern for Python generation:
 
 ```text
-Generate QuickThumb Python code for a 1280x720 YouTube thumbnail.
+Generate quickthumb Python code for a 1280x720 YouTube thumbnail.
 Use layered composition only.
 Keep text on the left, subject image on the right, and use high-contrast typography.
 Return runnable code that ends with canvas.render("thumbnail.png").
@@ -232,20 +318,20 @@ Return runnable code that ends with canvas.render("thumbnail.png").
 Prompt pattern for JSON generation:
 
 ```text
-Generate a QuickThumb JSON config with top-level width, height, and layers.
+Generate a quickthumb JSON config with top-level width, height, and layers.
 Use one background image layer, one dark overlay background layer, two text layers, and one outline layer.
-Only use valid QuickThumb layer types and effect names.
+Only use valid quickthumb layer types and effect names.
 ```
 
 Recommended workflow:
 
-1. Have the model produce QuickThumb Python or JSON.
+1. Have the model produce quickthumb Python or JSON.
 2. Validate or render it locally.
 3. Adjust only the content, colors, and assets instead of rewriting layout logic from scratch.
 
 ## Environment Variables
 
-QuickThumb looks for fonts using these environment variables:
+quickthumb looks for fonts using these environment variables:
 
 - `QUICKTHUMB_FONT_DIR`: directory that contains font files
 - `QUICKTHUMB_DEFAULT_FONT`: default font family/name to use when `font` is omitted
@@ -268,13 +354,15 @@ os.environ["QUICKTHUMB_DEFAULT_FONT"] = "Roboto"
 | Background controls | Opacity, blend modes, fit modes, blur, brightness, contrast, saturation |
 | Text | Positioning, alignment, wrapping, letter spacing, line height, rotation, auto-scale |
 | Rich text | Per-segment `TextPart` styling |
+| Text fills | Gradient (`LinearGradient`, `RadialGradient`) and image (`TextFillImage`) fills; per-`TextPart` override |
 | Text effects | Stroke, shadow, glow, background fill |
 | Fonts | Local fonts, CSS-style weights, italic/bold flags, webfont URLs, fallback mapping |
 | Images | Local/remote images, sizing, fit modes, alignment, opacity, rotation |
 | Image effects | Stroke, shadow, glow, filter effects, border radius, background removal |
+| Grain / noise | Per-layer `Grain` effect on background and image layers; monochrome or color noise |
 | Shapes | Rectangle and ellipse primitives with stroke/shadow/glow support |
 | Export | PNG, JPEG, WebP, file output, base64, data URLs |
-| Serialization | `to_json()` / `from_json()` for built-in layer types |
+| Serialization | `to_json()` / `from_json()` for built-in layer types and named custom layers |
 
 ## Real Example Scripts
 
@@ -289,7 +377,10 @@ See the shipped examples in [`examples/README.md`](examples/README.md):
 - `weight` and `bold=True` are mutually exclusive on text layers and `TextPart`
 - `auto_scale=True` requires `max_width`
 - `position` percentage values must be strings like `"50%"`
-- `canvas.custom(fn)` runs during render order and cannot be serialized to JSON
+- `fill` and `color` are independent fields; when `fill` is set it takes visual precedence over `color`
+- `canvas.custom(fn)` without a `name` runs during render order but cannot be serialized to JSON; pass `name=` and register the function with `Canvas.register_layer_fn()` to enable serialization
+- `Grain` is valid only on background and image layer `effects`; it is not a valid text or shape effect
+- `Grain(intensity=0.0)` is a no-op (no noise is generated or composited)
 
 ## Development
 
@@ -302,5 +393,4 @@ uv run ty quickthumb/
 
 ## Reference
 
-- Design notes: [DESIGN.md](DESIGN.md)
 - License: [LICENSE](LICENSE)

{quickthumb-0.3.1 → quickthumb-0.5.0}/docs/api/background.md

@@ -1,3 +1,7 @@
+---
+description: Reference for quickthumb background layers, including colors, gradients, images, opacity, effects, and render order.
+---
+
 # Background
 
 `.background()` adds a full-canvas background layer. Multiple background calls stack in render order — first call is backmost.
@@ -26,7 +30,7 @@ canvas.background(
 | `opacity` | `float` | `1.0` | Layer opacity from `0.0` (transparent) to `1.0` (opaque). |
 | `blend_mode` | `str \| BlendMode \| None` | `None` | How this layer composites over previous layers. See [BlendMode](enums.md#blendmode). |
 | `fit` | `str \| FitMode \| None` | `None` | How an image fills the canvas. See [FitMode](enums.md#fitmode). |
-| `effects` | `list[Filter] \| None` | `[]` | Background effects. Currently only `Filter` is supported. |
+| `effects` | `list \| None` | `[]` | Background effects. Accepts `Filter` and `Grain`. |
 
 ## Examples
 
@@ -75,4 +79,4 @@ canvas.background(color="#000000", opacity=0.4)
 - `color`, `gradient`, and `image` can each be used independently or together within one layer.
 - `blend_mode` applies when compositing this layer over previous layers.
 - Supports both local file paths and remote URLs for `image`.
-- For available effects, see [Filter](effects.md#filter).
+- For available effects, see [Filter](effects.md#filter) and [Grain](effects.md#grain).

{quickthumb-0.3.1 → quickthumb-0.5.0}/docs/api/canvas.md

@@ -1,3 +1,7 @@
+---
+description: Reference for quickthumb Canvas creation, aspect ratios, layer composition, rendering, JSON loading, and image output.
+---
+
 # Canvas
 
 The `Canvas` is the root object. It holds dimensions and an ordered list of layers.

{quickthumb-0.3.1 → quickthumb-0.5.0}/docs/api/effects.md

@@ -1,3 +1,7 @@
+---
+description: Reference for quickthumb effects, including filters, shadows, strokes, blend modes, opacity, and layer compatibility.
+---
+
 # Effects
 
 Effects are modifiers applied to layers. Each layer type accepts a specific set.
@@ -9,6 +13,7 @@ Effects are modifiers applied to layers. Each layer type accepts a specific set.
 | `Glow` | ✓ | ✓ | ✓ | — |
 | `Filter` | — | ✓ | — | ✓ |
 | `Background` | ✓ | — | — | — |
+| `Grain` | — | ✓ | — | ✓ |
 
 Pass effects as a list to the `effects` parameter of any layer:
 
@@ -193,3 +198,50 @@ canvas.text(
 
 !!! note
     `Background` as an effect is separate from the `.background()` layer builder. The effect applies behind a text block; the layer covers the full canvas.
+
+---
+
+## Grain
+
+Adds film-grain noise to a background or image layer.
+
+```python
+from quickthumb import Grain
+
+Grain(intensity=0.12, monochrome=True, blend_mode="overlay", opacity=1.0)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `intensity` | `float` | **required** | Noise amplitude from `0.0` (none) to `1.0` (maximum). |
+| `monochrome` | `bool` | `True` | `True` = luminance noise (grey grain); `False` = independent per-channel color noise. |
+| `blend_mode` | `str` | `"overlay"` | How noise composites onto the layer. One of `"overlay"`, `"screen"`, `"multiply"`, `"normal"`. |
+| `opacity` | `float` | `1.0` | Overall grain strength from `0.0` (invisible) to `1.0` (full). |
+| `seed` | `int \| None` | `None` | RNG seed for deterministic output. `None` = random each render. |
+
+`intensity=0.0` is a no-op — no noise is generated.
+
+### Example
+
+```python
+from quickthumb import Canvas, Grain
+
+canvas = (
+    Canvas(1280, 720)
+    .background(
+        color="#1A1A2E",
+        effects=[Grain(intensity=0.12, monochrome=True)],
+    )
+    .image(
+        path="portrait.png",
+        position=("70%", "50%"),
+        width=400,
+        height=500,
+        align=("center", "middle"),
+        effects=[Grain(intensity=0.08, monochrome=False, blend_mode="overlay", opacity=0.6)],
+    )
+)
+```
+
+!!! note
+    `Grain` is valid only on **background** and **image** layers. It is not available on text or shape layers.