From 9b79eef9a2e8072531d338e1b42cfaebd99c93b9 Mon Sep 17 00:00:00 2001
From: jbloom <jbloom@fredhutch.org>
Date: Fri, 30 Oct 2026 08:17:47 -0700
Subject: [PATCH 1/4] keep selection params' views when loading a chart from a
 spec

A chart with a selection param on a compound chart (layer, facet, concat)
failed to render when passed to `plot()` as a JSON path, HTML path or dict,
i.e. on every CLI call: Vega-Lite reported `Duplicate signal name:
"<selection>_tuple"`. `_load_chart` deleted `views` from every param before
`alt.Chart.from_dict`. When `_build` then nests the chart, altair keeps a
compound sub-chart's existing `views`, so the stripped params came out as
`views: []`, and Vega-Lite defines such a selection in every view. Live
charts never went through the strip, which is why the docs assets and
downstream Python users (e.g. flu-seqneut-2026) never hit it.

Why the strip existed: phase 2b (0812a7b) found that nesting a chart's
*dict* inside a dict-level concat fails validation with "'views' was
unexpected". `views` is only valid on top-level selection params, and nested
params are validated against the nested schema. Phase 2b avoided dict
round-trips altogether. Phase 2c (ded7beb) reused that note verbatim for the
new loader and stripped `views` before a *top-level* `from_dict`, where they
are valid. Reproducing it with the period chart JSON and the altair installed
then (6.1.0):
- top-level `from_dict` accepts `views`;
- only the dict-nesting approach rejects them;
- stripping doesn't rescue that approach either ("'select' is a required
  property").
The docstring's "the renderer rebinds params to views on its own" is not
true for an emptied list. No test rendered JSON-path output, and the phase 2c
and current suites both pass unchanged with the strip disabled.

Removing it is safe on every supported altair. On 6.0.0, 6.1.0, 6.2.2 and
6.3.0:
- with the strip, only unit charts (2 of 12 shape x tree-side cases) render;
- without it, all 12 do.
So the `altair>=6.0,<7` floor stays.

The `deepcopy` stays: `from_dict` aliases the input's `datasets` row lists.
The new regression test passes dict and JSON-path charts of each compound
shape, and checks both that every selection keeps `views` naming real views
and that vl-convert renders the result. It fails on the old loader in all 10
cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |  11 ++++
 CLAUDE.md                        |  12 +++-
 src/tree_annotated_plot/_plot.py |  35 ++++------
 tests/test_chart_loader.py       | 108 +++++++++++++++++++++++++++++++
 4 files changed, 141 insertions(+), 25 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf702ae..93d7f68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- A chart with selection parameters on a compound chart (layer, facet, or
+  concat) failed to render when passed to `plot()` as a JSON path, HTML path
+  or spec dict, which is every CLI use. Vega-Lite reported
+  `Duplicate signal name: "<selection>_tuple"`. This affected the flu examples'
+  CLI reproductions. The chart loader removed each selection's `views` before
+  loading, and altair then emitted empty `views`, which makes Vega-Lite define
+  the selection in every view. The loader now leaves the spec's `views` intact.
+  Live altair charts were never affected.
+
 ## [0.4.0] - 2026-08-20
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index f9fa2fe..632e1dd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,6 +52,13 @@
   on `x` or `y`, overrides its sort to match the tree's tip order, and
   hconcat's or vconcat's a tree panel on the matching side. Tree dictates
   tip ordering; plot follows.
