flextool 4.0.0__py3-none-any.whl

flextool/plot_outputs/plan.py

@@ -0,0 +1,1787 @@
+"""PlotPlan -- pre-computed plot plans for instant rendering.
+
+A PlotPlan captures everything needed to render any file page of a plot
+without re-running dimension rules, layout computation, or color mapping.
+Plans are saved alongside parquet files and loaded by the viewer.
+
+File format:
+  {result_key}__{sub_config}_plan.json  -- metadata, layout, colors, batch structure
+  {result_key}__{sub_config}_plan.parquet -- processed DataFrame (post dimension rules)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from flextool.lean_parquet import read_lean_parquet, write_lean_parquet
+import pandas as pd
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from flextool.plot_outputs.config import PlotConfig
+
+logger = logging.getLogger(__name__)
+
+
+# Bump when the on-disk PlotPlan schema or pagination semantics change so
+# stale plans get recomputed instead of silently mis-applied. Old JSONs
+# without a schema_version (or with a lower one) are ignored by
+# load_plot_plan and the GUI's compute_live_plan path takes over.
+PLAN_SCHEMA_VERSION = 3
+
+
+# ---------------------------------------------------------------------------
+#  JSON helper: make numpy / tuple types serializable
+# ---------------------------------------------------------------------------
+
+def _json_safe(obj: Any) -> Any:
+    """Recursively convert numpy scalars, tuples, etc. into JSON-safe types."""
+    if obj is None:
+        return None
+    if isinstance(obj, (np.integer,)):
+        return int(obj)
+    if isinstance(obj, (np.floating,)):
+        return float(obj)
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, tuple):
+        return list(obj)
+    if isinstance(obj, dict):
+        return {str(k): _json_safe(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_json_safe(v) for v in obj]
+    return obj
+
+
+# ---------------------------------------------------------------------------
+#  Time-axis label extraction (shared by planner + loader)
+# ---------------------------------------------------------------------------
+
+def _extract_time_labels(
+    df: pd.DataFrame,
+) -> tuple[list[str], list[str] | None, int]:
+    """Extract x-axis time values and optional period labels from a DataFrame.
+
+    - ``time_values``: last MultiIndex level as strings, or the whole index
+      when the DataFrame has a plain Index.
+    - ``period_labels``: values of a level named (case-insensitive) ``period``
+      or ``solve_period`` when the index is a MultiIndex; otherwise ``None``.
+    - ``max_period_label_len``: longest period label length, or 0 when there
+      are no period labels.
+
+    Mirrors the extraction pattern used in ``_compute_time_plan`` so both the
+    planner and the plan loader agree on how these fields are derived.
+    """
+    period_labels: list[str] | None = None
+    if isinstance(df.index, pd.MultiIndex):
+        time_values = df.index.get_level_values(-1).astype(str).tolist()
+        for lvl_i, name in enumerate(df.index.names[:-1]):
+            if name and str(name).lower() in ('period', 'solve_period'):
+                period_labels = (
+                    df.index.get_level_values(lvl_i).astype(str).tolist()
+                )
+                break
+    else:
+        time_values = df.index.astype(str).tolist()
+    max_len = (
+        max((len(lbl) for lbl in period_labels), default=0)
+        if period_labels else 0
+    )
+    return time_values, period_labels, max_len
+
+
+# ---------------------------------------------------------------------------
+#  PlotPlan dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PlotPlan:
+    """Pre-computed plan for rendering a set of figures."""
+
+    chart_type: str  # 'lines', 'stack', 'bar'
+    plot_name: str
+    total_file_count: int
+
+    # The processed DataFrame -- post dimension rules, time-sliced,
+    # file-member filtered, zero-filtered, multiplied.
+    # For bar charts: index = bar labels, columns = data.
+    # For time charts: index = time, columns = data.
+    processed_df: pd.DataFrame
+
+    # Effective plots structure: list of (title, column_labels_list)
+    # column_labels_list identifies which columns of processed_df belong
+    # to this subplot.
+    # For bars: (title, {rows: [...], cols: [...]}) with row and column selectors.
+    # For time-series: (title, column_labels_list).
+    effective_plot_specs: list[tuple[str | None, list | dict]]
+
+    # Batch structure: file_batches[i] = list of indices into effective_plot_specs
+    file_batches: list[list[int]]
+
+    # Visual config
+    shared_color_map: dict[str, tuple] | None = None
+    axis_bounds: list | None = None
+
+    # Color-template hints carried so the viewer can rebuild ONLY the
+    # shared_color_map (colors + file order) in place when the user edits
+    # the project's plot_settings.yaml — without recomputing dimension
+    # rules, layout, or the processed DataFrame. Mirror cfg.color_category /
+    # cfg.color_entity_class. Both None for plots that don't color by
+    # template (or non-shared legends).
+    color_category: str | None = None
+    color_entity_class: str | None = None
+
+    # For simple (non-stacked, non-grouped) bar charts only: the column-index
+    # level whose value supplies each bar's color, resolved from
+    # ``color_entity_class`` via ``resolve_color_bar_level``. Lines / stacked /
+    # grouped charts don't need this — their colored level is fixed by a role
+    # char. ``None`` => bars fall back to the default single color.
+    color_bar_level: str | None = None
+
+    # Layout (stored as plain dict for JSON serialization)
+    layout_type: str = ''  # 'line' or 'bar'
+    layout_params: dict = field(default_factory=dict)
+
+    # Figure builder parameters
+    sub_levels: list[int] = field(default_factory=list)
+    item_level_names: list[str] = field(default_factory=list)
+    time_index_values: list[str] | None = None  # serialized time index
+    period_labels: list[str] | None = None      # period name per x-position
+    max_period_label_len: int = 0               # longest period label (for overlap check)
+
+    # Config params for figure builder
+    subplots_per_row: int = 2
+    legend_position: str = 'right'
+    xlabel: str | None = None
+    ylabel: str | None = None
+    bar_orientation: str = 'horizontal'
+    axis_tick_format: str = 'dynamic'
+    always_include_zero_in_axis: bool = True
+    value_label: str | None = None
+    base_bar_length: float = 4.0
+    skip_data_with_only_zeroes: bool = False
+
+    # Per-subplot global y-axis range across full time series.
+    # List of (min, max) tuples, one per effective_plot_spec entry.
+    # Used by the result viewer to keep y-axis stable when scrolling.
+    subplot_y_ranges: list[tuple[float, float]] = field(default_factory=list)
+
+    # Bar-specific level metadata
+    stack_levels: list[int] = field(default_factory=list)
+    stack_level_names: list[str] = field(default_factory=list)
+    expand_axis_levels: list[int] = field(default_factory=list)
+    expand_axis_level_names: list[str] = field(default_factory=list)
+    grouped_bar_levels: list[int] = field(default_factory=list)
+    grouped_bar_level_names: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+#  save / load
+# ---------------------------------------------------------------------------
+
+def save_plot_plan(
+    plan: PlotPlan, output_dir: Path, result_key: str, sub_config: str,
+) -> None:
+    """Save a PlotPlan to disk as JSON metadata + parquet data."""
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    prefix = f"{result_key}__{sub_config}"
+
+    # write_lean_parquet handles single-level MultiIndex correctly, so no
+    # flattening is needed (the old pandas-metadata approach required it).
+    write_lean_parquet(plan.processed_df, output_dir / f"{prefix}_plan.parquet")
+
+    # Serialize effective_plot_specs: titles may be None, selectors are lists
+    # of scalars or tuples.  JSON-encode tuples as lists.
+    specs_json: list[list] = []
+    for title, selector in plan.effective_plot_specs:
+        specs_json.append([title, _json_safe(selector)])
+
+    # Build JSON-serializable metadata
+    meta: dict[str, Any] = {
+        'schema_version': PLAN_SCHEMA_VERSION,
+        'chart_type': plan.chart_type,
+        'plot_name': plan.plot_name,
+        'total_file_count': plan.total_file_count,
+        'effective_plot_specs': specs_json,
+        'file_batches': plan.file_batches,
+        'shared_color_map': (
+            {k: list(v) for k, v in plan.shared_color_map.items()}
+            if plan.shared_color_map else None
+        ),
+        'color_category': plan.color_category,
+        'color_entity_class': plan.color_entity_class,
+        'color_bar_level': plan.color_bar_level,
+        'axis_bounds': _json_safe(plan.axis_bounds),
+        'layout_type': plan.layout_type,
+        'layout_params': _json_safe(plan.layout_params),
+        'sub_levels': plan.sub_levels,
+        'item_level_names': plan.item_level_names,
+        # time_index_values / period_labels / max_period_label_len are
+        # intentionally NOT serialized — ``load_plot_plan`` reconstructs
+        # them from ``processed_df.index`` via ``_extract_time_labels``.
+        # Old JSON files that still carry these keys are accepted on load
+        # so rolling out this change doesn't force a plan regen.
+        'subplots_per_row': plan.subplots_per_row,
+        'legend_position': plan.legend_position,
+        'xlabel': plan.xlabel,
+        'ylabel': plan.ylabel,
+        'bar_orientation': plan.bar_orientation,
+        'axis_tick_format': plan.axis_tick_format,
+        'always_include_zero_in_axis': plan.always_include_zero_in_axis,
+        'value_label': plan.value_label,
+        'base_bar_length': plan.base_bar_length,
+        'skip_data_with_only_zeroes': plan.skip_data_with_only_zeroes,
+        'stack_levels': plan.stack_levels,
+        'stack_level_names': plan.stack_level_names,
+        'expand_axis_levels': plan.expand_axis_levels,
+        'expand_axis_level_names': plan.expand_axis_level_names,
+        'grouped_bar_levels': plan.grouped_bar_levels,
+        'grouped_bar_level_names': plan.grouped_bar_level_names,
+        'subplot_y_ranges': [list(r) for r in plan.subplot_y_ranges],
+        # Legacy: lean_parquet handles single-level MultiIndex now; kept
+        # so old plan JSON files still load via the reconstruction below.
+        'col_was_single_multi': False,
+        'idx_was_single_multi': False,
+    }
+
+    with open(output_dir / f"{prefix}_plan.json", 'w') as f:
+        json.dump(meta, f, indent=2, default=_json_safe)
+
+
+def load_plot_plan(
+    plan_dir: Path, result_key: str, sub_config: str,
+) -> PlotPlan | None:
+    """Load a PlotPlan from disk. Returns None if files don't exist."""
+    plan_dir = Path(plan_dir)
+    prefix = f"{result_key}__{sub_config}"
+
+    json_path = plan_dir / f"{prefix}_plan.json"
+    parquet_path = plan_dir / f"{prefix}_plan.parquet"
+
+    if not json_path.exists() or not parquet_path.exists():
+        return None
+
+    try:
+        with open(json_path, 'r', encoding='utf-8') as f:
+            meta = json.load(f)
+
+        # Reject stale schemas so a code change that affects pagination
+        # or plan content does not silently re-use plans saved before
+        # the change. compute_live_plan will rebuild from current code.
+        if meta.get('schema_version', 0) != PLAN_SCHEMA_VERSION:
+            return None
+
+        df = read_lean_parquet(parquet_path)
+
+        # Reconstruct single-level MultiIndex if it was flattened on save
+        if meta.get('col_was_single_multi', False):
+            df.columns = pd.MultiIndex.from_arrays(
+                [df.columns], names=[df.columns.name]
+            )
+        if meta.get('idx_was_single_multi', False):
+            df.index = pd.MultiIndex.from_arrays(
+                [df.index], names=[df.index.name]
+            )
+
+        # Reconstruct color map tuples
+        color_map = None
+        if meta.get('shared_color_map'):
+            color_map = {k: tuple(v) for k, v in meta['shared_color_map'].items()}
+
+        # Reconstruct effective_plot_specs as list of (title, selector)
+        raw_specs = meta.get('effective_plot_specs', [])
+        effective_plot_specs: list[tuple[str | None, list]] = [
+            (s[0], s[1]) for s in raw_specs
+        ]
+
+        chart_type = meta['chart_type']
+        # Time-axis fields: prefer values carried in old-format JSON (so
+        # rolling out the "don't serialize them" change doesn't force a
+        # plan regen). For new-format JSON, reconstruct from
+        # ``processed_df.index`` — but only for time-based charts. Bar
+        # charts never populate these (matching ``_compute_bar_plan``
+        # semantics), so we leave them at their None/0 defaults.
+        has_legacy_time_fields = (
+            'time_index_values' in meta
+            or 'period_labels' in meta
+            or 'max_period_label_len' in meta
+        )
+        if has_legacy_time_fields or chart_type == 'bar':
+            time_index_values = meta.get('time_index_values')
+            period_labels = meta.get('period_labels')
+            max_period_label_len = meta.get('max_period_label_len', 0)
+        else:
+            time_index_values, period_labels, max_period_label_len = (
+                _extract_time_labels(df)
+            )
+
+        plan = PlotPlan(
+            chart_type=chart_type,
+            plot_name=meta['plot_name'],
+            total_file_count=meta['total_file_count'],
+            processed_df=df,
+            effective_plot_specs=effective_plot_specs,
+            file_batches=meta['file_batches'],
+            shared_color_map=color_map,
+            color_category=meta.get('color_category'),
+            color_entity_class=meta.get('color_entity_class'),
+            color_bar_level=meta.get('color_bar_level'),
+            axis_bounds=meta.get('axis_bounds'),
+            layout_type=meta.get('layout_type', ''),
+            layout_params=meta.get('layout_params', {}),
+            sub_levels=meta.get('sub_levels', []),
+            item_level_names=meta.get('item_level_names', []),
+            time_index_values=time_index_values,
+            period_labels=period_labels,
+            max_period_label_len=max_period_label_len,
+            subplot_y_ranges=[tuple(r) for r in meta.get('subplot_y_ranges', [])],
+            subplots_per_row=meta.get('subplots_per_row', 2),
+            legend_position=meta.get('legend_position', 'right'),
+            xlabel=meta.get('xlabel'),
+            ylabel=meta.get('ylabel'),
+            bar_orientation=meta.get('bar_orientation', 'horizontal'),
+            axis_tick_format=meta.get('axis_tick_format', 'dynamic'),
+            always_include_zero_in_axis=meta.get('always_include_zero_in_axis', True),
+            value_label=meta.get('value_label'),
+            base_bar_length=meta.get('base_bar_length', 4.0),
+            skip_data_with_only_zeroes=meta.get('skip_data_with_only_zeroes', False),
+            stack_levels=meta.get('stack_levels', []),
+            stack_level_names=meta.get('stack_level_names', []),
+            expand_axis_levels=meta.get('expand_axis_levels', []),
+            expand_axis_level_names=meta.get('expand_axis_level_names', []),
+            grouped_bar_levels=meta.get('grouped_bar_levels', []),
+            grouped_bar_level_names=meta.get('grouped_bar_level_names', []),
+        )
+
+        # Compute subplot_y_ranges from data if not stored in the plan file
+        if not plan.subplot_y_ranges and plan.chart_type in ('lines', 'stack'):
+            _backfill_subplot_y_ranges(plan)
+
+        return plan
+    except Exception as exc:
+        logger.warning("Failed to load plot plan %s/%s: %s", result_key, sub_config, exc)
+        return None
+
+
+def _add_y_buffer(lo: float, hi: float, fraction: float = 0.05) -> tuple[float, float]:
+    """Add a small buffer to y-axis range so extremes are fully visible."""
+    span = hi - lo
+    if span == 0:
+        return (lo - 0.5, hi + 0.5) if lo == 0 else (lo * 0.95, hi * 1.05)
+    return (lo - span * fraction, hi + span * fraction)
+
+
+def _backfill_subplot_y_ranges(plan: PlotPlan) -> None:
+    """Compute subplot_y_ranges from the plan's processed_df.
+
+    Called for plans loaded from disk that predate the subplot_y_ranges field.
+    """
+    include_zero = plan.always_include_zero_in_axis
+    ranges: list[tuple[float, float]] = []
+    for _title, selector in plan.effective_plot_specs:
+        df_sub = _select_time_columns(plan.processed_df, selector)
+        lo, hi = 0.0, 0.0
+        if isinstance(df_sub, pd.Series):
+            vals = df_sub.dropna()
+            if len(vals):
+                lo, hi = float(vals.min()), float(vals.max())
+        elif isinstance(df_sub, pd.DataFrame):
+            num = df_sub.select_dtypes(include='number')
+            if not num.empty:
+                lo, hi = float(num.min().min()), float(num.max().max())
+        if include_zero:
+            lo = min(lo, 0.0)
+            hi = max(hi, 0.0)
+        ranges.append(_add_y_buffer(lo, hi))
+    plan.subplot_y_ranges = ranges
+
+
+# ---------------------------------------------------------------------------
+#  build_figure_from_plan  (the fast path)
+# ---------------------------------------------------------------------------
+
+def _select_bar_rows(df: pd.DataFrame, selector: list) -> pd.DataFrame:
+    """Select rows from a bar DataFrame using the stored index labels."""
+    if not selector:
+        return df
+    # Reconstruct tuples for MultiIndex row selection
+    if isinstance(df.index, pd.MultiIndex):
+        idx_labels = [tuple(s) if isinstance(s, list) else s for s in selector]
+        mask = df.index.isin(idx_labels)
+        return df.loc[mask]
+    # Unwrap single-element lists that originate from a single-level MultiIndex
+    # encoded via _encode_row_selector then JSON-roundtripped.
+    flat_sel = [s[0] if isinstance(s, list) and len(s) == 1 else s for s in selector]
+    return df.loc[df.index.isin(flat_sel)]
+
+
+def _select_time_columns(df: pd.DataFrame, selector: list) -> pd.DataFrame:
+    """Select columns from a time-series DataFrame using stored column labels."""
+    if selector is None or len(selector) == 0:
+        return df
+    if isinstance(df.columns, pd.MultiIndex):
+        col_tuples = [tuple(c) if isinstance(c, list) else c for c in selector]
+        try:
+            mask = df.columns.isin(col_tuples)
+        except (AssertionError, ValueError):
+            # MultiIndex nlevels mismatch — fall back to string matching
+            col_strs = {str(c) for c in col_tuples}
+            mask = pd.array([str(c) in col_strs for c in df.columns], dtype=bool)
+        if mask.any():
+            return df.loc[:, mask]
+        # Fallback: try matching as strings
+        col_strs = [str(c) for c in col_tuples]
+        str_cols = [str(c) for c in df.columns]
+        mask2 = pd.Index(str_cols).isin(col_strs)
+        if mask2.any():
+            return df.loc[:, mask2]
+        return df  # no match at all — return full DataFrame rather than empty
+    # Non-MultiIndex columns: unwrap single-element lists from JSON round-trip
+    flat_sel = []
+    for s in selector:
+        if isinstance(s, list):
+            flat_sel.append(s[0] if len(s) == 1 else tuple(s))
+        else:
+            flat_sel.append(s)
+    valid = [s for s in flat_sel if s in df.columns]
+    return df[valid] if valid else df
+
+
+def build_figure_from_plan(
+    plan: PlotPlan,
+    file_index: int = 0,
+    plot_rows: tuple[int, int] | None = None,
+) -> 'Figure | None':
+    """Build a single Figure from a pre-computed PlotPlan.
+
+    This is the fast path -- no dimension rules, no layout computation,
+    just direct figure building from pre-computed data.
+
+    For time-series plans whose *processed_df* covers the full timeline,
+    pass *plot_rows* ``(start, start + duration)`` to display a sub-range.
+    """
+    from flextool.plot_outputs.subplot_helpers import LineLayoutParams, BarLayoutParams
+
+    if file_index >= plan.total_file_count or file_index < 0:
+        return None
+
+    # For time-series plans, slice to the requested window.
+    # When slicing, use pre-computed global y-ranges so the axis stays stable.
+    # Skip slicing when the range covers the full data (nothing to slice).
+    processed_df = plan.processed_df
+    time_vals = plan.time_index_values
+    period_labels = plan.period_labels
+    use_global_y_ranges = False
+    # *expected_x_length* pins the time-axis xlim to (start, end) regardless
+    # of how short the underlying data turns out to be — keeps the time
+    # axis stable when scenarios with different model horizons are compared
+    # side by side.  Only meaningful for time-series charts.
+    expected_x_length: int | None = None
+    if plot_rows is not None and plan.chart_type != 'bar':
+        start, end = plot_rows
+        expected_x_length = max(0, end - start)
+        actually_slicing = start > 0 or end < len(processed_df)
+        if actually_slicing:
+            processed_df = processed_df.iloc[start:end]
+            if time_vals is not None:
+                time_vals = time_vals[start:end]
+            if period_labels is not None:
+                period_labels = period_labels[start:end]
+        if plan.subplot_y_ranges:
+            use_global_y_ranges = True
+
+    # Reconstruct effective_plots for the requested batch
+    batch_indices = plan.file_batches[file_index]
+    effective_plots: list[tuple[str | None, pd.DataFrame]] = []
+    for idx in batch_indices:
+        title, selector = plan.effective_plot_specs[idx]
+        if plan.chart_type == 'bar':
+            # selector may be a dict with 'rows'/'cols' keys (new format)
+            # or a plain list of row labels (old format, backward compat)
+            if isinstance(selector, dict):
+                df_sub = _select_bar_rows(processed_df, selector.get('rows', []))
+                col_sel = selector.get('cols')
+                if col_sel:
+                    df_sub = _select_time_columns(df_sub, col_sel)
+            else:
+                df_sub = _select_bar_rows(processed_df, selector)
+        else:
+            df_sub = _select_time_columns(processed_df, selector)
+        effective_plots.append((title, df_sub))
+
+    if not effective_plots:
+        return None
+
+    # Reconstruct time_index
+    time_index = None
+    if time_vals is not None:
+        time_index = pd.Index(time_vals)
+
+    # Reconstruct layout
+    if plan.layout_type == 'line':
+        layout = LineLayoutParams(**plan.layout_params)
+    elif plan.layout_type == 'bar':
+        # The category-label margin is computed once at plan-build time
+        # (_compute_bar_layout → _bar_label_width_inches: the longest label
+        # ACTUALLY drawn across all pages, not a longest-group + longest-bar
+        # sum) and stored, so every page reserves the same margin — the plot
+        # area stays at the same horizontal position when paging, and render
+        # stays fast (no recompute).
+        layout = BarLayoutParams(**plan.layout_params)
+    else:
+        return None
+
+    # Determine axis bounds — use global y-ranges when time-slicing
+    axis_bounds = plan.axis_bounds
+    if use_global_y_ranges and plan.subplot_y_ranges:
+        # Slice to match the current batch (batch_indices are global positions)
+        axis_bounds = [
+            plan.subplot_y_ranges[i]
+            for i in batch_indices
+            if i < len(plan.subplot_y_ranges)
+        ]
+
+    # Build the figure
+    if plan.chart_type == 'lines':
+        from flextool.plot_outputs.plot_lines import _build_lines_figure
+        return _build_lines_figure(
+            effective_plots, plan.plot_name, plan.sub_levels,
+            plan.item_level_names, time_index,
+            plan.subplots_per_row, plan.legend_position,
+            plan.xlabel, plan.ylabel,
+            axis_bounds, plan.axis_tick_format,
+            plan.always_include_zero_in_axis,
+            layout, plan.shared_color_map,
+            period_labels=period_labels,
+            expected_x_length=expected_x_length,
+        )
+    elif plan.chart_type == 'stack':
+        from flextool.plot_outputs.plot_lines import _build_stack_figure
+        return _build_stack_figure(
+            effective_plots, plan.plot_name, plan.sub_levels,
+            plan.item_level_names, time_index,
+            plan.subplots_per_row, plan.legend_position,
+            plan.xlabel, plan.ylabel,
+            axis_bounds, plan.axis_tick_format,
+            plan.always_include_zero_in_axis,
+            layout, plan.shared_color_map,
+            period_labels=period_labels,
+            expected_x_length=expected_x_length,
+        )
+    elif plan.chart_type == 'bar':
+        from flextool.plot_outputs.plot_bars import _build_bar_figure
+
+        # Resolve value_label
+        value_fmt = None
+        if plan.value_label is True or plan.value_label == 'true':
+            value_fmt = 'dynamic'
+        elif plan.value_label:
+            value_fmt = str(plan.value_label)
+
+        batch_title = (
+            f"{plan.plot_name} ({file_index + 1}/{plan.total_file_count})"
+            if plan.total_file_count > 1 else plan.plot_name
+        )
+        return _build_bar_figure(
+            effective_plots, plan.processed_df, batch_title, '',
+            plan.stack_levels, plan.stack_level_names,
+            plan.expand_axis_levels, plan.expand_axis_level_names,
+            plan.sub_levels,
+            plan.grouped_bar_levels, plan.grouped_bar_level_names,
+            plan.legend_position, plan.subplots_per_row,
+            plan.xlabel, plan.ylabel,
+            plan.bar_orientation, plan.base_bar_length,
+            value_fmt,
+            plan.axis_bounds, plan.axis_tick_format,
+            plan.always_include_zero_in_axis,
+            layout, plan.shared_color_map,
+            plan.skip_data_with_only_zeroes,
+            color_bar_level=plan.color_bar_level,
+        )
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+#  _encode_column_selector / _encode_row_selector
+# ---------------------------------------------------------------------------
+
+def _encode_column_selector(
+    df_sub: pd.DataFrame,
+    df_full: pd.DataFrame,
+    sub_levels: list[int] | None = None,
+    sub_value=None,
+) -> list:
+    """Encode columns of df_sub as a JSON-serializable selector list.
+
+    The selector must be usable with ``df_full.columns.isin(...)`` at
+    reconstruction time. ``_extract_subplot_data`` applies ``xs`` to
+    df_full, which drops the sub-levels, so df_sub's column tuples are
+    NARROWER than df_full's. When *sub_levels* and *sub_value* are
+    provided, we reinsert the sub values at the correct level positions
+    so the stored selector matches df_full's full-width tuples.
+    """
+    if not isinstance(df_full.columns, pd.MultiIndex):
+        return df_sub.columns.tolist()
+    if not sub_levels or sub_value is None:
+        # Nothing was dropped (or caller didn't ask) — df_sub already
+        # matches df_full's level count.
+        return [list(c) if isinstance(c, tuple) else [c] for c in df_sub.columns]
+    sub_vals = sub_value if isinstance(sub_value, tuple) else (sub_value,)
+    if len(sub_vals) != len(sub_levels):
+        # Mismatch — best effort, fall back to reduced form.
+        return [list(c) if isinstance(c, tuple) else [c] for c in df_sub.columns]
+    sub_positions = dict(zip(sub_levels, sub_vals))
+    full_width = df_full.columns.nlevels
+    result: list[list] = []
+    for c in df_sub.columns:
+        reduced = list(c) if isinstance(c, tuple) else [c]
+        full: list = [None] * full_width
+        for lvl, val in sub_positions.items():
+            if 0 <= lvl < full_width:
+                full[lvl] = val
+        r_iter = iter(reduced)
+        for i in range(full_width):
+            if full[i] is None:
+                try:
+                    full[i] = next(r_iter)
+                except StopIteration:
+                    break
+        result.append(full)
+    return result
+
+
+def _encode_row_selector(df_sub: pd.DataFrame) -> list:
+    """Encode the row index labels of df_sub for bar charts."""
+    if isinstance(df_sub.index, pd.MultiIndex):
+        return [list(idx) for idx in df_sub.index]
+    return df_sub.index.tolist()
+
+
+# ---------------------------------------------------------------------------
+#  _compute_time_plan / _compute_bar_plan
+# ---------------------------------------------------------------------------
+
+def _compute_time_plan(
+    df_fm: pd.DataFrame,
+    effective_plot_name: str,
+    cfg: 'PlotConfig',
+    fm_stack_levels: list[int],
+    fm_subplot_levels: list[int],
+    fm_line_levels: list[int],
+    axis_bounds,
+    plot_rows: tuple[int, int],
+    color_path: Path | None = None,
+) -> PlotPlan | None:
+    """Compute a PlotPlan for a time-series (lines or stack) chart.
+
+    Replicates the planning steps of build_line_figures() and
+    build_stack_figures() without actually creating matplotlib Figures.
+    """
+    from flextool.plot_outputs.plot_lines import (
+        _build_effective_plots, _compute_line_layout, _make_file_batches,
+        _get_column_items,
+    )
+    from flextool.plot_outputs.legend_helpers import build_shared_color_map
+    from flextool.plot_outputs.color_template import (
+        load_color_template,
+        order_labels_by_template,
+    )
+    from flextool.plot_outputs.subplot_helpers import _extract_subplot_data
+
+    # Determine chart sub-type
+    is_stack = bool(fm_stack_levels)
+    chart_type = 'stack' if is_stack else 'lines'
+    item_levels = fm_stack_levels if is_stack else fm_line_levels
+
+    # Convert level indices to level names
+    if isinstance(df_fm.columns, pd.MultiIndex):
+        item_level_names = [df_fm.columns.names[i] for i in item_levels]
+    else:
+        item_level_names = item_levels
+
+    # Get x-axis index, and the period label per x-position when the
+    # DataFrame has a ``period`` / ``solve_period`` MultiIndex level.
+    # The secondary period tick row on the x-axis depends on this being
+    # populated here and carried through the plan. Shared helper keeps
+    # this in sync with the loader's reconstruction path.
+    time_values, period_labels, max_period_label_len = _extract_time_labels(df_fm)
+
+    # Determine max items
+    default_max_items = 10
+    max_items = (
+        cfg.max_items_per_plot
+        if cfg.max_items_per_plot is not None
+        else default_max_items
+    )
+
+    # Build effective_plots with item splitting, tracking which sub-value
+    # each chunk came from so we can reconstruct full df_fm column tuples
+    # later (see _encode_column_selector).
+    from flextool.plot_outputs.subplot_helpers import _get_unique_levels, _sort_subs
+    if fm_subplot_levels:
+        subs_for_iter = _sort_subs(_get_unique_levels(df_fm.columns, fm_subplot_levels))
+    else:
+        subs_for_iter = [None]
+    effective_plots = []
+    chunk_subs: list = []
+    for sub in subs_for_iter:
+        if sub is None:
+            df_for_sub = df_fm
+            per_sub_levels: list[int] = []
+        else:
+            df_for_sub = _extract_subplot_data(df_fm, sub, fm_subplot_levels)
+            per_sub_levels = []  # already extracted; no further sub_levels inside
+        per_sub_plots = _build_effective_plots(
+            df_for_sub, per_sub_levels, item_level_names, max_items,
+            subplots_by_magnitudes=cfg.subplots_by_magnitudes if not is_stack else False,
+        )
+        if sub is not None:
+            base_title = (
+                ' | '.join(str(v) for v in sub) if isinstance(sub, tuple)
+                else str(sub)
+            )
+            retitled = []
+            for t, d in per_sub_plots:
+                if t is None:
+                    retitled.append((base_title, d))
+                elif str(t).startswith('None'):
+                    # chunk indicator appended after a base title of None
+                    retitled.append((base_title + str(t)[len('None'):], d))
+                else:
+                    retitled.append((t, d))
+            per_sub_plots = retitled
+        effective_plots.extend(per_sub_plots)
+        chunk_subs.extend([sub] * len(per_sub_plots))
+    if not effective_plots:
+        return None
+
+    # Build shared color map. When the colored (legend) series IS the
+    # scenario dim — comparison plots with scenario_rule 'l'/'s' — color it
+    # from the project's scenarios section instead of the entity/category
+    # hint (which describes a different, non-legend dim here).
+    shared_color_map = None
+    use_scenario = (
+        len(item_level_names) == 1 and str(item_level_names[0]) == 'scenario'
+    )
+    if (cfg.legend == 'shared' or cfg.color_category or cfg.color_entity_class
+            or use_scenario) and item_level_names:
+        cat = None if use_scenario else cfg.color_category
+        ent = None if use_scenario else cfg.color_entity_class
+        all_labels: list[str] = []
+        for _, df_sub in effective_plots:
+            for item in _get_column_items(df_sub, item_level_names):
+                label = str(item)
+                if label not in all_labels:
+                    all_labels.append(label)
+        template = load_color_template(color_path)
+        # Listed labels first in file order; unlisted appended alphabetically.
+        all_labels = order_labels_by_template(
+            all_labels, template,
+            category=cat, entity_class=ent, scenario=use_scenario,
+        )
+        shared_color_map = build_shared_color_map(
+            all_labels, color_template=template,
+            category=cat, entity_class=ent, scenario=use_scenario,
+        )
+
+    # Compute layout
+    layout = _compute_line_layout(
+        effective_plots, item_level_names,
+        cfg.legend, cfg.subplots_per_row,
+        6,  # base_width_per_col default
+        cfg.base_length,
+        cfg.axis_tick_format,
+    )
+
+    # Split into file batches
+    file_batches_raw = _make_file_batches(
+        effective_plots, cfg.max_subplots_per_file, None, '', effective_plot_name,
+    )
+    total_file_count = len(file_batches_raw)
+
+    # Encode effective_plot_specs and build batch index lists. Pass the
+    # per-chunk sub-value so the encoder can reinsert dropped sub-levels
+    # and produce full df_fm column tuples.
+    effective_plot_specs: list[tuple[str | None, list]] = []
+    for (title, df_sub), chunk_sub in zip(effective_plots, chunk_subs):
+        selector = _encode_column_selector(
+            df_sub, df_fm, fm_subplot_levels, chunk_sub,
+        )
+        effective_plot_specs.append((title, selector))
+
+    file_batches: list[list[int]] = []
+    # _make_file_batches returns [(batch_list, filepath), ...]
+    # We need to map each batch's items back to effective_plot indices.
+    offset = 0
+    for batch, _filepath in file_batches_raw:
+        batch_size = len(batch)
+        file_batches.append(list(range(offset, offset + batch_size)))
+        offset += batch_size
+
+    # Compute per-subplot global y-axis ranges from full time series.
+    # For stacked charts the visual ceiling is the column-wise stacked
+    # sum (positives stack up, negatives stack down), not the per-series
+    # max — using the per-series max here clips peaks when multiple
+    # series are non-zero at the same timestep.
+    include_zero = cfg.always_include_zero_in_axis
+    subplot_y_ranges: list[tuple[float, float]] = []
+    for _title, df_sub in effective_plots:
+        lo, hi = 0.0, 0.0
+        if isinstance(df_sub, pd.Series):
+            vals = df_sub.dropna()
+            if len(vals):
+                lo, hi = float(vals.min()), float(vals.max())
+        elif isinstance(df_sub, pd.DataFrame):
+            num = df_sub.select_dtypes(include='number')
+            if not num.empty:
+                if is_stack:
+                    pos_stack = num.clip(lower=0).sum(axis=1)
+                    neg_stack = num.clip(upper=0).sum(axis=1)
+                    lo, hi = float(neg_stack.min()), float(pos_stack.max())
+                else:
+                    lo, hi = float(num.min().min()), float(num.max().max())
+        if include_zero:
+            lo = min(lo, 0.0)
+            hi = max(hi, 0.0)
+        subplot_y_ranges.append(_add_y_buffer(lo, hi))
+
+    # Serialize layout
+    layout_params = {
+        'value_label_width': layout.value_label_width,
+        'legend_width': layout.legend_width,
+        'base_width': layout.base_width,
+        'subplot_height': layout.subplot_height,
+    }
+
+    return PlotPlan(
+        chart_type=chart_type,
+        plot_name=effective_plot_name,
+        total_file_count=total_file_count,
+        processed_df=df_fm,
+        effective_plot_specs=effective_plot_specs,
+        file_batches=file_batches,
+        shared_color_map=shared_color_map,
+        color_category=cfg.color_category,
+        color_entity_class=cfg.color_entity_class,
+        axis_bounds=axis_bounds,
+        layout_type='line',
+        layout_params=layout_params,
+        sub_levels=fm_subplot_levels,
+        item_level_names=item_level_names,
+        time_index_values=time_values,
+        period_labels=period_labels,
+        max_period_label_len=max_period_label_len,
+        subplots_per_row=cfg.subplots_per_row,
+        legend_position=cfg.legend,
+        xlabel=cfg.xlabel,
+        ylabel=cfg.ylabel,
+        axis_tick_format=cfg.axis_tick_format,
+        always_include_zero_in_axis=cfg.always_include_zero_in_axis,
+        subplot_y_ranges=subplot_y_ranges,
+    )
+
+
+# Engine-internal map from a column/index level NAME (set by the output
+# processing, see ``flextool/process_outputs/*.py`` ``.columns.names = [...]``)
+# to the entity class(es) that level can carry. Some levels are *mixed*: a
+# ``process`` is a unit or a connection, and a ``group`` is a nodeGroup or a
+# flowGroup (the entity-class split keyed them apart). This is the inverse of
+# the masking the engine already owns, so a plot author writes the class hint
+# (``color_entity_class: unit`` / ``group``) and never an internal level name.
+# A hint that is itself a mixed key (``process`` / ``group``) resolves each
+# value against both constituent classes.
+_LEVEL_NAME_TO_CLASSES: dict[str, tuple[str, ...]] = {
+    'process': ('unit', 'connection'),
+    'unit': ('unit',),
+    'connection': ('connection',),
+    'node': ('node',),
+    'source': ('node',),
+    'sink': ('node',),
+    'group': ('nodeGroup', 'flowGroup'),
+    'node_group': ('nodeGroup',),
+    'flow_group': ('flowGroup',),
+    'nodeGroup': ('nodeGroup',),
+    'flowGroup': ('flowGroup',),
+    'commodity': ('commodity',),
+}
+
+
+def resolve_color_bar_level(
+    level_names: list, entity_class: str | None
+) -> str | None:
+    """Pick the column/index level that carries ``entity_class`` for a bar.
+
+    Lines / stacked / grouped charts designate their colored level via a
+    role char (``l`` / ``s`` / ``g``); a simple bar has none, so given
+    ``color_entity_class: unit`` the engine must *find* the level holding
+    units. A level matches when its class-set and the hint's class-set
+    overlap — so ``unit`` matches the mixed ``process`` level, ``group``
+    (= nodeGroup+flowGroup) matches a ``group`` or ``node_group`` level, and
+    a literal name match always wins. Returns the first match
+    (``process__source__sink`` never reaches plotting, so first-match is a
+    safe tiebreak), or ``None`` when nothing matches / no class is set.
+    """
+    if not entity_class:
+        return None
+    want = set(_LEVEL_NAME_TO_CLASSES.get(entity_class, (entity_class,)))
+    for name in level_names:
+        have = set(_LEVEL_NAME_TO_CLASSES.get(name, (name,)))
+        if name == entity_class or (want & have):
+            return name
+    return None
+
+
+def _color_level_values(df_sub: pd.DataFrame, level: str) -> list:
+    """Distinct values of ``level`` in ``df_sub``, from columns or index.
+
+    The color-bar level may sit on the columns (expand / subplot dim) or on
+    the row index (a ``b``-role dim moved there by the fm-transform). Returns
+    ``[]`` when the level is on neither (e.g. a level dropped from this slice).
+    """
+    col_multi = isinstance(df_sub.columns, pd.MultiIndex)
+    col_names = list(df_sub.columns.names) if col_multi else [df_sub.columns.name]
+    if level in col_names:
+        if col_multi:
+            return df_sub.columns.get_level_values(level).unique().tolist()
+        return df_sub.columns.unique().tolist()
+    idx_multi = isinstance(df_sub.index, pd.MultiIndex)
+    idx_names = list(df_sub.index.names) if idx_multi else [df_sub.index.name]
+    if level in idx_names:
+        if idx_multi:
+            return df_sub.index.get_level_values(level).unique().tolist()
+        return df_sub.index.unique().tolist()
+    return []
+
+
+def _multiclass_color_map(
+    labels: list, color_template: dict | None, classes: tuple,
+) -> dict:
+    """Color map for labels that resolve against more than one entity class.
+
+    For a mixed level like ``process`` (each value is *either* a unit or a
+    connection), resolve every label against ``classes`` in order — first
+    section that lists it wins — and give the rest tab10/tab20 palette
+    colors in input order (mirroring ``build_shared_color_map``'s fallback).
+    """
+    import matplotlib.pyplot as plt
+    from flextool.plot_outputs.color_template import resolve_label_color
+
+    template = color_template or {}
+    resolved: dict = {}
+    palette_needed = 0
+    for lbl in labels:
+        col = None
+        for cls in classes:
+            col = resolve_label_color(lbl, template, category=None, entity_class=cls)
+            if col is not None:
+                break
+        resolved[lbl] = col
+        if col is None:
+            palette_needed += 1
+    cmap_colors = (
+        plt.colormaps['tab10'].colors if palette_needed <= 10
+        else plt.colormaps['tab20'].colors
+    )
+    out: dict = {}
+    pi = 0
+    for lbl in labels:
+        if resolved[lbl] is not None:
+            out[lbl] = resolved[lbl]
+        else:
+            out[lbl] = cmap_colors[pi % len(cmap_colors)]
+            pi += 1
+    return out
+
+
+def build_simple_bar_color_map(
+    df_fm: pd.DataFrame,
+    entity_class: str | None,
+    color_template: dict | None,
+) -> tuple[dict | None, str | None]:
+    """Color map + color level for a simple (non-stacked, non-grouped) bar.
+
+    Resolves the column/index level carrying ``entity_class`` and builds a
+    ``{value: rgb}`` map over that level's distinct values (read from the
+    full ``df_fm`` so subplot levels — which subplot extraction would drop —
+    are still captured), ordered by the picker's file order. Shared by the
+    plan path (``_compute_bar_plan``) and the live render path
+    (``build_bar_figures``) so both color identically.
+
+    ``entity_class`` may name a mixed level: ``process`` carries both units
+    and connections, so each value is resolved against ``unit`` then
+    ``connection`` — the one place a plot author writes ``process``. Returns
+    ``(None, None)`` when no class is set or no level carries it.
+    """
+    from flextool.plot_outputs.legend_helpers import build_shared_color_map
+    from flextool.plot_outputs.color_template import order_labels_by_template
+
+    col_names = list(df_fm.columns.names) if isinstance(
+        df_fm.columns, pd.MultiIndex) else [df_fm.columns.name]
+    idx_names = list(df_fm.index.names) if isinstance(
+        df_fm.index, pd.MultiIndex) else [df_fm.index.name]
+    # Index first: a 'b'-role dim (sum/total variant) lives on the index;
+    # an expand/subplot dim (period variant) lives on a column.
+    color_bar_level = resolve_color_bar_level(idx_names + col_names, entity_class)
+    if not color_bar_level:
+        return None, None
+    all_labels: list[str] = []
+    for v in _color_level_values(df_fm, color_bar_level):
+        label = str(v)
+        if label not in all_labels:
+            all_labels.append(label)
+
+    # A mixed level (process) resolves against several classes; a plain one
+    # against itself.
+    classes = _LEVEL_NAME_TO_CLASSES.get(entity_class, (entity_class,))
+    if len(classes) > 1:
+        shared_color_map = _multiclass_color_map(all_labels, color_template, classes)
+    else:
+        cls = classes[0]
+        all_labels = order_labels_by_template(
+            all_labels, color_template or {}, category=None, entity_class=cls,
+        )
+        shared_color_map = build_shared_color_map(
+            all_labels, color_template=color_template, category=None, entity_class=cls,
+        )
+    return shared_color_map, color_bar_level
+
+
+def _compute_bar_plan(
+    df_fm: pd.DataFrame,
+    effective_plot_name: str,
+    cfg: 'PlotConfig',
+    fm_stack_levels: list[int],
+    fm_expand_axis_levels: list[int],
+    fm_subplot_levels: list[int],
+    fm_grouped_bar_levels: list[int],
+    axis_bounds,
+    color_path: Path | None = None,
+) -> PlotPlan | None:
+    """Compute a PlotPlan for a bar chart.
+
+    Replicates the planning steps of build_bar_figures() without actually
+    creating matplotlib Figures.
+    """
+    from flextool.plot_outputs.plot_bars import _compute_bar_layout
+    from flextool.plot_outputs.subplot_helpers import (
+        _get_unique_levels, _extract_subplot_data, _sort_subs,
+    )
+    from flextool.plot_outputs.legend_helpers import build_shared_color_map, _format_legend_labels
+    from flextool.plot_outputs.color_template import (
+        load_color_template,
+        order_labels_by_template,
+    )
+
+    sub_levels = fm_subplot_levels or []
+    stack_levels = fm_stack_levels or []
+    grouped_bar_levels = fm_grouped_bar_levels or []
+    expand_axis_levels = fm_expand_axis_levels or []
+
+    # Convert level indices to names
+    if isinstance(df_fm.columns, pd.MultiIndex):
+        stack_level_names = [df_fm.columns.names[i] for i in stack_levels] if stack_levels else []
+        expand_axis_level_names = [df_fm.columns.names[i] for i in expand_axis_levels] if expand_axis_levels else []
+        grouped_bar_level_names = [df_fm.columns.names[i] for i in grouped_bar_levels] if grouped_bar_levels else []
+    else:
+        stack_level_names = stack_levels
+        expand_axis_level_names = [df_fm.columns.name] if expand_axis_levels else []
+        grouped_bar_level_names = [df_fm.columns.name] if grouped_bar_levels else []
+
+    subs = _sort_subs(_get_unique_levels(df_fm.columns, sub_levels))
+
+    # Compute expand-group count. When columns is a plain (single-level)
+    # Index, each unique column value still acts as one expand group at
+    # render time (see ``_build_bar_figure`` group-iteration loop), so the
+    # visual bar count is ``n_rows × n_unique_cols`` — not ``n_rows`` as
+    # the old code assumed. Without this, pagination undercounts and a
+    # 175×245 frame collapses to "175 items" and renders 42 875 bars in
+    # one figure (~2 350-inch height, ~290 MP bitmap → GUI hard hang).
+    if expand_axis_levels:
+        if isinstance(df_fm.columns, pd.MultiIndex):
+            if len(expand_axis_level_names) == 1:
+                expand_level_name = expand_axis_level_names[0]
+                n_expand_groups = len(df_fm.columns.get_level_values(expand_level_name).unique())
+            else:
+                expand_frame = df_fm.columns.to_frame()[expand_axis_level_names].drop_duplicates()
+                n_expand_groups = len(expand_frame)
+        else:
+            # Single-level columns: each unique value is its own expand group.
+            n_expand_groups = len(df_fm.columns.unique())
+    else:
+        n_expand_groups = 1
+
+    # Determine max items
+    default_max_items = 10
+    max_items = (
+        cfg.max_items_per_plot
+        if cfg.max_items_per_plot is not None
+        else default_max_items
+    )
+
+    # Build effective_plots (mirrors build_bar_figures logic).
+    # Split subplots that exceed max_items_per_plot visual bar labels
+    # (n_rows * n_expand_groups).
+    effective_plots: list[tuple[str | None, pd.DataFrame]] = []
+    # Parallel list: which sub-value each chunk was extracted from, so
+    # the column selector encoder can reinsert it and produce tuples
+    # that match df_fm.columns at reconstruction time.
+    chunk_subs: list = []
+    for sub in subs:
+        df_sub = _extract_subplot_data(df_fm, sub, sub_levels)
+        df_sub = df_sub.dropna(how='all')
+        if df_sub.empty:
+            continue
+        df_sub = df_sub.fillna(0)
+        title = (
+            ' | '.join(str(v) for v in sub) if isinstance(sub, tuple)
+            else str(sub) if sub is not None else None
+        )
+        n_rows = len(df_sub)
+
+        def _add(label: str | None, df_chunk: pd.DataFrame) -> None:
+            effective_plots.append((label, df_chunk))
+            chunk_subs.append(sub)
+
+        if not max_items:
+            _add(title, df_sub)
+            continue
+
+        total_items = n_rows * max(n_expand_groups, 1)
+        if total_items <= max_items:
+            _add(title, df_sub)
+            continue
+
+        if expand_axis_levels and expand_axis_level_names and n_expand_groups > 1:
+            expand_level_name_local = expand_axis_level_names[0]
+            max_groups = max(1, max_items // max(n_rows, 1))
+            if isinstance(df_sub.columns, pd.MultiIndex):
+                all_groups = df_sub.columns.get_level_values(expand_level_name_local).unique().tolist()
+            else:
+                all_groups = df_sub.columns.unique().tolist()
+            for gi, grp_start in enumerate(range(0, len(all_groups), max_groups)):
+                grp_chunk = all_groups[grp_start:grp_start + max_groups]
+                if isinstance(df_sub.columns, pd.MultiIndex):
+                    mask = df_sub.columns.get_level_values(expand_level_name_local).isin(grp_chunk)
+                else:
+                    mask = df_sub.columns.isin(grp_chunk)
+                chunk = df_sub.loc[:, mask]
+                # When a chunk still has more rows than max_items, further
+                # split by rows so per-subplot bar count stays bounded.
+                if n_rows > max_items:
+                    n_row_chunks = (n_rows + max_items - 1) // max_items
+                    for ri in range(n_row_chunks):
+                        row_chunk = chunk.iloc[ri * max_items:(ri + 1) * max_items]
+                        sub_label = (
+                            f"{title}_{gi + 1}.{ri + 1}"
+                            if title else f"{gi + 1}.{ri + 1}"
+                        )
+                        _add(sub_label, row_chunk)
+                else:
+                    chunk_label = f"{title}_{gi + 1}" if title else None
+                    _add(chunk_label, chunk)
+        elif n_rows > max_items:
+            for i in range(0, n_rows, max_items):
+                chunk = df_sub.iloc[i:i + max_items]
+                chunk_label = f"{title}_{i // max_items + 1}" if title else None
+                _add(chunk_label, chunk)
+        else:
+            _add(title, df_sub)
+
+    if not effective_plots:
+        return None
+
+    # Build shared color map. When the colored (legend) series IS the
+    # scenario dim — comparison plots with scenario_rule 'g'/'s' — color it
+    # from the scenarios section rather than the entity/category hint.
+    shared_color_map = None
+    color_bar_level: str | None = None
+    colored_names = grouped_bar_level_names if grouped_bar_levels else stack_level_names
+    use_scenario = (
+        len(colored_names) == 1 and str(colored_names[0]) == 'scenario'
+    )
+    if (cfg.legend == 'shared' or cfg.color_category or cfg.color_entity_class
+            or use_scenario) and (stack_levels or grouped_bar_levels):
+        cat = None if use_scenario else cfg.color_category
+        ent = None if use_scenario else cfg.color_entity_class
+        all_labels: list[str] = []
+        for _, df_sub in effective_plots:
+            if grouped_bar_levels:
+                if len(grouped_bar_level_names) == 1:
+                    items = df_sub.columns.get_level_values(
+                        grouped_bar_level_names[0]).unique().tolist()
+                else:
+                    item_df = df_sub.columns.to_frame()[grouped_bar_level_names].drop_duplicates()
+                    items = [tuple(row) for row in item_df.values]
+            else:
+                if len(stack_level_names) == 1:
+                    if isinstance(df_sub.columns, pd.MultiIndex):
+                        items = df_sub.columns.get_level_values(
+                            stack_level_names[0]).unique().tolist()
+                    else:
+                        items = df_sub.columns.unique().tolist()
+                else:
+                    stack_df = df_sub.columns.to_frame()[stack_level_names].drop_duplicates()
+                    items = [tuple(row) for row in stack_df.values]
+            for item in items:
+                label = _format_legend_labels([item])[0]
+                if label not in all_labels:
+                    all_labels.append(label)
+        template = load_color_template(color_path)
+        # Listed labels first in file order; unlisted appended alphabetically.
+        all_labels = order_labels_by_template(
+            all_labels, template,
+            category=cat, entity_class=ent, scenario=use_scenario,
+        )
+        shared_color_map = build_shared_color_map(
+            all_labels, color_template=template,
+            category=cat, entity_class=ent, scenario=use_scenario,
+        )
+    elif cfg.color_entity_class and not (stack_levels or grouped_bar_levels):
+        # Simple bars: no role char designates a colored level, so resolve
+        # the level carrying the entity class and color each bar by its value
+        # there — a column (expand → per-bar; subplot → whole-subplot) or the
+        # row index (a 'b'-role dim, e.g. the sum/total variant). Same
+        # entities.<class> resolution + picker order as the line path; shared
+        # with the live render path via build_simple_bar_color_map.
+        shared_color_map, color_bar_level = build_simple_bar_color_map(
+            df_fm, cfg.color_entity_class, load_color_template(color_path),
+        )
+
+    # Compute layout
+    layout = _compute_bar_layout(
+        effective_plots, df_fm,
+        expand_axis_levels, expand_axis_level_names,
+        stack_levels, stack_level_names,
+        grouped_bar_levels, grouped_bar_level_names,
+        cfg.legend, cfg.subplots_per_row,
+        cfg.base_length,
+    )
+
+    # Split into file batches respecting max_subplots_per_file and, for
+    # horizontal bars, max_items_per_subplot_column (total bar-label count
+    # in any single grid column must not exceed the limit).
+    spr = max(cfg.subplots_per_row, 1)
+    max_per_file = cfg.max_subplots_per_file or len(effective_plots)
+    col_limit = (
+        cfg.max_items_per_subplot_column
+        if cfg.bar_orientation == 'horizontal' else 0
+    )
+
+    # Compute visual item counts per subplot (bar labels on the y-axis).
+    # With expand groups, each group contributes its own set of labels,
+    # so the count can be much larger than len(df_sub).
+    def _count_visual_items(df_sub: pd.DataFrame) -> int:
+        if not expand_axis_level_names:
+            return max(len(df_sub), 1)
+        if not isinstance(df_sub.columns, pd.MultiIndex):
+            # Single-level columns: each unique value is its own expand
+            # group, each contributing one row-set worth of bars.
+            return max(len(df_sub) * len(df_sub.columns.unique()), 1)
+        count = 0
+        if len(expand_axis_level_names) == 1:
+            groups = df_sub.columns.get_level_values(expand_axis_level_names[0]).unique()
+        else:
+            gf = df_sub.columns.to_frame()[expand_axis_level_names].drop_duplicates()
+            groups = [tuple(r) for r in gf.values]
+        for grp in groups:
+            try:
+                if len(expand_axis_level_names) == 1:
+                    df_g = df_sub.xs(grp, level=expand_axis_level_names[0], axis=1)
+                else:
+                    df_g = df_sub.xs(grp, level=expand_axis_level_names, axis=1)
+            except KeyError:
+                continue
+            if isinstance(df_g, pd.Series):
+                df_g = df_g.to_frame()
+            count += len(df_g)
+        return max(count, 1)
+
+    visual_item_counts = [_count_visual_items(df_sub) for _, df_sub in effective_plots]
+
+    # Group subplots into grid rows so we never break mid-row.
+    grid_rows: list[list[int]] = []
+    for i in range(0, len(effective_plots), spr):
+        grid_rows.append(list(range(i, min(i + spr, len(effective_plots)))))
+
+    raw_batches: list[list[tuple[str | None, pd.DataFrame]]] = []
+    current_batch: list[tuple[str | None, pd.DataFrame]] = []
+    col_counts = [0] * spr  # cumulative bar-label count per grid column
+
+    for row_indices in grid_rows:
+        # Check whether adding this row would breach either limit.
+        would_exceed_subplots = len(current_batch) + len(row_indices) > max_per_file
+        would_exceed_col = False
+        if col_limit and current_batch:
+            for j, idx in enumerate(row_indices):
+                if col_counts[j] + visual_item_counts[idx] > col_limit:
+                    would_exceed_col = True
+                    break
+
+        if (would_exceed_subplots or would_exceed_col) and current_batch:
+            raw_batches.append(current_batch)
+            current_batch = []
+            col_counts = [0] * spr
+
+        current_batch.extend([effective_plots[i] for i in row_indices])
+        for j, idx in enumerate(row_indices):
+            col_counts[j] += visual_item_counts[idx]
+
+    if current_batch:
+        raw_batches.append(current_batch)
+
+    total_file_count = len(raw_batches)
+
+    # Encode effective_plot_specs: store row index labels AND column
+    # selectors so that reconstruction filters both dimensions.
+    # The column selector is stored as FULL df_fm tuples (with the
+    # sub-level values reinserted) so reconstruction via
+    # ``df_fm.columns.isin(...)`` matches exactly. Without this the
+    # narrower tuples from ``xs`` never match and the fallback returns
+    # the whole df_fm, flooding the subplot with columns from every
+    # other subplot.
+    effective_plot_specs: list[tuple[str | None, list]] = []
+    for (title, df_sub), chunk_sub in zip(effective_plots, chunk_subs):
+        selector = {
+            'rows': _encode_row_selector(df_sub),
+            'cols': _encode_column_selector(df_sub, df_fm, sub_levels, chunk_sub),
+        }
+        effective_plot_specs.append((title, selector))
+
+    # Build batch index lists
+    file_batches: list[list[int]] = []
+    offset = 0
+    for batch in raw_batches:
+        batch_size = len(batch)
+        file_batches.append(list(range(offset, offset + batch_size)))
+        offset += batch_size
+
+    # Serialize layout
+    layout_params = {
+        'bar_label_width': layout.bar_label_width,
+        'total_label_width': layout.total_label_width,
+        'legend_width': layout.legend_width,
+        'legend_height': layout.legend_height,
+        'base_bar_length': layout.base_bar_length,
+        'value_axis_width': layout.value_axis_width,
+    }
+
+    return PlotPlan(
+        chart_type='bar',
+        plot_name=effective_plot_name,
+        total_file_count=total_file_count,
+        processed_df=df_fm,
+        effective_plot_specs=effective_plot_specs,
+        file_batches=file_batches,
+        shared_color_map=shared_color_map,
+        color_category=cfg.color_category,
+        color_entity_class=cfg.color_entity_class,
+        color_bar_level=color_bar_level,
+        axis_bounds=axis_bounds,
+        layout_type='bar',
+        layout_params=layout_params,
+        sub_levels=sub_levels,
+        item_level_names=[],
+        subplots_per_row=cfg.subplots_per_row,
+        legend_position=cfg.legend,
+        xlabel=cfg.xlabel,
+        ylabel=cfg.ylabel,
+        bar_orientation=cfg.bar_orientation,
+        axis_tick_format=cfg.axis_tick_format,
+        always_include_zero_in_axis=cfg.always_include_zero_in_axis,
+        value_label=cfg.value_label,
+        base_bar_length=cfg.base_length,
+        skip_data_with_only_zeroes=cfg.skip_data_with_only_zeroes,
+        stack_levels=stack_levels,
+        stack_level_names=stack_level_names,
+        expand_axis_levels=expand_axis_levels,
+        expand_axis_level_names=expand_axis_level_names,
+        grouped_bar_levels=grouped_bar_levels,
+        grouped_bar_level_names=grouped_bar_level_names,
+    )
+
+
+# ---------------------------------------------------------------------------
+#  compute_plot_plans_for_result
+# ---------------------------------------------------------------------------
+
+def compute_plot_plans_for_result(
+    df: pd.DataFrame,
+    result_key: str,
+    plot_settings: dict,
+    output_dir: Path,
+    plot_rows: tuple[int, int] = (0, 167),
+    break_times: set[str] | None = None,
+    active_settings: list[str] | None = None,
+    period_weights=None,
+    manifest_accumulator=None,
+    manifest_scenario_name: str | None = None,
+    color_path: Path | None = None,
+) -> list[tuple[str, str]]:
+    """Compute and save PlotPlans for all configs of a result_key.
+
+    Called after scenario runs to pre-compute plans.
+    Returns list of (result_key, sub_config) pairs that produced valid plans.
+    The *active_settings* parameter is accepted for backward compatibility
+    but ignored — all configs in the YAML entry are processed so that the
+    viewer can build a complete availability manifest.
+
+    When *manifest_accumulator* is provided (a
+    :class:`~flextool.plot_outputs.shared_manifest.ManifestAccumulator`),
+    each generated plan is also folded into a cross-scenario axis-bounds
+    manifest under *manifest_scenario_name*.  The caller is responsible
+    for invoking ``accumulator.write()`` once the batch is done.
+    """
+    from flextool.plot_outputs.config import PlotConfig, PLOT_FIELD_NAMES, _is_single_config
+    from flextool.plot_outputs.orchestrator import (
+        _apply_dimension_rules, _resolve_shared_axis_bounds, _process_file_member,
+        reattach_file_level_for_color,
+    )
+    from flextool.plot_outputs.axis_helpers import _normalize_axis_bounds
+    from flextool.plot_outputs.format_helpers import insert_timeline_breaks
+
+    entry = plot_settings.get(result_key)
+    if not isinstance(entry, dict):
+        return []
+
+    succeeded: list[tuple[str, str]] = []
+
+    # Collect all configs (not just active ones)
+    chosen: list[tuple[str, dict]] = []
+    if _is_single_config(entry):
+        chosen.append(('default', entry))
+    else:
+        for name, sub in entry.items():
+            if isinstance(sub, dict):
+                chosen.append((name, sub))
+
+    for sub_config, raw_setting in chosen:
+        # Parse into PlotConfig
+        filtered = {k: v for k, v in raw_setting.items() if k in PLOT_FIELD_NAMES}
+        if 'axis_scale_min_max' in filtered and 'axis_bounds' not in filtered:
+            filtered['axis_bounds'] = filtered.pop('axis_scale_min_max')
+        elif 'axis_scale_min_max' in filtered:
+            del filtered['axis_scale_min_max']
+        filtered.pop('variant', None)
+        try:
+            cfg = PlotConfig(**filtered)
+        except TypeError:
+            continue
+
+        if not cfg.map_dimensions_for_plots or len(cfg.map_dimensions_for_plots) < 2:
+            continue
+
+        # Title: explicit plot_name > settings-group entry name > result key.
+        # Mirrors the live-render path in orchestrator.py so disk plans don't
+        # fall back to the raw parquet file name (result_key) as the title.
+        plot_name = cfg.plot_name or raw_setting.get('_entry_name') or result_key
+
+        # Check availability using the FULL data range — a variant is
+        # "available" if there's any non-zero data anywhere in the time
+        # series, even if the current plot_rows window is all zeros.
+        # This prevents hourly variants from being marked unavailable when
+        # spikes happen outside the displayed window.
+        full_range = (0, len(df))
+        avail_result = _apply_dimension_rules(df, cfg, full_range, period_weights=period_weights)
+        if avail_result is None:
+            continue
+        df_avail = avail_result[0]
+        has_data = True
+        if cfg.skip_data_with_only_zeroes:
+            numeric = df_avail.select_dtypes(include='number')
+            has_data = not numeric.empty and (numeric.abs() >= 1e-6).any().any()
+        if not has_data:
+            continue
+        # Record availability regardless of whether plan generation succeeds
+        succeeded.append((result_key, sub_config))
+
+        # Apply dimension rules.  For time-series plans, use the full data
+        # range so the plan can be rendered at any start/duration without
+        # recomputing.  For bar charts, plot_rows is irrelevant.
+        dim_result = _apply_dimension_rules(df, cfg, full_range, period_weights=period_weights)
+        if dim_result is None:
+            continue
+        df_processed, rules, chart_type, summed_dims, averaged_dims = dim_result
+
+        # Identify level roles
+        col_rules = rules[df_processed.index.nlevels:]
+        grouped_bar_levels = [i for i, c in enumerate(col_rules) if c == 'g']
+        stack_levels = [i for i, c in enumerate(col_rules) if c == 's']
+        expand_axis_levels = [i for i, c in enumerate(col_rules) if c == 'e']
+        subplot_levels = [i for i, c in enumerate(col_rules) if c == 'u']
+        line_levels = [i for i, c in enumerate(col_rules) if c == 'l']
+        file_levels = [i for i, c in enumerate(col_rules) if c == 'f']
+
+        # Build plot title
+        plot_title = plot_name
+        if summed_dims:
+            dim_str = "', '".join(str(d) for d in summed_dims)
+            plot_title = f"{plot_title} ('{dim_str}' summed)"
+        if averaged_dims:
+            dim_str = "', '".join(str(d) for d in averaged_dims)
+            plot_title = f"{plot_title} ('{dim_str}' averaged)"
+
+        # File members
+        if file_levels:
+            if len(file_levels) == 1:
+                all_file_members = (
+                    df_processed.columns.get_level_values(file_levels[0]).unique().tolist()
+                )
+            else:
+                fm_df = (
+                    df_processed.columns.to_frame().iloc[:, file_levels].drop_duplicates()
+                )
+                all_file_members = [tuple(row) for row in fm_df.values]
+        else:
+            all_file_members = [None]
+
+        # Resolve shared axis bounds
+        axis_bounds = _normalize_axis_bounds(cfg.axis_bounds)
+        axis_bounds = _resolve_shared_axis_bounds(
+            df_processed, axis_bounds, stack_levels, subplot_levels,
+            cfg.always_include_zero_in_axis,
+        )
+
+        # Process each file member
+        for file_member in all_file_members:
+            result = _process_file_member(
+                df_processed, file_member, file_levels, plot_title,
+                grouped_bar_levels, stack_levels, expand_axis_levels,
+                subplot_levels, line_levels,
+            )
+            if result is None:
+                continue
+            (df_fm, effective_plot_name, member_str,
+             fm_grouped_bar_levels, fm_stack_levels, fm_expand_axis_levels,
+             fm_subplot_levels, fm_line_levels) = result
+
+            # Simple bar colored by the file-split entity: restore the file
+            # member's value so the whole file gets that group's color.
+            if chart_type == 'bar' and cfg.color_entity_class:
+                file_level_names = [df_processed.columns.names[i] for i in file_levels]
+                df_fm = reattach_file_level_for_color(
+                    df_fm, file_member, file_level_names, cfg.color_entity_class)
+
+            # Apply skip_zeroes, multiply_by, timeline breaks
+            if cfg.skip_data_with_only_zeroes:
+                df_fm = df_fm.loc[:, (df_fm.abs() > 1e-6).any()]
+                if chart_type == 'bar':
+                    df_fm = df_fm.loc[(df_fm.abs() > 1e-6).any(axis=1)]
+                if df_fm.empty:
+                    continue
+
+            if cfg.multiply_by is not None:
+                df_fm = df_fm * cfg.multiply_by
+
+            if chart_type == 'time' and break_times:
+                df_fm = insert_timeline_breaks(df_fm, break_times)
+
+            # Compute plan based on chart type
+            if chart_type == 'bar':
+                plan = _compute_bar_plan(
+                    df_fm, effective_plot_name, cfg,
+                    fm_stack_levels, fm_expand_axis_levels,
+                    fm_subplot_levels, fm_grouped_bar_levels,
+                    axis_bounds,
+                    color_path=color_path,
+                )
+            elif chart_type == 'time':
+                plan = _compute_time_plan(
+                    df_fm, effective_plot_name, cfg,
+                    fm_stack_levels, fm_subplot_levels, fm_line_levels,
+                    axis_bounds, plot_rows,
+                    color_path=color_path,
+                )
+            else:
+                continue
+
+            if plan is None:
+                continue
+
+            # Determine sub_config name for file member variants
+            save_sub = sub_config
+            if member_str:
+                save_sub = f"{sub_config}__{member_str}"
+
+            save_plot_plan(plan, output_dir, result_key, save_sub)
+            if manifest_accumulator is not None and manifest_scenario_name:
+                try:
+                    manifest_accumulator.add_plan(
+                        result_key, save_sub, plan, manifest_scenario_name,
+                    )
+                except Exception as exc:
+                    logger.warning(
+                        "Failed to accumulate axis bounds for %s/%s: %s",
+                        result_key, save_sub, exc,
+                    )
+            # Record file-member-specific availability if different from base
+            if save_sub != sub_config:
+                succeeded.append((result_key, save_sub))
+
+    return succeeded
+
+
+def compute_live_plan(
+    df: pd.DataFrame,
+    cfg: 'PlotConfig',
+    plot_name: str,
+    break_times: set[str] | None = None,
+    period_weights=None,
+    color_path: Path | None = None,
+) -> PlotPlan | None:
+    """Compute a PlotPlan in memory without disk I/O.
+
+    Uses the full data range so time-series plans can be rendered at any
+    start/duration via :func:`build_figure_from_plan` with *plot_rows*.
+    """
+    from flextool.plot_outputs.orchestrator import (
+        _apply_dimension_rules, _resolve_shared_axis_bounds, _process_file_member,
+        reattach_file_level_for_color,
+    )
+    from flextool.plot_outputs.axis_helpers import _normalize_axis_bounds
+    from flextool.plot_outputs.format_helpers import insert_timeline_breaks
+
+    full_range = (0, len(df))
+    dim_result = _apply_dimension_rules(df, cfg, full_range, period_weights=period_weights)
+    if dim_result is None:
+        return None
+    df_processed, rules, chart_type, summed_dims, averaged_dims = dim_result
+
+    col_rules = rules[df_processed.index.nlevels:]
+    grouped_bar_levels = [i for i, c in enumerate(col_rules) if c == 'g']
+    stack_levels = [i for i, c in enumerate(col_rules) if c == 's']
+    expand_axis_levels = [i for i, c in enumerate(col_rules) if c == 'e']
+    subplot_levels = [i for i, c in enumerate(col_rules) if c == 'u']
+    line_levels = [i for i, c in enumerate(col_rules) if c == 'l']
+    file_levels = [i for i, c in enumerate(col_rules) if c == 'f']
+
+    plot_title = plot_name
+    if summed_dims:
+        plot_title = f"{plot_title} ('{', '.join(str(d) for d in summed_dims)}' summed)"
+    if averaged_dims:
+        plot_title = f"{plot_title} ('{', '.join(str(d) for d in averaged_dims)}' averaged)"
+
+    # File members (take the first — live plans don't split across files by member)
+    file_member = None
+    if file_levels:
+        if len(file_levels) == 1:
+            members = df_processed.columns.get_level_values(file_levels[0]).unique().tolist()
+        else:
+            fm_df = df_processed.columns.to_frame().iloc[:, file_levels].drop_duplicates()
+            members = [tuple(row) for row in fm_df.values]
+        if members:
+            file_member = members[0]
+
+    axis_bounds = _normalize_axis_bounds(cfg.axis_bounds)
+    axis_bounds = _resolve_shared_axis_bounds(
+        df_processed, axis_bounds, stack_levels, subplot_levels,
+        cfg.always_include_zero_in_axis,
+    )
+
+    result = _process_file_member(
+        df_processed, file_member, file_levels, plot_title,
+        grouped_bar_levels, stack_levels, expand_axis_levels,
+        subplot_levels, line_levels,
+    )
+    if result is None:
+        return None
+    (df_fm, effective_plot_name, _member_str,
+     fm_grouped_bar_levels, fm_stack_levels, fm_expand_axis_levels,
+     fm_subplot_levels, fm_line_levels) = result
+
+    if chart_type == 'bar' and cfg.color_entity_class:
+        file_level_names = [df_processed.columns.names[i] for i in file_levels]
+        df_fm = reattach_file_level_for_color(
+            df_fm, file_member, file_level_names, cfg.color_entity_class)
+
+    if cfg.skip_data_with_only_zeroes:
+        df_fm = df_fm.loc[:, (df_fm.abs() > 1e-6).any()]
+        if chart_type == 'bar':
+            df_fm = df_fm.loc[(df_fm.abs() > 1e-6).any(axis=1)]
+        if df_fm.empty:
+            return None
+
+    if cfg.multiply_by is not None:
+        df_fm = df_fm * cfg.multiply_by
+
+    if chart_type == 'time' and break_times:
+        df_fm = insert_timeline_breaks(df_fm, break_times)
+
+    if chart_type == 'bar':
+        return _compute_bar_plan(
+            df_fm, effective_plot_name, cfg,
+            fm_stack_levels, fm_expand_axis_levels,
+            fm_subplot_levels, fm_grouped_bar_levels,
+            axis_bounds,
+            color_path=color_path,
+        )
+    elif chart_type == 'time':
+        return _compute_time_plan(
+            df_fm, effective_plot_name, cfg,
+            fm_stack_levels, fm_subplot_levels, fm_line_levels,
+            axis_bounds, full_range,
+            color_path=color_path,
+        )
+    return None
+
+
+def rebuild_plan_color_map(
+    plan: PlotPlan,
+    color_path: Path | None = None,
+) -> dict[str, tuple] | None:
+    """Recompute *plan*'s ``shared_color_map`` from the current template.
+
+    This is the in-place recolor/reorder path used by the result viewer
+    when the user edits the project's ``plot_settings.yaml``.  It rebuilds
+    ONLY the color map (new colors AND new file order) from the freshly
+    loaded template, reusing the plan's stored ``color_category`` /
+    ``color_entity_class`` hints and its existing color-map label keys —
+    without touching dimension rules, layout, or the processed DataFrame.
+
+    The label set is taken from the plan's current ``shared_color_map``
+    keys: ``build_shared_color_map`` returns exactly one entry per input
+    label, so those keys are precisely the label set the compute path
+    produced.  Running them back through ``order_labels_by_template`` +
+    ``build_shared_color_map`` with the same ``category`` / ``entity_class``
+    arguments yields a result identical to a full ``compute_live_plan``
+    recompute for a color/order-only template change.
+
+    Returns the new ordered ``shared_color_map`` (and assigns it to
+    ``plan.shared_color_map``).  Returns ``None`` and leaves the plan
+    unchanged when the plan has no ``shared_color_map`` to rebuild (e.g. a
+    non-shared legend) — the caller falls back gracefully.
+    """
+    from flextool.plot_outputs.color_template import (
+        load_color_template,
+        order_labels_by_template,
+    )
+    from flextool.plot_outputs.legend_helpers import build_shared_color_map
+
+    if not plan.shared_color_map:
+        return None
+
+    labels = list(plan.shared_color_map.keys())
+    template = load_color_template(color_path)
+    ordered = order_labels_by_template(
+        labels,
+        template,
+        category=plan.color_category,
+        entity_class=plan.color_entity_class,
+    )
+    new_map = build_shared_color_map(
+        ordered,
+        color_template=template,
+        category=plan.color_category,
+        entity_class=plan.color_entity_class,
+    )
+    plan.shared_color_map = new_map
+    return new_map