fluxplot 0.1.0__py3-none-any.whl

fluxplot/manifest.py

@@ -0,0 +1,788 @@
+"""Assemble the ``*.fluxplot.json`` manifest — the semantic index (spec §4–§8).
+
+Authority rule: geometry stays in the SVG (we never copy paths/bboxes here); the manifest owns
+data, semantics, the coordinate mapping, and choreography. Every node points *into* the SVG by id.
+"""
+from __future__ import annotations
+
+from . import ids as _ids
+from . import presets as _presets
+from . import roles as _roles
+from .capture import svg_viewbox
+from .descriptors import mark_kind
+
+
+def _floats(seq):
+    from .data import values
+    return values(seq)
+
+
+# Composite sub-part roles → the plural series-svg key listing every member. An errorbar/box/
+# violin renders its statistics as numbered sibling groups; collecting EVERY member across the
+# series' marks makes each whisker/cap/median addressable (the shipped errorbar pattern,
+# generalized per plan §4). The singular key keeps the first gid as the primary ref (compat).
+COMPOSITE_ROLES = {
+    "errorbar": "errorbars",
+    "whisker": "whiskers",
+    "cap": "caps",
+    "median": "medians",
+    "flier": "fliers",
+    "mean": "means",
+    "segment": "segments",
+    # A surface (brain) map draws one collection per category, so every region is separately
+    # addressable; ``regions`` lists them all while ``surface-region`` keeps the first as the
+    # primary ref (compat, as for the other composites).
+    "surface-region": "regions",
+}
+
+
+def build_manifest(
+    fig,
+    reg,
+    guides,
+    axes_capture: list,
+    plot_type: str,
+    svg_filename: str,
+    spec_version: str,
+    fluxplot_version: str,
+    mpl_version: str,
+    present: set | None = None,
+    svg_sha256: str | None = None,
+    rasterized: set | None = None,
+    extra_scales=(),
+    style: dict | None = None,
+    quality: dict | None = None,
+) -> dict:
+    vbw, vbh = svg_viewbox(fig)
+    # gids rendered as a single embedded <image> instead of vector primitives (raster.py).
+    # Additive: consumers that ignore it are unaffected; those that read it know why a
+    # point cloud has no per-point ids and can label the layer honestly.
+    rasterized = rasterized or set()
+
+    # `present` = the gids that actually survived into the SVG (matplotlib culls
+    # boundary ticks and renders point clouds as collections where per-point ids
+    # can't be assigned). Reference only what's really there so the parts tree /
+    # group members stay honest. None = keep everything (direct/legacy callers).
+    def _keep(gid) -> bool:
+        return present is None or gid in present
+
+    # group series marks by series name (insertion order preserved)
+    by_series: dict[str, list] = {}
+    overlays = []
+    for m in reg.marks:
+        if m.series is not None:
+            by_series.setdefault(m.series, []).append(m)
+        else:
+            overlays.append(m)
+
+    series_entries = []
+    # per-series {role → data-kind hint} for the parts tree (artist-informed for x- roles)
+    series_kinds: dict = {}
+    for series, marks in by_series.items():
+        svg: dict = {}
+        data: dict = {}
+        points = None
+        kind = None
+        label = None
+        roles = sorted({m.role for m in marks})
+        kinds: dict = {}
+        composite_members: dict[str, list] = {}
+        components = []
+        for m in marks:
+            actual = [g for g in m.member_gids or ([m.gid] if m.gid else []) if _keep(g)]
+            if m.data.get('field_members') and _keep(m.gid):
+                # a field's members are cells / contour bands / hexagons: say which, so a
+                # consumer never has to guess a leaf's role from its id
+                member_role = m.data.get('field_member_role') or (
+                    'cell' if m.data.get('cells') else 'contour-level')
+                components.append({'role': m.role, 'svgId': m.gid, 'memberRole': member_role,
+                                   'members': [g for g in m.data['field_members'] if _keep(g)]})
+            elif m.role == "point" and (_keep(m.gid) or (m.data.get("point_group") and _keep(m.data["point_group"]))):
+                comp = {"role": "point", "svgId": m.data.get("point_group") or m.gid, "memberRole": "point",
+                        "members": actual}
+                if m.data.get("point_group"):  # the SVG group is shared with another series
+                    comp["groupId"] = m.gid
+                components.append(comp)
+            else:
+                components.extend({"role": m.role, "svgId": g} for g in actual)
+            if not actual and not _keep(m.gid) and not (m.data.get("point_group") and _keep(m.data["point_group"])):
+                continue
+            kind = kind or m.kind
+            label = label or m.label
+            if m.role not in kinds:
+                mk = mark_kind(m)
+                if mk is not None:
+                    kinds[m.role] = mk
+            if m.x is not None and not data:
+                data = {"x": _floats(m.x), "y": _floats(m.y)}
+            if m.role == "line":
+                if _keep(m.gid):
+                    svg.setdefault("line", m.gid)
+            elif m.role == "point":
+                if _keep(m.gid):
+                    svg.setdefault("points", m.gid)
+                elif m.data.get("point_group") and _keep(m.data["point_group"]):
+                    svg.setdefault("points", m.data["point_group"])
+                points = (points or []) + [
+                    {
+                        "index": m.member_indices[k],
+                        "svgId": m.member_gids[k],
+                        "x": m.x[m.member_indices[k]],
+                        "y": m.y[m.member_indices[k]],
+                    }
+                    for k in range(len(m.member_gids))
+                    if _keep(m.member_gids[k])
+                ]
+            elif m.role == "bar":
+                bars = [g for g in m.member_gids if _keep(g)]
+                if bars:
+                    svg.setdefault("bars", []).extend(bars)
+            elif m.role in COMPOSITE_ROLES:
+                if _keep(m.gid) and m.role not in svg:
+                    svg[m.role] = m.gid  # primary ref stays (compat); first mark wins
+                composite_members.setdefault(m.role, []).extend(
+                    g for g in m.member_gids if _keep(g)
+                )
+            elif _keep(m.gid):
+                svg.setdefault(m.role, m.gid)
+        for crole, members in composite_members.items():
+            if members:
+                svg[COMPOSITE_ROLES[crole]] = members
+        # Escape-hatch series (fp.tag) carry no helper kind; fall back to the first
+        # tagged role so `kind` is always a string (Flux's validator rejects null).
+        if kind is None:
+            kind = marks[0].role
+        if not svg:
+            continue
+        datasets = [(m.x, m.y) for m in marks if m.x is not None and _keep(m.gid)]
+        if (datasets and any(pair != datasets[0] for pair in datasets[1:])) or sum(m.role == 'point' for m in marks) > 1:
+            # Several components may share one semantic series while depicting different
+            # observations (a hue level's points across categories). Keep part identity without
+            # one false data table; each point still carries its own x / y, and its index counts
+            # within its own group (the svgId's prefix says which).
+            data = {}
+        entry = {
+            "id": _ids.series_root(series),
+            "name": str(series),
+            "kind": kind,
+            "roles": roles,
+            "svg": svg,
+            "data": data,
+            "components": components,
+        }
+        # categorical / date axes: say what each x (y) means, beside the number matplotlib plots
+        owner = next((m.axes for m in marks if m.axes is not None), None)
+        if data and owner is not None:
+            for key, mpl_axis in (("x", owner.xaxis), ("y", owner.yaxis)):
+                if data.get(key):
+                    extra = axis_value_labels(mpl_axis, data[key])
+                    for k, v in extra.items():
+                        data[key + k] = v
+        for field in ("bar", "band", "uncertainty", "field", "glowbar", "fluxbox", "hexmatrix", "image", "step", "stem",
+                      "regression", "kde"):
+            payload = next((m.data[field] for m in marks if m.data.get(field)), None)
+            if payload is not None:
+                entry[field] = payload
+        axis = next((m.data["axis"] for m in marks if m.data.get("axis")), None)
+        if axis is not None:  # drawn against a twin's value axis (axes[].y2 / .x2)
+            entry["axis"] = axis
+        # the series' colour: its primary paint (data.primary_paint) and / or the scale colouring it
+        colour = {}
+        primary = ("line", "point", "bar", "area", "box", "violin", "errorbar", "x-hexbin", "x-heatmap", "x-contourf", "x-contour")
+        drawn = lambda m: _keep(m.gid) or any(_keep(g) for g in m.member_gids)  # noqa: E731  (bars have members only)
+        paint = next((m.data["color"] for m in marks if m.data.get("color") and drawn(m) and m.role in primary), None)
+        if paint is None:
+            paint = next((m.data["color"] for m in marks if m.data.get("color") and drawn(m)), None)
+        if paint:
+            colour.update(paint)
+        scale = next((m.data["color_scale"]["id"] for m in marks if m.data.get("color_scale") and _keep(m.gid)), None)
+        if scale is not None:
+            colour["scale"] = scale
+        if colour:
+            entry["color"] = colour
+        ordinary = all(m.role in ('line', 'point') for m in marks)
+        ordinary = ordinary and len([m for m in marks if m.role == 'line']) <= 1
+        ordinary = ordinary and len([m for m in marks if m.role == 'point']) <= 1
+        for m in marks:
+            for a in m.artists:
+                if hasattr(a, 'get_drawstyle') and a.get_drawstyle() != 'default': ordinary = False
+                if getattr(getattr(a, 'axes', None), 'name', None) not in (None, 'rectilinear'): ordinary = False
+                if hasattr(a, 'get_transform') and m.axes is not None and a.get_transform() != m.axes.transData:
+                    # Collections carry data through their offset transform.
+                    if not hasattr(a, 'get_offset_transform') or a.get_offset_transform() != m.axes.transData:
+                        ordinary = False
+        entry['capabilities'] = {'dataMorph': bool(ordinary and data and
+            not any(c['svgId'] in rasterized for c in components) and
+            (svg.get('line') or points))}
+        # keyed members (bars by category, cells and hexes by row.col, glowbar / fluxbox parts by
+        # category) let two versions of the plot be tweened member by member
+        keyed = any((m.role == 'bar' and (m.data.get('bar') or {}).get('keys'))
+                    or (m.data.get('field_config') and (m.data.get('cells') or m.data.get('hexmatrix')))
+                    or m.kind in ('glowbar', 'fluxbox') for m in marks)
+        entry['capabilities']['valueMorph'] = bool(keyed and not any(c['svgId'] in rasterized for c in components))
+        if label:
+            entry["label"] = label
+        if points:
+            entry["points"] = points
+        if any(c["svgId"] in rasterized for c in components):
+            entry["rasterized"] = True
+        # additive provenance for auto-promoted series: how identity/data were captured
+        # (identity=artist-label, data=artist — see autotag.py)
+        cap = next((m.data["capture"] for m in marks if m.data.get("capture")), None)
+        if cap:
+            entry["capture"] = cap
+        # additive exact-distribution payload (fp.hist bin edges/counts; opt-in raw values) —
+        # deliberately separate from data{x,y}: bar heights are not original observations
+        dist = next((m.data["distribution"] for m in marks if m.data.get("distribution")), None)
+        if dist:
+            entry["distribution"] = dist
+        # additive surface payload — the complete value→colour contract of a surface (brain) map.
+        # The point of the primitive is that this mapping is DATA, not baked pixels: each part is
+        # listed with its own id and style, so recolouring a region, swapping a colormap or moving a
+        # threshold is a declarative edit that re-renders deterministically.
+        surf_marks = [m for m in marks if m.data.get("surface")]
+        if surf_marks:
+            summary = next((m.data["surface"] for m in surf_marks if m.role == "surface"), {})
+            parts_payload = []
+            for m in surf_marks:
+                if m.role == "surface":
+                    continue
+                p = {k: v for k, v in m.data["surface"].items()
+                     if k not in ("views", "hemispheres", "missingRule", "missingColor")}
+                if _keep(m.gid):
+                    p["ref"] = m.gid
+                p.setdefault("part", m.name or m.role)
+                parts_payload.append(p)
+            entry["surface"] = {**summary, "parts": parts_payload}
+        series_entries.append(entry)
+        series_kinds[entry["id"]] = kinds
+
+    # organize the scaffold guides per axis (+ legend entries + titles + swept text/artists)
+    axes_parts, legend_entries, figure_titles, scaffold_annotations, extras, backgrounds = _organize_guides(guides)
+
+    # guides → manifest guides (axis refs + legend with per-entry svg ids)
+    guide_entries = []
+    legend_present = any(g.role == "legend" for g in guides)
+    for g in guides:
+        if g.role == "axis":
+            guide_entries.append({"id": g.gid, **({} if g.virtual else {"svgId": g.gid}), "role": "axis", "axis": g.axis})
+    if legend_present:
+        # entry ↔ series joined by exact, UNIQUE label text — positional order is not
+        # identity (plan §7). An entry whose text matches no series label (or an ambiguous
+        # duplicated label) keeps its swatch/label as addressable guides, with no series claim.
+        by_label: dict[str, list] = {}
+        for s in series_entries:
+            if s.get("label"):
+                by_label.setdefault(s["label"], []).append(s["id"])
+        # A surface map's legend keys its PARTS, not its series (all its regions live under one
+        # series), so an entry also joins on a unique part name — giving it a ref to the very
+        # element it describes, which is what makes "recolour the block this swatch names" possible.
+        by_part: dict[str, list] = {}
+        for s in series_entries:
+            for prt in (s.get("surface") or {}).get("parts", []):
+                if prt.get("part") and prt.get("ref"):
+                    by_part.setdefault(prt["part"], []).append((s["id"], prt["ref"]))
+        # the authoritative join: the artist the entry stands for (tagger.legend_sources) is one
+        # of a series' artists (or one of a container's children)
+        def series_of_artist(src):
+            children = list(getattr(src, "get_children", lambda: [])()) if src is not None else []
+            for series, marks in by_series.items():
+                for m in marks:
+                    if any(a is src or any(a is c for c in children) for a in m.artists):
+                        return _ids.series_root(series)
+            return None
+
+        entries = []
+        for k in sorted(legend_entries):
+            ent = legend_entries[k]
+            e = {}
+            matches = by_label.get(ent.get("text"), [])
+            if len(matches) == 1:
+                e["series"] = matches[0]
+            part_matches = by_part.get(ent.get("text"), [])
+            if len(part_matches) == 1:
+                e["series"], e["part"] = part_matches[0]
+            joined = series_of_artist(ent.get("source"))
+            if joined is not None and any(s["id"] == joined for s in series_entries):
+                e["series"] = joined
+                e.pop("part", None) if by_part.get(ent.get("text")) is None else None
+            if ent.get("text"):
+                e["text"] = ent["text"]
+            if ent.get("swatch"):
+                e["swatch"] = ent["swatch"]
+            if ent.get("label"):
+                e["label"] = ent["label"]
+            entries.append(e)
+        guide_entries.append({"id": "legend", "svgId": "legend", "role": "legend", "entries": entries})
+
+    # colour scales: one record per control key, listing every group it colours and every colour
+    # key drawing it (colorscale.py). Private capture state (keys starting with "_") never leaves.
+    import copy as _copy
+    scales: dict = {}
+    scale_of_mappable: dict = {}
+    for m in reg.marks:
+        records = ([m.data['color_scale']] if m.data.get('color_scale') else []) + list(m.data.get('color_scales') or [])
+        if not records or not _keep(m.gid):
+            continue
+        for rec in records:  # an fp.image carries one scale per channel
+            entry = scales.get(rec['id'])
+            if entry is None:
+                entry = scales[rec['id']] = _copy.deepcopy(rec)
+            if m.gid not in entry['mappables']:
+                entry['mappables'].append(m.gid)
+            scale_of_mappable[m.gid] = entry
+            if m.gid in rasterized and entry['recolor'] == 'live':
+                entry['recolor'] = 'regenerate'
+    for extra in extra_scales:  # raw colour-mapped artists: a scale named after their gid
+        gid = extra['gid']
+        if not _keep(gid):
+            continue
+        entry = scales.get(extra['record']['id'])
+        if entry is None:
+            entry = scales[extra['record']['id']] = _copy.deepcopy(extra['record'])
+        if gid not in entry['mappables']:
+            entry['mappables'].append(gid)
+        scale_of_mappable[gid] = entry
+        if gid in rasterized and entry['recolor'] == 'live':
+            entry['recolor'] = 'regenerate'
+
+    for g in guides:
+        if g.role == 'colorbar':
+            payload = {k: v for k, v in g.data.items() if not k.startswith('_')}
+            payload['parts'] = [part for part in payload.get('parts', []) if _keep(part['svgId'])]
+            if not _keep(payload.get('mappable')): payload.pop('mappable', None)
+            scale = scale_of_mappable.get(payload.get('mappable'))
+            if scale is not None:
+                payload['colorScale'] = scale['id']
+                if g.gid not in scale['colorbars']:
+                    scale['colorbars'].append(g.gid)
+                if not scale.get('label') and payload.get('label'):
+                    scale['label'] = payload['label']
+            guide_entries.append({'id': g.gid, 'svgId': g.gid, 'role': g.role, **payload})
+
+    overlay_entries = []
+    for m in overlays:
+        if not _keep(m.gid):
+            continue
+        oe = {"id": m.gid, "svgId": m.gid, "role": m.role}
+        mk = mark_kind(m)
+        if mk is not None:
+            oe["kind"] = mk
+        if m.name is not None:
+            oe["name"] = m.name
+        for key in ("label", "between", "p", "text", "stats", "length", "units"):  # carry the annotation text too
+            if key in m.data:
+                oe[key] = m.data[key]
+        if m.gid in rasterized:
+            oe["rasterized"] = True
+        overlay_entries.append(oe)
+    # swept free text → annotation overlays (addressable + animatable like fp.annotation)
+    for a in scaffold_annotations:
+        oe = {"id": a["id"], "svgId": a["id"], "role": "annotation", "kind": "text"}
+        if a.get("text"):
+            oe["text"] = a["text"]
+        overlay_entries.append(oe)
+
+    # swept untagged artists (raw ax.plot lines / collections / patches) → "extra" overlays.
+    # Kept separate from overlay_entries so they group under a single "extras" node in the parts
+    # tree (rather than each becoming a loose ref) while still appearing in the manifest overlays.
+    extra_entries = []
+    for e in extras:
+        ee = {"id": e["id"], "svgId": e["id"], "role": e.get("role", "extra")}
+        if e.get("kind"):
+            ee["kind"] = e["kind"]
+        if e.get("text"):
+            ee["text"] = e["text"]
+        if e["id"] in rasterized:
+            ee["rasterized"] = True
+        extra_entries.append(ee)
+
+    parts = _build_parts_tree(
+        series_entries, axes_parts, legend_entries, figure_titles, overlay_entries,
+        legend_present, extra_entries, series_kinds, backgrounds,
+    )
+    for guide in guide_entries:
+        if guide['role'] == 'colorbar':
+            children = []
+            grouped = {'colorbar-tick': ('ticks', 'tick'),
+                       'colorbar-tick-label': ('tick-labels', 'tick-label'),
+                       'colorbar-gridline': ('gridlines', 'gridline')}
+            for role, (suffix, group_role) in grouped.items():
+                members = [p['svgId'] for p in guide.get('parts', []) if p['role'] == role]
+                if members:
+                    children.append(_group(guide['id'] + '.' + suffix, group_role, members))
+            children.extend(_ref(p['svgId'], p.get('kind'), p['role']) for p in guide.get('parts', [])
+                            if p['role'] not in grouped)
+            parts['children'].append({'id': guide['id'], 'role': 'colorbar', 'kind': 'container',
+                                      'children': children})
+    build = _build_order(series_entries, guide_entries, overlay_entries, reg, figure_titles, extra_entries,
+                         guide_roles={g.role for g in guides})
+
+    out = {
+        "spec": "fluxplot/manifest",
+        "schemaVersion": spec_version,
+        "generator": {
+            "name": "fluxplot",
+            "version": fluxplot_version,
+            "matplotlib": mpl_version,
+        },
+        "plotType": plot_type,
+        "svg": svg_filename,
+        "size": {"width": vbw, "height": vbh, "unit": "pt"},
+        "axes": axes_capture,
+        "series": series_entries,
+        "guides": guide_entries,
+        "overlays": overlay_entries + extra_entries,
+        "parts": parts,
+        "build": build,
+    }
+    if scales:
+        out["colorScales"] = list(scales.values())
+    # ids an older fluxplot gave the same parts (renamed spines; series whose slug changed with
+    # the 0.3.2 slug rule): a consumer resolves saved overrides through them. A key is an old id
+    # or an old id prefix (a series root stands for every part under it).
+    aliases = {g.data["alias"]: g.gid for g in guides if g.data.get("alias") and _keep(g.gid) and g.data["alias"] != g.gid}
+    roots_in_use = {_ids.series_root(series) for series in by_series}
+    legacy_roots = [_ids.legacy_slugify(series) for series in by_series]
+    for series, marks in by_series.items():
+        new_root = _ids.series_root(series)
+        old_root = _ids.legacy_slugify(series)
+        # only an unambiguous rename is aliased: two series that shared the old slug cannot be told apart
+        if (old_root != new_root and old_root not in roots_in_use and legacy_roots.count(old_root) == 1
+                and any(_keep(m.gid) or m.member_gids for m in marks)):
+            aliases[old_root] = new_root
+    if aliases:
+        out["idAliases"] = aliases
+    if style is not None:
+        out["style"] = style
+    if quality is not None:
+        out["quality"] = quality
+    if svg_sha256 is not None:
+        # checksum of the FINAL postprocessed SVG bytes: deterministic (the SVG is
+        # byte-stable) and acyclic (the SVG does not contain the manifest). Consumers use it
+        # to detect a stale/mismatched sidecar pair instead of silently degrading (plan §5).
+        out["artifact"] = {"svgSha256": svg_sha256}
+    return out
+
+
+def axis_value_labels(mpl_axis, numbers) -> dict:
+    """``{"Labels": [...]}`` for a categorical axis (the category each number stands for) or
+    ``{"Iso": [...]}`` for a date axis (ISO-8601), else ``{}``."""
+    converter = getattr(mpl_axis, "get_converter", lambda: getattr(mpl_axis, "converter", None))()
+    module = type(converter).__module__ if converter else ""
+    if module == "matplotlib.category":
+        mapping = getattr(getattr(mpl_axis, "units", None), "_mapping", None) or {}
+        inverse = {float(v): str(k) for k, v in mapping.items()}
+        return {"Labels": [None if v is None else inverse.get(float(v)) for v in numbers]}
+    if module == "matplotlib.dates":
+        from matplotlib.dates import num2date
+        out = []
+        for v in numbers:
+            try:
+                out.append(None if v is None else num2date(v).isoformat())
+            except (ValueError, OverflowError):
+                out.append(None)
+        return {"Iso": out}
+    return {}
+
+
+def figure_scope(figure_guides, reg, present=None, rasterized=None):  # noqa: ARG001 (present: kept for symmetry)
+    """The manifest's figure-scope block from :func:`tagger.autotag_figure`'s tags:
+    ``(figure, guide_entries, overlay_entries, parts_children, build_first, build_last)``.
+
+    ``figure`` is ``{background?, title?, xlabel?, ylabel?, legends: [...], annotations: [...], extras: [...]}``
+    with svg ids; a figure legend is a ``guides[]`` entry (``role: legend``, ``entries`` joined to
+    series by the artist each stands for) and its parts sit under the figure node of the tree."""
+    rasterized = rasterized or set()  # (the caller passes only the tags present in the SVG)
+    fig: dict = {"legends": [], "annotations": [], "extras": []}
+    guide_entries, overlay_entries, children, first, last = [], [], [], [], []
+    legends: dict = {}
+    aliases: dict = {}
+    for g in figure_guides:
+        if g.data.get("alias"):
+            aliases[g.data["alias"]] = g.gid
+        if g.role == "background" and g.text == "figure":
+            fig["background"] = g.gid
+            children.insert(0, _ref(g.gid, _roles.kind_for_role("background"), "background"))  # the ground first
+        elif g.role == "title":
+            fig[g.data.get("slot", "title")] = g.gid
+            children.append(_ref(g.gid, _roles.kind_for_role("title"), "title"))
+            first.append(g.gid)
+        elif g.role == "legend":
+            legends.setdefault(g.gid, {"entries": {}, "background": None})
+        elif g.role == "background" and g.data.get("legend"):
+            legends.setdefault(g.data["legend"], {"entries": {}, "background": None})["background"] = g.gid
+        elif g.role in ("legend-label", "legend-swatch") and g.data.get("legend"):
+            ent = legends.setdefault(g.data["legend"], {"entries": {}, "background": None})["entries"].setdefault(g.index, {})
+            ent["label" if g.role == "legend-label" else "swatch"] = g.gid
+            if g.role == "legend-label":
+                ent["text"] = g.text
+            if g.data.get("_source") is not None:
+                ent["source"] = g.data["_source"]
+        elif g.role == "annotation":
+            fig["annotations"].append({"id": g.gid, "text": g.text})
+            oe = {"id": g.gid, "svgId": g.gid, "role": "annotation", "kind": "text"}
+            if g.text:
+                oe["text"] = g.text
+            overlay_entries.append(oe)
+            children.append(_ref(g.gid, "text", "annotation"))
+            last.append(g.gid)
+        elif g.role == "extra":
+            fig["extras"].append(g.gid)
+            oe = {"id": g.gid, "svgId": g.gid, "role": "extra"}
+            if g.kind:
+                oe["kind"] = g.kind
+            if g.gid in rasterized:
+                oe["rasterized"] = True
+            overlay_entries.append(oe)
+            children.append(_ref(g.gid, g.kind, "extra"))
+            last.append(g.gid)
+
+    def series_id_of(src):
+        kids = list(getattr(src, "get_children", lambda: [])()) if src is not None else []
+        for m in reg.marks:
+            gid = m.gid or (m.member_gids[0] if m.member_gids else None)  # bars have members only
+            if m.series is None or not gid:
+                continue
+            if any(a is src or any(a is c for c in kids) for a in m.artists):
+                root = _ids.series_root(m.series)
+                prefix = gid[: gid.index(root)] if root in gid else ""
+                return prefix + root
+        return None
+
+    for gid, leg in legends.items():
+        entries, kids = [], []
+        if leg["background"]:
+            kids.append(_ref(leg["background"], _roles.kind_for_role("background"), "background"))
+        for k in sorted(leg["entries"]):
+            ent = leg["entries"][k]
+            e = {}
+            joined = series_id_of(ent.get("source"))
+            if joined is not None:
+                e["series"] = joined
+            for key in ("text", "swatch", "label"):
+                if ent.get(key):
+                    e[key] = ent[key]
+            entries.append(e)
+            ek = []
+            if ent.get("swatch"):
+                ek.append(_ref(ent["swatch"], _roles.kind_for_role("legend-swatch"), "legend-swatch"))
+            if ent.get("label"):
+                ek.append(_ref(ent["label"], _roles.kind_for_role("legend-label"), "legend-label"))
+            node = {"id": f"{gid}.entry.{k}", "role": "legend-entry", "kind": "container", "children": ek}
+            if ent.get("text"):
+                node["label"] = ent["text"]
+            kids.append(node)
+        fig["legends"].append(gid)
+        guide_entries.append({"id": gid, "svgId": gid, "role": "legend", "entries": entries})
+        children.append({"id": gid, "role": "legend", "kind": "container", "children": kids})
+    fig = {k: v for k, v in fig.items() if v not in ([], None)}
+    return fig, guide_entries, overlay_entries, children, first, last, aliases
+
+
+def _organize_guides(guides):
+    """Bucket the flat GuideTag list into per-axis parts + legend entries + the figure title."""
+    axes: dict = {}
+    legend_entries: dict = {}
+    figure_titles: list = []  # left/center/right + suptitle can coexist (no last-wins)
+    annotations: list = []  # swept free text → addressable annotation overlays
+    extras: list = []  # swept untagged artists → addressable "extra" content
+    backgrounds: dict = {}  # "axes" / "figure" / "legend" → the background patch's gid
+    for g in guides:
+        if g.data.get("scope") == "figure":
+            continue  # figure-scope tags are organized by figure_scope()
+        if g.role == "background" and g.axis is None:
+            backgrounds[g.text] = g.gid
+        elif g.role == "axis":
+            axes.setdefault(g.axis, {})["gid"] = g.gid
+        elif g.role == "axis-title":
+            axes.setdefault(g.axis, {})["title"] = g.gid
+        elif g.role == "tick-label":
+            axes.setdefault(g.axis, {}).setdefault("ticklabels", []).append(g.gid)
+        elif g.role == "tick":
+            axes.setdefault(g.axis, {}).setdefault("ticks", []).append(g.gid)
+        elif g.role == "gridline":
+            axes.setdefault(g.axis, {}).setdefault("gridlines", []).append(g.gid)
+        elif g.role in ("spine", "background"):
+            axes.setdefault(g.axis, {}).setdefault("spines", []).append(g.gid)
+        elif g.role == "legend-swatch":
+            legend_entries.setdefault(g.index, {})["swatch"] = g.gid
+            if g.data.get("_source") is not None:
+                legend_entries[g.index]["source"] = g.data["_source"]
+        elif g.role == "legend-label":
+            legend_entries.setdefault(g.index, {})["label"] = g.gid
+            legend_entries[g.index]["text"] = g.text
+            if g.data.get("_source") is not None:
+                legend_entries[g.index]["source"] = g.data["_source"]
+        elif g.role == "title":
+            figure_titles.append(g.gid)
+        elif g.role == "annotation":
+            annotations.append({"id": g.gid, "text": g.text})
+        elif g.role == "extra":
+            extras.append({"id": g.gid, "kind": g.kind})
+        elif g.role == "label" and g.gid.startswith("extra."):  # a swept anchored box's text
+            extras.append({"id": g.gid, "kind": g.kind, "role": "label", "text": g.text})
+    return axes, legend_entries, figure_titles, annotations, extras, backgrounds
+
+
+def _group(gid: str, group_role: str, members: list) -> dict:
+    """A manifest-only node grouping sibling leaves so a consumer can act on all at once.
+
+    The node mirrors its members' data-kind (a group of tick labels edits like text, a
+    group of gridlines like a line) so consumers can pick property sets without the DOM, and
+    names the members' role (``memberRole``) so each member leaf is classified without
+    parsing its id.
+    """
+    node = {"id": gid, "role": "group", "groupRole": group_role, "memberRole": group_role,
+            "members": list(members)}
+    k = _roles.kind_for_role(group_role)
+    if k is not None:
+        node["kind"] = k
+    return node
+
+
+def _ref(gid: str, kind=None, role=None) -> dict:
+    """A leaf reference into the SVG, carrying its role and the data-kind hint when known."""
+    node = {"ref": gid}
+    if role is not None:
+        node["role"] = role
+    if kind is not None:
+        node["kind"] = kind
+    return node
+
+
+def _build_parts_tree(
+    series_entries, axes_parts, legend_entries, figure_titles, overlay_entries, legend_present,
+    extra_entries=(), series_kinds=None, backgrounds=None,
+) -> dict:
+    series_kinds = series_kinds or {}
+    backgrounds = backgrounds or {}
+    plot_children = []
+    if backgrounds.get("axes"):  # the ground comes first, as it is drawn
+        plot_children.append(_ref(backgrounds["axes"], _roles.kind_for_role("background"), "background"))
+
+    # axes → real <g id="axis.x"> nodes, each with spine + grouped ticks/labels/gridlines + title
+    for which in ("x", "y", "z", "x2", "y2"):
+        ap = axes_parts.get(which)
+        if not ap:
+            continue
+        kids = []
+        for sp in ap.get("spines", []):
+            kids.append(_ref(sp, _roles.kind_for_role("spine"), "spine"))
+        if ap.get("ticks"):
+            kids.append(_group(f"axis.{which}.ticks", "tick", ap["ticks"]))
+        if ap.get("ticklabels"):
+            kids.append(_group(f"axis.{which}.tick-labels", "tick-label", ap["ticklabels"]))
+        if ap.get("gridlines"):
+            kids.append(_group(f"axis.{which}.gridlines", "gridline", ap["gridlines"]))
+        if ap.get("title"):
+            kids.append(_ref(ap["title"], _roles.kind_for_role("axis-title"), "axis-title"))
+        plot_children.append(
+            {
+                "id": ap.get("gid", f"axis.{which}"),
+                "role": "axis",
+                "axis": which,
+                "kind": "container",
+                "children": kids,
+            }
+        )
+
+    # series → line + grouped points/bars + ANY other tagged role. The generic
+    # tail covers area/errorbar/box AND custom plot kinds (x-violin, x-heatmap-cell,
+    # x-stem, x-trajectory, x-contour, …) so every drawn series part is addressable
+    # and no series becomes a childless phantom node.
+    for s in series_entries:
+        kinds = series_kinds.get(s["id"], {})
+        kids = []
+        by_role = {}
+        for component in s["components"]:
+            by_role.setdefault(component["role"], []).append(component)
+        for role, components in by_role.items():
+            kind = kinds.get(role, _roles.kind_for_role(role))
+            if role == "point" or any(c.get("members") for c in components):
+                for c in components:
+                    if c.get("members"):
+                        node = _group(c.get("groupId", c["svgId"]), role, c["members"])
+                        node["memberRole"] = c.get("memberRole", role)
+                        mk = _roles.kind_for_role(node["memberRole"])
+                        if mk is not None:
+                            node["kind"] = mk
+                        kids.append(node)
+                    else:
+                        kids.append(_ref(c["svgId"], kind, role))
+            elif role == "bar" or role in COMPOSITE_ROLES or len(components) > 1:
+                plural = "bars" if role == "bar" else COMPOSITE_ROLES.get(role, role + "-parts")
+                kids.append(_group(s["id"] + "." + plural, role, [c["svgId"] for c in components]))
+            else:
+                kids.append(_ref(components[0]["svgId"], kind, role))
+        node = {"id": s["id"], "role": "series", "kind": "container", "children": kids,
+                "label": s.get("label") or s["name"]}
+        plot_children.append(node)
+
+    for o in overlay_entries:
+        plot_children.append(_ref(o["svgId"], o.get("kind"), o.get("role")))
+
+    # untagged user-drawn artists → one "extras" group so a consumer can act on all at once
+    if extra_entries:
+        plot_children.append(_group("extras", "extra", [e["svgId"] for e in extra_entries]))
+
+    figure_children = []
+    if backgrounds.get("figure"):
+        figure_children.append(_ref(backgrounds["figure"], _roles.kind_for_role("background"), "background"))
+    figure_children.append(
+        {"id": "plot-area", "role": "plot-area", "kind": "container", "children": plot_children}
+    )
+    if legend_present:
+        leg_kids = []
+        if backgrounds.get("legend"):
+            leg_kids.append(_ref(backgrounds["legend"], _roles.kind_for_role("background"), "background"))
+        for k in sorted(legend_entries):
+            ent = legend_entries[k]
+            ek = []
+            if ent.get("swatch"):
+                ek.append(_ref(ent["swatch"], _roles.kind_for_role("legend-swatch"), "legend-swatch"))
+            if ent.get("label"):
+                ek.append(_ref(ent["label"], _roles.kind_for_role("legend-label"), "legend-label"))
+            entry = {"id": f"legend.entry.{k}", "role": "legend-entry", "kind": "container", "children": ek}
+            if ent.get("text"):
+                entry["label"] = ent["text"]
+            leg_kids.append(entry)
+        figure_children.append(
+            {"id": "legend", "role": "legend", "kind": "container", "children": leg_kids}
+        )
+    for t in figure_titles:
+        figure_children.append(_ref(t, _roles.kind_for_role("title"), "title"))
+    return {"id": "figure", "role": "figure", "kind": "container", "children": figure_children}
+
+
+def _build_order(series_entries, guide_entries, overlay_entries, reg, figure_titles=(), extra_entries=(),
+                 guide_roles=()) -> dict:
+    order = []
+    for g in guide_entries:
+        if g["role"] == "axis":
+            order.append(g.get("svgId", g["id"]))
+    order.extend(g['svgId'] for g in guide_entries if g['role'] == 'colorbar')
+    order.extend(figure_titles)  # titles reveal with the axes (phase 0)
+    if "gridline" in guide_roles:  # the legacy figure-wide token, only when gridlines exist
+        order.append("gridlines")
+    # Use the same component inventory as the tree. Unknown/extension roles are
+    # ordinary drawable parts, not exceptions silently excluded from animation.
+    for s in series_entries:
+        order.extend(c["svgId"] for c in s["components"] if c["role"] == "line")
+    for s in series_entries:
+        order.extend(c["svgId"] for c in s["components"] if c["role"] != "line")
+    if any(g["role"] == "legend" for g in guide_entries):
+        order.append("legend")
+    for o in overlay_entries:
+        order.append(o["svgId"])
+    for e in extra_entries:
+        order.append(e["svgId"])
+
+    # every role a consumer may animate: the marks' roles, their members' roles (hexes, cells,
+    # contour bands) and the scaffold/guide roles that are present (legend, colorbar, title, …)
+    roles_present = {m.role for m in reg.marks} | {"axis", "gridline"} | set(guide_roles)
+    for s in series_entries:
+        roles_present.update(c["memberRole"] for c in s["components"] if c.get("memberRole"))
+    if extra_entries:
+        roles_present.add("extra")
+    return {"order": list(dict.fromkeys(order)), "presets": _presets.presets_for(sorted(roles_present))}