scverse · timtreis · May 27, 2026 · May 21, 2026 · May 27, 2026 · May 27, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,14 @@ pre-commit install
 5. Add the notebook to the appropriate `index.md` so it appears in the gallery
  toctree.
 
-6. Open a PR. CI will:
+6. Place the gallery thumbnail and any other media (GIFs, screenshots, static
+ PNGs referenced from the notebook) under `_static/img/`. Reference them from
+ `index.md` and notebook markdown cells with relative paths
+ (e.g. `:img-top: ../_static/img/<slug>.png` from inside `examples/` or
+ `tutorials/`, and `![…](../_static/img/<slug>.gif)` from a notebook cell).
+ Do **not** drop assets next to the notebook itself.
+
+7. Open a PR. CI will:
  - Lint structure and code (`lint.yaml`).
  - Re-execute the notebook against the latest `spatialdata-plot` release
  and diff outputs (`execute.yaml`).

diff --git a/tutorials/color_and_palette.png → _static/img/color_and_palette.png b/tutorials/color_and_palette.png → _static/img/color_and_palette.png
diff --git a/tutorials/getting_started.png → _static/img/getting_started.png b/tutorials/getting_started.png → _static/img/getting_started.png
diff --git a/_static/img/interactive_annotate.gif b/_static/img/interactive_annotate.gif
diff --git a/_static/img/interactive_annotate.png b/_static/img/interactive_annotate.png
diff --git a/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png b/examples/visium_mouse_brain.png → _static/img/visium_mouse_brain.png
diff --git a/examples/index.md b/examples/index.md
@@ -1,24 +1,34 @@
 # Examples
 
-Worked examples on real datasets you'd actually analyse.
+Examples from real datasets you'd actually analyse.
 
 ::::{grid} 1 2 2 2
 :gutter: 3
 
 :::{grid-item-card} Visium mouse brain
 :link: visium_mouse_brain
 :link-type: doc
-:img-top: visium_mouse_brain.png
+:img-top: ../_static/img/visium_mouse_brain.png
 
 Render H&E tissue, overlay spots, color by gene expression and by cluster,
 and finish with a publication-style figure.
 :::
 
+:::{grid-item-card} Interactive region annotation
+:link: interactive_annotate
+:link-type: doc
+:img-top: ../_static/img/interactive_annotate.png
+
+Draw regions of interest directly on a `spatialdata-plot` canvas with
+`sdata.pl.annotate(...)` and persist them as a `ShapesModel` element.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 visium_mouse_brain
+interactive_annotate
 ```
diff --git a/examples/interactive_annotate.ipynb b/examples/interactive_annotate.ipynb
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
- "spatialdata-plot>=0.3.4",
+ "spatialdata-plot[interactive]>=0.4.0",
  "squidpy",
  "jupyter",
  "ipykernel",
@@ -40,22 +40,25 @@ bypass-selection = true
 # kernel-install`; the kernel will point at the pixi env's Python, so
 # `pixi run lab` (or any external Jupyter) can execute the notebooks
 # against the exact pinned dependencies.
-[tool.pixi]
-workspace.channels = ["conda-forge"]
-workspace.platforms = ["linux-64", "osx-arm64"]
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
 
-dependencies.python = ">=3.11"
-dependencies.jupyterlab = "*"
-dependencies.ipykernel = "*"
-dependencies.nbconvert = "*"
-dependencies.watermark = "*"
+[tool.pixi.dependencies]
+python = ">=3.11"
+jupyterlab = "*"
+ipykernel = "*"
+nbconvert = "*"
+watermark = "*"
 
-pypi-dependencies.spatialdata-plot = ">=0.3"
-pypi-dependencies.squidpy = "*"
+[tool.pixi.pypi-dependencies]
+spatialdata-plot = { version = ">=0.4.0", extras = ["interactive"] }
+squidpy = "*"
 
-tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
-tasks.lab = "jupyter lab"
-tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+[tool.pixi.tasks]
+kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+lab = "jupyter lab"
+execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
 
 [tool.ruff]
 line-length = 120

diff --git a/tutorials/index.md b/tutorials/index.md
@@ -8,7 +8,7 @@ Entry-point material for learning the API on synthetic data.
 :::{grid-item-card} Getting started
 :link: getting_started
 :link-type: doc
-:img-top: getting_started.png
+:img-top: ../_static/img/getting_started.png
 
 The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
@@ -17,7 +17,7 @@ dataset. Ideal first read.
 :::{grid-item-card} Colour and palettes
 :link: color_and_palette
 :link-type: doc
-:img-top: color_and_palette.png
+:img-top: ../_static/img/color_and_palette.png
 
 How `color=` resolves, the v0.3.0 `groups` behaviour, and building
 perceptually well-spaced or colourblind-safe palettes with