+- **Loaded specs go to `from_dict` unmodified.** Don't strip or rewrite
+  altair's annotations when loading a dict / JSON / HTML chart. Selection
+  params' `views` in particular are valid at the top level; removing them made
+  every compound chart with a selection fail to render ("Duplicate signal
+  name"). See `_load_chart`. Likewise, declare extra params by appending to
+  the combined chart's top-level `params`, never with `add_params`, which
+  recurses into sub-charts and raises on spec-loaded ones.
 - **Two surfaces, one config**: `tree_annotated_plot.plot()` and the `tree-annotated-plot`
   CLI both accept the same parameters via `PlotConfig`. They converge on
   `_build(tree, chart, config)` so they can never disagree.
@@ -78,7 +85,10 @@
 - **Eyeball examples after any rendering change.** There are no
   image-snapshot regression tests (vl-convert/font/platform variance
   makes them flaky), so visual regressions only get caught by
-  looking. After any change to `_plot.py`, `_tree.py`, the example
+  looking. Tests may still render with `vl_convert.vegalite_to_svg`
+  to check that a spec renders at all, or to assert discrete SVG
+  attributes such as a label's `font-weight` / `fill`; those are
+  deterministic. After any change to `_plot.py`, `_tree.py`, the example
   scripts, or anything they touch: run `scripts/build_docs.sh`, open
   `site/examples.html`, and click through each example — both the
   embedded SVG and the interactive HTML link. Confirm tip-row
diff --git a/src/tree_annotated_plot/_plot.py b/src/tree_annotated_plot/_plot.py
index f3639e8..0432d62 100644
--- a/src/tree_annotated_plot/_plot.py
+++ b/src/tree_annotated_plot/_plot.py
@@ -390,9 +390,15 @@ def _load_chart(chart_input: ChartInput, *, strict_version: bool) -> alt.TopLeve
     A live `alt.TopLevelMixin` is returned as-is — its `$schema` is
     irrelevant since the constructing altair version is necessarily the
     running altair version. For dict / JSON path / HTML path inputs we run
-    the Vega-Lite version check (under `strict_version`), strip altair's
-    `params[].views` round-trip annotations, and then dispatch to the right
-    chart subclass via `alt.Chart.from_dict(...)`.
+    the Vega-Lite version check (under `strict_version`) and then dispatch to
+    the right chart subclass via `alt.Chart.from_dict(...)`.
+
+    The spec goes to `from_dict` unmodified. In particular, each selection
+    param's `views` must survive: when `_build` nests a compound chart (layer
+    / facet / concat), altair keeps its params' existing `views`, and an
+    emptied list makes Vega-Lite define the selection in every view, which
+    fails with "Duplicate signal name". `views` is valid on top-level params,
+    which is the only place altair emits it.
     """
     if isinstance(chart_input, alt.TopLevelMixin):
         return chart_input
@@ -420,8 +426,9 @@ def _load_chart(chart_input: ChartInput, *, strict_version: bool) -> alt.TopLeve
         )
 
     _check_chart_schema_version(spec, strict_version=strict_version)
+    # `from_dict` keeps references into the spec (e.g. the `datasets` row
+    # lists), so copy it to keep the caller's dict out of later mutation.
     spec = copy.deepcopy(spec)
-    _strip_params_views(spec)
     # `from_dict` with validate=True dispatches to the right subclass
     # (Chart / LayerChart / FacetChart / HConcatChart / VConcatChart /
     # ConcatChart) based on the spec's shape.
@@ -485,26 +492,6 @@ def _check_chart_schema_version(spec: dict, *, strict_version: bool) -> None:
         )
 
 
-def _strip_params_views(spec: Any) -> None:
-    """Recursively delete `views` from every params[] entry.
-
-    altair's `to_dict()` annotates each selection-param with the views it's
-    bound to, but altair's own `from_dict()` validation rejects the field.
-    Stripping is safe: the renderer rebinds params to views on its own.
-    """
-    if isinstance(spec, dict):
-        params = spec.get("params")
-        if isinstance(params, list):
-            for p in params:
-                if isinstance(p, dict):
-                    p.pop("views", None)
-        for v in spec.values():
-            _strip_params_views(v)
-    elif isinstance(spec, list):
-        for item in spec:
-            _strip_params_views(item)
-
-
 class _ScriptCollector(HTMLParser):
     """Collect the text content of every <script> tag in an HTML document."""
 
diff --git a/tests/test_chart_loader.py b/tests/test_chart_loader.py
index 6853614..57e3b09 100644
--- a/tests/test_chart_loader.py
+++ b/tests/test_chart_loader.py
@@ -12,11 +12,14 @@
 
 import json
 from pathlib import Path
+from typing import Any
 
 import altair as alt
 import pandas as pd
 import pytest
+import vl_convert as vlc
 
+import tree_annotated_plot
 from tree_annotated_plot import _tree
 from tree_annotated_plot._plot import (
     _extract_spec_from_html,
@@ -142,6 +145,111 @@ def test_html_extraction_takes_first_when_multiple_blocks(tmp_path: Path) -> Non
     assert extracted == {"a": 1}
 
 
+# ---------- selection params keep their `views` through spec loading ----------
+
+
+def _four_tip_auspice() -> dict:
+    return {
+        "version": "v2",
+        "meta": {},
+        "tree": {
+            "name": "ROOT",
+            "node_attrs": {"div": 0.0},
+            "children": [
+                {"name": s, "node_attrs": {"div": 0.01 * (i + 1)}}
+                for i, s in enumerate("ABCD")
+            ],
+        },
+    }
+
+
+def _selection_chart(shape: str) -> alt.TopLevelMixin:
+    """A compound chart of the given `shape` carrying a point selection."""
+    df = pd.DataFrame(
+        {
+            "strain": list("ABCD"),
+            "titer": [1.0, 2.0, 4.0, 8.0],
+            "grp": ["a", "b", "a", "b"],
+        }
+    )
+    sel = alt.selection_point(name="sel", fields=["strain"], empty=False)
+    base = (
+        alt.Chart(df).encode(y="strain:N", x="titer:Q").properties(height=alt.Step(15))
+    )
+    points = base.mark_point().add_params(sel)
+    if shape == "layer":
+        return alt.layer(points, base.mark_tick())
+    if shape == "facet":
+        return points.facet(column="grp:N")
+    if shape == "facet(layer)":
+        return alt.layer(points, base.mark_tick()).facet(column="grp:N")
+    if shape == "vconcat":
+        legend_sel = alt.selection_point(
+            name="legend_sel", fields=["grp"], bind="legend"
+        )
+        return alt.vconcat(
+            points.facet(column="grp:N"),
+            base.mark_point().encode(color="grp:N").add_params(legend_sel),
+        )
+    if shape == "hconcat":
+        return alt.hconcat(points, base.mark_tick())
+    raise ValueError(shape)
+
+
+def _unit_view_names(spec: Any) -> set[str]:
+    names: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if "mark" in node and isinstance(node.get("name"), str):
+                names.add(node["name"])
+            for k, v in node.items():
+                if k not in ("data", "datasets"):
+                    walk(v)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(spec)
+    return names
+
+
+@pytest.mark.parametrize("as_path", [False, True], ids=["dict", "json_path"])
+@pytest.mark.parametrize(
+    "shape", ["layer", "facet", "facet(layer)", "vconcat", "hconcat"]
+)
+def test_selection_params_keep_views_through_spec_loading(
+    tmp_path: Path, shape: str, as_path: bool
+) -> None:
+    """A chart loaded from a spec must keep each selection param's `views`.
+
+    The loader once stripped them, which left `views: []` on the combined
+    chart; Vega-Lite then defines the selection in every view and rendering
+    fails with "Duplicate signal name". This is the path every CLI call takes.
+    """
+    chart = _selection_chart(shape)
+    if as_path:
+        source: Any = tmp_path / "chart.json"
+        chart.save(str(source))
+    else:
+        source = chart.to_dict()
+    out = tree_annotated_plot.plot(
+        _four_tip_auspice(),
+        source,
+        chart_strain_field="strain",
+        tree_strain_field="name",
+        branch_length="div",
+    )
+    spec = out.to_dict()
+    selections = [p for p in spec.get("params", []) if "select" in p]
+    assert selections
+    view_names = _unit_view_names(spec)
+    for p in selections:
+        assert p.get("views"), f"selection {p['name']!r} lost its views"
+        assert set(p["views"]) <= view_names
+    vlc.vegalite_to_svg(spec)
+
+
 # ---------- Vega-Lite $schema version check ----------
 
 

From daf734b9598857a7756f02bef8a8b28ab47c3e9d Mon Sep 17 00:00:00 2001
From: jbloom <jbloom@fredhutch.org>
Date: Fri, 30 Oct 2026 08:25:02 -0700
Subject: [PATCH 2/4] add strain_label_styles for styling a subset of
 tree-panel labels (#12)

`strain_label_styles` is a list of rules. Each names some `strains` and a
`style` of Vega-Lite text properties (`fill`, `opacity`, `fontWeight`,
`fontStyle`). An optional `when` condition can be:
- a param name declared in the chart, e.g. a checkbox;
- any Vega expression, e.g. "emphasis == 'cell'" for a radio button;
- in Python, an `alt.Parameter`, which is declared on the returned chart if
  the chart doesn't declare it.

Where rules overlap, later rules win property by property. The rules require
`connect_leader_to_label=True`; with it off the labels are the chart's own
axis labels, and the error says so. On the CLI it's a JSON array, and `when`
names a param saved in the chart JSON.

No layers are duplicated. #12 assumed a mark-property ExprRef can't see
`datum`, but Vega-Lite compiles a mark-level `{"expr": ...}` into the Vega
encode block, where it can. So each styled property becomes one per-label
expression on the existing halo and text layers: a ternary chain over
per-rule membership columns in the label data. The halo follows the
glyph-shape properties (fontWeight / fontStyle), so it keeps masking the
leaders; `fill` and `opacity` apply to the text only. The returned chart
keeps its shape, which also covers a scale bar and any future merge of the
halo and text marks. Params are appended to the combined chart's top-level
`params`: `add_params` recurses into sub-charts and raises on spec-loaded
ones.

Validation fails fast:
- strains must be tips of the input tree, and the error shows samples from
  both sides; strains dropped by `prune_tree_to_chart` are skipped;
- unknown style keys raise, with hints for `color` and `fontSize` (the latter
  is excluded because it would change the label-strip width estimate);
- a bare `when` name must be a declared variable param; selection params are
  rejected.

Checked against flu-seqneut-2026's own `plot_titer_summaries.py` (it nests
our output in a further vconcat) under altair 6.0.0, 6.2.2 and 6.3.0:
- all 10 tree charts render with exactly the vaccine strains' labels styled;
- the checkbox param is declared once, whether `plot()` declares it or their
  `base_chart` does;
- their unstyled output is unchanged.

Also fixes the `plot()` Returns docstring: for a strain on `x` the default
`tree_location="bottom"` puts the chart first and the tree second.

Adds a docs example (H3N2 vaccine strains in bold red behind a checkbox),
`vaccine_axis_labels` in the flu example module, and
tests/test_strain_label_styles.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  24 +
 docs/examples.md                              |  71 +++
 .../flu-seqneut-2025to2026_titer_charts.py    |  11 +
 scripts/generate_docs_assets.py               |  43 ++
 src/tree_annotated_plot/_config.py            |  45 +-
 src/tree_annotated_plot/_label_style.py       | 349 +++++++++++
 src/tree_annotated_plot/_plot.py              | 109 ++--
 src/tree_annotated_plot/cli.py                |  74 ++-
 tests/test_strain_label_styles.py             | 565 ++++++++++++++++++
 9 files changed, 1236 insertions(+), 55 deletions(-)
 create mode 100644 src/tree_annotated_plot/_label_style.py
 create mode 100644 tests/test_strain_label_styles.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93d7f68..779eac2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `strain_label_styles` (default `None`): style a subset of the strain labels
+  rendered in the tree panel when `connect_leader_to_label` is on, e.g. to draw
+  the vaccine strains' labels in bold red. A list of rules, each naming some
+  `strains` and a `style` of Vega-Lite text properties (`fill`, `opacity`,
+  `fontWeight`, `fontStyle`). Where rules overlap, later rules win property by
+  property. An optional `when` condition applies a rule only while it holds:
+  - the name of a parameter declared in the chart, such as a checkbox;
+  - any Vega expression, e.g. `"emphasis == 'cell'"` for a radio button;
+  - in Python, an `alt.Parameter`, which is declared on the returned chart if
+    the chart doesn't already declare it.
+
+  Each styled property becomes a per-label expression on the existing label
+  layers, so no layers are added and the returned chart keeps its shape. A
+  strain that isn't a tree tip raises; strains dropped by `prune_tree_to_chart`
+  are skipped. CLI form: `--strain-label-styles` with a JSON array, where
+  `when` names a parameter saved in the chart JSON.
+  ([#12](https://github.com/jbloomlab/tree-annotated-plot/issues/12))
+
 ### Fixed
 
 - A chart with selection parameters on a compound chart (layer, facet, or
@@ -17,6 +37,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   loading, and altair then emitted empty `views`, which makes Vega-Lite define
   the selection in every view. The loader now leaves the spec's `views` intact.
   Live altair charts were never affected.
+- The `plot()` docstring's Returns section described the panel order wrongly
+  for a strain on `x`. The default `tree_location="bottom"` puts the chart
+  first and the tree second. The section now gives the order for each
+  `tree_location`.
 
 ## [0.4.0] - 2026-08-20
 
diff --git a/docs/examples.md b/docs/examples.md
index 0df0d6d..c04155b 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -140,6 +140,77 @@ CLI flags: `--connect-leader-to-label --strain-label-font-size 9
 --shift-tree-loc 60`. In Python:
 `connect_leader_to_label=True, strain_label_font_size=9, shift_tree_loc=60`.
 
+### Optional: emphasize some strains' labels
+
+With label connection on, you can also style a subset of the labels, for
+example so the vaccine strains are easy to pick out. Pass
+`strain_label_styles`, a list of rules. Each rule names some `strains`
+(tree tip identifiers, i.e. `tree_strain_field` values) and a `style` built
+from Vega-Lite text properties: `fill`, `opacity`, `fontWeight` and
+`fontStyle`. A rule can also take a `when` condition, usually the name of a
+checkbox parameter, so the style applies only while the box is ticked.
+Where rules overlap, later rules win.
+
+The example below draws the labels of the H3N2 recent vaccine strains in
+bold red, with a checkbox that turns the emphasis off and on:
+
+![H3N2 with vaccine-strain labels in bold red](images/h3n2_combined_label_styles.svg)
+
+[Open the interactive chart in a new tab →](charts/h3n2_combined_label_styles.html){target="_blank"}
+
+From the CLI, a `when` parameter has to be declared in the saved chart, so
+add it before saving:
+
+```python
+chart = chart.add_params(
+    alt.param(
+        name="vaccine_strains",
+        value=True,
+        bind=alt.binding_checkbox(name="highlight vaccine strains "),
+    )
+)
+chart.save("titers.json")
+```
+
+then pass the rules as a JSON array, alongside the label-connection flags
+above:
+
+```bash
+--connect-leader-to-label --strain-label-styles \
+    '[{"strains": ["J.2.4", "J.2:S145N"],
+       "style": {"fill": "#d62728", "fontWeight": "bold"},
+       "when": "vaccine_strains"}]'
+```
+
+In Python, pass the parameter object itself. If your chart doesn't already
+declare it, it is declared on the returned chart for you:
+
+```python
+vaccine_strains = alt.param(
+    name="vaccine_strains",
+    value=True,
+    bind=alt.binding_checkbox(name="highlight vaccine strains "),
+)
+tree_annotated_plot.plot(
+    ...,
+    connect_leader_to_label=True,
+    strain_label_styles=[
+        {
+            "strains": ["J.2.4", "J.2:S145N"],
+            "style": {"fill": "#d62728", "fontWeight": "bold"},
+            "when": vaccine_strains,
+        }
+    ],
+)
+```
+
+Leave out `when` for a style that is always on. `when` can be any Vega
+expression, so other inputs work too. For example, with a radio button
+`alt.param(name="emphasis", value="cell", bind=alt.binding_radio(options=["cell", "egg"]))`
+declared on the chart, one rule with `"when": "emphasis == 'cell'"` and
+another with `"when": "emphasis == 'egg'"` switch the emphasis between two
+groups of strains.
+
 ### Color the tree
 
 Pass `color_tree_by` to color the tree's branches and tip circles by
diff --git a/examples/flu-seqneut-2025to2026_titer_charts.py b/examples/flu-seqneut-2025to2026_titer_charts.py
index f899586..c99abb7 100644
--- a/examples/flu-seqneut-2025to2026_titer_charts.py
+++ b/examples/flu-seqneut-2025to2026_titer_charts.py
@@ -131,6 +131,17 @@ def strain_plot_order(viruses_subset: pd.DataFrame) -> list[str]:
     return sorted_df["virus"].tolist()
 
 
+def vaccine_axis_labels(viruses: pd.DataFrame, subtype: str) -> list[str]:
+    """Axis labels of the `RECENT_VACCINE_STRAINS` in `subtype`, in table order.
+
+    These are the strain-axis values the chart (and so the tree's tips) use for
+    the vaccine strains, e.g. for `strain_label_styles`."""
+    is_vaccine = (viruses["subtype"] == subtype) & viruses["virus"].isin(
+        RECENT_VACCINE_STRAINS
+    )
+    return viruses.loc[is_vaccine, "axis_label"].tolist()
+
+
 def make_chart(
     subtype: str,
     chart_type: str,
diff --git a/scripts/generate_docs_assets.py b/scripts/generate_docs_assets.py
index 89f18f9..0532ffa 100644
--- a/scripts/generate_docs_assets.py
+++ b/scripts/generate_docs_assets.py
@@ -25,6 +25,8 @@
 from pathlib import Path
 from types import ModuleType
 
+import altair as alt
+
 import tree_annotated_plot
 
 REPO = Path(__file__).resolve().parent.parent
@@ -163,6 +165,47 @@ def _render_kikawa() -> None:
     )
     _save_pair(out, "h3n2_combined_label_connect")
 
+    # The same label-connect H3N2 chart, with the recent vaccine strains'
+    # labels drawn in bold red while a checkbox is ticked: `strain_label_styles`
+    # with a `when` param. The checkbox starts ticked so the static SVG shows
+    # the emphasis.
+    h3n2_chart_styles = builder.make_chart(
+        subtype="H3N2",
+        chart_type="iqr",
+        titers=titers,
+        viruses=viruses,
+        metadata=metadata,
+        all_cohorts=all_cohorts,
+    )
+    vaccine_strains = alt.param(
+        name="vaccine_strains",
+        value=True,
+        bind=alt.binding_checkbox(name="highlight vaccine strains "),
+    )
+    out = tree_annotated_plot.plot(
+        DATA_DIR / "flu-seqneut-2025to2026_H3N2.json",
+        h3n2_chart_styles,
+        chart_strain_field="axis_label",
+        tree_strain_field="derived_haplotype",
+        branch_length="div",
+        tree_size=140,
+        scale_bar=True,
+        branch_length_units="substitutions",
+        connect_leader_to_label=True,
+        strain_label_font_size=9,
+        shift_tree_loc=60,
+        color_tree_by="subclade",
+        tree_color_legend_format={"orient": "left"},
+        strain_label_styles=[
+            {
+                "strains": builder.vaccine_axis_labels(viruses, "H3N2"),
+                "style": {"fill": "#d62728", "fontWeight": "bold"},
+                "when": vaccine_strains,
+            }
+        ],
+    )
+    _save_pair(out, "h3n2_combined_label_styles")
+
     # H3N2 once more, colored by genotype at HA1 site 158: same chart and
     # default layout as `h3n2_combined`, with `color_tree_by` switched to
     # the genotype form. Site 158 has two mutations (N158K, N158D) in the
diff --git a/src/tree_annotated_plot/_config.py b/src/tree_annotated_plot/_config.py
index cbfbd7c..9679818 100644
--- a/src/tree_annotated_plot/_config.py
+++ b/src/tree_annotated_plot/_config.py
@@ -161,6 +161,28 @@ class PlotConfig:
         "when `connect_leader_to_label` is on.",
     ] = "normal"
 
+    strain_label_styles: Annotated[
+        list[dict[str, Any]] | None,
+        "Style a subset of the strain labels rendered in the tree panel; "
+        "requires `connect_leader_to_label`. A list of rules, each a dict "
+        'with keys "strains" (a list of tip identifiers, i.e. '
+        '`tree_strain_field` values), "style" and, optionally, "when". '
+        '"style" holds Vega-Lite text-mark properties: "fill" (a color), '
+        '"opacity" (0 to 1), "fontWeight" ("normal", "bold", or 100-900) '
+        'and "fontStyle" ("normal" or "italic"). "when" is a Vega '
+        "expression that turns the rule on while it is truthy, usually just "
+        "the name of a parameter declared in the chart (e.g. one bound to a "
+        "checkbox), but any expression works (e.g. \"emphasis == 'cell'\" "
+        'for a radio button). Without "when" the style always applies. '
+        "Where rules overlap, later rules win property by property; "
+        "properties no rule sets keep `strain_label_font_weight` and the "
+        "default black, upright text. A strain that isn't a tree tip is an "
+        "error; strains dropped by `prune_tree_to_chart` are skipped. CLI "
+        "form: a JSON array (quote the whole argument), e.g. "
+        '\'[{"strains": ["K"], "style": {"fill": "#d62728", '
+        '"fontWeight": "bold"}, "when": "vaccine_strains"}]\'.',
+    ] = None
+
     shift_tree_loc: Annotated[
         int,
         "Pixels by which to shift the tree toward (positive) or away from "
@@ -225,10 +247,25 @@ class PlotConfig:
 
 
 # Sidecar for Python-docstring-only prose, keyed by PlotConfig field name.
-# Empty by default — add an entry when a field's docstring entry needs more
-# than the CLI `--help` text covers. The extras are appended to the field's
-# description in `tree_annotated_plot.plot.__doc__`, never in CLI --help.
-PARAM_DOC_EXTRAS: dict[str, str] = {}
+# Add an entry when a field's docstring entry needs more than the CLI
+# `--help` text covers. The extras are appended to the field's description in
+# `tree_annotated_plot.plot.__doc__`, never in CLI --help.
+PARAM_DOC_EXTRAS: dict[str, str] = {
+    "strain_label_styles": (
+        'In Python, "when" may also be an `altair.Parameter`, e.g. '
+        '`alt.param(name="vaccine_strains", value=True, '
+        "bind=alt.binding_checkbox())`, which is declared on the returned "
+        "chart if your chart doesn't already declare it; or an altair "
+        'parameter expression such as `emphasis == "cell"`. Only a bare '
+        "`altair.Parameter` is declared for you: parameters that an "
+        "expression refers to must be declared on the chart, and an "
+        "expression other than a bare name isn't checked until the chart "
+        "renders. A bare name or parameter must be a variable parameter: "
+        "selection parameters are rejected, since the label data doesn't "
+        "carry the fields a selection tests. Any iterable of strings (e.g. "
+        'a pandas Series) works for "strains".'
+    ),
+}
 
 
 # Descriptions for the three data-input parameters. These can't live on
diff --git a/src/tree_annotated_plot/_label_style.py b/src/tree_annotated_plot/_label_style.py
new file mode 100644
index 0000000..0a6a6e9
--- /dev/null
+++ b/src/tree_annotated_plot/_label_style.py
@@ -0,0 +1,349 @@
+"""Per-strain styling of the tree-panel strain labels (`strain_label_styles`).
+
+Public entry points: :func:`resolve_rules` validates and normalizes the
+user's rules, and :func:`mark_props` turns them into label mark properties.
+
+Each rule names some strains, a style (a subset of Vega-Lite text-mark
+properties) and, optionally, a `when` condition. Every property a rule sets
+becomes one `alt.ExprRef` on the existing label mark(s), evaluated per label:
+Vega-Lite compiles a mark-level ``{"expr": ...}`` into the Vega encode block,
+where ``datum`` is the label's row. That is why a property with no encoding
+channel (``fontWeight``, ``fontStyle``) can still vary by strain without
+duplicating the label layers. Which rules a label belongs to is carried in
+one boolean column per rule (:func:`membership_column`) on the label data.
+
+``fontSize`` is deliberately not a style key: the label strip's width is
+estimated from `strain_label_font_size`, so a per-strain size would need a
+different layout calculation.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import altair as alt
+from altair.expr.core import Expression
+
+# Allowed `style` keys, in the order their expressions are emitted.
+STYLE_KEYS = ("fill", "opacity", "fontWeight", "fontStyle")
+
+# Style keys that change the glyph outline. The white halo layer drawn under
+# each label has to follow these so it keeps masking the leader exactly where
+# the text is; `fill` and `opacity` apply to the visible text only.
+_GLYPH_KEYS = frozenset({"fontWeight", "fontStyle"})
+
+_RULE_KEYS = frozenset({"strains", "style", "when"})
+
+_FONT_WEIGHTS = ("normal", "bold")
+_NUMERIC_FONT_WEIGHTS = tuple(range(100, 1000, 100))
+_FONT_STYLES = ("normal", "italic")
+
+# Hints for style keys a user is likely to reach for that we don't accept.
+_STYLE_KEY_HINTS = {
+    "color": 'use "fill" to set the label color',
+    "fontSize": (
+        "per-strain font sizes are not supported because they change the "
+        "label-strip layout; use `strain_label_font_size` for all labels"
+    ),
+}
+
+# A bare Vega expression identifier, i.e. what a param name looks like.
+_IDENTIFIER = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+
+
+@dataclass(frozen=True)
+class LabelStyleRule:
+    """One validated `strain_label_styles` rule.
+
+    `strains` holds only the strains drawn in the tree (pruned ones are
+    dropped); `when` is a Vega expression string, or None for always-on.
+    """
+
+    strains: frozenset[str]
+    style: dict[str, Any]
+    when: str | None
+
+
+def membership_column(index: int) -> str:
+    """Name of the boolean label-data column marking rule `index`'s strains."""
+    return f"_tap_label_style_{index}"
+
+
+def resolve_rules(
+    raw: Any,
+    *,
+    input_tip_names: Iterable[str],
+    drawn_tip_names: Iterable[str],
+    chart_spec: dict,
+    tree_strain_field: str,
+) -> tuple[list[LabelStyleRule], list[alt.Parameter]]:
+    """Validate `strain_label_styles` and return ``(rules, params_to_declare)``.
+
+    `input_tip_names` are the tree's tips before `prune_tree_to_chart`; a
+    strain outside them is an error. `drawn_tip_names` are the tips left
+    after pruning; strains pruned away are silently dropped from their rule.
+    `params_to_declare` lists the `alt.Parameter` objects passed as `when`
+    that the chart doesn't already declare, deduplicated by name.
+    """
+    if raw is None:
+        return [], []
+    if isinstance(raw, (str, bytes, Mapping)) or not isinstance(raw, Iterable):
+        raise ValueError(
+            "strain_label_styles must be a list of rule dicts, each with "
+            f'"strains" and "style" keys; got {type(raw).__name__}.'
+        )
+    raw_rules = list(raw)
+    if not raw_rules:
+        return [], []
+
+    input_tips = set(input_tip_names)
+    drawn_tips = set(drawn_tip_names)
+    declared = _declared_params(chart_spec)
+    rule_params: dict[str, alt.Parameter] = {}
+    for rule in raw_rules:
+        when = rule.get("when") if isinstance(rule, Mapping) else None
+        if isinstance(when, alt.Parameter):
+            rule_params.setdefault(_param_name(when), when)
+
+    rules: list[LabelStyleRule] = []
+    for i, rule in enumerate(raw_rules):
+        if not isinstance(rule, Mapping):
+            raise ValueError(
+                f"strain_label_styles[{i}] must be a dict with "
+                f'"strains" and "style" keys; got {type(rule).__name__}.'
+            )
+        unknown_keys = set(rule) - _RULE_KEYS
+        if unknown_keys:
+            raise ValueError(
+                f"strain_label_styles[{i}] has unknown key(s) "
+                f"{sorted(unknown_keys)}; allowed keys are "
+                f"{sorted(_RULE_KEYS)}."
+            )
+        for required in ("strains", "style"):
+            if required not in rule:
+                raise ValueError(
+                    f"strain_label_styles[{i}] is missing the required "
+                    f"{required!r} key."
+                )
+        rules.append(
+            LabelStyleRule(
+                strains=_resolve_strains(
+                    i,
+                    rule["strains"],
+                    input_tips=input_tips,
+                    drawn_tips=drawn_tips,
+                    tree_strain_field=tree_strain_field,
+                ),
+                style=_validate_style(i, rule["style"]),
+                when=_resolve_when(
+                    i,
+                    rule.get("when"),
+                    declared=declared,
+                    rule_param_names=set(rule_params),
+                ),
+            )
+        )
+
+    to_declare = [p for name, p in rule_params.items() if name not in declared]
+    return rules, to_declare
+
+
+def mark_props(
+    rules: list[LabelStyleRule], *, default_font_weight: str
+) -> tuple[dict[str, alt.ExprRef], dict[str, alt.ExprRef]]:
+    """Return ``(halo_props, text_props)``: mark properties for the label layers.
+
+    Only properties that some rule sets get an expression; the rest keep the
+    marks' static settings. Each expression is a chain of ternaries built in
+    rule order, so the last rule's test is evaluated first and later rules
+    win where strains overlap. The fallback is the label's unstyled value:
+    `default_font_weight` for ``fontWeight``, and Vega-Lite's text defaults
+    (black, fully opaque, upright) for the others.
+    """
+    defaults = {
+        "fill": "black",
+        "opacity": 1,
+        "fontWeight": default_font_weight,
+        "fontStyle": "normal",
+    }
+    text_props: dict[str, alt.ExprRef] = {}
+    for key in STYLE_KEYS:
+        expr = json.dumps(defaults[key])
+        styled = False
+        for i, rule in enumerate(rules):
+            if key not in rule.style:
+                continue
+            test = f"datum[{json.dumps(membership_column(i))}]"
+            if rule.when is not None:
+                test = f"({rule.when}) && {test}"
+            expr = f"{test} ? {json.dumps(rule.style[key])} : ({expr})"
+            styled = True
+        if styled:
+            text_props[key] = alt.ExprRef(expr)
+    halo_props = {k: v for k, v in text_props.items() if k in _GLYPH_KEYS}
+    return halo_props, text_props
+
+
+def _resolve_strains(
+    index: int,
+    strains: Any,
+    *,
+    input_tips: set[str],
+    drawn_tips: set[str],
+    tree_strain_field: str,
+) -> frozenset[str]:
+    if isinstance(strains, (str, bytes, Mapping)) or not isinstance(strains, Iterable):
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] must be a list of '
+            f"strain names; got {type(strains).__name__} {strains!r}."
+        )
+    strains = list(strains)
+    if not strains:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] is empty; a rule must '
+            "name at least one strain."
+        )
+    non_str = [s for s in strains if not isinstance(s, str)]
+    if non_str:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] must contain strings; '
+            f"got {non_str[:5]!r}."
+        )
+    unknown = sorted(set(strains) - input_tips)
+    if unknown:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] has {len(unknown)} '
+            "strain(s) that are not tips of the tree under "
+            f"tree_strain_field={tree_strain_field!r}.\n"
+            f"Sample unknown strains: {unknown[:5]}\n"
+            f"Sample tree tips:       {sorted(input_tips)[:5]}"
+        )
+    return frozenset(s for s in strains if s in drawn_tips)
+
+
+def _validate_style(index: int, style: Any) -> dict[str, Any]:
+    where = f'strain_label_styles[{index}]["style"]'
+    if not isinstance(style, Mapping) or not style:
+        raise ValueError(
+            f"{where} must be a non-empty dict of label properties (any of "
+            f"{list(STYLE_KEYS)}); got {style!r}."
+        )
+    for key, value in style.items():
+        if key not in STYLE_KEYS:
+            hint = _STYLE_KEY_HINTS.get(key)
+            raise ValueError(
+                f"{where} has unsupported key {key!r}; allowed keys are "
+                f"{list(STYLE_KEYS)}." + (f" Hint: {hint}." if hint else "")
+            )
+        if key == "fill":
+            ok = isinstance(value, str) and bool(value.strip())
+            expected = "a non-empty color string"
+        elif key == "opacity":
+            ok = (
+                isinstance(value, (int, float))
+                and not isinstance(value, bool)
+                and math.isfinite(value)
+                and 0 <= value <= 1
+            )
+            expected = "a number from 0 to 1"
+        elif key == "fontWeight":
+            ok = value in _FONT_WEIGHTS or (
+                isinstance(value, int)
+                and not isinstance(value, bool)
+                and value in _NUMERIC_FONT_WEIGHTS
+            )
+            expected = f"one of {list(_FONT_WEIGHTS)} or 100-900 in steps of 100"
+        else:  # fontStyle
+            ok = value in _FONT_STYLES
+            expected = f"one of {list(_FONT_STYLES)}"
+        if not ok:
+            raise ValueError(f"{where}[{key!r}] must be {expected}; got {value!r}.")
+    return dict(style)
+
+
+def _resolve_when(
+    index: int,
+    when: Any,
+    *,
+    declared: dict[str, dict],
+    rule_param_names: set[str],
+) -> str | None:
+    """Return `when` as a Vega expression string (None means always on)."""
+    where = f'strain_label_styles[{index}]["when"]'
+    if when is None:
+        return None
+    if isinstance(when, alt.Parameter):
+        if when.param_type != "variable":
+            raise ValueError(
+                f"{where} is a selection parameter ({_param_name(when)!r}); "
+                "only variable parameters (alt.param(...), e.g. bound to a "
+                "checkbox) are supported, since the label data doesn't carry "
+                "the fields a selection tests."
+            )
+        return _param_name(when)
+    if isinstance(when, alt.ParameterExpression):
+        expr = when.to_dict().get("expr")
+    elif isinstance(when, Expression):
+        expr = when.to_dict()
+    elif isinstance(when, str):
+        expr = when
+    else:
+        raise ValueError(
+            f"{where} must be a param name or Vega expression string, an "
+            "alt.Parameter, or an altair parameter expression; got "
+            f"{type(when).__name__}."
+        )
+    if not isinstance(expr, str) or not expr.strip():
+        raise ValueError(f"{where} must not be empty; got {when!r}.")
+    expr = expr.strip()
+    if _IDENTIFIER.fullmatch(expr) and expr not in rule_param_names:
+        if expr not in declared:
+            raise ValueError(
+                f"{where}={expr!r} names no parameter declared in the chart. "
+                f"Declared parameters: {sorted(declared) or 'none'}. Declare "
+                "it on the chart (e.g. chart.add_params(alt.param(name="
+                f"{expr!r}, value=True, bind=alt.binding_checkbox()))) before "
+                "saving it, or, in Python, pass the alt.Parameter itself."
+            )
+        if "select" in declared[expr]:
+            raise ValueError(
+                f"{where}={expr!r} is a selection parameter; only variable "
+                "parameters (e.g. bound to a checkbox) are supported, since "
+                "the label data doesn't carry the fields a selection tests."
+            )
+    return expr
+
+
+def _declared_params(spec: Any) -> dict[str, dict]:
+    """Map every param name declared anywhere in a chart spec to its definition."""
+    found: dict[str, dict] = {}
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            params = node.get("params")
+            if isinstance(params, list):
+                for p in params:
+                    if isinstance(p, dict) and isinstance(p.get("name"), str):
+                        found.setdefault(p["name"], p)
+            for k, v in node.items():
+                if k in ("data", "datasets"):
+                    continue
+                walk(v)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(spec)
+    return found
+
+
+def _param_name(param: alt.Parameter) -> str:
+    name = param.name
+    if hasattr(name, "to_dict"):
+        name = name.to_dict()
+    return str(name)
diff --git a/src/tree_annotated_plot/_plot.py b/src/tree_annotated_plot/_plot.py
index 0432d62..396b857 100644
--- a/src/tree_annotated_plot/_plot.py
+++ b/src/tree_annotated_plot/_plot.py
@@ -15,7 +15,7 @@
 import altair as alt
 import pandas as pd
 
