jarvisplot 2.1.6__tar.gz → 2.1.8__tar.gz

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/JarvisPLOT.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.6
+Version: 2.1.8
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -66,6 +66,7 @@ Render with a bare path — there is no `jplot run`:
 ```bash
 jplot path/to/config.yaml
 jplot path/to/config.yaml --rebuild-cache
+jplot path/to/config.yaml --print
 ```
 
 Everything else is discovery and judgement, in three groups.
@@ -160,12 +161,22 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
+`jplot man --json` is the machine-readable manual: a topic index, plus
 live pages for every registered layer method and transform step
 (`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
 For continuous one-dimensional distributions from raw samples, use `PDF1D`
 (CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
 `lim`, and `grid`; optional `repeat` computes independent batch means and
@@ -208,9 +219,45 @@ from jarvisplot import render_flowchart, render_flowchart_file
 - You can set `project.workdir` in YAML.
 - If `output.dir` is omitted, Jarvis-PLOT defaults to `<workdir>/plots/`.
 - Data cache is stored in `<workdir>/.cache/`.
+- `--print` accepts the current settings and renders final figures without the logo. It announces that, after all enabled figures are saved successfully, cache payloads used or created by this run will be deleted (pipeline data and metadata, named/shared data, summaries, and HDF5 materialization slots). Rendering failures or a run with no enabled figures keep the cache. Unrelated cache entries and the lightweight fingerprint manifest are retained; later renders rebuild deleted entries as needed.
 - Profiling pipelines are prebuilt once and reused from cache when source fingerprint and profile settings are unchanged.
 - Profiling uses a fast two-stage grid reduction (`pregrid` + render `bin`) for large datasets.
 
+Plot caches are automatically registered in `~/.jarvis/plot.json` (or
+`$JARVIS_HOME/plot.json`). The registry groups caches by workdir and records
+associated YAML paths and last use; payloads stay in their original directories.
+This includes caches created by `data describe` and default `dryrun --with-data`
+exports. Sizes are calculated when listing, rather than stored in the registry.
+
+```bash
+jplot cache list
+jplot cache scan ~/Jarvis-Workshop               # register existing plot caches
+jplot cache clean --workdir /path/to/project    # this directory and all nested projects; repeatable
+jplot cache clean --all --older-than 30         # unused for at least 30 days
+jplot cache clean --all --dry-run               # preview; no deletion/index changes
+jplot cache clean --all                         # clean all registered inactive caches
+jplot cache -h
+jplot man cache
+```
+
+`--workdir PATH` selects registered caches in PATH itself and all of its
+subdirectories, even when PATH has no cache of its own. Repeat it to select
+multiple directory trees; overlapping selections are deduplicated. Use
+`cache scan PATH` first for old caches that have not been registered.
+
+All cache subcommands accept `--json` and use the existing CLI envelope and
+exit codes (0 success/partial, 1 failure, 2 usage). Non-TTY stdout defaults to
+JSON; human results go to stderr. Active caches are skipped (`ok: null` when
+the remaining operation succeeds), and records for missing paths are pruned
+during cleanup. Only marked Jarvis-PLOT components are removed; source data,
+plots, and unrelated `.cache` content are retained. Failed deletions retain
+their registry entries. Scanning adopts legacy caches only when the four
+pipeline directories and a compatible `manifest.json` identify them; old
+unmarked twin-only directories need a new `dryrun --with-data` run to register.
+An explicitly supplied `--out-dir` is an export directory and is not registered.
+Concurrent registry writes use a lock and atomic replacement. Registration
+failures warn without preventing rendering.
+
 ### Example: SUSYRun2 Ternary Plots
 
 ```bash

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/JarvisPLOT.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ JarvisPLOT.egg-info/top_level.txt
 jarvisplot/__init__.py
 jarvisplot/agent_digest.py
 jarvisplot/agent_io.py
+jarvisplot/cache_registry.py
 jarvisplot/cache_store.py
 jarvisplot/capabilities.py
 jarvisplot/cli.py
@@ -37,6 +38,7 @@ jarvisplot/fix_apply.py
 jarvisplot/flowchart.py
 jarvisplot/generated_data.py
 jarvisplot/inner_func.py
+jarvisplot/legend_cards.py
 jarvisplot/man_catalog.py
 jarvisplot/man_methods.py
 jarvisplot/man_render_agent.py
@@ -77,6 +79,7 @@ jarvisplot/Figure/interp_natural_neighbor.py
 jarvisplot/Figure/interp_natural_neighbor_exact.py
 jarvisplot/Figure/layer_runtime.py
 jarvisplot/Figure/layout_runtime.py
+jarvisplot/Figure/legend_runtime.py
 jarvisplot/Figure/method_registry.py
 jarvisplot/Figure/posterior_density_runtime.py
 jarvisplot/Figure/posterior_hpd.py
@@ -120,7 +123,12 @@ jarvisplot/cards/icons/flowchart/inputfile.png
 jarvisplot/cards/icons/flowchart/opera.png
 jarvisplot/cards/icons/flowchart/outputfile.png
 jarvisplot/cards/icons/flowchart/sampler.png
+jarvisplot/cards/legends/compact/legend-card.json
+jarvisplot/cards/legends/default/legend-card.json
+jarvisplot/cards/legends/paper/legend-card.json
+jarvisplot/cards/legends/presentation/legend-card.json
 jarvisplot/manual_cards/agent-output.yaml
+jarvisplot/manual_cards/cache.yaml
 jarvisplot/manual_cards/cli-map.yaml
 jarvisplot/manual_cards/data-columns.yaml
 jarvisplot/manual_cards/debug-overlay.yaml
@@ -129,6 +137,7 @@ jarvisplot/manual_cards/dryrun-viz.yaml
 jarvisplot/manual_cards/field-interp.yaml
 jarvisplot/manual_cards/generated-data.yaml
 jarvisplot/manual_cards/layer-method.yaml
+jarvisplot/manual_cards/legend.yaml
 jarvisplot/manual_cards/manifest.yaml
 jarvisplot/manual_cards/method_notes.yaml
 jarvisplot/manual_cards/style-axes.yaml
@@ -146,6 +155,8 @@ jarvisplot/schema/core/distribution-1d.json
 jarvisplot/schema/core/figure.json
 jarvisplot/schema/core/generated-data.json
 jarvisplot/schema/core/layer.json
+jarvisplot/schema/core/legend-card.json
+jarvisplot/schema/core/legend.json
 jarvisplot/schema/core/transform.json
 jarvisplot/schema/methods/bar.json
 jarvisplot/schema/methods/barh.json
@@ -184,6 +195,7 @@ jarvisplot/utils/expression.py
 jarvisplot/utils/interpolator.py
 jarvisplot/utils/pathing.py
 jarvisplot/verbs/__init__.py
+jarvisplot/verbs/cache.py
 jarvisplot/verbs/cap.py
 jarvisplot/verbs/config_cmd.py
 jarvisplot/verbs/data.py
@@ -195,15 +207,19 @@ jarvisplot/verbs/suggest.py
 jarvisplot/verbs/template.py
 jarvisplot/verbs/validate.py
 tests/test_adaptive_cdf.py
+tests/test_add_column.py
 tests/test_agent_digest.py
 tests/test_agent_envelope.py
 tests/test_axis_title.py
+tests/test_cache_cleanup.py
+tests/test_cache_registry.py
 tests/test_capabilities.py
 tests/test_card_debug_shape.py
 tests/test_cli_help.py
 tests/test_cli_verbs.py
 tests/test_cmaps.py
 tests/test_column_existence.py
+tests/test_column_pruning.py
 tests/test_config_addressing.py
 tests/test_config_edit.py
 tests/test_config_expand.py
@@ -223,7 +239,9 @@ tests/test_diagnostic_guidance.py
 tests/test_distribution_1d_transform.py
 tests/test_docs_status_labels.py
 tests/test_doctor_partial.py
+tests/test_examples_validate.py
 tests/test_explain.py
+tests/test_expression_semantics.py
 tests/test_figure_contracts.py
 tests/test_figure_type_expander.py
 tests/test_fix_application.py
@@ -234,6 +252,9 @@ tests/test_interp_2d_transform.py
 tests/test_interp_natural_neighbor.py
 tests/test_interpolator_contracts.py
 tests/test_jpcontour_methods.py
+tests/test_layer_legend.py
+tests/test_legend_cards.py
+tests/test_legend_runtime.py
 tests/test_man_cli.py
 tests/test_method_contracts.py
 tests/test_parse_data_metadata.py
@@ -241,6 +262,7 @@ tests/test_pathing_contracts.py
 tests/test_posterior_hpd.py
 tests/test_profile_runtime.py
 tests/test_render_health.py
+tests/test_render_lifecycle.py
 tests/test_row_ledger.py
 tests/test_schema_catalog.py
 tests/test_suggest.py

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: JarvisPLOT
-Version: 2.1.6
+Version: 2.1.8
 Summary: Jarvis-PLOT: YAML-driven plotting engine
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -66,6 +66,7 @@ Render with a bare path — there is no `jplot run`:
 ```bash
 jplot path/to/config.yaml
 jplot path/to/config.yaml --rebuild-cache
+jplot path/to/config.yaml --print
 ```
 
 Everything else is discovery and judgement, in three groups.
@@ -160,12 +161,22 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
+`jplot man --json` is the machine-readable manual: a topic index, plus
 live pages for every registered layer method and transform step
 (`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
 For continuous one-dimensional distributions from raw samples, use `PDF1D`
 (CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
 `lim`, and `grid`; optional `repeat` computes independent batch means and
@@ -208,9 +219,45 @@ from jarvisplot import render_flowchart, render_flowchart_file
 - You can set `project.workdir` in YAML.
 - If `output.dir` is omitted, Jarvis-PLOT defaults to `<workdir>/plots/`.
 - Data cache is stored in `<workdir>/.cache/`.
+- `--print` accepts the current settings and renders final figures without the logo. It announces that, after all enabled figures are saved successfully, cache payloads used or created by this run will be deleted (pipeline data and metadata, named/shared data, summaries, and HDF5 materialization slots). Rendering failures or a run with no enabled figures keep the cache. Unrelated cache entries and the lightweight fingerprint manifest are retained; later renders rebuild deleted entries as needed.
 - Profiling pipelines are prebuilt once and reused from cache when source fingerprint and profile settings are unchanged.
 - Profiling uses a fast two-stage grid reduction (`pregrid` + render `bin`) for large datasets.
 
+Plot caches are automatically registered in `~/.jarvis/plot.json` (or
+`$JARVIS_HOME/plot.json`). The registry groups caches by workdir and records
+associated YAML paths and last use; payloads stay in their original directories.
+This includes caches created by `data describe` and default `dryrun --with-data`
+exports. Sizes are calculated when listing, rather than stored in the registry.
+
+```bash
+jplot cache list
+jplot cache scan ~/Jarvis-Workshop               # register existing plot caches
+jplot cache clean --workdir /path/to/project    # this directory and all nested projects; repeatable
+jplot cache clean --all --older-than 30         # unused for at least 30 days
+jplot cache clean --all --dry-run               # preview; no deletion/index changes
+jplot cache clean --all                         # clean all registered inactive caches
+jplot cache -h
+jplot man cache
+```
+
+`--workdir PATH` selects registered caches in PATH itself and all of its
+subdirectories, even when PATH has no cache of its own. Repeat it to select
+multiple directory trees; overlapping selections are deduplicated. Use
+`cache scan PATH` first for old caches that have not been registered.
+
+All cache subcommands accept `--json` and use the existing CLI envelope and
+exit codes (0 success/partial, 1 failure, 2 usage). Non-TTY stdout defaults to
+JSON; human results go to stderr. Active caches are skipped (`ok: null` when
+the remaining operation succeeds), and records for missing paths are pruned
+during cleanup. Only marked Jarvis-PLOT components are removed; source data,
+plots, and unrelated `.cache` content are retained. Failed deletions retain
+their registry entries. Scanning adopts legacy caches only when the four
+pipeline directories and a compatible `manifest.json` identify them; old
+unmarked twin-only directories need a new `dryrun --with-data` run to register.
+An explicitly supplied `--out-dir` is an export directory and is not registered.
+Concurrent registry writes use a lock and atomic replacement. Registration
+failures warn without preventing rendering.
+
 ### Example: SUSYRun2 Ternary Plots
 
 ```bash

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/README.md

@@ -44,6 +44,7 @@ Render with a bare path — there is no `jplot run`:
 ```bash
 jplot path/to/config.yaml
 jplot path/to/config.yaml --rebuild-cache
+jplot path/to/config.yaml --print
 ```
 
 Everything else is discovery and judgement, in three groups.
@@ -138,12 +139,22 @@ The loop `jplot man` prints is:
    carry `JP-*` codes; `jplot explain JP-XXX-NNN` expands any of them.
 5. `jplot <file>` — render, only when the figure itself is needed.
 
-`jplot man --json` is the machine-readable manual: 15 topics, plus a
+`jplot man --json` is the machine-readable manual: a topic index, plus
 live pages for every registered layer method and transform step
 (`jplot man scatter`, `jplot man transform.profile`, `jplot man PDF1D`). Method contracts come from
 the same registry `jplot cap methods` reads, so a man page cannot drift from the
 code.
 
+For compact legends and keys composed from real layers, use
+`jplot man legend --json`. Declare `legend: {object, label, role}` on each drawing layer; components
+with the same object regroup automatically using card templates such as
+`band_line`, `line_errorbar` and `error_bounds`. The role is optional for a
+single-component object. `frame.<axes>.legend` owns card selection, `order`,
+`ncols`, position and spacing. JSON cards provide
+reusable defaults, and YAML can override them. See
+[the legend contract](docs/specs/LEGEND.md) and the
+[self-contained example](Example/compact_legend.yaml).
+
 For continuous one-dimensional distributions from raw samples, use `PDF1D`
 (CDF plus PDF) or `CDF1D` in a data transform. `coordinates.x` owns `expr`,
 `lim`, and `grid`; optional `repeat` computes independent batch means and
@@ -186,9 +197,45 @@ from jarvisplot import render_flowchart, render_flowchart_file
 - You can set `project.workdir` in YAML.
 - If `output.dir` is omitted, Jarvis-PLOT defaults to `<workdir>/plots/`.
 - Data cache is stored in `<workdir>/.cache/`.
+- `--print` accepts the current settings and renders final figures without the logo. It announces that, after all enabled figures are saved successfully, cache payloads used or created by this run will be deleted (pipeline data and metadata, named/shared data, summaries, and HDF5 materialization slots). Rendering failures or a run with no enabled figures keep the cache. Unrelated cache entries and the lightweight fingerprint manifest are retained; later renders rebuild deleted entries as needed.
 - Profiling pipelines are prebuilt once and reused from cache when source fingerprint and profile settings are unchanged.
 - Profiling uses a fast two-stage grid reduction (`pregrid` + render `bin`) for large datasets.
 
+Plot caches are automatically registered in `~/.jarvis/plot.json` (or
+`$JARVIS_HOME/plot.json`). The registry groups caches by workdir and records
+associated YAML paths and last use; payloads stay in their original directories.
+This includes caches created by `data describe` and default `dryrun --with-data`
+exports. Sizes are calculated when listing, rather than stored in the registry.
+
+```bash
+jplot cache list
+jplot cache scan ~/Jarvis-Workshop               # register existing plot caches
+jplot cache clean --workdir /path/to/project    # this directory and all nested projects; repeatable
+jplot cache clean --all --older-than 30         # unused for at least 30 days
+jplot cache clean --all --dry-run               # preview; no deletion/index changes
+jplot cache clean --all                         # clean all registered inactive caches
+jplot cache -h
+jplot man cache
+```
+
+`--workdir PATH` selects registered caches in PATH itself and all of its
+subdirectories, even when PATH has no cache of its own. Repeat it to select
+multiple directory trees; overlapping selections are deduplicated. Use
+`cache scan PATH` first for old caches that have not been registered.
+
+All cache subcommands accept `--json` and use the existing CLI envelope and
+exit codes (0 success/partial, 1 failure, 2 usage). Non-TTY stdout defaults to
+JSON; human results go to stderr. Active caches are skipped (`ok: null` when
+the remaining operation succeeds), and records for missing paths are pruned
+during cleanup. Only marked Jarvis-PLOT components are removed; source data,
+plots, and unrelated `.cache` content are retained. Failed deletions retain
+their registry entries. Scanning adopts legacy caches only when the four
+pipeline directories and a compatible `manifest.json` identify them; old
+unmarked twin-only directories need a new `dryrun --with-data` run to register.
+An explicitly supplied `--out-dir` is an export directory and is not registered.
+Concurrent registry writes use a lock and atomic replacement. Registration
+failures warn without preventing rendering.
+
 ### Example: SUSYRun2 Ternary Plots
 
 ```bash

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/jarvisplot/Figure/adapters_rect.py

@@ -36,7 +36,6 @@ class StdAxesAdapter:
         self._defaults = defaults or {}
         self._clip_path = clip_path  # None means no cropping
         self.config = self._load_internal_config()
-        self._legend = False
         self.status = "init"           # lifecycle: init -> configured -> drawn -> finalized
         self.needs_finalize = True      # allow some axes (e.g., logo) to opt out
 

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/jarvisplot/Figure/config_runtime.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Mapping
 
+from .style_runtime import normalize_style_tokens
+
 
 def apply_figure_config(fig, info: Mapping) -> bool:
     """Apply a YAML figure block to a Figure instance."""
@@ -13,6 +15,8 @@ def apply_figure_config(fig, info: Mapping) -> bool:
     fig._setup_error = None
 
     try:
+        if "legend" in info:
+            raise ValueError("Figure-level legend is not supported; declare items on layers and overall layout under frame.<axes>.legend")
         if "name" in info:
             fig.name = info["name"]
 
@@ -53,7 +57,7 @@ def apply_figure_config(fig, info: Mapping) -> bool:
             )
 
         if "style" in info:
-            style_tokens = info["style"]
+            style_tokens = normalize_style_tokens(info["style"])
         else:
             style_tokens = ["a4paper_2x1"]
         fig.style = style_tokens

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/jarvisplot/Figure/figure.py

@@ -11,9 +11,11 @@ from types import MethodType
 from .adapters_rect import StdAxesAdapter
 from .adapters_ternary import TernaryAxesAdapter
 from .method_registry import resolve_callable
-from .style_runtime import resolve_style_bundle_payload
+from .style_runtime import normalize_style_tokens, resolve_style_bundle_payload
 from .config_runtime import apply_figure_config
 from .design_runtime import draw_design_reference
+from .legend_runtime import apply_legend
+from ..legend_cards import merge_axes_legend, effective_axes_legend
 from .layer_runtime import (
     load_layer_runtime_data as runtime_load_layer_runtime_data,
     release_layer_runtime_data as runtime_release_layer_runtime_data,
@@ -356,15 +358,35 @@ class Figure:
     
     @frame.setter
     def frame(self, value) -> None: 
+        self._legend_disabled_axes = getattr(self, "_legend_disabled_axes", set())
+        for name, node in (value or {}).items():
+            if isinstance(node, dict) and "legend" in node:
+                declared = node["legend"]
+                if declared is False or (isinstance(declared, dict) and declared.get("enabled") is False):
+                    self._legend_disabled_axes.add(name)
+                else:
+                    self._legend_disabled_axes.discard(name)
         if self._frame is None:
             self._frame = value
         else:
+            # Legend order/roles are replacement lists, not deepmerge's
+            # default append lists. Explicit YAML also enables a disabled card
+            # default, unless enabled:false was supplied by the user.
+            value = deepcopy(value)
+            legends = {}
+            for name, node in (value or {}).items():
+                if isinstance(node, dict) and "legend" in node:
+                    legends[name] = merge_axes_legend(
+                        self._frame.get(name, {}).get("legend", False), node.pop("legend")
+                    )
             for _name, _node in (value or {}).items():
                 _color = _node.get("color") if isinstance(_node, dict) else None
                 if isinstance(_color, dict) and "cmap" in _color:
                     self._yaml_axc_cmaps.add(str(_name))
             from deepmerge import always_merger
             self._frame = always_merger.merge(self._frame, value)
+            for name, legend in legends.items():
+                self._frame.setdefault(name, {})["legend"] = legend
 
     @property
     def yaml_colorbar_cmaps(self) -> set:
@@ -377,12 +399,16 @@ class Figure:
     
     
     @style.setter
-    def style(self, value) -> None: 
-        if len(value) not in (1, 2):
-            self.logger.error("Undefined style -> {}".format(value))
-            raise TypeError
+    def style(self, value) -> None:
+        value = normalize_style_tokens(value)
+        if not isinstance(value, list) or len(value) not in (1, 2):
+            raise TypeError(
+                "style must name a card family or [family, variant], e.g. "
+                "a4paper_2x1 or [a4paper_2x1, rect]; got {!r}".format(value)
+            )
         family, selected, bundle = resolve_style_bundle_payload(self.jpstyles, value)
         self._frame = deepcopy(bundle["Frame"])
+        self._legend_disabled_axes = set()
         self._yaml_axc_cmaps = set()
         self._style = deepcopy(bundle["Style"])
         self._debug_config = deepcopy(bundle.get("Debug", {}))
@@ -485,7 +511,7 @@ class Figure:
             return {kk: self._ensure_pandas_data(vv, reason=reason) for kk, vv in data.items()}
         return data
 
-    def _concat_loaded_data(self, items):
+    def _concat_loaded_data(self, items, layer_name: str = ""):
         if len(items) == 0:
             return None
         if len(items) == 1:
@@ -496,7 +522,28 @@ class Figure:
         pandas_items = [self._ensure_pandas_data(item, reason="concat-layer") for item in items]
         try:
             return pd.concat(pandas_items, ignore_index=False)
-        except Exception:
+        except Exception as exc:
+            # Keep drawing what can be drawn, but never drop data silently.
+            if self.logger:
+                shapes = ", ".join(
+                    str(getattr(item, "shape", type(item).__name__)) for item in pandas_items
+                )
+                self.logger.warning(
+                    "Layer '{}': the {} data blocks could not be concatenated, so only "
+                    "the first block is drawn and the other {} are dropped.\n"
+                    "\t reason \t-> {}: {}\n"
+                    "\t blocks \t-> {}\n"
+                    "\t hint \t\t-> blocks combined with `combine: concat` must be tables "
+                    "with compatible columns (no duplicated column names); use "
+                    "`combine: separate` to draw them independently.".format(
+                        layer_name or "<unnamed>",
+                        len(pandas_items),
+                        len(pandas_items) - 1,
+                        type(exc).__name__,
+                        exc,
+                        shapes,
+                    )
+                )
             return pandas_items[0]
 
     def _store_share_data_if_needed(self, layer, data, cache_ref: str | None = None):
@@ -616,7 +663,6 @@ class Figure:
                 clip_path=Path(vertices, codes)  # 用 path 做 clip，transform 使用 ax.transData 已在适配器里处理
             )
             adapter._type = 'tri'
-            adapter._legend = False
             adapter.layers = []
             adapter.status = 'configured'
             self.axes["axtri"] = adapter
@@ -1075,7 +1121,6 @@ class Figure:
             adapter = StdAxesAdapter(raw_ax)
             adapter._type = "rect"
             adapter.layers = []
-            adapter._legend = self.frame['ax'].get("legend", False)
             self.axes['ax'] = adapter 
             adapter.status = 'configured'
         
@@ -1185,19 +1230,13 @@ class Figure:
         self.logger.debug("Loaded main rectangle axes -> ax")
 
     def _apply_legend_on_axes(self, ax_name: str, ax_obj, leg_cfg: dict):
-        """Apply a legend on a specific axes using a YAML dict stored under frame['axes'][ax_name]['legend'].
-        Supports an optional 'enabled' key (default True). Any 'axes' key will be ignored here."""
-        if not isinstance(leg_cfg, dict):
-            return
-        if leg_cfg.get("enabled", True) is False:
-            return
-        kw = dict(leg_cfg)
-        kw.pop("axes", None)  # per-axes legend doesn't need this
-        try:
-            (ax_obj.ax if hasattr(ax_obj, "ax") else ax_obj).legend(**kw)
-        except Exception as e:
-            if self.logger:
-                self.logger.warning(f"Legend apply failed on '{ax_name}': {e}")
+        """Apply frame.<axes>.legend after all real layer handles are available."""
+        target_ax = ax_obj.ax if hasattr(ax_obj, "ax") else ax_obj
+        layer_specs = getattr(self, "_legend_layers", {}).get(ax_name, [])
+        return apply_legend(
+            target_ax, leg_cfg, getattr(self, "_legend_layer_handles", {}).get(ax_name, {}),
+            base_dir=self._yaml_dir, layer_specs=layer_specs,
+        )
 
 
     def _install_tri_auto_clip(self, ax):
@@ -1326,10 +1365,17 @@ class Figure:
         # determined by frame config + data — never by render order.
         self._prescan_colorbar_ranges()
 
+        self._legend_layer_handles = {}
+        self._legend_layers = {}
+        axes_names = {id(ax): name for name, ax in self.axes.items()}
         for ax, ly in self._render_queue:
             runtime_load_layer_runtime_data(self, ly)
             try:
-                runtime_render_layer(self, ax, ly)
+                rendered = runtime_render_layer(self, ax, ly)
+                name = axes_names[id(ax)]
+                specs = self._legend_layers.setdefault(name, [])
+                self._legend_layer_handles.setdefault(name, {})[f"@layer:{len(specs)}"] = rendered
+                specs.append(ly.get("layer_spec", {}))
             finally:
                 runtime_release_layer_runtime_data(self, ly)
 
@@ -1340,12 +1386,14 @@ class Figure:
 
         for name, ax in self.axes.items():
             try:
-                if hasattr(ax, "_legend") and ax._legend:
-                    target_ax = ax.ax if hasattr(ax, "ax") else ax
-                    target_ax.legend(**ax._legend)
+                legend_config = self.frame.get(name, {}).get("legend", False)
+                legend_config = effective_axes_legend(
+                    legend_config, self._legend_layers.get(name, []),
+                    explicitly_disabled=name in getattr(self, "_legend_disabled_axes", set()),
+                )
+                self._apply_legend_on_axes(name, ax, legend_config)
             except Exception as e:
-                if self.logger:
-                    self.logger.warning(f"Legend draw failed on axes '{name}': {e}")
+                raise ValueError(f"Legend draw failed on axes '{name}': {e}") from e
 
         # Finalize all colorbar axes (axc and any named axc*)
         for name in list(self.axes.keys()):

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/jarvisplot/Figure/layer_runtime.py

@@ -642,7 +642,7 @@ def _load_layer_data(fig, layer):
                     fig.logger.error("DataSet -> {} not specified".format(src))
             if len(dts) == 0:
                 return None, None
-            combined = fig._concat_loaded_data(dts)
+            combined = fig._concat_loaded_data(dts, layer_name=str(layer.get("name", "") or ""))
             cache_ref = None
             if len(dts) == 1 and combined is dts[0] and len(cache_keys) == 1:
                 cache_ref = cache_keys[0]

{jarvisplot-2.1.6 → jarvisplot-2.1.8}/jarvisplot/Figure/layout_runtime.py

@@ -164,7 +164,6 @@ def ensure_rect_axes(fig, ax_name: str, kwgs: dict):
         adapter = StdAxesAdapter(raw_ax)
         adapter._type = "rect"
         adapter.layers = []
-        adapter._legend = fig.frame.get(ax_name, {}).get("legend", False)
         fig.axes[ax_name] = adapter
         adapter.status = "configured"
 
@@ -309,7 +308,6 @@ def ensure_corr_axes(fig, kwgs: dict):
         adapter = StdAxesAdapter(raw_ax)
         adapter._type = "rect"
         adapter.layers = []
-        adapter._legend = False
         fig.axes[name] = adapter
         adapter.status = "configured"