flextool 4.0.0__py3-none-any.whl

flextool/gui/dialogs/plot_settings_picker.py

@@ -0,0 +1,2184 @@
+"""Non-modal color/order picker for a project's ``plot_settings.yaml``.
+
+This is the GUI editor that replaces the old plain-text
+``PlotSettingsEditor``.  It treats the project ``plot_settings.yaml`` as a
+plain STRUCTURED data file (pyyaml load -> dict -> dump with
+``sort_keys=False``).  The window is **non-modal** so it can be used at the
+same time as the result viewer: every user edit writes the file **live**
+(debounced) and calls an ``on_apply`` callback (the viewer re-renders = live
+preview) while the window stays open — there is no Apply button.
+
+The window loads the file and renders a two-pane layout: a LEFT
+``ttk.Treeview`` selector lists every present section (fixed order, not
+reorderable) and the RIGHT pane shows the selected section's reorderable
+``ttk.Treeview``, each entry with a composite ``[pos][neg]`` swatch image
+next to its name.  Editing interactions:
+reorder (drag + Alt-arrow), per-row color dialog (double-click), and
+multi-level **Undo/Redo** over the in-memory working dict — each mutation
+schedules a debounced live write + ``on_apply``.  **Close** keeps all
+changes (flushes the pending live write); **Cancel** reverts to the on-open
+file text.  On open, the entity tabs are seeded additively from the solved
+``output_parquet`` dispatch (falling back to the project input DB(s) only
+when there is no dispatch output yet), with newly-discovered entries given a
+one-time std-dev order (see ``_order_new_names_by_std``); this on-open
+discovery does not itself write the file (only user actions do).
+"""
+
+from __future__ import annotations
+
+import base64
+import colorsys
+import copy
+import logging
+import struct
+import tkinter as tk
+import zlib
+from collections.abc import Callable
+from pathlib import Path
+from tkinter import ttk
+
+import numpy as np
+import yaml
+
+from flextool.scenario_comparison.plot_settings_seed import dump_plot_settings
+
+logger = logging.getLogger(__name__)
+
+# Entity classes, in the order they should appear as tabs.
+_ENTITY_CLASSES = ("nodeGroup", "flowGroup", "unit", "connection", "node")
+# Category subsections, in tab order.
+_CATEGORY_SECTIONS = ("costs", "node_flows", "nodegroup_flows", "dispatch")
+
+# The ``("categories", "dispatch")`` category is ENGINE-FIXED order (see the
+# module docstring for the stack): its special columns are pinned by the
+# engine — positive specials at the top, negative specials at the bottom — with
+# the movable flowGroup entity bands stacked near the zero axis in between.  In
+# the picker it is therefore rendered as a NON-reorderable list that mirrors
+# that stack, with a synthetic, immovable divider row marking where the flow
+# bands stack.  ``_DIVIDER_TAG`` tags the divider row (a Treeview tag used for
+# its distinct highlight); ``_DIVIDER_TEXT`` is the display-only label — it is
+# NEVER a key in ``self._data`` and must never be treated as an entity.
+_DISPATCH_SECTION = ("categories", "dispatch")
+_DIVIDER_TAG = "flowgroups_divider"
+_DIVIDER_TEXT = "flowGroups"
+# Sentinel marking the divider's position in the dispatch display sequence.
+_DIVIDER = object()
+
+# Swatch geometry (pixels).  Entity rows show two boxes (positive | gap |
+# negative); categories / scenarios show one.  ``_SWATCH_GAP`` separates the
+# two boxes; ``_SWATCH_PAD_L`` / ``_SWATCH_PAD_R`` inset the boxes from the
+# (indicator-less) cell edge and from the row name.
+_SWATCH_H = 14
+_SWATCH_W = 14  # width of ONE box
+_SWATCH_GAP = 4  # transparent gap between the positive and negative boxes
+_SWATCH_PAD_L = 3  # small left inset
+_SWATCH_PAD_R = 6  # gap after the boxes, before the row name
+_SWATCH_BORDER = (0x80, 0x80, 0x80)  # gray 1px frame so swatches read on any bg
+
+
+def _swatch_width(two_box: bool) -> int:
+    """Total swatch image width for a two-box (entity) or single row."""
+    boxes = _SWATCH_W * 2 + _SWATCH_GAP if two_box else _SWATCH_W
+    return _SWATCH_PAD_L + boxes + _SWATCH_PAD_R
+
+
+def _to_rgb255(value) -> tuple[int, int, int]:
+    """Best-effort parse of a YAML color value to an ``(r, g, b)`` 0..255 tuple.
+
+    Accepts ``#RRGGBB`` hex strings, ``[r, g, b]`` lists (0..1 floats or
+    0..255 ints), and matplotlib named colors (e.g. ``crimson``, ``aqua``
+    used by the dispatch defaults).  Falls back to a neutral mid-gray for
+    anything unparseable so a row always shows a swatch.
+    """
+    # Hex / list path reuses the canonical plot-side parser (0..1 floats).
+    from flextool.plot_outputs.color_template import _parse_color_value
+
+    rgb = _parse_color_value(value)
+    if rgb is None and isinstance(value, str):
+        # Named colors (matplotlib) — only the dispatch defaults use these.
+        try:
+            import matplotlib.colors as mcolors
+
+            rgb = mcolors.to_rgb(value.strip())
+        except (ValueError, ImportError):
+            rgb = None
+    if rgb is None:
+        return (0x99, 0x99, 0x99)
+    return (
+        max(0, min(255, round(rgb[0] * 255))),
+        max(0, min(255, round(rgb[1] * 255))),
+        max(0, min(255, round(rgb[2] * 255))),
+    )
+
+
+def _resolve_pos_neg(value) -> tuple[object, object | None]:
+    """Split an entity entry into ``(pos_value, neg_value_or_None)``.
+
+    A bare color -> ``(color, None)`` (pos == neg).  A mapping
+    ``{color, neg_color}`` -> ``(color, neg_color)``; a mapping with only
+    ``color`` -> ``(color, None)``.
+    """
+    if isinstance(value, dict):
+        return value.get("color"), value.get("neg_color")
+    return value, None
+
+
+def _to_hex(value) -> str:
+    """Normalize any YAML color value to a lowercase ``#RRGGBB`` hex string.
+
+    Reuses the same best-effort parser as the swatches so a named color
+    (e.g. ``lime``) or an ``[r, g, b]`` list becomes a concrete hex the
+    color chooser can seed its initial swatch from.
+    """
+    return "#%02x%02x%02x" % _to_rgb255(value)
+
+
+def _photo_from_rgb(arr: np.ndarray) -> tk.PhotoImage:
+    """Build a Tk ``PhotoImage`` from an ``(H, W, 3)`` uint8 RGB array.
+
+    Encodes a minimal truecolor PNG (numpy + stdlib ``zlib``/``struct``,
+    no Pillow) and hands the base64 to Tk, which reads PNG natively from
+    8.6 on.  ~2 ms for a 168x168 square, fast enough for live hue drags.
+    """
+    h, w, _ = arr.shape
+    rows = np.empty((h, 1 + w * 3), "uint8")
+    rows[:, 0] = 0  # PNG filter type 0 (none) per scanline
+    rows[:, 1:] = np.ascontiguousarray(arr).reshape(h, w * 3)
+
+    def _chunk(typ: bytes, data: bytes) -> bytes:
+        return (
+            struct.pack(">I", len(data)) + typ + data
+            + struct.pack(">I", zlib.crc32(typ + data) & 0xFFFFFFFF)
+        )
+
+    png = (
+        b"\x89PNG\r\n\x1a\n"
+        + _chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+        + _chunk(b"IDAT", zlib.compress(rows.tobytes(), 6))
+        + _chunk(b"IEND", b"")
+    )
+    return tk.PhotoImage(data=base64.b64encode(png))
+
+
+def _sv_square_photo(hue: float, size: int) -> tk.PhotoImage:
+    """Saturation (x, 0→1) × Value (y, top 1 → bottom 0) square at *hue*."""
+    ss = np.linspace(0.0, 1.0, size)[None, :].repeat(size, 0)
+    vv = np.linspace(1.0, 0.0, size)[:, None].repeat(size, 1)
+    i = int(hue * 6.0) % 6
+    f = hue * 6.0 - int(hue * 6.0)
+    p = vv * (1.0 - ss)
+    q = vv * (1.0 - f * ss)
+    t = vv * (1.0 - (1.0 - f) * ss)
+    rgb = [
+        (vv, t, p), (q, vv, p), (p, vv, t),
+        (p, q, vv), (t, p, vv), (vv, p, q),
+    ][i]
+    arr = (np.stack(rgb, -1) * 255.0 + 0.5).astype("uint8")
+    return _photo_from_rgb(arr)
+
+
+def _hue_bar_photo(width: int, height: int) -> tk.PhotoImage:
+    """Vertical full-saturation/value hue ramp (top 0 → bottom 1)."""
+    hues = np.linspace(0.0, 1.0, height)
+    rgb = np.array([colorsys.hsv_to_rgb(h, 1.0, 1.0) for h in hues])
+    arr = (np.repeat(rgb[:, None, :], width, 1) * 255.0 + 0.5).astype("uint8")
+    return _photo_from_rgb(arr)
+
+
+class _ColorChooser(ttk.Frame):
+    """An embedded HSV color picker (no OS dialog, no Pillow).
+
+    A saturation/value square + a vertical hue slider (both drag-pickable)
+    with a live "new" preview and editable Hex / R,G,B / H,S,V fields.  The
+    canonical state is ``(h, s, v)`` floats in ``0..1``; RGB/Hex are derived.
+
+    Callbacks:
+
+    * ``on_change(hex)`` — fired on EVERY change (user or programmatic);
+      used by the dialog to mirror a linked negative and update previews.
+    * ``on_user_edit()`` — fired only on USER-initiated changes (square /
+      slider / entry commit); used by the dialog to break the link when the
+      user edits the negative.
+    """
+
+    SQ = 168          # square edge (px)
+    HUE_W = 18        # hue-bar width (px)
+
+    def __init__(
+        self,
+        parent: tk.Misc,
+        initial_hex: str,
+        on_change: Callable[[str], None] | None = None,
+        on_user_edit: Callable[[], None] | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self._on_change = on_change
+        self._on_user_edit = on_user_edit
+        self._sq_img: tk.PhotoImage | None = None
+        self._hue_img: tk.PhotoImage | None = None
+
+        r, g, b = (c / 255.0 for c in _to_rgb255(initial_hex))
+        self._h, self._s, self._v = colorsys.rgb_to_hsv(r, g, b)
+
+        # ── Square + hue canvases ─────────────────────────────────
+        self._sq = tk.Canvas(
+            self, width=self.SQ, height=self.SQ, highlightthickness=1,
+            highlightbackground="#808080", cursor="crosshair",
+        )
+        self._sq.grid(row=0, column=0, rowspan=8, sticky="nw")
+        self._hue = tk.Canvas(
+            self, width=self.HUE_W, height=self.SQ, highlightthickness=1,
+            highlightbackground="#808080", cursor="sb_v_double_arrow",
+        )
+        self._hue.grid(row=0, column=1, rowspan=8, sticky="nw", padx=(6, 10))
+
+        self._sq.bind("<ButtonPress-1>", self._on_square_drag)
+        self._sq.bind("<B1-Motion>", self._on_square_drag)
+        self._hue.bind("<ButtonPress-1>", self._on_hue_drag)
+        self._hue.bind("<B1-Motion>", self._on_hue_drag)
+
+        # ── Fields column ─────────────────────────────────────────
+        fields = ttk.Frame(self)
+        fields.grid(row=0, column=2, sticky="nw")
+
+        self._preview = tk.Label(
+            fields, width=10, height=2, relief="solid", borderwidth=1,
+        )
+        self._preview.grid(row=0, column=0, columnspan=2, sticky="w",
+                           pady=(0, 8))
+
+        self._entries: dict[str, ttk.Entry] = {}
+
+        def _row(rownum: int, label: str, key: str, commit) -> None:
+            ttk.Label(fields, text=label).grid(
+                row=rownum, column=0, sticky="e", padx=(0, 4), pady=1,
+            )
+            ent = ttk.Entry(fields, width=10)
+            ent.grid(row=rownum, column=1, sticky="w", pady=1)
+            ent.bind("<Return>", commit)
+            ent.bind("<FocusOut>", commit)
+            self._entries[key] = ent
+
+        _row(1, "Hex", "hex", self._commit_hex)
+        _row(2, "R", "r", self._commit_rgb)
+        _row(3, "G", "g", self._commit_rgb)
+        _row(4, "B", "b", self._commit_rgb)
+        _row(5, "H°", "h", self._commit_hsv)
+        _row(6, "S%", "s", self._commit_hsv)
+        _row(7, "V%", "v", self._commit_hsv)
+
+        self._render_hue_bar()
+        self._render_square()
+        self._sync_all()
+
+    # ── Public API ────────────────────────────────────────────────
+    def get_hex(self) -> str:
+        r, g, b = colorsys.hsv_to_rgb(self._h, self._s, self._v)
+        return "#%02x%02x%02x" % (
+            round(r * 255), round(g * 255), round(b * 255),
+        )
+
+    def set_hex(self, hex_str: str, *, user: bool = False) -> None:
+        """Set the color from a hex string (programmatic mirror by default)."""
+        r, g, b = (c / 255.0 for c in _to_rgb255(hex_str))
+        h, s, v = colorsys.rgb_to_hsv(r, g, b)
+        self._apply_hsv(h, s, v, user=user, redraw_square=True)
+
+    # ── Rendering ─────────────────────────────────────────────────
+    def _render_square(self) -> None:
+        self._sq_img = _sv_square_photo(self._h, self.SQ)
+        self._sq.delete("img")
+        self._sq.create_image(0, 0, anchor="nw", image=self._sq_img, tags="img")
+        self._sq.tag_lower("img")
+        self._draw_square_marker()
+
+    def _render_hue_bar(self) -> None:
+        self._hue_img = _hue_bar_photo(self.HUE_W, self.SQ)
+        self._hue.delete("img")
+        self._hue.create_image(0, 0, anchor="nw", image=self._hue_img, tags="img")
+        self._hue.tag_lower("img")
+        self._draw_hue_marker()
+
+    def _draw_square_marker(self) -> None:
+        x = self._s * (self.SQ - 1)
+        y = (1.0 - self._v) * (self.SQ - 1)
+        self._sq.delete("marker")
+        for col, rad in (("#000000", 6), ("#ffffff", 5)):
+            self._sq.create_oval(
+                x - rad, y - rad, x + rad, y + rad,
+                outline=col, width=1, tags="marker",
+            )
+
+    def _draw_hue_marker(self) -> None:
+        y = self._h * (self.SQ - 1)
+        self._hue.delete("marker")
+        self._hue.create_rectangle(
+            0, y - 2, self.HUE_W, y + 2,
+            outline="#000000", width=1, tags="marker",
+        )
+        self._hue.create_rectangle(
+            1, y - 1, self.HUE_W - 1, y + 1,
+            outline="#ffffff", width=1, tags="marker",
+        )
+
+    def _update_preview(self) -> None:
+        self._preview.configure(background=self.get_hex())
+
+    # ── Entry sync (no recursion: set via delete/insert) ──────────
+    def _set_entry(self, key: str, text: str) -> None:
+        ent = self._entries[key]
+        had = str(ent.cget("state"))
+        ent.configure(state="normal")
+        ent.delete(0, "end")
+        ent.insert(0, text)
+        ent.configure(state=had)
+
+    def _sync_entries(self) -> None:
+        r, g, b = colorsys.hsv_to_rgb(self._h, self._s, self._v)
+        self._set_entry("hex", self.get_hex())
+        self._set_entry("r", str(round(r * 255)))
+        self._set_entry("g", str(round(g * 255)))
+        self._set_entry("b", str(round(b * 255)))
+        self._set_entry("h", str(round(self._h * 360)))
+        self._set_entry("s", str(round(self._s * 100)))
+        self._set_entry("v", str(round(self._v * 100)))
+
+    def _sync_all(self) -> None:
+        self._draw_square_marker()
+        self._draw_hue_marker()
+        self._update_preview()
+        self._sync_entries()
+
+    # ── Central update ────────────────────────────────────────────
+    def _apply_hsv(
+        self, h: float, s: float, v: float, *,
+        user: bool, redraw_square: bool,
+    ) -> None:
+        self._h = min(1.0, max(0.0, h))
+        self._s = min(1.0, max(0.0, s))
+        self._v = min(1.0, max(0.0, v))
+        if redraw_square:
+            self._render_square()
+        self._sync_all()
+        if self._on_change is not None:
+            self._on_change(self.get_hex())
+        if user and self._on_user_edit is not None:
+            self._on_user_edit()
+
+    # ── Canvas interaction ────────────────────────────────────────
+    def _on_square_drag(self, event: tk.Event) -> None:
+        s = min(1.0, max(0.0, event.x / (self.SQ - 1)))
+        v = 1.0 - min(1.0, max(0.0, event.y / (self.SQ - 1)))
+        self._apply_hsv(self._h, s, v, user=True, redraw_square=False)
+
+    def _on_hue_drag(self, event: tk.Event) -> None:
+        h = min(1.0, max(0.0, event.y / (self.SQ - 1)))
+        self._apply_hsv(h, self._s, self._v, user=True, redraw_square=True)
+
+    # ── Entry commits ─────────────────────────────────────────────
+    def _commit_hex(self, _event=None) -> None:
+        raw = self._entries["hex"].get().strip()
+        rgb = _parse_hex_or_none(raw)
+        if rgb is None:
+            self._sync_entries()  # revert invalid text
+            return
+        h, s, v = colorsys.rgb_to_hsv(*(c / 255.0 for c in rgb))
+        self._apply_hsv(h, s, v, user=True, redraw_square=True)
+
+    def _commit_rgb(self, _event=None) -> None:
+        try:
+            r = _clamp_int(self._entries["r"].get(), 0, 255)
+            g = _clamp_int(self._entries["g"].get(), 0, 255)
+            b = _clamp_int(self._entries["b"].get(), 0, 255)
+        except ValueError:
+            self._sync_entries()
+            return
+        h, s, v = colorsys.rgb_to_hsv(r / 255.0, g / 255.0, b / 255.0)
+        self._apply_hsv(h, s, v, user=True, redraw_square=True)
+
+    def _commit_hsv(self, _event=None) -> None:
+        try:
+            h = _clamp_int(self._entries["h"].get(), 0, 360) / 360.0
+            s = _clamp_int(self._entries["s"].get(), 0, 100) / 100.0
+            v = _clamp_int(self._entries["v"].get(), 0, 100) / 100.0
+        except ValueError:
+            self._sync_entries()
+            return
+        self._apply_hsv(h, s, v, user=True, redraw_square=True)
+
+
+def _parse_hex_or_none(text: str) -> tuple[int, int, int] | None:
+    """Parse ``#rrggbb`` / ``rrggbb`` to an ``(r, g, b)`` tuple, else None."""
+    s = text.strip().lstrip("#")
+    if len(s) != 6:
+        return None
+    try:
+        return int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
+    except ValueError:
+        return None
+
+
+def _clamp_int(text: str, lo: int, hi: int) -> int:
+    """Parse *text* to an int clamped to ``[lo, hi]`` (raises on non-int)."""
+    return min(hi, max(lo, int(float(text.strip()))))
+
+
+class ColorPickerDialog(tk.Toplevel):
+    """Modal embedded color editor for one row.
+
+    Hosts an embedded :class:`_ColorChooser` (saturation/value square + hue
+    slider + numeric fields).  With ``single=False`` (the default, for entity
+    rows) it shows TWO choosers side by side — left **positive**, right
+    **negative** — under a **"Link negative to positive"** checkbox:
+
+    * **linked** (checked): the negative mirrors the positive (and its value
+      is ignored on OK).  Default for a bare ``"#color"`` entry.  The panel
+      stays interactive — see below.
+    * **unlinked** (unchecked): positive and negative are independent.
+      Default for a ``{color, neg_color}`` entry.
+
+    The negative panel is never greyed out: while linked its value has no
+    meaning, but the moment the user edits it that is taken as intent to
+    separate, so it **auto-breaks the link** (unchecks the box).  Re-checking
+    RE-LINKS (``neg := pos``).
+
+    With ``single=True`` (categories / scenarios — one color, no negative)
+    only the positive chooser is shown; the negative panel and the link
+    checkbox are hidden.
+
+    The result is read from :pyattr:`result` after ``wait_window``:
+    ``(pos_hex, neg_hex_or_None)`` on OK (``neg_hex`` is ``None`` when single
+    or linked, else the explicit negative), or ``None`` on Cancel.
+    """
+
+    def __init__(
+        self,
+        parent: tk.Misc,
+        name: str,
+        pos_hex: str,
+        neg_hex: str,
+        linked: bool,
+        *,
+        single: bool = False,
+    ) -> None:
+        super().__init__(parent)
+        self.title(f"Color — {name}")
+        self.transient(parent)
+        self.resizable(False, False)
+
+        self._single = single
+        self._linked = tk.BooleanVar(value=True if single else linked)
+        self.result: tuple[str, str | None] | None = None
+
+        body = ttk.Frame(self, padding=12)
+        body.grid(row=0, column=0, sticky="nsew")
+
+        if not single:
+            ttk.Checkbutton(
+                body,
+                text="Link negative to positive",
+                variable=self._linked,
+                command=self._on_link_toggle,
+            ).grid(row=0, column=0, columnspan=2, sticky="w", pady=(0, 8))
+
+        panels = ttk.Frame(body)
+        panels.grid(row=1, column=0, columnspan=2, sticky="nw")
+
+        pos_panel = ttk.Frame(panels)
+        pos_panel.grid(row=0, column=0, sticky="nw")
+        if not single:
+            ttk.Label(pos_panel, text="Positive").grid(
+                row=0, column=0, sticky="w", pady=(0, 2),
+            )
+        self._pos_chooser = _ColorChooser(
+            pos_panel, _to_hex(pos_hex), on_change=self._on_pos_change,
+        )
+        self._pos_chooser.grid(row=1, column=0, sticky="nw")
+
+        self._neg_chooser: _ColorChooser | None = None
+        if not single:
+            neg_panel = ttk.Frame(panels)
+            neg_panel.grid(row=0, column=1, sticky="nw", padx=(16, 0))
+            ttk.Label(neg_panel, text="Negative").grid(
+                row=0, column=0, sticky="w", pady=(0, 2),
+            )
+            self._neg_chooser = _ColorChooser(
+                neg_panel, _to_hex(neg_hex),
+                on_user_edit=self._on_neg_user_edit,
+            )
+            self._neg_chooser.grid(row=1, column=0, sticky="nw")
+
+        # OK / Cancel.
+        btns = ttk.Frame(self, padding=(12, 0, 12, 12))
+        btns.grid(row=1, column=0, sticky="ew")
+        ttk.Button(btns, text="Cancel", command=self._on_cancel).pack(
+            side="right", padx=(5, 0),
+        )
+        self._ok_button = ttk.Button(
+            btns, text="OK", command=self._on_ok, default="active",
+        )
+        self._ok_button.pack(side="right")
+
+        if not single:
+            self._apply_link_state()
+
+        self.bind("<Return>", lambda _e: self._on_ok())
+        self.bind("<Escape>", lambda _e: self._on_cancel())
+        self.protocol("WM_DELETE_WINDOW", self._on_cancel)
+        self._grab_when_viewable()
+
+    def _grab_when_viewable(self) -> None:
+        """Acquire the modal grab as soon as the window is mapped.
+
+        ``grab_set`` on a not-yet-mapped Toplevel raises ``"grab failed:
+        window not viewable"`` under some window managers (the Toplevel is
+        created but the WM hasn't mapped it yet).  Retry on the Tk event
+        loop until it maps, then take keyboard focus on OK (the Enter
+        target).  Guarded against a window destroyed before it ever mapped.
+        """
+        if not self.winfo_exists():
+            return
+        try:
+            self.grab_set()
+        except tk.TclError:
+            self.after(20, self._grab_when_viewable)
+            return
+        try:
+            self._ok_button.focus_set()
+        except tk.TclError:
+            pass
+
+    # ── Link logic ────────────────────────────────────────────────
+    def _on_pos_change(self, hex_str: str) -> None:
+        """Mirror the positive onto a linked negative (programmatic)."""
+        if (
+            not self._single
+            and self._linked.get()
+            and self._neg_chooser is not None
+        ):
+            self._neg_chooser.set_hex(hex_str, user=False)
+
+    def _on_neg_user_edit(self) -> None:
+        """A user edit to the negative separates the two colors → unlink."""
+        if self._linked.get():
+            self._linked.set(False)
+            self._apply_link_state()
+
+    def _on_link_toggle(self) -> None:
+        """Checkbox toggled: re-check mirrors neg:=pos; uncheck frees neg."""
+        self._apply_link_state()
+
+    def _apply_link_state(self) -> None:
+        """When linked, mirror the negative onto the positive.
+
+        The negative panel stays interactive even while linked: its value
+        is simply ignored on OK (linked → neg is None), and the moment the
+        user touches it the link auto-breaks (see ``_on_neg_user_edit``).
+        """
+        if self._neg_chooser is None:
+            return
+        if self._linked.get():
+            self._neg_chooser.set_hex(
+                self._pos_chooser.get_hex(), user=False,
+            )
+
+    # ── Result ────────────────────────────────────────────────────
+    def _on_ok(self) -> None:
+        pos = self._pos_chooser.get_hex()
+        if self._single or self._linked.get() or self._neg_chooser is None:
+            self.result = (pos, None)
+        else:
+            self.result = (pos, self._neg_chooser.get_hex())
+        self.destroy()
+
+    def _on_cancel(self) -> None:
+        self.result = None
+        self.destroy()
+
+
+class PlotSettingsPicker(tk.Toplevel):
+    """Non-modal color/order picker for a project ``plot_settings.yaml``.
+
+    Parameters
+    ----------
+    parent:
+        Owning widget; the window is ``transient`` to it but NOT modal
+        (no ``grab_set``), so the result viewer stays usable.
+    settings_path:
+        Path to the project ``plot_settings.yaml`` (already seeded by the
+        caller via ``seed_plot_settings``).
+    on_apply:
+        Optional zero-arg callback invoked after every live write
+        (debounced, on each user edit), on Close, and after a Cancel
+        restore, so an opener with a live preview (the result viewer)
+        re-renders with the current on-disk colors.  Pass ``None`` for no
+        live preview (the PNG batch dialog).
+    """
+
+    # Debounce for the live write + re-render: a burst of edits (e.g. a
+    # hue drag committed through several handler calls) collapses into one
+    # write after the last change settles.
+    _LIVE_UPDATE_MS = 250
+
+    def __init__(
+        self,
+        parent: tk.Misc,
+        settings_path: Path,
+        on_apply: Callable[[], None] | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.title("Colors and order")
+        self._settings_path = Path(settings_path)
+        self._on_apply = on_apply
+        # Pending debounced live-update ``after`` id (None = none pending).
+        self._live_after_id: str | None = None
+
+        # Non-modal: transient (stacks with the parent, no taskbar entry on
+        # some WMs) but NO grab_set / wait_window — the viewer stays live.
+        self.transient(parent)
+
+        # Strong references to every PhotoImage so Tk does not GC them
+        # (a GC'd image renders blank in the Treeview cell).
+        self._swatches: list[tk.PhotoImage] = []
+
+        # Per-tree reorder bookkeeping: maps a Treeview to the
+        # ``(*keys,)`` path of its section in the working dict (e.g.
+        # ``("entities", "unit")`` or ``("scenarios",)``) so a reorder can
+        # rewrite exactly that section.  Drag state distinguishes a MOVE
+        # drag (press began on an already-selected row → move the whole
+        # selection) from a native draw-select drag (press on an unselected
+        # row → let ttk extend the selection).  ``_drag_anchor`` is the
+        # pressed row; ``_drag_moved`` records whether the drag actually
+        # reordered (so a click-without-move can collapse the selection).
+        self._tree_section: dict[ttk.Treeview, tuple[str, ...]] = {}
+        self._drag_move: dict[ttk.Treeview, bool] = {}
+        self._drag_anchor: dict[ttk.Treeview, str | None] = {}
+        self._drag_moved: dict[ttk.Treeview, bool] = {}
+        # Whether a tree's rows carry a positive AND negative color
+        # (entities) or a single color (categories / scenarios).  Drives
+        # the double-click edit dialog and the swatch rebuild.
+        self._tree_composite: dict[ttk.Treeview, bool] = {}
+        # Per-row PhotoImage references after an in-place swatch rebuild,
+        # keyed by ``(tree, item_id)`` so the replacement survives GC
+        # (the originals in ``self._swatches`` stay too).
+        self._row_swatches: dict[tuple[ttk.Treeview, str], tk.PhotoImage] = {}
+        # Trees rendered in a FIXED (engine-pinned) order — currently only the
+        # dispatch category.  Their rows are never reorderable (drag / Alt-move
+        # are no-ops) and never synced back to ``self._data``; the specials'
+        # colors stay editable.  ``_divider_items`` holds every synthetic
+        # divider row as ``(tree, item_id)`` so it can be recognised (and
+        # skipped) everywhere a tree row maps back to an entity.
+        self._fixed_order_trees: set[ttk.Treeview] = set()
+        self._divider_items: set[tuple[ttk.Treeview, str]] = set()
+        # Lazily-built italic font for the divider row (None until first use);
+        # a copy of TkDefaultFont so it tracks the theme's default face/size.
+        self._divider_font: object | None = None
+
+        # Working state = parsed dict; snapshot the original TEXT for Cancel.
+        self._original_text = self._read_text()
+        self._data = self._parse(self._original_text)
+        # Populate the scenarios section from the project's output folders so
+        # the always-shown scenarios tab is useful before any comparison run.
+        # Add-only; Cancel still restores the on-disk text untouched.
+        self._merge_scenarios_from_folders()
+        # Populate the entity sections from the input DB(s) ∪ the dispatch
+        # output aggregates so every drawn entity — including processGroup
+        # aggregates that live only in solved output (e.g. ``Fossil``) — is
+        # listable/colorable on open, without a manual "Refresh from DB".
+        # Add-only; Cancel still restores the on-disk text untouched.
+        self._merge_entities_from_sources()
+
+        # Dispatch-aggregator flowGroup set (display filter only — never
+        # touches ``self._data``): parquet ``group_aggregate`` names ∪ input-DB
+        # ``flow_aggregator`` ∈ {dispatch_plots_only, both}.  Computed ONCE here
+        # and reused by every (re)build (including undo/redo) so the flowGroup
+        # tab lists only dispatch aggregators; a non-aggregator flowGroup stays
+        # in the file but is not drawn.  Guarded like the merge above so a
+        # discovery failure can never break the window opening — an empty set
+        # then disables the filter (all flowGroups show).
+        try:
+            self._dispatch_flowgroup_aggregators = (
+                self._compute_dispatch_flowgroup_aggregators()
+            )
+        except Exception as exc:  # never let discovery break the window open
+            logger.warning("flowGroup aggregator discovery on open failed: %s", exc)
+            self._dispatch_flowgroup_aggregators = set()
+
+        # In-memory edit history (deep copies of ``self._data``).  Every
+        # mutator calls ``_snapshot()`` (push pre-edit state, clear redo)
+        # before it changes ``self._data``; undo/redo move states between
+        # the two stacks and rebuild every tab from ``self._data``.  This
+        # history is independent of the on-disk Cancel snapshot above.
+        self._undo_stack: list[dict] = []
+        self._redo_stack: list[dict] = []
+        # Set by undo/redo button construction; refreshed by
+        # ``_update_history_buttons`` to reflect stack emptiness.
+        self._undo_button: ttk.Button | None = None
+        self._redo_button: ttk.Button | None = None
+
+        # ── Sizing ────────────────────────────────────────────────
+        from flextool.gui.ui_metrics import get_metrics
+
+        _metrics = get_metrics(self)
+        cw = _metrics.cw
+        lh = _metrics.lh
+        # The two-pane layout (a narrow left category selector + one entity
+        # list) needs only ~half the old notebook width, so the default is
+        # much narrower.  Width clamps to the screen (40px margin); height is
+        # a fixed 80% of the screen, positioned with a 10% top/bottom margin
+        # and centred horizontally.
+        _margin = 40
+        _w = min(cw * 59, self.winfo_screenwidth() - _margin)
+        _h = int(self.winfo_screenheight() * 0.8)
+        _y = int(self.winfo_screenheight() * 0.1)
+        _x = max(0, (self.winfo_screenwidth() - _w) // 2)
+        self.geometry(f"{_w}x{_h}+{_x}+{_y}")
+        self.resizable(True, True)
+        self.minsize(cw * 22, lh * 16)
+
+        self.columnconfigure(0, weight=1)
+        self.rowconfigure(0, weight=1)
+
+        self._tree_style = self._make_tree_style()
+
+        # ── Two-pane category-list + entity-list layout ───────────
+        # A horizontal ``PanedWindow`` (user-resizable sash): the LEFT pane is
+        # a narrow, single-select category selector (fixed order — a selector
+        # only, never reorderable); the RIGHT pane holds one entity Treeview
+        # per category, of which only the selected category's tree is shown.
+        self._paned = ttk.PanedWindow(self, orient="horizontal")
+        self._paned.grid(row=0, column=0, sticky="nsew", padx=10, pady=(10, 4))
+
+        left = ttk.Frame(self._paned)
+        left.columnconfigure(0, weight=1)
+        left.rowconfigure(0, weight=1)
+        self._category_list = ttk.Treeview(
+            left, show="tree", selectmode="browse",
+        )
+        self._category_list.grid(row=0, column=0, sticky="nsew")
+        _cat_scroll = ttk.Scrollbar(
+            left, orient="vertical", command=self._category_list.yview,
+        )
+        _cat_scroll.grid(row=0, column=1, sticky="ns")
+        self._category_list.configure(yscrollcommand=_cat_scroll.set)
+        # Pure selector: selection swaps the visible right-pane tree.  NO
+        # drag / Alt-arrow / move bindings are attached here.
+        self._category_list.bind(
+            "<<TreeviewSelect>>", self._on_category_select,
+        )
+
+        # Right pane: a container holding every category's entity tree; only
+        # the selected one is shown (grid / grid_remove) so per-tree state
+        # persists across selections.
+        self._entity_container = ttk.Frame(self._paned)
+        self._entity_container.columnconfigure(0, weight=1)
+        self._entity_container.rowconfigure(0, weight=1)
+
+        self._paned.add(left, weight=0)
+        self._paned.add(self._entity_container, weight=1)
+
+        # Category-selector state (exposed for tests): display order + the
+        # per-category entity tree / frame / left-list item, and the title of
+        # the currently-shown category.
+        self._category_order: list[str] = []
+        self._category_trees: dict[str, ttk.Treeview] = {}
+        self._category_frames: dict[str, ttk.Frame] = {}
+        self._category_items: dict[str, str] = {}
+        self._current_category: str | None = None
+
+        self._build_panes()
+
+        # ── Buttons ───────────────────────────────────────────────
+        # Buttons are CREATED in tab-traversal order (Undo → Redo → Cancel →
+        # Close) — Tk's focus traversal follows the parent's child order.
+        # ``grid`` then places them visually (left cluster / flexible spacer /
+        # right cluster), decoupling the on-screen layout from the traversal
+        # order.  Edits now write the file LIVE (debounced), so there is no
+        # Apply button; Refresh is gone too — the on-open discovery already
+        # seeds every listable entity add-only (stale entries are harmless).
+        btn_frame = ttk.Frame(self)
+        btn_frame.grid(row=1, column=0, sticky="ew", padx=10, pady=(4, 10))
+        btn_frame.columnconfigure(2, weight=1)  # spacer between clusters
+
+        self._undo_button = ttk.Button(
+            btn_frame, text="Undo", command=self._on_undo,
+        )
+        self._undo_button.grid(row=0, column=0)
+        self._redo_button = ttk.Button(
+            btn_frame, text="Redo", command=self._on_redo,
+        )
+        self._redo_button.grid(row=0, column=1, padx=(5, 0))
+        ttk.Button(
+            btn_frame, text="Cancel", command=self._on_cancel,
+        ).grid(row=0, column=3, padx=(5, 0))
+        ttk.Button(
+            btn_frame, text="Close", command=self._on_close,
+        ).grid(row=0, column=4, padx=(5, 0))
+        self._update_history_buttons()
+
+        # ── Keyboard-shortcut hint strip (two rows) ───────────────
+        ttk.Label(
+            self,
+            text=(
+                "Enter: edit selected row    "
+                "Alt+↑ / Alt+↓: move row    drag: reorder\n"
+                "Changes apply live    "
+                "Ctrl+Z: undo    Ctrl+Y: redo    Esc: close (keeps changes)"
+            ),
+            foreground="gray",
+            anchor="w",
+            justify="left",
+        ).grid(row=2, column=0, sticky="ew", padx=12, pady=(0, 8))
+
+        # Edits are written live, so Escape and the window ``X`` KEEP the
+        # user's changes (flush the pending write + close) — only the
+        # explicit Cancel button reverts to the on-open text.
+        self.bind("<Escape>", lambda _e: self._on_close())
+        self.bind("<Control-z>", lambda _e: self._on_undo())
+        self.bind("<Control-y>", lambda _e: self._on_redo())
+        self.bind("<Control-Shift-Z>", lambda _e: self._on_redo())
+        self.protocol("WM_DELETE_WINDOW", lambda: self._on_close())
+
+    # ── File I/O ──────────────────────────────────────────────────
+    def _read_text(self) -> str:
+        try:
+            return self._settings_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            logger.warning("Cannot read %s: %s", self._settings_path, exc)
+            return ""
+
+    @staticmethod
+    def _parse(text: str) -> dict:
+        try:
+            parsed = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            logger.warning("Cannot parse plot_settings.yaml: %s", exc)
+            return {}
+        return parsed if isinstance(parsed, dict) else {}
+
+    def _write(self) -> None:
+        """Dump the working dict back to the project file."""
+        self._settings_path.write_text(
+            dump_plot_settings(self._data), encoding="utf-8",
+        )
+
+    # ── Swatches ──────────────────────────────────────────────────
+    def _make_swatch(self, pos, neg=None, reserve_neg: bool = False) -> tk.PhotoImage:
+        """Build a swatch ``PhotoImage`` for one row.
+
+        Two fixed columns of boxes: the LEFT (positive) box is always drawn;
+        the RIGHT (negative) box is drawn only when *neg* is set.  On entity
+        rows pass ``reserve_neg=True`` so the image is always two boxes wide
+        even when *neg* is ``None`` — the negative half is left transparent,
+        which keeps every row's name text aligned and makes the negative box
+        appear/disappear in a fixed column.  Categories / scenarios (no
+        negative concept) pass ``reserve_neg=False`` for a single box.
+
+        The returned image is appended to ``self._swatches`` so it survives
+        garbage collection (a GC'd image renders blank in the cell).
+        """
+        pos_rgb = _to_rgb255(pos)
+        has_neg = neg is not None
+        two_box = has_neg or reserve_neg
+        width = _swatch_width(two_box)
+        img = tk.PhotoImage(width=width, height=_SWATCH_H)
+
+        def _fill(x0: int, x1: int, rgb: tuple[int, int, int]) -> None:
+            color = "#%02x%02x%02x" % rgb
+            border = "#%02x%02x%02x" % _SWATCH_BORDER
+            for x in range(x0, x1):
+                for y in range(_SWATCH_H):
+                    edge = (
+                        x == x0 or x == x1 - 1
+                        or y == 0 or y == _SWATCH_H - 1
+                    )
+                    img.put(border if edge else color, (x, y))
+
+        _fill(_SWATCH_PAD_L, _SWATCH_PAD_L + _SWATCH_W, pos_rgb)
+        if has_neg:
+            nx = _SWATCH_PAD_L + _SWATCH_W + _SWATCH_GAP
+            _fill(nx, nx + _SWATCH_W, _to_rgb255(neg))
+        # else: a reserved-but-unset negative box stays transparent, so it is
+        # invisible while the column (and name alignment) is kept.
+
+        self._swatches.append(img)
+        return img
+
+    # ── Edit history (undo / redo) ────────────────────────────────
+    def _snapshot(self) -> None:
+        """Push the PRE-edit ``self._data`` onto the undo stack.
+
+        Called by EVERY mutator (color write-back, reorder sync)
+        before it changes ``self._data``, so the undo stack always holds the
+        states to roll back to.  A fresh edit invalidates any redo history,
+        so the redo stack is cleared here.  States are deep copies so later
+        in-place edits to ``self._data`` cannot mutate them.
+        """
+        self._undo_stack.append(copy.deepcopy(self._data))
+        self._redo_stack.clear()
+        self._update_history_buttons()
+
+    def _on_undo(self) -> None:
+        """Roll back one edit: restore the last pre-edit ``self._data``."""
+        if not self._undo_stack:
+            return
+        self._redo_stack.append(copy.deepcopy(self._data))
+        self._data = self._undo_stack.pop()
+        self._rebuild_panes()
+        self._update_history_buttons()
+        self._schedule_live_update()
+
+    def _on_redo(self) -> None:
+        """Re-apply one undone edit."""
+        if not self._redo_stack:
+            return
+        self._undo_stack.append(copy.deepcopy(self._data))
+        self._data = self._redo_stack.pop()
+        self._rebuild_panes()
+        self._update_history_buttons()
+        self._schedule_live_update()
+
+    def _update_history_buttons(self) -> None:
+        """Enable/disable Undo/Redo to reflect each stack's emptiness."""
+        if self._undo_button is not None:
+            self._undo_button.configure(
+                state="normal" if self._undo_stack else "disabled",
+            )
+        if self._redo_button is not None:
+            self._redo_button.configure(
+                state="normal" if self._redo_stack else "disabled",
+            )
+
+    def _rebuild_panes(self) -> None:
+        """Discard every entity tree + left-list row and rebuild from
+        ``self._data``.
+
+        Used by undo/redo so the displayed trees + swatches exactly
+        match the (possibly replaced) working dict — order, colors, and row
+        presence.  All per-tree bookkeeping and swatch references are reset
+        so stale rows/images cannot leak across a rebuild.  The currently
+        selected category is preserved when it still exists, else the first
+        category is selected (``_build_panes`` already selects the first).
+        """
+        prev = self._current_category
+        for frame in self._category_frames.values():
+            frame.destroy()
+        # Clear category bookkeeping BEFORE deleting the left rows so a
+        # delete-driven ``<<TreeviewSelect>>`` finds no frames and no-ops.
+        self._category_order = []
+        self._category_trees = {}
+        self._category_frames = {}
+        self._category_items = {}
+        self._current_category = None
+        for item in self._category_list.get_children(""):
+            self._category_list.delete(item)
+        self._tree_section.clear()
+        self._drag_move.clear()
+        self._drag_anchor.clear()
+        self._drag_moved.clear()
+        self._tree_composite.clear()
+        self._row_swatches.clear()
+        self._fixed_order_trees.clear()
+        self._divider_items.clear()
+        self._swatches.clear()
+        self._build_panes()
+        if prev is not None and prev in self._category_trees:
+            self._show_category(prev)
+
+    # ── Pane construction ─────────────────────────────────────────
+    def _make_tree_style(self) -> str:
+        """Return a Treeview style whose item layout drops the disclosure
+        indicator, so leaf rows start flush-left (no ~18px indent) — the
+        swatch carries its own small inset instead.  Falls back to the
+        default ``"Treeview"`` style if the layout override is rejected.
+        """
+        name = "PlotSettingsPicker.Treeview"
+        style = ttk.Style(self)
+        try:
+            style.layout(name, style.layout("Treeview"))
+            style.layout(
+                f"{name}.Item",
+                [("Treeitem.padding", {"sticky": "nswe", "children": [
+                    ("Treeitem.image", {"side": "left", "sticky": ""}),
+                    ("Treeitem.text", {"side": "left", "sticky": ""}),
+                ]})],
+            )
+        except tk.TclError:
+            return "Treeview"
+        return name
+
+    def _build_panes(self) -> None:
+        """Populate the left category selector and the right entity trees.
+
+        Entity-class categories (nodeGroup / flowGroup / unit / connection /
+        node) are ALWAYS shown — even when empty — so it is visible that a
+        class has no entities (the on-open discovery seeds any it can).  The
+        scenarios category is ALWAYS shown too, and last.  Category
+        subsections appear only when present.  The first category (nodeGroup)
+        is selected by default.
+        """
+        entities = self._data.get("entities")
+        entities = entities if isinstance(entities, dict) else {}
+        for cls in _ENTITY_CLASSES:
+            section = entities.get(cls)
+            rows = list(section.items()) if isinstance(section, dict) else []
+            self._add_category(
+                title=cls,
+                rows=rows,
+                composite=True,
+                section_path=("entities", cls),
+            )
+
+        categories = self._data.get("categories")
+        if isinstance(categories, dict):
+            for name in _CATEGORY_SECTIONS:
+                section = categories.get(name)
+                if isinstance(section, dict) and section:
+                    self._add_category(
+                        title=name,
+                        rows=list(section.items()),
+                        composite=False,
+                        section_path=("categories", name),
+                    )
+
+        # Scenarios is ALWAYS shown, and last — users rarely edit it, but it
+        # must be discoverable so scenario-comparison colors are editable even
+        # before a comparison run (populated from output folders on open).
+        scenarios = self._data.get("scenarios")
+        scenarios = scenarios if isinstance(scenarios, dict) else {}
+        self._add_category(
+            title="scenarios",
+            rows=list(scenarios.items()),
+            composite=False,
+            section_path=("scenarios",),
+        )
+
+        # Default selection = the first category (nodeGroup).
+        if self._category_order:
+            self._show_category(self._category_order[0])
+
+    def _add_category(
+        self,
+        title: str,
+        rows: list[tuple[str, object]],
+        composite: bool,
+        section_path: tuple[str, ...],
+    ) -> None:
+        """Register a category: append it to the LEFT selector and build its
+        RIGHT-pane entity Treeview (initially hidden except the first).
+
+        The entity tree is built exactly as the old notebook tab was — same
+        widgets, same per-tree bookkeeping, same drag / Alt-arrow / edit
+        bindings — so all reorder / color-edit behaviour is unchanged; only
+        the container differs (a swapped grid cell instead of a notebook tab).
+        """
+        # Display filter (rows only — ``self._data`` is never touched, so the
+        # file still round-trips every flowGroup): the flowGroup tab lists ONLY
+        # dispatch aggregators (parquet ``group_aggregate`` ∪ input-DB
+        # ``flow_aggregator`` ∈ {dispatch_plots_only, both}).  When the
+        # aggregator set is empty (no DB and no parquet aggregates discovered —
+        # e.g. a pre-solve project with an unreadable DB) the filter is disabled
+        # so we never wrongly hide every flowGroup.
+        aggregators = getattr(self, "_dispatch_flowgroup_aggregators", None)
+        if section_path == ("entities", "flowGroup") and aggregators:
+            rows = [(name, value) for name, value in rows if name in aggregators]
+
+        # Left selector row (pure selector — no reorder bindings attached).
+        item = self._category_list.insert("", "end", text=title)
+        self._category_items[title] = item
+
+        # Right-pane entity tree (same construction as the old tab).
+        frame = ttk.Frame(self._entity_container)
+        frame.columnconfigure(0, weight=1)
+        frame.rowconfigure(0, weight=1)
+
+        tree = ttk.Treeview(
+            frame, show="tree", selectmode="extended", style=self._tree_style,
+        )
+        tree.grid(row=0, column=0, sticky="nsew")
+
+        vscroll = ttk.Scrollbar(frame, orient="vertical", command=tree.yview)
+        vscroll.grid(row=0, column=1, sticky="ns")
+        tree.configure(yscrollcommand=vscroll.set)
+
+        hscroll = ttk.Scrollbar(frame, orient="horizontal", command=tree.xview)
+        hscroll.grid(row=1, column=0, sticky="ew")
+        tree.configure(xscrollcommand=hscroll.set)
+
+        if section_path == _DISPATCH_SECTION:
+            # Render the stack top→bottom with the flowGroups divider between
+            # the positive and negative specials.  The specials are reorderable
+            # WITHIN each sign group (positives among themselves above the
+            # divider, negatives among themselves below), but a row may not
+            # cross the divider and the divider itself never moves — enforced in
+            # the reorder paths via the divider row index (see
+            # ``_clamp_insert_for_divider``).  The tree is therefore NOT added
+            # to ``_fixed_order_trees``.
+            self._insert_dispatch_rows(tree, rows)
+        else:
+            for name, value in rows:
+                if composite:
+                    pos, neg = _resolve_pos_neg(value)
+                    image = self._make_swatch(pos, neg, reserve_neg=True)
+                else:
+                    image = self._make_swatch(value, None)
+                tree.insert("", "end", text=str(name), image=image)
+
+        # Register for reordering and wire drag + keyboard moves.
+        self._tree_section[tree] = section_path
+        self._drag_move[tree] = False
+        self._drag_anchor[tree] = None
+        self._drag_moved[tree] = False
+        self._tree_composite[tree] = composite
+        tree.bind("<ButtonPress-1>", self._on_drag_start)
+        tree.bind("<B1-Motion>", self._on_drag_motion)
+        tree.bind("<ButtonRelease-1>", self._on_drag_end)
+        tree.bind("<Alt-Up>", self._on_key_move_up)
+        tree.bind("<Alt-Down>", self._on_key_move_down)
+        tree.bind("<Double-Button-1>", self._on_row_double_click)
+        tree.bind("<Return>", self._on_row_return)
+        tree.bind("<FocusIn>", self._on_tree_focus_in)
+
+        # All frames share the one container cell; built hidden and shown on
+        # selection (grid / grid_remove) so per-tree state survives swaps.
+        frame.grid(row=0, column=0, sticky="nsew")
+        frame.grid_remove()
+
+        self._category_order.append(title)
+        self._category_trees[title] = tree
+        self._category_frames[title] = frame
+
+    # ── Dispatch category: engine-fixed order + flowGroups divider ────
+    @staticmethod
+    def _order_dispatch_rows(
+        rows: list[tuple[str, object]],
+    ) -> list[object]:
+        """Order the dispatch section rows into the two sign groups + divider.
+
+        The dispatch plot's special columns split into a POSITIVE group (above
+        the zero axis) and a NEGATIVE group (below it); the flowGroups divider
+        marks the boundary where the movable flowGroup bands stack.  A special
+        can be reordered WITHIN its sign group but never crosses the divider (a
+        positive special is always positive).  So the picker renders the
+        positive specials, then the divider sentinel, then the negative
+        specials — each group in the FILE's top-to-bottom key order, which is
+        the visual top-to-bottom stack order the engine honors
+        (``categories.dispatch`` order → ``special_order`` in
+        ``dispatch_data._order_dispatch_columns``).  Only rows actually present
+        are emitted.  Any entry that is neither a positive nor a negative
+        special (defensive — should not occur) is appended just BEFORE the
+        divider so it never masquerades as a negative band.
+
+        Returns a display sequence of ``(name, value)`` tuples with the
+        :data:`_DIVIDER` sentinel marking the divider position.
+        """
+        from flextool.scenario_comparison.constants import (
+            NEGATIVE_SPECIAL,
+            POSITIVE_SPECIAL,
+        )
+
+        present = dict(rows)
+        pos_set = set(POSITIVE_SPECIAL)
+        neg_set = set(NEGATIVE_SPECIAL)
+        # Preserve the file's key order within each sign group (that IS the
+        # visual top-to-bottom order the engine renders).
+        pos = [n for n, _v in rows if n in pos_set]
+        neg = [n for n, _v in rows if n in neg_set]
+        # Any unclassified defensive extras keep their raw file order.
+        unknown = [n for n, _v in rows if n not in pos_set and n not in neg_set]
+
+        seq: list[object] = [(n, present[n]) for n in pos]
+        seq += [(n, present[n]) for n in unknown]
+        seq.append(_DIVIDER)
+        seq += [(n, present[n]) for n in neg]
+        return seq
+
+    def _insert_dispatch_rows(
+        self, tree: ttk.Treeview, rows: list[tuple[str, object]],
+    ) -> None:
+        """Insert the fixed-order dispatch rows plus the flowGroups divider.
+
+        Real special rows carry a single-box swatch (dispatch is not
+        composite) and are color-editable; the synthetic divider row carries
+        the distinct ``_DIVIDER_TAG`` highlight, no swatch, and is recorded in
+        ``self._divider_items`` so it is skipped everywhere a row maps back to
+        an entity (it is display-only — never written to ``self._data``).
+        """
+        self._configure_divider_tag(tree)
+        for entry in self._order_dispatch_rows(rows):
+            if entry is _DIVIDER:
+                iid = tree.insert(
+                    "", "end", text=_DIVIDER_TEXT, tags=(_DIVIDER_TAG,),
+                )
+                self._divider_items.add((tree, iid))
+            else:
+                name, value = entry
+                image = self._make_swatch(value, None)
+                tree.insert("", "end", text=str(name), image=image)
+
+    def _configure_divider_tag(self, tree: ttk.Treeview) -> None:
+        """Style the divider tag: a contrasting band + italic text.
+
+        A muted blue-gray background reads as a divider against the default
+        (light) ttk Treeview row background in both the classic and modern
+        themes.  The italic font is a copy of ``TkDefaultFont`` (so it tracks
+        the theme's default face / size); font creation is guarded so a Tk
+        without font introspection still gets the background highlight.
+        """
+        if self._divider_font is None:
+            try:
+                import tkinter.font as tkfont
+
+                base = tkfont.nametofont("TkDefaultFont")
+                self._divider_font = tkfont.Font(**base.actual())
+                self._divider_font.configure(slant="italic")
+            except tk.TclError:
+                self._divider_font = ""  # sentinel: font unavailable
+        opts = {"background": "#c8d4e0", "foreground": "#1a1a1a"}
+        if self._divider_font:
+            opts["font"] = self._divider_font
+        tree.tag_configure(_DIVIDER_TAG, **opts)
+
+    def _is_divider(self, tree: ttk.Treeview, item: str) -> bool:
+        """True iff *item* in *tree* is the synthetic flowGroups divider row."""
+        return (tree, item) in self._divider_items
+
+    def _divider_index(self, tree: ttk.Treeview) -> int | None:
+        """Row index of *tree*'s flowGroups divider, or ``None`` if it has none.
+
+        Used by the reorder paths to keep a special on its own side of the
+        divider (positives above, negatives below) and to keep the divider
+        itself pinned.  A tree without a divider (every non-dispatch tree)
+        returns ``None``, so the sign-group clamp is a no-op there.
+        """
+        for i, iid in enumerate(tree.get_children("")):
+            if (tree, iid) in self._divider_items:
+                return i
+        return None
+
+    def _clamp_insert_for_divider(
+        self,
+        tree: ttk.Treeview,
+        order: list[str],
+        selected: list[str],
+        remaining: list[str],
+        insert_at: int,
+    ) -> int:
+        """Clamp *insert_at* so the moved block stays on its side of the divider.
+
+        *insert_at* is an index into *remaining* (the non-selected rows, which
+        always include the divider).  A block of positive specials (currently
+        above the divider) is clamped so it lands at or above the divider's slot
+        in *remaining*; a block of negatives (below) is clamped so it lands just
+        below it.  A move that would cross is thus clamped to the boundary (no
+        crossing), never rejected.  The divider is never in *selected*, so it
+        never moves.  No-op for trees without a divider.
+        """
+        div_idx = self._divider_index(tree)
+        if div_idx is None:
+            return insert_at
+        div_iid = order[div_idx]
+        if div_iid not in remaining:
+            return insert_at  # divider defensively selected — leave untouched
+        div_rem_idx = remaining.index(div_iid)
+        sel_idx = [order.index(r) for r in selected]
+        if not sel_idx:
+            return insert_at
+        if max(sel_idx) < div_idx:
+            # Positives: keep the block at/above the divider's slot.
+            return min(insert_at, div_rem_idx)
+        if min(sel_idx) > div_idx:
+            # Negatives: keep the block just below the divider's slot.
+            return max(insert_at, div_rem_idx + 1)
+        return insert_at
+
+    def _show_category(self, title: str) -> None:
+        """Show *title*'s entity tree, hiding the previously shown one.
+
+        Also reflects the selection in the left selector so a programmatic
+        show (default open, undo/redo restore) and a user click stay in sync.
+        """
+        if title not in self._category_frames:
+            return
+        if (
+            self._current_category is not None
+            and self._current_category != title
+            and self._current_category in self._category_frames
+        ):
+            self._category_frames[self._current_category].grid_remove()
+        self._category_frames[title].grid()
+        self._current_category = title
+        item = self._category_items.get(title)
+        if (
+            item is not None
+            and self._category_list.exists(item)
+            and self._category_list.selection() != (item,)
+        ):
+            self._category_list.selection_set(item)
+
+    def _on_category_select(self, _event=None) -> None:
+        """Left-list selection changed → show that category's entity tree."""
+        sel = self._category_list.selection()
+        if not sel:
+            return
+        self._show_category(self._category_list.item(sel[0], "text"))
+
+    # ── Reordering (drag + keyboard) ──────────────────────────────
+    def _selected_rows(self, tree: ttk.Treeview) -> list[str]:
+        """Current selection in top-to-bottom row order (focus as fallback)."""
+        sel = set(tree.selection())
+        if not sel:
+            f = tree.focus()
+            if f:
+                sel = {f}
+        return [r for r in tree.get_children("") if r in sel]
+
+    def _reorder_selection_block(
+        self, tree: ttk.Treeview, insert_at: int,
+    ) -> bool:
+        """Place the selected rows as a contiguous block at *insert_at*.
+
+        *insert_at* is an index into the rows that are NOT selected (so the
+        block is dropped between them).  Preserves each row's value, keeps
+        the selection, and returns True iff the order actually changed.
+        """
+        order = list(tree.get_children(""))
+        # The flowGroups divider is display-only: never part of a moved block
+        # (so an arrow-key selection that landed on it can't drag it).
+        selected = [
+            r for r in self._selected_rows(tree)
+            if not self._is_divider(tree, r)
+        ]
+        if not selected:
+            return False
+        remaining = [r for r in order if r not in set(selected)]
+        # Keep the block on its side of the divider (no-op without a divider).
+        insert_at = self._clamp_insert_for_divider(
+            tree, order, selected, remaining, insert_at,
+        )
+        insert_at = max(0, min(insert_at, len(remaining)))
+        new_order = remaining[:insert_at] + selected + remaining[insert_at:]
+        if new_order == order:
+            return False
+        for i, row in enumerate(new_order):
+            tree.move(row, "", i)
+        tree.selection_set(selected)
+        tree.focus(selected[0])
+        return True
+
+    def _on_drag_start(self, event: tk.Event) -> str | None:
+        """Begin a MOVE drag whenever the press lands on a row.
+
+        Pressing an already-selected row moves the whole selection.
+        Pressing an UNSELECTED row (no Shift/Ctrl) first collapses the
+        selection onto that row, then moves it — so a drag started on a
+        not-yet-selected item picks it up, as users expect, instead of
+        ttk's native range draw-select.  Either way we return ``"break"``
+        to own the selection and keep it intact for the drag.
+
+        Shift/Ctrl presses are left to ttk's default handler so extend /
+        toggle multi-selection still works (the user builds a selection,
+        then drags it as a block).  A press on empty space is native too.
+        """
+        tree = event.widget
+        if tree not in self._tree_section:
+            return None
+        # Fixed-order (dispatch) trees never reorder — let ttk's native
+        # ButtonPress run (selection / focus) but prime no move drag.
+        if tree in self._fixed_order_trees:
+            self._drag_move[tree] = False
+            self._drag_moved[tree] = False
+            self._drag_anchor[tree] = None
+            return None
+        row = tree.identify_row(event.y) or None
+        self._drag_moved[tree] = False
+        # The flowGroups divider is display-only — never selected or dragged.
+        # Swallow the press (``"break"``) so ttk's native handler does not
+        # select it, and prime no move.
+        if row and self._is_divider(tree, row):
+            self._drag_move[tree] = False
+            self._drag_anchor[tree] = None
+            return "break"
+        # Shift (0x0001) / Control (0x0004) → let ttk extend/toggle select.
+        if getattr(event, "state", 0) & 0x0005:
+            self._drag_move[tree] = False
+            self._drag_anchor[tree] = None
+            return None
+        if row:
+            if row not in set(tree.selection()):
+                tree.selection_set(row)
+                tree.focus(row)
+            # Returning "break" suppresses ttk's default ButtonPress handler,
+            # which is what normally gives the tree KEYBOARD focus — without
+            # this the Alt-Up / Alt-Down reorder bindings (which require the
+            # tree to hold keyboard focus) never fire after a click.
+            tree.focus_set()
+            self._drag_move[tree] = True
+            self._drag_anchor[tree] = row
+            return "break"
+        self._drag_move[tree] = False
+        self._drag_anchor[tree] = None
+        return None
+
+    def _on_drag_motion(self, event: tk.Event) -> None:
+        """Move the selection to follow the cursor (move drags only)."""
+        tree = event.widget
+        if tree in self._fixed_order_trees:
+            return  # engine-fixed order — no reorder drag
+        if not self._drag_move.get(tree):
+            return  # native draw-select drag — do not interfere
+        target = tree.identify_row(event.y)
+        if not target:
+            return
+        order = list(tree.get_children(""))
+        selected = set(self._selected_rows(tree))
+        target_idx = order.index(target)
+        # Number of non-selected rows above the hovered row = the insertion
+        # slot that lands the block JUST ABOVE the target.
+        above = sum(1 for r in order[:target_idx] if r not in selected)
+        # Decide above/below from the cursor's position within the hovered
+        # row: upper half drops before it, lower half after.  Using the row
+        # midpoint (not an unconditional "+1") is what makes the TOP slot
+        # reachable — hovering the upper half of the first row gives
+        # insert_at == 0.  When the row has no geometry (scrolled off), fall
+        # back to "below" (the previous behaviour).
+        if target in selected:
+            insert_at = above
+        else:
+            bbox = tree.bbox(target)
+            drop_below = True
+            if bbox:
+                _bx, by, _bw, bh = bbox
+                drop_below = event.y >= by + bh / 2
+            insert_at = above + 1 if drop_below else above
+        if self._reorder_selection_block(tree, insert_at):
+            self._drag_moved[tree] = True
+            tree.see(target)
+
+    def _on_drag_end(self, event: tk.Event) -> None:
+        """Finish a drag: persist a move, or collapse a no-move click."""
+        tree = event.widget
+        was_move = self._drag_move.get(tree)
+        self._drag_move[tree] = False
+        if not was_move:
+            return
+        if self._drag_moved.get(tree):
+            section_path = self._tree_section.get(tree)
+            if section_path is not None:
+                self._sync_section_order_from_tree(section_path, tree)
+        else:
+            # A plain click on a selected row (no drag) collapses the
+            # multi-selection down to that one row, as a normal click would.
+            anchor = self._drag_anchor.get(tree)
+            if anchor and tree.exists(anchor):
+                tree.selection_set(anchor)
+                tree.focus(anchor)
+
+    def _on_key_move_up(self, event: tk.Event) -> str:
+        """Alt+Up: move the selected row(s) up one position."""
+        return self._key_move(event.widget, -1)
+
+    def _on_key_move_down(self, event: tk.Event) -> str:
+        """Alt+Down: move the selected row(s) down one position."""
+        return self._key_move(event.widget, +1)
+
+    def _key_move(self, tree: ttk.Treeview, delta: int) -> str:
+        """Shift the selected row(s) by ``delta`` as a group; persist order.
+
+        Returns ``"break"`` so Tk's default Alt-arrow handling does not
+        also fire.
+        """
+        if tree not in self._tree_section:
+            return "break"
+        # Fixed-order trees are engine-pinned — Alt-move is a no-op.
+        if tree in self._fixed_order_trees:
+            return "break"
+        order = list(tree.get_children(""))
+        # The flowGroups divider never moves and is never part of the block;
+        # drop it from the selection so it can't be Alt-moved even when it holds
+        # focus from arrow-key navigation.
+        selected = [
+            r for r in self._selected_rows(tree)
+            if not self._is_divider(tree, r)
+        ]
+        if not selected:
+            return "break"
+        sset = set(selected)
+        first = order.index(selected[0])
+        last = order.index(selected[-1])
+        if delta < 0 and first == 0:
+            return "break"
+        if delta > 0 and last == len(order) - 1:
+            return "break"
+        # Unselected rows above the block; the block jumps one such row
+        # up (insert_at - 1) or down (insert_at + 1) among the others.
+        before = sum(1 for r in order[:first] if r not in sset)
+        insert_at = before - 1 if delta < 0 else before + 1
+        if self._reorder_selection_block(tree, insert_at):
+            tree.see(selected[0] if delta < 0 else selected[-1])
+            self._sync_section_order_from_tree(self._tree_section[tree], tree)
+        return "break"
+
+    def _sync_section_order_from_tree(
+        self, section_path: tuple[str, ...], tree: ttk.Treeview,
+    ) -> None:
+        """Rebuild ``section_path`` in the working dict to match the tree.
+
+        The new dict preserves each entry's VALUE (bare color or
+        ``{color, neg_color}``) and only reorders the keys to match the
+        tree's current top-to-bottom row order.  Centralised so 6.5's
+        undo can reuse it.
+        """
+        # Resolve the existing section mapping (the value source of truth).
+        section = self._data
+        for key in section_path:
+            if not isinstance(section, dict):
+                return
+            section = section.get(key)
+        if not isinstance(section, dict):
+            return
+
+        # Tree row order, by name (column #0 text).  Skip any synthetic
+        # divider row so its display-only label ("flowGroups") can never leak
+        # into the working dict as an entity (defensive — fixed-order trees
+        # are never synced, but a stray divider must not round-trip).
+        ordered_names = [
+            tree.item(iid, "text")
+            for iid in tree.get_children("")
+            if not self._is_divider(tree, iid)
+        ]
+        # Rebuild preserving values; keep any keys not represented as rows
+        # (defensive — should not happen) appended in their original order.
+        rebuilt: dict[str, object] = {}
+        for name in ordered_names:
+            if name in section:
+                rebuilt[name] = section[name]
+        for name, value in section.items():
+            if name not in rebuilt:
+                rebuilt[name] = value
+
+        # A reorder that did not actually change the key order (e.g. a press
+        # + release with no motion) is a no-op — do not record an undo step.
+        if list(rebuilt.keys()) == list(section.keys()):
+            return
+
+        # Record the pre-edit state, then write back into the parent
+        # container so the change is in-place for the live write / Close dump.
+        self._snapshot()
+        parent = self._data
+        for key in section_path[:-1]:
+            parent = parent[key]
+        parent[section_path[-1]] = rebuilt
+        self._schedule_live_update()
+
+    # ── Color editing (double-click / Enter) ──────────────────────
+    def _restore_tree_focus(self, tree: ttk.Treeview, item: str) -> None:
+        """Return keyboard focus to *tree* and re-select/refocus *item*.
+
+        Called after a color dialog closes so the focus lands back in the
+        list (not lost to the window) and Enter can edit the next row.
+        """
+        tree.focus_set()
+        if item and tree.exists(item):
+            tree.selection_set(item)
+            tree.focus(item)
+            tree.see(item)
+
+    def _on_tree_focus_in(self, event: tk.Event) -> None:
+        """Activate a row when the tree gains focus (e.g. via Tab).
+
+        Without an active row the arrow / Alt-arrow keys have nothing to act
+        on.  Tk's item-focus persists across focus changes, so reuse the
+        last-active row when it still exists, otherwise activate the first.
+        """
+        tree = event.widget
+        if tree not in self._tree_section:
+            return
+        item = tree.focus()
+        if not item or not tree.exists(item):
+            children = tree.get_children("")
+            if not children:
+                return
+            item = children[0]
+        tree.focus(item)
+        tree.selection_set(item)
+        tree.see(item)
+
+    def _on_row_return(self, event: tk.Event) -> str:
+        """Enter on a row opens its color editor (keyboard parity with the
+        double-click)."""
+        tree = event.widget
+        if tree not in self._tree_section:
+            return ""
+        item = tree.focus() or (
+            tree.selection()[0] if tree.selection() else ""
+        )
+        if not item:
+            return "break"
+        self._edit_row_color(tree, item)
+        return "break"
+
+    def _on_row_double_click(self, event: tk.Event) -> str:
+        """Open the color editor for the double-clicked row.
+
+        Resolves the row under the cursor; a double-click on empty space is
+        ignored.  Returns ``"break"`` so the click is consumed and does not
+        feed the drag/select bindings from 6.3.
+        """
+        tree = event.widget
+        if tree not in self._tree_section:
+            return ""
+        item = tree.identify_row(event.y)
+        if not item:
+            return "break"
+        # A double-click must not leave a stale move-drag primed.
+        self._drag_move[tree] = False
+        self._edit_row_color(tree, item)
+        return "break"
+
+    def _section_dict(self, section_path: tuple[str, ...]) -> dict | None:
+        """Resolve a section path to its mapping in the working dict."""
+        section = self._data
+        for key in section_path:
+            if not isinstance(section, dict):
+                return None
+            section = section.get(key)
+        return section if isinstance(section, dict) else None
+
+    def _edit_row_color(self, tree: ttk.Treeview, item: str) -> None:
+        """Open the appropriate color dialog and write the result back."""
+        # The synthetic flowGroups divider is display-only — never editable.
+        if self._is_divider(tree, item):
+            return
+        section_path = self._tree_section[tree]
+        section = self._section_dict(section_path)
+        if section is None:
+            return
+        name = tree.item(item, "text")
+        if name not in section:
+            return
+        value = section[name]
+
+        if self._tree_composite.get(tree, False):
+            self._edit_entity_color(tree, item, section, name, value)
+        else:
+            self._edit_single_color(tree, item, section, name, value)
+
+    def _edit_entity_color(
+        self,
+        tree: ttk.Treeview,
+        item: str,
+        section: dict,
+        name: str,
+        value,
+    ) -> None:
+        """Edit a pos/neg entity entry via the modal lock dialog."""
+        pos_val, neg_val = _resolve_pos_neg(value)
+        # A bare entry (no explicit negative) opens LINKED.
+        linked = neg_val is None
+        pos_hex = _to_hex(pos_val)
+        neg_hex = _to_hex(neg_val if neg_val is not None else pos_val)
+
+        dialog = ColorPickerDialog(self, name, pos_hex, neg_hex, linked)
+        self.wait_window(dialog)
+        self._restore_tree_focus(tree, item)
+        if dialog.result is None:
+            return  # Cancel: no change.
+
+        new_pos, new_neg = dialog.result
+        # Record the pre-edit state before mutating the working dict.
+        self._snapshot()
+        if new_neg is None:
+            section[name] = new_pos
+            self._rebuild_row_swatch(tree, item, new_pos, None)
+        else:
+            section[name] = {"color": new_pos, "neg_color": new_neg}
+            self._rebuild_row_swatch(tree, item, new_pos, new_neg)
+        self._schedule_live_update()
+
+    def _edit_single_color(
+        self,
+        tree: ttk.Treeview,
+        item: str,
+        section: dict,
+        name: str,
+        value,
+    ) -> None:
+        """Edit a single-color (category / scenario) entry.
+
+        Uses the same embedded picker as entities but in single mode (the
+        negative chooser + link checkbox are hidden), so categories /
+        scenarios get the same look without a negative concept.
+        """
+        cur = _to_hex(value)
+        dialog = ColorPickerDialog(self, name, cur, cur, True, single=True)
+        self.wait_window(dialog)
+        self._restore_tree_focus(tree, item)
+        if dialog.result is None:
+            return  # Cancel: no change.
+        new_color = dialog.result[0]
+        # Record the pre-edit state before mutating the working dict.
+        self._snapshot()
+        section[name] = new_color
+        self._rebuild_row_swatch(tree, item, new_color, None)
+        self._schedule_live_update()
+
+    def _rebuild_row_swatch(
+        self,
+        tree: ttk.Treeview,
+        item: str,
+        pos,
+        neg,
+    ) -> None:
+        """Rebuild and re-attach a row's swatch image in place."""
+        image = self._make_swatch(
+            pos, neg, reserve_neg=self._tree_composite.get(tree, False),
+        )
+        # Keep a per-row reference so the replacement is not GC'd (the
+        # superseded image stays referenced in ``self._swatches`` too, but
+        # is no longer displayed).
+        self._row_swatches[(tree, item)] = image
+        tree.item(item, image=image)
+
+    # ── Entity discovery (on-open seeding) ────────────────────────
+    def _discover_input_dbs(self) -> list[str]:
+        """Return ``sqlite:///`` URLs for the project's input/intermediate DBs.
+
+        The project root is the settings file's parent directory.  Every
+        ``*.sqlite`` under ``<project>/input_sources`` and
+        ``<project>/intermediate`` is a candidate input DB; URLs are
+        returned in a stable (sorted) order so the union is deterministic.
+        """
+        project_root = self._settings_path.parent
+        urls: list[str] = []
+        for sub in ("input_sources", "intermediate"):
+            db_dir = project_root / sub
+            if not db_dir.is_dir():
+                continue
+            for path in sorted(db_dir.glob("*.sqlite")):
+                if path.is_file():
+                    urls.append(f"sqlite:///{path}")
+        return urls
+
+    def _discover_scenario_names(self) -> list[str]:
+        """Executed-scenario folder names under ``<project>/output_parquet``.
+
+        These folder names are the scenario identities comparison plots key
+        off (the folder name, including any ``_<n>`` source suffix), so using
+        them verbatim makes picker-set colors line up with the plot labels.
+        ``_``-prefixed manifest dirs are skipped; order is stable (sorted).
+        """
+        parquet_dir = self._settings_path.parent / "output_parquet"
+        if not parquet_dir.is_dir():
+            return []
+        return [
+            entry.name
+            for entry in sorted(parquet_dir.iterdir())
+            if entry.is_dir() and not entry.name.startswith("_")
+        ]
+
+    def _merge_scenarios_from_folders(self) -> None:
+        """Add newly discovered scenario folder names to the working
+        ``scenarios`` section with a default palette color (add-only — never
+        prunes, never overwrites an existing/edited color).  Called on open so
+        the always-shown scenarios tab is immediately useful.
+        """
+        names = self._discover_scenario_names()
+        if not names:
+            return
+        from flextool.scenario_comparison.config_builder import (
+            assign_palette_colors,
+        )
+
+        scenarios = self._data.get("scenarios")
+        scenarios = scenarios if isinstance(scenarios, dict) else {}
+        new_names = [n for n in names if n not in scenarios]
+        if not new_names:
+            return
+        for name, color in assign_palette_colors(new_names).items():
+            scenarios[name] = color
+        self._data["scenarios"] = scenarios
+
+    def _discover_dispatch_sources(
+        self,
+    ) -> tuple[dict[str, set[str]], dict[str, float]]:
+        """Discover dispatch entities + per-entity std dev from output parquet.
+
+        PRIMARY discovery source: the solved ``output_parquet`` — i.e. exactly
+        what the dispatch plots draw.  For every executed-scenario folder
+        (``_``-prefixed manifest dirs skipped) the dispatch bundle is loaded
+        with :func:`~flextool.scenario_comparison.dispatch_data.load_dispatch_bundle`
+        (the same load sequence the result viewer uses), then:
+
+        * :func:`~flextool.scenario_comparison.config_builder.discover_dispatch_entities`
+          classifies the discovered names into ``nodeGroup`` / ``flowGroup`` /
+          ``unit`` / ``connection`` (processGroup ``group_aggregate`` names —
+          e.g. ``Fossil`` — land in ``flowGroup``), unioned across folders;
+        * :meth:`_accumulate_dispatch_std` runs
+          :func:`~flextool.scenario_comparison.dispatch_data.prepare_dispatch_data`
+          per dispatch node_group and records a per-entity std dev (max across
+          node_groups / scenarios) used to order newly-discovered entries.
+
+        The ``node`` class is intentionally NOT discovered here:
+        ``discover_dispatch_entities`` omits nodes (node colors are
+        dataset-coupled), so the node tab stays file-driven.
+
+        Robust by construction: a missing ``output_parquet``, empty / partial
+        scenario folders, unreadable parquet, a scenario with no dispatch
+        groups, and per-node_group prepare failures are all skipped — never
+        raising.  Returns ``({class -> names}, {entity -> std})`` with empty
+        sets/map when nothing is discoverable.
+        """
+        parquet_dir = self._settings_path.parent / "output_parquet"
+        per_class: dict[str, set[str]] = {
+            "nodeGroup": set(),
+            "flowGroup": set(),
+            "unit": set(),
+            "connection": set(),
+        }
+        std_by_entity: dict[str, float] = {}
+        if not parquet_dir.is_dir():
+            return per_class, std_by_entity
+
+        from flextool.scenario_comparison.config_builder import (
+            discover_dispatch_entities,
+        )
+        from flextool.scenario_comparison.dispatch_data import (
+            load_dispatch_bundle,
+        )
+
+        for scen_dir in sorted(parquet_dir.iterdir()):
+            if not scen_dir.is_dir() or scen_dir.name.startswith("_"):
+                continue
+            scenario = scen_dir.name
+            try:
+                bundle = load_dispatch_bundle(parquet_dir, scenario)
+            except Exception as exc:  # unreadable / partial parquet bundle
+                logger.warning(
+                    "Cannot load dispatch bundle for %s: %s", scenario, exc,
+                )
+                continue
+            if bundle is None:
+                continue
+            mappings, results = bundle
+            try:
+                discovered = discover_dispatch_entities(mappings, [])
+            except Exception as exc:
+                logger.warning(
+                    "discover_dispatch_entities failed for %s: %s",
+                    scenario, exc,
+                )
+                discovered = {}
+            for cls in per_class:
+                per_class[cls].update(discovered.get(cls, []))
+            self._accumulate_dispatch_std(
+                mappings, results, scenario, std_by_entity,
+            )
+        return per_class, std_by_entity
+
+    def _accumulate_dispatch_std(
+        self, mappings, results, scenario: str,
+        std_by_entity: dict[str, float],
+    ) -> None:
+        """Fold per-entity dispatch std devs from one scenario into the map.
+
+        For each dispatch node_group (the ``group`` values of
+        ``mappings.dispatch_groups``) the scenario's dispatch DataFrame is
+        prepared exactly as the plots build it (``config_order=None``).  Each
+        column's std dev (``series.std()``) is attributed to the base entity
+        name — any ``_pos`` / ``_neg`` split suffix stripped — and accumulated
+        as the MAX across occurrences (node_groups / scenarios) so a per-entity
+        value is stable.  ``NaN`` std devs (degenerate single-point series) and
+        any prepare failure are skipped, never raising.
+        """
+        dispatch_groups = getattr(mappings, "dispatch_groups", None)
+        if (
+            dispatch_groups is None
+            or dispatch_groups.empty
+            or "group" not in dispatch_groups.columns
+        ):
+            return
+
+        from flextool.scenario_comparison.dispatch_data import (
+            prepare_dispatch_data,
+        )
+
+        for node_group in dispatch_groups["group"].unique():
+            try:
+                df_dispatch, _ = prepare_dispatch_data(
+                    results, mappings, scenario, str(node_group),
+                    config_order=None,
+                )
+            except Exception as exc:
+                logger.warning(
+                    "prepare_dispatch_data failed (%s / %s): %s",
+                    scenario, node_group, exc,
+                )
+                continue
+            if df_dispatch is None or df_dispatch.empty:
+                continue
+            for col in df_dispatch.columns:
+                base = str(col)
+                for suffix in ("_pos", "_neg"):
+                    if base.endswith(suffix):
+                        base = base[: -len(suffix)]
+                        break
+                try:
+                    std = float(df_dispatch[col].std())
+                except (TypeError, ValueError):
+                    continue
+                if std != std:  # NaN
+                    continue
+                prev = std_by_entity.get(base)
+                if prev is None or std > prev:
+                    std_by_entity[base] = std
+
+    def _order_new_names_by_std(
+        self, new_names, std_by_entity: dict[str, float],
+    ) -> list[str]:
+        """Order newly-discovered entity names by std dev (one-time default).
+
+        Matches ``_order_dispatch_columns``' remaining / std-dev buckets, which
+        sort ASCENDING by std dev with the name as a deterministic secondary
+        key (``sorted(..., key=lambda c: (col_std.get(c, 0), c))``), so the
+        persisted order of new entries equals the stacking order the dispatch
+        render would have produced.  Names with no computed std dev (not a
+        dispatch entity, or the DB fallback path where no std is available)
+        sort LAST, by name.
+        """
+        def key(name: str):
+            std = std_by_entity.get(name)
+            if std is None:
+                return (1, 0.0, name)  # no std → after std-bearing, by name
+            return (0, std, name)
+
+        return sorted(new_names, key=key)
+
+    def _discover_all_entities(
+        self,
+    ) -> tuple[dict[str, set[str]], dict[str, float]]:
+        """Per-class entity names + per-entity std dev for the on-open merge.
+
+        Source of truth for the add-only on-open merge
+        (:meth:`_merge_entities_from_sources`), so the discovery policy lives
+        in one place.
+
+        * **PRIMARY** — dispatch entities discovered from the solved
+          ``output_parquet`` (:meth:`_discover_dispatch_sources`).  This is
+          what the plots actually draw, and it carries the std devs used to
+          order new entries.  Node is not covered here (file-driven).
+        * **FALLBACK** — only when there is NO dispatch output to discover
+          from (e.g. the pre-solve PNG-batch dialog on a project that hasn't
+          solved yet) is the input DB consulted (:meth:`_discover_input_dbs`
+          + :meth:`_fetch_entity_union`).  The DB fallback yields no std devs
+          (new entries then order by name).
+
+        Returns ``({class -> set of names}, {entity -> std})``.  Never raises
+        for a missing ``output_parquet`` or DB (both contribute nothing).
+        """
+        per_class, std_by_entity = self._discover_dispatch_sources()
+        if any(per_class.values()):
+            return per_class, std_by_entity
+        # Fallback: input DB(s).  No std devs → new entries order by name.
+        return self._fetch_entity_union(self._discover_input_dbs()), {}
+
+    def _merge_entities_from_sources(self) -> None:
+        """Additively seed entities from the solved dispatch output (DB fallback).
+
+        Called on open so the entity tabs are populated immediately (fixes
+        the symptom where entities only appeared after a manual "Refresh",
+        and where output-only aggregates like ``Fossil`` were never listable).
+        Discovery is parquet-first with a DB fallback
+        (:meth:`_discover_all_entities`).  **Add-only**: newly discovered
+        names (per class) are appended, ORDERED among themselves by std dev
+        (:meth:`_order_new_names_by_std` — a one-time default matching the
+        dispatch render's stacking order) with a default palette color
+        (:func:`assign_palette_colors`); existing entries — including any
+        edited color and the current order — are never touched, and nothing
+        is pruned.  Node is not seeded from parquet (file-driven; see
+        :meth:`_discover_dispatch_sources`).
+
+        Mutates ``self._data['entities']`` in memory only and records NO undo
+        step; Cancel reverts via the on-disk text snapshot, exactly like
+        :meth:`_merge_scenarios_from_folders`.  Any discovery failure (e.g. a
+        corrupt input DB) is logged and skipped so opening the picker is never
+        broken.
+        """
+        try:
+            discovered, std_by_entity = self._discover_all_entities()
+        except Exception as exc:  # never let discovery break the window open
+            logger.warning("Entity discovery on open failed: %s", exc)
+            return
+        if not any(discovered.values()):
+            return
+
+        from flextool.scenario_comparison.config_builder import (
+            assign_palette_colors,
+        )
+
+        entities = self._data.get("entities")
+        entities = entities if isinstance(entities, dict) else {}
+        changed = False
+        for cls, names in discovered.items():
+            if not names:
+                continue
+            section = entities.get(cls)
+            section = section if isinstance(section, dict) else {}
+            # Add-only: append names not already present, ordered by std dev;
+            # keep existing entries' order + values untouched.
+            new_names = self._order_new_names_by_std(
+                [n for n in names if n not in section], std_by_entity,
+            )
+            if not new_names:
+                continue
+            for name, color in assign_palette_colors(new_names).items():
+                section[name] = color
+            entities[cls] = section
+            changed = True
+        if changed:
+            self._data["entities"] = entities
+
+    def _compute_dispatch_flowgroup_aggregators(self) -> set[str]:
+        """flowGroups that are dispatch aggregators (for the display filter).
+
+        The set is the UNION of:
+
+        * the parquet ``group_aggregate`` flowGroup names discovered from the
+          solved ``output_parquet`` (:meth:`_discover_dispatch_sources` —
+          exactly the aggregates the dispatch plots draw, e.g. ``Fossil``), and
+        * every input-DB flowGroup whose ``flow_aggregator`` parameter is
+          ``dispatch_plots_only`` or ``both``
+          (:func:`~flextool.scenario_comparison.input_entity_colors.fetch_flow_aggregator_flowgroups`,
+          one DB open each over :meth:`_discover_input_dbs`).
+
+        Each source is individually guarded so one failing does not lose the
+        other; a total failure yields an empty set, which
+        :meth:`_add_category` treats as "do not filter" (show all flowGroups).
+        """
+        aggregators: set[str] = set()
+        try:
+            per_class, _std = self._discover_dispatch_sources()
+            aggregators |= set(per_class.get("flowGroup", set()))
+        except Exception as exc:  # parquet discovery must not break the filter
+            logger.warning("Dispatch flowGroup discovery failed: %s", exc)
+
+        from flextool.scenario_comparison.input_entity_colors import (
+            fetch_flow_aggregator_flowgroups,
+        )
+
+        for url in self._discover_input_dbs():
+            try:
+                aggregators |= fetch_flow_aggregator_flowgroups(url)
+            except Exception as exc:  # per-DB read must not break the filter
+                logger.warning(
+                    "flow_aggregator read failed for %s: %s", url, exc,
+                )
+        return aggregators
+
+    def _fetch_entity_union(self, db_urls: list[str]) -> dict[str, set[str]]:
+        """Union per-class entity names across every input DB (one open each).
+
+        Reuses
+        :func:`flextool.scenario_comparison.input_entity_colors.fetch_entities_by_class`
+        — one :class:`DatabaseMapping` open per DB — and unions the returned
+        per-class name sets across DBs.
+        """
+        from flextool.scenario_comparison.input_entity_colors import (
+            RELEVANT_ENTITY_CLASSES,
+            fetch_entities_by_class,
+        )
+
+        union: dict[str, set[str]] = {
+            cls: set() for cls in RELEVANT_ENTITY_CLASSES
+        }
+        for url in db_urls:
+            per_db = fetch_entities_by_class(url)
+            for cls, names in per_db.items():
+                union[cls].update(names)
+        return union
+
+    # NOTE: there is deliberately no "Refresh from DB" action any more.  The
+    # on-open discovery (:meth:`_merge_entities_from_sources`) already seeds
+    # every listable entity add-only; the manual add+prune refresh was
+    # dropped along with its button.  Add-only leaves at most a few stale
+    # entries in the file, which are harmless (an unused color/order key never
+    # drawn), so nothing prunes them — the simplicity is worth it.
+
+    # ── Live update (debounced) ───────────────────────────────────
+    def _schedule_live_update(self) -> None:
+        """Debounce a live write + re-render after a user mutation.
+
+        Cancels any pending update and schedules a fresh one, so a burst of
+        edits (e.g. a color-drag committed through several handler calls)
+        collapses into a single write once the changes settle.  Guarded
+        against a destroyed window (the ``after`` call raises then).
+        """
+        if self._live_after_id is not None:
+            try:
+                self.after_cancel(self._live_after_id)
+            except tk.TclError:
+                pass
+            self._live_after_id = None
+        try:
+            self._live_after_id = self.after(
+                self._LIVE_UPDATE_MS, self._flush_live_update,
+            )
+        except tk.TclError:
+            self._live_after_id = None
+
+    def _flush_live_update(self) -> None:
+        """Write the working dict to disk and re-render the live preview.
+
+        This is the debounced live commit: it never touches
+        ``self._original_text`` (the on-open baseline), so a later Cancel can
+        still revert every change made since the dialog opened.
+        """
+        self._live_after_id = None
+        self._write()
+        if self._on_apply is not None:
+            self._on_apply()
+
+    # ── Buttons ───────────────────────────────────────────────────
+    def _on_close(self) -> None:
+        """Flush any pending live write, then close — KEEPING all changes.
+
+        Bound to the Close button, the window ``X``, and Escape.  Because
+        edits are written live, closing must not discard them: cancel the
+        pending debounce, write the final in-memory ``self._data`` (including
+        entities discovered on open), re-render, and destroy.
+        """
+        if self._live_after_id is not None:
+            try:
+                self.after_cancel(self._live_after_id)
+            except tk.TclError:
+                pass
+            self._live_after_id = None
+        self._write()
+        if self._on_apply is not None:
+            self._on_apply()
+        self.destroy()
+
+    def _on_cancel(self) -> None:
+        """Revert to the on-open file text, revert the preview, and close.
+
+        Cancels the pending live write, restores the byte-for-byte on-open
+        text (undoing every live write made since the dialog opened), and
+        re-renders so the preview matches.
+        """
+        if self._live_after_id is not None:
+            try:
+                self.after_cancel(self._live_after_id)
+            except tk.TclError:
+                pass
+            self._live_after_id = None
+        try:
+            self._settings_path.write_text(
+                self._original_text, encoding="utf-8",
+            )
+        except OSError as exc:
+            logger.warning(
+                "Cannot restore %s on cancel: %s", self._settings_path, exc,
+            )
+        if self._on_apply is not None:
+            self._on_apply()
+        self.destroy()