-from . import _color, _config, _tree
+from . import _color, _config, _label_style, _tree
 from ._config import PlotConfig, TreeLocation
 
 # Vega-Lite `orient` values that anchor the legend to the chart's left or
@@ -61,6 +61,7 @@ def plot(
     connect_leader_to_label: bool = False,
     strain_label_font_size: float = 10.0,
     strain_label_font_weight: Literal["normal", "bold"] = "normal",
+    strain_label_styles: list[dict[str, Any]] | None = None,
     shift_tree_loc: int = 0,
     color_tree_by: str | None = None,
     tree_color_scale: dict[str, str] | None = None,
@@ -90,6 +91,7 @@ def plot(
             connect_leader_to_label=connect_leader_to_label,
             strain_label_font_size=strain_label_font_size,
             strain_label_font_weight=strain_label_font_weight,
+            strain_label_styles=strain_label_styles,
             shift_tree_loc=shift_tree_loc,
             color_tree_by=color_tree_by,
             tree_color_scale=tree_color_scale,
@@ -124,10 +126,12 @@ def plot(
 Returns
 -------
 altair.HConcatChart | altair.VConcatChart
-    For vertical layout (chart strain on `y`), an `HConcatChart` with the
-    tree on the left and the user's chart on the right. For horizontal
-    layout (chart strain on `x`), a `VConcatChart` with the tree on top
-    and the chart below.
+    For vertical layout (chart strain on `y`), an `HConcatChart` whose
+    panels are the tree then the chart for `tree_location="left"` (the
+    default), or the chart then the tree for `"right"`. For horizontal
+    layout (chart strain on `x`), a `VConcatChart` whose panels are the
+    chart then the tree for `tree_location="bottom"` (the default), or the
+    tree then the chart for `"top"`.
 """
 
 
@@ -149,6 +153,14 @@ def _build(
     set on a config object); `config` carries every styling / behavior
     knob. Both surfaces converge here so they can never disagree.
     """
+    if config.strain_label_styles and not config.connect_leader_to_label:
+        raise ValueError(
+            "strain_label_styles styles the strain labels rendered in the "
+            "tree panel, which exist only when connect_leader_to_label=True. "
+            "With it off, the strain labels are your chart's own axis labels; "
+            "style those with Vega-Lite's conditional axis-label properties "
+            "(e.g. labelColor / labelFontWeight expressions on datum.value)."
+        )
     root, auspice_meta = _ensure_tree(
         tree,
         config.tree_strain_field,
@@ -157,6 +169,9 @@ def _build(
     )
     tip_list = _tree.layout(root)
     tip_names = [t.name for t in tip_list]
+    # Kept for `strain_label_styles` validation: a styled strain must be a tip
+    # of the input tree even if `prune_tree_to_chart` later drops it.
+    input_tip_names = list(tip_names)
 
     _check_no_duplicate_tip_strains(
         tip_names, tree_strain_field=config.tree_strain_field
@@ -208,6 +223,14 @@ def _build(
         tip_list = _tree.layout(root)
         tip_names = [t.name for t in tip_list]
 
+    label_style_rules, label_style_params = _label_style.resolve_rules(
+        config.strain_label_styles,
+        input_tip_names=input_tip_names,
+        drawn_tip_names=tip_names,
+        chart_spec=spec,
+        tree_strain_field=config.tree_strain_field,
+    )
+
     strain_dim = _coerce_dim(
         _chart_strain_dim(spec, axis_hits, axis), n_tips=len(tip_names)
     )
@@ -242,6 +265,7 @@ def _build(
         connect_leader_to_label=config.connect_leader_to_label,
         strain_label_font_size=config.strain_label_font_size,
         strain_label_font_weight=config.strain_label_font_weight,
+        label_style_rules=label_style_rules,
         shift_tree_loc=config.shift_tree_loc,
         tip_names=tip_names,
         color_mapping=color_mapping,
@@ -291,6 +315,15 @@ def _build(
     _apply_combined_config(combined, hoisted_config)
     for k, v in hoisted_other.items():
         combined._kwds[k] = v
+    # Declare any `when` parameter the user's chart doesn't already declare.
+    # Appended to the top-level `params` directly: `combined.add_params(...)`
+    # pushes params down into each sub-chart instead, which raises on charts
+    # loaded from a spec (e.g. a `FacetSpec` has no `add_params`).
+    if label_style_params:
+        existing = _live_attr(combined, "params") or []
+        combined._kwds["params"] = list(existing) + [
+            p.param for p in label_style_params
+        ]
     return combined
 
 
@@ -1495,6 +1528,7 @@ def _build_tree_chart(
     connect_leader_to_label: bool = False,
     strain_label_font_size: float = 10.0,
     strain_label_font_weight: str = "normal",
+    label_style_rules: list[_label_style.LabelStyleRule] | None = None,
     shift_tree_loc: int = 0,
     tip_names: list[str] | None = None,
     color_mapping: _color.ColorMapping | None = None,
@@ -1600,6 +1634,10 @@ def _build_tree_chart(
     #     text — and masks the dashed leader behind each label without any
     #     width estimation. Vega-Lite doesn't expose `paintOrder`, so the
     #     two-layer trick stands in for a single text-with-halo mark.
+    #   - `strain_label_styles` rules restyle individual labels by replacing
+    #     these layers' mark properties with per-label `datum` expressions
+    #     (see `_label_style`); the halo follows the glyph-shape ones
+    #     (fontWeight / fontStyle) so it keeps matching the text.
     #   - `shift_tree_loc` (pixels) shrinks the strip — bringing the tree
     #     visually closer to the labels — by reducing the data-units between
     #     branch_max and chart_edge_branch. The tree's tree_size-pixel
@@ -1607,6 +1645,23 @@ def _build_tree_chart(
     # When connect_leader_to_label is off, the chart's natural strain-axis
     # labels are kept and leaders stop at branch_max (the prior behavior).
     halo_px = max(2.0, strain_label_font_size * _LABEL_HALO_RATIO)
+    halo_style, text_style = _label_style.mark_props(
+        label_style_rules or [], default_font_weight=strain_label_font_weight
+    )
+    label_font_kwargs = {
+        "baseline": "middle",
+        "fontSize": strain_label_font_size,
+        "fontWeight": strain_label_font_weight,
+    }
+    label_halo_mark_kwargs = {
+        **label_font_kwargs,
+        "fill": "white",
+        "stroke": "white",
+        "strokeWidth": halo_px,
+        "strokeJoin": "round",
+        **halo_style,
+    }
+    label_text_mark_kwargs = {**label_font_kwargs, **text_style}
     if connect_leader_to_label:
         names = tip_names if tip_names is not None else list(tips_df["name"])
         max_name_len = max((len(n) for n in names), default=0)
@@ -1641,6 +1696,12 @@ def _build_tree_chart(
         leader_df = tips_df[tips_df["x"] < label_anchor_branch].assign(
             x2=label_anchor_branch
         )
+        tips_df = tips_df.assign(
+            **{
+                _label_style.membership_column(i): tips_df["name"].isin(rule.strains)
+                for i, rule in enumerate(label_style_rules or [])
+            }
+        )
         extended_tree_size = tree_size + strip_pixel_width
     else:
         chart_edge_branch = branch_max
@@ -1756,26 +1817,12 @@ def _build_tree_chart(
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                    fill="white",
-                    stroke="white",
-                    strokeWidth=halo_px,
-                    strokeJoin="round",
-                )
+                .mark_text(align=text_align, **label_halo_mark_kwargs)
                 .encode(**label_text_enc)
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                )
+                .mark_text(align=text_align, **label_text_mark_kwargs)
                 .encode(**label_text_enc)
             )
         if scale_bar_layer is not None:
@@ -1862,28 +1909,12 @@ def _build_tree_chart(
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    angle=270,
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                    fill="white",
-                    stroke="white",
-                    strokeWidth=halo_px,
-                    strokeJoin="round",
-                )
+                .mark_text(align=text_align, angle=270, **label_halo_mark_kwargs)
                 .encode(**label_text_enc)
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    angle=270,
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                )
+                .mark_text(align=text_align, angle=270, **label_text_mark_kwargs)
                 .encode(**label_text_enc)
             )
         if scale_bar_layer is not None:
diff --git a/src/tree_annotated_plot/cli.py b/src/tree_annotated_plot/cli.py
index 7039885..b90ea2f 100644
--- a/src/tree_annotated_plot/cli.py
+++ b/src/tree_annotated_plot/cli.py
@@ -74,19 +74,26 @@ def convert(self, value, param, ctx):  # type: ignore[override]
 _COLOR_SCALE_PARAM_TYPE = _ColorScaleParamType()
 
 
-class _JsonDictParamType(click.ParamType):
-    """Parse a JSON-object string into a dict.
-
-    Used for ``--tree-color-legend-format``: any subset of Vega-Lite's
-    Legend properties as a JSON object (e.g.
-    ``'{"orient":"left","labelFontSize":13}'``). The user must quote the
-    whole argument so the shell doesn't interpret braces or quotes.
+class _JsonParamType(click.ParamType):
+    """Parse a JSON string into a dict, or into a list of dicts.
+
+    `container=dict` expects a JSON object; used for
+    ``--tree-color-legend-format``: any subset of Vega-Lite's Legend
+    properties (e.g. ``'{"orient":"left","labelFontSize":13}'``).
+    `container=list` expects a JSON array of objects; used for
+    ``--strain-label-styles`` (e.g.
+    ``'[{"strains":["K"],"style":{"fill":"red"}}]'``). The user must quote
+    the whole argument so the shell doesn't interpret braces or quotes.
+    `example` is shown in the error message when the JSON has the wrong shape.
     """
 
-    name = "json_dict"
+    def __init__(self, container: type, *, name: str, example: str) -> None:
+        self.container = container
+        self.name = name
+        self.example = example
 
     def convert(self, value, param, ctx):  # type: ignore[override]
-        if value is None or isinstance(value, dict):
+        if value is None or isinstance(value, self.container):
             return value
         text = str(value).strip()
         if not text:
@@ -95,17 +102,34 @@ def convert(self, value, param, ctx):  # type: ignore[override]
             parsed = json.loads(text)
         except json.JSONDecodeError as exc:
             self.fail(f"invalid JSON: {exc}", param, ctx)
-        if not isinstance(parsed, dict):
+        kind = "object" if self.container is dict else "array of objects"
+        if not isinstance(parsed, self.container):
             self.fail(
-                f'expected a JSON object (e.g. \'{{"orient":"left"}}\'); '
+                f"expected a JSON {kind} (e.g. {self.example}); "
                 f"got {type(parsed).__name__}.",
                 param,
                 ctx,
             )
+        if self.container is list:
+            for i, item in enumerate(parsed):
+                if not isinstance(item, dict):
+                    self.fail(
+                        f"expected a JSON {kind} (e.g. {self.example}); "
+                        f"element {i} is {type(item).__name__}.",
+                        param,
+                        ctx,
+                    )
         return parsed
 
 
-_JSON_DICT_PARAM_TYPE = _JsonDictParamType()
+_JSON_DICT_PARAM_TYPE = _JsonParamType(
+    dict, name="json_dict", example='\'{"orient":"left"}\''
+)
+_JSON_LIST_PARAM_TYPE = _JsonParamType(
+    list,
+    name="json_list",
+    example='\'[{"strains":["K"],"style":{"fill":"red"}}]\'',
+)
 
 
 def _is_str_dict(tp: Any) -> bool:
@@ -126,6 +150,14 @@ def _is_dict_any(tp: Any) -> bool:
     return False
 
 
+def _is_list_of_dicts(tp: Any) -> bool:
+    """Return True for `list[dict[str, Any]]`."""
+    if get_origin(tp) is list:
+        args = get_args(tp)
+        return len(args) == 1 and _is_dict_any(args[0])
+    return False
+
+
 def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
     """Build a `click.option(...)` decorator from a PlotConfig field.
 
@@ -188,6 +220,16 @@ def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
             show_default=False,
         )
 
+    # list[dict[str, Any]] (with or without `| None`) → JSON-array parser.
+    if _is_list_of_dicts(real_type):
+        return click.option(
+            cli_name,
+            type=_JSON_LIST_PARAM_TYPE,
+            default=field.default if has_default else None,
+            help=description,
+            show_default=False,
+        )
+
     # Optional / Union — unwrap to the non-None branch.
     origin = get_origin(real_type)
     if origin in (typing.Union, types.UnionType):
@@ -210,6 +252,14 @@ def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
                     help=description,
                     show_default=False,
                 )
+            if _is_list_of_dicts(inner):
+                return click.option(
+                    cli_name,
+                    type=_JSON_LIST_PARAM_TYPE,
+                    default=field.default if has_default else None,
+                    help=description,
+                    show_default=False,
+                )
             if get_origin(inner) is Literal:
                 choices = [str(c) for c in get_args(inner)]
                 return click.option(
diff --git a/tests/test_strain_label_styles.py b/tests/test_strain_label_styles.py
new file mode 100644
index 0000000..a257373
--- /dev/null
+++ b/tests/test_strain_label_styles.py
@@ -0,0 +1,565 @@
+"""Tests for `strain_label_styles`: per-strain styling of the tree-panel labels."""
+
+from __future__ import annotations
+
+import json
+import re
+
+import altair as alt
+import pandas as pd
+import pytest
+import vl_convert as vlc
+
+import tree_annotated_plot
+from tree_annotated_plot import _label_style
+
+STRAINS = ["A", "B", "C", "D"]
+RED = "#d62728"
+
+
+def _auspice() -> dict:
+    return {
+        "version": "v2",
+        "meta": {},
+        "tree": {
+            "name": "ROOT",
+            "node_attrs": {"div": 0.0},
+            "children": [
+                {"name": "A", "node_attrs": {"div": 0.04}},
+                {"name": "B", "node_attrs": {"div": 0.05}},
+                {"name": "C", "node_attrs": {"div": 0.03}},
+                {"name": "D", "node_attrs": {"div": 0.06}},
+            ],
+        },
+    }
+
+
+def _chart(strain_axis: str = "y", strains: list[str] = STRAINS) -> alt.Chart:
+    df = pd.DataFrame(
+        {"strain": strains, "titer": [2.0**i for i in range(len(strains))]}
+    )
+    strain_enc = alt.Y("strain:N") if strain_axis == "y" else alt.X("strain:N")
+    titer_enc = "titer:Q"
+    enc = (
+        {"y": strain_enc, "x": titer_enc}
+        if strain_axis == "y"
+        else {"x": strain_enc, "y": titer_enc}
+    )
+    return alt.Chart(df).mark_circle().encode(**enc).properties(width=200, height=200)
+
+
+def _kw(**extra) -> dict:
+    return dict(
+        chart_strain_field="strain",
+        tree_strain_field="name",
+        branch_length="div",
+        connect_leader_to_label=True,
+        **extra,
+    )
+
+
+def _checkbox(name: str = "hl", value: bool = True) -> alt.Parameter:
+    return alt.param(name=name, value=value, bind=alt.binding_checkbox(name="hl "))
+
+
+def _label_layers(spec: dict) -> tuple[dict, dict]:
+    """Return the (halo, text) strain-label layers of the tree panel."""
+    panels = spec.get("hconcat") or spec.get("vconcat")
+    layers = [
+        layer
+        for panel in panels
+        for layer in panel.get("layer", [])
+        if isinstance(layer.get("mark"), dict)
+        and layer["mark"].get("type") == "text"
+        and layer.get("encoding", {}).get("text", {}).get("field") == "name"
+    ]
+    assert len(layers) == 2, f"expected halo + text label layers, got {len(layers)}"
+    halo, text = layers
+    assert halo["mark"]["fill"] == "white"
+    return halo, text
+
+
+def _rendered_labels(spec: dict) -> dict[str, dict[str, str]]:
+    """Render `spec` to SVG and return each visible label's text attributes.
+
+    The halo layer draws the same strings in white first; the visible text
+    layer comes second, so later occurrences overwrite the halo's.
+    """
+    svg = vlc.vegalite_to_svg(spec)
+    labels: dict[str, dict[str, str]] = {}
+    for tag, text in re.findall(r"<text([^>]*)>([^<]*)</text>", svg):
+        if text not in STRAINS or "graphics-symbol" not in tag:
+            continue
+        attrs = dict(re.findall(r'([\w-]+)="([^"]*)"', tag))
+        if attrs.get("fill") == "white":
+            continue
+        labels[text] = attrs
+    assert set(labels) == set(STRAINS), f"labels rendered: {sorted(labels)}"
+    return labels
+
+
+def _bold_red(labels: dict[str, dict[str, str]]) -> list[str]:
+    return sorted(
+        s
+        for s, a in labels.items()
+        if a.get("font-weight") == "bold" and a.get("fill") == RED
+    )
+
+
+def _top_level_param_names(spec: dict) -> list[str]:
+    return [p["name"] for p in spec.get("params", [])]
+
+
+VACCINE_RULE = {"strains": ["A", "C"], "style": {"fill": RED, "fontWeight": "bold"}}
+
+
+# ---------- static rules ----------
+
+
+def test_static_rule_sets_expressions_on_label_layers() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(), _chart(), **_kw(strain_label_styles=[VACCINE_RULE])
+    )
+    halo, text = _label_layers(out.to_dict())
+    # Visible text gets every styled property; the halo only the glyph-shape
+    # one, keeping its white fill so it still masks the leader.
+    assert set(text["mark"]["fill"]) == {"expr"}
+    assert set(text["mark"]["fontWeight"]) == {"expr"}
+    assert set(halo["mark"]["fontWeight"]) == {"expr"}
+    assert halo["mark"]["fill"] == "white"
+    assert text["mark"]["fontWeight"] == halo["mark"]["fontWeight"]
+
+
+def test_static_rule_adds_membership_column() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(), _chart(), **_kw(strain_label_styles=[VACCINE_RULE])
+    )
+    spec = out.to_dict()
+    _, text = _label_layers(spec)
+    rows = spec["datasets"][text["data"]["name"]]
+    column = _label_style.membership_column(0)
+    assert {r["name"]: r[column] for r in rows} == {
+        "A": True,
+        "B": False,
+        "C": True,
+        "D": False,
+    }
+
+
+def test_static_rule_renders_styled_labels() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(), _chart(), **_kw(strain_label_styles=[VACCINE_RULE])
+    )
+    labels = _rendered_labels(out.to_dict())
+    assert _bold_red(labels) == ["A", "C"]
+    for s in ("B", "D"):
+        assert labels[s]["font-weight"] == "normal"
+        assert labels[s]["fill"] == "black"
+
+
+def test_unstyled_font_weight_follows_global_setting() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(
+            strain_label_font_weight="bold",
+            strain_label_styles=[{"strains": ["A"], "style": {"fontWeight": "normal"}}],
+        ),
+    )
+    labels = _rendered_labels(out.to_dict())
+    assert labels["A"]["font-weight"] == "normal"
+    assert all(labels[s]["font-weight"] == "bold" for s in ("B", "C", "D"))
+
+
+def test_no_styles_leaves_label_marks_static() -> None:
+    for styles in (None, []):
+        out = tree_annotated_plot.plot(
+            _auspice(), _chart(), **_kw(strain_label_styles=styles)
+        )
+        halo, text = _label_layers(out.to_dict())
+        assert text["mark"]["fontWeight"] == "normal"
+        assert "fill" not in text["mark"]
+        assert halo["mark"]["fontWeight"] == "normal"
+
+
+def test_overlapping_rules_combine_property_by_property() -> None:
+    """A strain in two rules gets both styles; where both set the same
+    property, the later rule wins."""
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(
+            strain_label_styles=[
+                {"strains": ["A", "C"], "style": {"fill": RED, "fontWeight": "bold"}},
+                {"strains": ["C", "D"], "style": {"fontStyle": "italic"}},
+                {"strains": ["A"], "style": {"fill": "#1f77b4"}},
+            ]
+        ),
+    )
+    labels = _rendered_labels(out.to_dict())
+    assert labels["A"]["fill"] == "#1f77b4"
+    assert labels["A"]["font-weight"] == "bold"
+    assert labels["A"]["font-style"] == "normal"
+    assert labels["C"]["fill"] == RED
+    assert labels["C"]["font-weight"] == "bold"
+    assert labels["C"]["font-style"] == "italic"
+    assert labels["D"]["font-style"] == "italic"
+    assert labels["D"]["fill"] == "black"
+    assert labels["B"] == {**labels["B"], "fill": "black", "font-style": "normal"}
+
+
+def test_opacity_and_numeric_font_weight_render() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(
+            strain_label_styles=[
+                {"strains": ["B"], "style": {"opacity": 0.4, "fontWeight": 700}}
+            ]
+        ),
+    )
+    labels = _rendered_labels(out.to_dict())
+    assert labels["B"]["opacity"] == "0.4"
+    assert labels["B"]["font-weight"] == "700"
+
+
+@pytest.mark.parametrize("strain_axis", ["y", "x"])
+def test_both_layouts_with_scale_bar(strain_axis: str) -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(strain_axis),
+        **_kw(scale_bar=True, strain_label_styles=[VACCINE_RULE]),
+    )
+    assert _bold_red(_rendered_labels(out.to_dict())) == ["A", "C"]
+
+
+def test_strains_accept_any_iterable_of_strings() -> None:
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(
+            strain_label_styles=[
+                {"strains": pd.Series(["A", "C"]), "style": VACCINE_RULE["style"]}
+            ]
+        ),
+    )
+    assert _bold_red(_rendered_labels(out.to_dict())) == ["A", "C"]
+
+
+# ---------- `when` toggles ----------
+
+
+@pytest.mark.parametrize("value", [True, False])
+def test_when_parameter_is_declared_once_and_toggles(value: bool) -> None:
+    hl = _checkbox(value=value)
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(strain_label_styles=[{**VACCINE_RULE, "when": hl}]),
+    )
+    spec = out.to_dict()
+    assert _top_level_param_names(spec) == ["hl"]
+    assert _bold_red(_rendered_labels(spec)) == (["A", "C"] if value else [])
+
+
+def test_when_parameter_already_on_chart_is_not_redeclared() -> None:
+    hl = _checkbox()
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart().add_params(hl),
+        **_kw(strain_label_styles=[{**VACCINE_RULE, "when": hl}]),
+    )
+    spec = out.to_dict()
+    assert _top_level_param_names(spec).count("hl") == 1
+    assert _bold_red(_rendered_labels(spec)) == ["A", "C"]
+
+
+def test_when_shared_parameter_across_rules_declared_once() -> None:
+    hl = _checkbox()
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(),
+        **_kw(
+            strain_label_styles=[
+                {"strains": ["A"], "style": {"fill": RED}, "when": hl},
+                {"strains": ["C"], "style": {"fontWeight": "bold"}, "when": "hl"},
+            ]
+        ),
+    )
+    assert _top_level_param_names(out.to_dict()) == ["hl"]
+
+
+def test_when_name_of_chart_param_from_json_chart(tmp_path) -> None:
+    """The CLI form: the param lives in the saved chart and `when` names it."""
+    path = tmp_path / "chart.json"
+    _chart().add_params(_checkbox(value=False)).save(str(path))
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        path,
+        **_kw(strain_label_styles=[{**VACCINE_RULE, "when": "hl"}]),
+    )
+    spec = out.to_dict()
+    assert _top_level_param_names(spec) == ["hl"]
+    assert _bold_red(_rendered_labels(spec)) == []
+    spec["params"][0]["value"] = True
+    assert _bold_red(_rendered_labels(spec)) == ["A", "C"]
+
+
+@pytest.mark.parametrize("emphasis, expected", [("cell", ["A"]), ("egg", ["C"])])
+def test_when_expressions_drive_a_radio_param(emphasis, expected) -> None:
+    emph = alt.param(
+        name="emph",
+        value=emphasis,
+        bind=alt.binding_radio(options=["none", "cell", "egg"]),
+    )
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart().add_params(emph),
+        **_kw(
+            strain_label_styles=[
+                # A string expression and an altair parameter expression.
+                {
+                    "strains": ["A"],
+                    "style": VACCINE_RULE["style"],
+                    "when": "emph == 'cell'",
+                },
+                {
+                    "strains": ["C"],
+                    "style": VACCINE_RULE["style"],
+                    "when": emph == "egg",
+                },
+            ]
+        ),
+    )
+    assert _bold_red(_rendered_labels(out.to_dict())) == expected
+
+
+def test_renested_output_keeps_single_param_and_renders() -> None:
+    """Like flu-seqneut-2026's `finalize()`: the returned chart is nested in a
+    further vconcat whose other panel declares params of its own."""
+    hl = _checkbox()
+    slider = alt.param(name="slider", value=1, bind=alt.binding_range(min=0, max=2))
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart("x"),
+        **_kw(strain_label_styles=[{**VACCINE_RULE, "when": hl}]),
+    )
+    readout = (
+        alt.Chart(pd.DataFrame({"row": [0]}))
+        .add_params(slider)
+        .mark_text()
+        .encode(text=alt.value("readout"))
+        .properties(width=100, height=14)
+    )
+    spec = alt.vconcat(readout, out).to_dict()
+    assert sorted(_top_level_param_names(spec)) == ["hl", "slider"]
+    assert _bold_red(_rendered_labels(spec)) == ["A", "C"]
+
+
+def test_when_undeclared_name_raises() -> None:
+    with pytest.raises(ValueError, match="names no parameter declared"):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart(),
+            **_kw(strain_label_styles=[{**VACCINE_RULE, "when": "nope"}]),
+        )
+
+
+def test_when_selection_parameter_object_raises() -> None:
+    sel = alt.selection_point(name="sel", fields=["strain"])
+    with pytest.raises(ValueError, match="selection parameter"):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart().add_params(sel),
+            **_kw(strain_label_styles=[{**VACCINE_RULE, "when": sel}]),
+        )
+
+
+def test_when_selection_parameter_name_raises() -> None:
+    sel = alt.selection_point(name="sel", fields=["strain"])
+    with pytest.raises(ValueError, match="selection parameter"):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart().add_params(sel),
+            **_kw(strain_label_styles=[{**VACCINE_RULE, "when": "sel"}]),
+        )
+
+
+@pytest.mark.parametrize("when", ["", "   ", 3, ["hl"]])
+def test_when_bad_value_raises(when) -> None:
+    with pytest.raises(ValueError, match=r'\["when"\]'):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart().add_params(_checkbox()),
+            **_kw(strain_label_styles=[{**VACCINE_RULE, "when": when}]),
+        )
+
+
+# ---------- strains ----------
+
+
+def test_unknown_strain_raises_with_samples() -> None:
+    with pytest.raises(ValueError) as exc:
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart(),
+            **_kw(
+                strain_label_styles=[{"strains": ["A", "Z"], "style": {"fill": RED}}]
+            ),
+        )
+    msg = str(exc.value)
+    assert "not tips of the tree" in msg
+    assert "'Z'" in msg
+    assert "Sample tree tips" in msg and "'A'" in msg
+
+
+def test_strain_pruned_from_tree_is_skipped() -> None:
+    """D is a tree tip but not in the chart, so `prune_tree_to_chart` drops it;
+    styling it is not an error."""
+    out = tree_annotated_plot.plot(
+        _auspice(),
+        _chart(strains=["A", "B", "C"]),
+        **_kw(
+            prune_tree_to_chart=True,
+            strain_label_styles=[{"strains": ["A", "D"], "style": {"fill": RED}}],
+        ),
+    )
+    spec = out.to_dict()
+    _, text = _label_layers(spec)
+    rows = spec["datasets"][text["data"]["name"]]
+    column = _label_style.membership_column(0)
+    assert {r["name"]: r[column] for r in rows} == {"A": True, "B": False, "C": False}
+
+
+@pytest.mark.parametrize(
+    "strains, match",
+    [
+        ("A", "must be a list of strain names"),
+        ({"A": 1}, "must be a list of strain names"),
+        ([], "is empty"),
+        (["A", 3], "must contain strings"),
+    ],
+)
+def test_bad_strains_raise(strains, match) -> None:
+    with pytest.raises(ValueError, match=match):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart(),
+            **_kw(strain_label_styles=[{"strains": strains, "style": {"fill": RED}}]),
+        )
+
+
+# ---------- style ----------
+
+
+@pytest.mark.parametrize(
+    "style, match",
+    [
+        ({}, "non-empty dict"),
+        ("bold", "non-empty dict"),
+        ({"color": RED}, 'use "fill"'),
+        ({"fontSize": 12}, "strain_label_font_size"),
+        ({"strokeWidth": 2}, "unsupported key"),
+        ({"fill": ""}, "non-empty color string"),
+        ({"opacity": 1.5}, "number from 0 to 1"),
+        ({"opacity": True}, "number from 0 to 1"),
+        ({"fontWeight": "heavy"}, "fontWeight"),
+        ({"fontWeight": 750}, "fontWeight"),
+        ({"fontStyle": "oblique"}, "fontStyle"),
+    ],
+)
+def test_bad_style_raises(style, match) -> None:
+    with pytest.raises(ValueError, match=match):
+        tree_annotated_plot.plot(
+            _auspice(),
+            _chart(),
+            **_kw(strain_label_styles=[{"strains": ["A"], "style": style}]),
+        )
+
+
+# ---------- rule shape ----------
+
+
+@pytest.mark.parametrize(
+    "styles, match",
+    [
+        ({"strains": ["A"], "style": {"fill": RED}}, "must be a list of rule dicts"),
+        (["A"], r"strain_label_styles\[0\] must be a dict"),
+        ([{"style": {"fill": RED}}], "missing the required 'strains'"),
+        ([{"strains": ["A"]}], "missing the required 'style'"),
+        ([{"strains": ["A"], "style": {"fill": RED}, "param": "hl"}], "unknown key"),
+    ],
+)
+def test_bad_rule_shape_raises(styles, match) -> None:
+    with pytest.raises(ValueError, match=match):
+        tree_annotated_plot.plot(
+            _auspice(), _chart(), **_kw(strain_label_styles=styles)
+        )
+
+
+def test_requires_connect_leader_to_label() -> None:
+    kw = _kw(strain_label_styles=[VACCINE_RULE])
+    kw["connect_leader_to_label"] = False
+    with pytest.raises(ValueError, match="connect_leader_to_label=True"):
+        tree_annotated_plot.plot(_auspice(), _chart(), **kw)
+
+
+# ---------- CLI ----------
+
+
+def _cli(tmp_path, chart: alt.Chart, styles_arg: str):
+    from click.testing import CliRunner
+
+    from tree_annotated_plot import cli as cli_module
+
+    tree_path = tmp_path / "tree.json"
+    chart_path = tmp_path / "chart.json"
+    out_path = tmp_path / "out.json"
+    tree_path.write_text(json.dumps(_auspice()))
+    chart.save(str(chart_path))
+    result = CliRunner().invoke(
+        cli_module.main,
+        [
+            "--tree",
+            str(tree_path),
+            "--chart",
+            str(chart_path),
+            "--output",
+            str(out_path),
+            "--chart-strain-field",
+            "strain",
+            "--tree-strain-field",
+            "name",
+            "--branch-length",
+            "div",
+            "--connect-leader-to-label",
+            "--strain-label-styles",
+            styles_arg,
+        ],
+    )
+    return result, out_path
+
+
+def test_cli_strain_label_styles_with_chart_param(tmp_path) -> None:
+    rule = {**VACCINE_RULE, "when": "hl"}
+    result, out_path = _cli(
+        tmp_path, _chart().add_params(_checkbox()), json.dumps([rule])
+    )
+    assert result.exit_code == 0, result.output
+    spec = json.loads(out_path.read_text())
+    assert _top_level_param_names(spec) == ["hl"]
+    assert _bold_red(_rendered_labels(spec)) == ["A", "C"]
+
+
+@pytest.mark.parametrize(
+    "arg, match",
+    [
+        ("[{not json", "invalid JSON"),
+        (json.dumps(VACCINE_RULE), "expected a JSON array of objects"),
+        ('["A"]', "element 0 is str"),
+    ],
+)
+def test_cli_strain_label_styles_bad_json(tmp_path, arg, match) -> None:
+    result, _ = _cli(tmp_path, _chart(), arg)
+    assert result.exit_code != 0
+    assert match in result.output

From ee6f08a4a4fc8c2e5431ebb7f9b9cac91c08991b Mon Sep 17 00:00:00 2001
From: jbloom <jbloom@fredhutch.org>
Date: Fri, 30 Oct 2026 08:25:12 -0700
Subject: [PATCH 3/4] release 0.5.0: strain_label_styles, selection-param
 charts via JSON/CLI

Bump `version` to 0.5.0 and close the `[Unreleased]` section.

This is a minor release rather than a patch: `strain_label_styles` is a new
parameter, and charts with selection parameters now render through the
JSON / HTML / dict (CLI) path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md   | 2 +-
 pyproject.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 779eac2..7fb18eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.5.0] - 2026-10-30
 
 ### Added
 
diff --git a/pyproject.toml b/pyproject.toml
index 69bc7cf..6083975 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tree-annotated-plot"
-version = "0.4.0"
+version = "0.5.0"
 description = "Annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree."
 readme = "README.md"
 requires-python = ">=3.11"

From 575ff11f1363fa1af07972abba6a34a8f5271165 Mon Sep 17 00:00:00 2001
From: jbloom <jbloom@fredhutch.org>
Date: Fri, 30 Oct 2026 08:38:20 -0700
Subject: [PATCH 4/4] CLAUDE.md: don't leave an empty [Unreleased] section
 after a release

The release step now renames `## [Unreleased]` to the version heading and
leaves no empty section above it. The next change adds a fresh
`## [Unreleased]` when it lands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 632e1dd..b35af8d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,7 +7,9 @@
   section as you make them — new parameters, behavior changes, removed
   features, bug fixes — in [Keep a Changelog](https://keepachangelog.com/)
   format. At release time, `## [Unreleased]` is renamed to
-  `## [X.Y.Z] - YYYY-MM-DD` and a fresh `## [Unreleased]` is created.
+  `## [X.Y.Z] - YYYY-MM-DD`, with no empty `## [Unreleased]` left above it.
+  When the next change lands and there's no `## [Unreleased]` section, add
+  one at the top.
 - **Single source of truth — `pyproject.toml`**: canonical for dependencies,
   supported Python version, build config, tool settings. Don't restate any of
   these in prose; refer to `pyproject.toml`.