plotlet 0.6.0__tar.gz → 0.7.0__tar.gz

plotlet-0.7.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: plotlet
+Version: 0.7.0
+Summary: Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types.
+Author: gitbamboo42
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gitbamboo42/plotlet
+Project-URL: Repository, https://github.com/gitbamboo42/plotlet
+Project-URL: Issues, https://github.com/gitbamboo42/plotlet/issues
+Keywords: plot,svg,scientific,visualization,jupyter,reproducible
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fonttools>=4.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: resvg_py>=0.3
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Requires-Dist: jsonschema; extra == "test"
+Provides-Extra: pdf
+Requires-Dist: cairosvg; extra == "pdf"
+Dynamic: license-file
+
+# plotlet
+
+plotlet is a Python library for reproducible, multi-panel scientific figures, built for AI authorship: figures are written, inspected, and verified as data, not pixels. Byte-identical output across machines, a standard plotting vocabulary, built-in Cartesian and circular coordinate systems, and an easy way to add your own plot types.
+
+## Documentation
+
+Online documentation is available at [gitbamboo42.github.io/plotlet](https://gitbamboo42.github.io/plotlet/).
+
+The docs include a [tutorial](https://gitbamboo42.github.io/plotlet/tutorial.html), a [plot-type reference](https://gitbamboo42.github.io/plotlet/reference.html), a [cookbook](https://gitbamboo42.github.io/plotlet/cookbook.html), an [extensions gallery](https://gitbamboo42.github.io/plotlet/extensions.html), [deep-dive guides](https://gitbamboo42.github.io/plotlet/docs-api.html), and a [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html).
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy`, `resvg_py`. numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## For AI assistants
+
+Tell your assistant to run plotlet's `skill()` and follow it. The guides, docs, and worked examples ship inside the installed package; the [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html) shows the full workflow.
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

plotlet-0.7.0/README.md

@@ -0,0 +1,35 @@
+# plotlet
+
+plotlet is a Python library for reproducible, multi-panel scientific figures, built for AI authorship: figures are written, inspected, and verified as data, not pixels. Byte-identical output across machines, a standard plotting vocabulary, built-in Cartesian and circular coordinate systems, and an easy way to add your own plot types.
+
+## Documentation
+
+Online documentation is available at [gitbamboo42.github.io/plotlet](https://gitbamboo42.github.io/plotlet/).
+
+The docs include a [tutorial](https://gitbamboo42.github.io/plotlet/tutorial.html), a [plot-type reference](https://gitbamboo42.github.io/plotlet/reference.html), a [cookbook](https://gitbamboo42.github.io/plotlet/cookbook.html), an [extensions gallery](https://gitbamboo42.github.io/plotlet/extensions.html), [deep-dive guides](https://gitbamboo42.github.io/plotlet/docs-api.html), and a [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html).
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy`, `resvg_py`. numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## For AI assistants
+
+Tell your assistant to run plotlet's `skill()` and follow it. The guides, docs, and worked examples ship inside the installed package; the [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html) shows the full workflow.
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

{plotlet-0.6.0 → plotlet-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plotlet"
-version = "0.6.0"
+version = "0.7.0"
 description = "Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types."
 readme = "README.md"
 license = "MIT"
@@ -48,6 +48,7 @@ dev = [
 test = [
   "pytest>=7",
   "pandas",
+  "jsonschema",
 ]
 pdf = [
   "cairosvg",
@@ -70,4 +71,16 @@ namespaces = true
 # draw/fonts/*.txt are the font licenses — DejaVu (Bitstream Vera–derived)
 # and Arimo (SIL OFL 1.1) both require the license text to accompany
 # redistribution, so they must ship in the wheel next to the TTFs.
-plotlet = ["spec.json", "themes/*.json", "draw/fonts/*.ttf", "draw/fonts/*.txt", "_datasets/*.csv"]
+plotlet = ["spec.json", "themes/*.json", "draw/fonts/*.ttf", "draw/fonts/*.txt", "_datasets/*.csv", "_datasets/*.npz",
+           # AI onboarding: pt.skill() reads skills/, and the guides point
+           # at the shipped docs/ and examples/ so an installed package is
+           # self-sufficient — no repo clone, no web access needed.
+           "skills/*.md", "docs/*.md", "examples/*.py",
+           # JSON twins of the examples, for authoring plots as JSON
+           # journals (skills/json.md). Generated by
+           # tests/gen_json_examples.py — never edited by hand.
+           "examples/json/*.json",
+           # JSON Schema for journal-lite blobs, for editor/server-side
+           # validation. Generated by tests/gen_json_schema.py from
+           # pt.op_schema() — never edited by hand.
+           "schemas/*.json"]

{plotlet-0.6.0 → plotlet-0.7.0}/src/plotlet/__init__.py

@@ -1,15 +1,17 @@
 """plotlet — pure-Python deferred-rendering SVG plot library.
 
     import plotlet as pt
+    from plotlet import aes
+
     c = pt.chart(df, title="...", xlabel="x", ylabel="y", legend=True, gridlines=True)
-    c.line(x="time", y="value", color="series")
+    c.add_line(aes(x="time", y="value", color="series"))
     c                         # auto-renders in Jupyter
 
 Chart methods chain for incremental composition:
 
     df = {"x": [1, 2, 3], "y": [1, 4, 9]}
     c = pt.chart()
-    c.line(df, x="x", y="y", label="squares")
+    c.add_line(df, aes(x="x", y="y"), label="squares")
     c.title("Hello").legend().gridlines(True)
     c
 """
@@ -17,21 +19,31 @@ from ._spec import SPEC
 from .draw import TAB10, palette, list_palettes
 from .draw import colormap, list_colormaps, register_colormap
 from . import artists  # noqa: F401  — registers built-in artists on import
-from .chart import Chart, Layout, chart, grid
-from .legend import legend
+from .record.chart import Chart, Layout, chart, grid
+from .utils import aes
+from .record.legend import legend
 from .registry import ArtistSpec, add_artist, artist_table, declare_coord_support
 from .sectors import Sectors
 from .layout_diagram import layout_diagram
 from .themes import load_theme, list_themes, register_theme
-from .facet import facet, FacetGrid
+from .record.facet import facet, FacetGrid
 from .datasets import load_dataset, list_datasets
 from .cluster import linkage, linkage_split, SplitTree
 from .formatters import (register_formatter, list_formatters,
                          superscript, subscript)
 from ._coord_registry import register_coord_codec
-from ._journal import (to_journal, from_journal, to_json, from_json,
+from .record.journal import (to_journal, from_journal, to_json, from_json,
                        JournalNode, Journal)
-from ._ir import to_ir, from_ir, resolve_ir, FigureIR, IRNode
+from .record.journal_lite import to_json_lite, from_json_lite
+from .record.codegen import to_python
+from .record.figure_ir import to_ir, from_ir, FigureIR, IRNode
+from .skill import skill
+# Shadows the `plotlet.lint` submodule attribute with the function —
+# the os.path-style pattern: `pt.lint(c)` calls it, and
+# `from plotlet.lint import lint` still resolves via sys.modules.
+from .lint import lint
+from .describe import describe
+from .op_help import op_help, op_schema  # same shadowing pattern as lint
 from . import draw, utils
 
 
@@ -41,7 +53,7 @@ def __getattr__(name):
     # the render half loads on first render (or first touch of this
     # name). Enforced by tests/test_import_boundary.py.
     if name == "CircularCoordinate":
-        from .render.coordinates import CircularCoordinate
+        from .render._coord_circular import CircularCoordinate
         return CircularCoordinate
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
@@ -58,9 +70,11 @@ __all__ = ["chart", "Chart", "Layout", "SPEC", "TAB10",
            "linkage", "linkage_split", "SplitTree",
            "register_formatter", "list_formatters",
            "superscript", "subscript",
-           "to_json", "from_json", "register_coord_codec",
+           "to_json", "from_json", "to_json_lite", "from_json_lite",
+           "to_python", "register_coord_codec",
            "to_journal", "from_journal", "JournalNode", "Journal",
-           "to_ir", "from_ir", "FigureIR", "IRNode", "resolve_ir",
+           "to_ir", "from_ir", "FigureIR", "IRNode",
+           "skill", "lint", "describe", "op_help", "op_schema",
            "draw", "utils"]
 
 # Single source of truth: pyproject.toml. importlib.metadata reads it at

{plotlet-0.6.0 → plotlet-0.7.0}/src/plotlet/_coord_registry.py

@@ -1,11 +1,16 @@
-"""Coord codec registry — a neutral home for the `class_name → class` map
-that both `serialize.py` and `_journal.py` need for round-tripping coord
-objects like `CircularCoordinate`.
+"""Coord codec registry — the `class_name → class` map behind
+`{"$coord": ...}` envelopes, for coord objects like
+`CircularCoordinate`.
 
-Lives here rather than in either consumer so that removing one of them
-later (e.g. retiring the JSON tree serializer once the journal covers
-the same ground) doesn't leave the registry orphaned. The public API
-`plotlet.register_coord_codec` re-exports from this module directly.
+`record/journal.py` encodes a coord object to its class name;
+`_json_layer._decode` turns the name back into the class via
+`resolve_coord`, which imports the built-in coord module on the first
+miss so cold processes decode without a prior render. The render half
+reads the map too (`render/_validate.py` cross-checks the `container`
+flag, `render/resolved_ir.py` rehydrates coords), so the registry sits
+at the package root, where `record/` and `render/` may both import it.
+The public API `plotlet.register_coord_codec` re-exports from this
+module directly.
 """
 from __future__ import annotations
 
@@ -38,7 +43,7 @@ def resolve_coord(name: str) -> type:
         return _COORD_REGISTRY[name]
     except KeyError:
         pass
-    from .render import coordinates  # noqa: F401 — registers built-ins
+    from .render import _coord_circular  # noqa: F401 — registers built-ins
     try:
         return _COORD_REGISTRY[name]
     except KeyError:

plotlet-0.7.0/src/plotlet/_json_layer.py

@@ -0,0 +1,227 @@
+"""JSON envelope layer — shared by `record/` and `render/`.
+
+Envelopes Python values that aren't JSON-native (tuple, set, date,
+datetime, dicts with non-string keys, DataFrameLite) so they can be
+dumped through `json.dumps` and rehydrated. Four consumers: the
+journal's JSON form (`record/journal.py`), the FigureIR wire format
+(`record/figure_ir.py`), value-envelope decoding at render hydration
+(`_decode`, `render/_nodes.py`), and the resolved IR's debug view
+(`render/resolved_ir.py`). It sits at the package root because both
+`record/` and `render/` need it and neither may import the other
+(`tests/test_import_boundary.py`). It also keeps JSON support out of
+`journal.py` itself — the journal stays a plain event log.
+
+DataFrame-shaped inputs never reach this layer: they're normalized to
+`DataFrameLite` / plain lists at the recorder boundary in
+`record/chart.py` (via `utils._normalize_data`), so it never imports
+pandas or grows a branch per data library. numpy is the one exception:
+a matrix artist's data rides through record as a 2-D ndarray (numpy is
+a guaranteed dependency, via scipy), and `json_safe` lowers it to
+nested lists — the JSON wire format itself carries no array types.
+
+Envelope keys used here:
+    $dataframe    utils.DataFrameLite (canonical DataFrame form)
+    $tuple        tuple (JSON has no tuple type; without this every
+                  tuple would silently degrade to list, breaking
+                  isinstance dispatch inside artist code)
+    $set          set
+    $date         datetime.date
+    $datetime     datetime.datetime
+    $dict_pairs   dict whose keys aren't all JSON-native strings
+
+`_decode` at the bottom handles the other envelope family — the
+*reference* envelopes ($node / $coord / $sectors / $data) that journals
+and IRs carry whether or not they ever touch JSON. It lives here because
+both halves need it (the render tree's hydrator and the front half's
+facet expansion) and it resolves only against shared vocabulary.
+"""
+from __future__ import annotations
+import json
+from typing import Any
+
+import numpy as np
+
+from .utils import DataFrameLite, all_primitive
+
+
+def json_safe(value: Any) -> Any:
+    """Walk `value`, replace non-JSON types with envelopes. Plotlet
+    envelopes ($node / $coord / $sectors) already added at `to_journal`
+    time pass through as regular dicts — their inner values still get
+    recursed."""
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    # datetime.datetime is a subclass of datetime.date — check the more
+    # specific type first so datetimes get $datetime, not $date.
+    import datetime as _dt
+    if isinstance(value, _dt.datetime):
+        return {"$datetime": value.isoformat()}
+    if isinstance(value, _dt.date):
+        return {"$date": value.isoformat()}
+    if isinstance(value, DataFrameLite):
+        # index and cell values recurse — a date/datetime column must
+        # wire as `$date` / `$datetime` cells, same as anywhere else.
+        return {"$dataframe": {
+            "columns": value.columns,
+            "index":   [json_safe(v) for v in value.index],
+            "values":  [[json_safe(v) for v in row] for row in value.values],
+        }}
+    from .sectors import Sectors
+    if isinstance(value, Sectors):
+        # Live instance → the same envelope `to_journal` emits and
+        # `_decode` reconstructs (`Sectors._from_dict`). Reached by
+        # values that never passed through the journal emitter, e.g. a
+        # resolved-IR state dict.
+        return {"$sectors": json_safe(value._to_dict())}
+    if isinstance(value, np.ndarray):
+        # A matrix artist's data section entry. The wire format stays
+        # plain nested lists — identical JSON whether the matrix came
+        # in as an array or as lists. Recursing catches the rare
+        # object-dtype cell.
+        return json_safe(value.tolist())
+    if isinstance(value, tuple):
+        return {"$tuple": [json_safe(v) for v in value]}
+    if isinstance(value, (set, frozenset)):
+        # Iteration order is hash order, which varies across processes
+        # (PYTHONHASHSEED) — sort the serialized elements so $set
+        # payloads are byte-stable.
+        return {"$set": sorted((json_safe(v) for v in value), key=repr)}
+    if isinstance(value, dict):
+        if all(isinstance(k, str) for k in value):
+            return {k: json_safe(v) for k, v in value.items()}
+        # Non-string key means the whole dict can't be a JSON object;
+        # emit as a list of [key, value] pairs.
+        return {"$dict_pairs": [[json_safe(k), json_safe(v)]
+                                for k, v in value.items()]}
+    if isinstance(value, list):
+        # Bulk numeric rows are already JSON-native — one flat scan
+        # instead of per-cell recursion (same bail-out in json_hydrate,
+        # _decode, and the journal/IR walkers).
+        if all_primitive(value):
+            return list(value)
+        return [json_safe(v) for v in value]
+    return value
+
+
+def json_hydrate(value: Any) -> Any:
+    """Inverse of `json_safe`. Plotlet envelopes ($node / $coord /
+    $sectors) are left as dicts — the journal's own `_decode` handles
+    them at replay time."""
+    if isinstance(value, dict):
+        if "$dataframe" in value:
+            d = value["$dataframe"]
+            return DataFrameLite(
+                values=[[json_hydrate(v) for v in row]
+                        for row in d["values"]],
+                columns=d["columns"],
+                index=[json_hydrate(v) for v in d["index"]],
+            )
+        if "$tuple" in value:
+            return tuple(json_hydrate(v) for v in value["$tuple"])
+        if "$set" in value:
+            return {json_hydrate(v) for v in value["$set"]}
+        if "$date" in value:
+            import datetime as _dt
+            return _dt.date.fromisoformat(value["$date"])
+        if "$datetime" in value:
+            import datetime as _dt
+            return _dt.datetime.fromisoformat(value["$datetime"])
+        if "$dict_pairs" in value:
+            return {json_hydrate(k): json_hydrate(v)
+                    for k, v in value["$dict_pairs"]}
+        return {k: json_hydrate(v) for k, v in value.items()}
+    if isinstance(value, list):
+        if all_primitive(value):
+            return list(value)
+        return [json_hydrate(v) for v in value]
+    return value
+
+
+_PRETTY_WIDTH = 100     # target line width for pretty_dumps
+
+
+def pretty_dumps(value: Any) -> str:
+    """Canonical JSON text form — what `pt.to_json` returns and the
+    shipped example twins use. Objects and arrays stay on one line when
+    they fit in `_PRETTY_WIDTH` columns; a too-long dict or mixed list
+    expands one element per line (1-space indent steps); a too-long
+    list of primitives wraps at the width, continuation lines aligned
+    under its opening bracket — so journal entries read structurally
+    while data columns stay a few dense lines. Deterministic (same
+    value → same bytes) and whitespace-only: `json.loads` of the
+    result equals `json.loads(json.dumps(value))`."""
+    return _pretty(value, 0, "")
+
+
+def _pretty(value: Any, col: int, pad: str) -> str:
+    """Render `value` starting at column `col`; `pad` is the
+    indentation of the enclosing construct."""
+    compact = json.dumps(value)
+    if col + len(compact) <= _PRETTY_WIDTH \
+            or not isinstance(value, (dict, list)):
+        return compact
+    inner = pad + " "
+    if isinstance(value, dict):
+        lines = []
+        for k, v in value.items():
+            key = f"{inner}{json.dumps(k)}: "
+            lines.append(key + _pretty(v, len(key), inner))
+        return "{\n" + ",\n".join(lines) + "\n" + pad + "}"
+    if all(not isinstance(v, (dict, list)) for v in value):
+        room = max(_PRETTY_WIDTH - col - 1, 20)     # width left after "["
+        parts, lines, used = [json.dumps(v) for v in value], [], -2
+        for part in parts:
+            if used < 0 or used + 2 + len(part) > room:
+                lines.append([part])
+                used = len(part)
+            else:
+                lines[-1].append(part)
+                used += 2 + len(part)
+        joined = (",\n" + " " * (col + 1)).join(
+            ", ".join(line) for line in lines)
+        return "[" + joined + "]"
+    lines = [inner + _pretty(v, len(inner), inner) for v in value]
+    return "[\n" + ",\n".join(lines) + "\n" + pad + "]"
+
+
+def _decode(value: Any, nid_to_node: dict, data_table: dict) -> Any:
+    """Resolve plotlet's *reference* envelopes back to live objects —
+    `{"$node"}` via `nid_to_node`, `{"$coord"}` via the coord registry,
+    `{"$sectors"}` via `Sectors`, `{"$data"}` via `data_table` (the
+    Journal's / FigureIR's data section). Containers recurse; everything
+    else passes through.
+
+    Distinct from `json_hydrate` above: that undoes the JSON-native
+    envelopes at the JSON boundary, while these reference envelopes live
+    in journals and IRs whether or not they ever touch JSON, and decode
+    at hydration time. Shared vocabulary — used by the render tree's
+    hydrator (`render.hydrate`) and by the facet expansion in
+    `record/figure_ir.py`."""
+    if isinstance(value, dict):
+        if "$node" in value and len(value) == 1:
+            return nid_to_node[value["$node"]]
+        if "$data" in value and len(value) == 1:
+            return data_table[value["$data"]]
+        if "$coord" in value:
+            from ._coord_registry import resolve_coord
+            cls = resolve_coord(value["$coord"])
+            return cls._from_dict(
+                _decode(value.get("kwargs", {}), nid_to_node, data_table))
+        if "$sectors" in value:
+            from .sectors import Sectors
+            return Sectors._from_dict(
+                _decode(value["$sectors"], nid_to_node, data_table))
+        if "$aes" in value and len(value) == 1:
+            from .utils import Aes
+            return Aes(value["$aes"])
+        return {k: _decode(v, nid_to_node, data_table)
+                for k, v in value.items()}
+    if isinstance(value, list):
+        if all_primitive(value):
+            return list(value)
+        return [_decode(v, nid_to_node, data_table) for v in value]
+    if isinstance(value, tuple):
+        if all_primitive(value):
+            return value
+        return tuple(_decode(v, nid_to_node, data_table) for v in value)
+    return value

{plotlet-0.6.0 → plotlet-0.7.0}/src/plotlet/_regions.py

@@ -15,7 +15,9 @@ The mechanism enforces this:
     When set, the primitive records its bbox under that name. When
     unset (the default), nothing is recorded — so artist `draw()`
     bodies, which never pass `tag=`, produce no regions for free.
-  * Central code (`core.py`, `legend.py`) passes `tag="title"` /
+  * Central code (`render/_chrome_emit.py`, `render/emit.py`,
+    `render/_legend.py`)
+    passes `tag="title"` /
     `"spine"` / `"tick-x"` / `"legend-text"` etc. at the chrome
     emission sites. The tag is right there in the call, grep-able,
     no contextvar magic.
@@ -56,6 +58,11 @@ class _Sink:
     # offset to recorded bboxes so consumers receive outer-SVG coords
     # regardless of whether the chart is single- or multi-panel.
     translate_stack: list[tuple[float, float]] = field(default_factory=list)
+    # Depth of active `structural()` blocks — chrome recorded inside
+    # one lives inside the panel rect by design (coordinate-owned
+    # chrome, an inside-positioned legend), so overlap lint can tell
+    # it from misplaced chrome.
+    structural_depth: int = 0
 
     def _offset(self) -> tuple[float, float]:
         dx = dy = 0.0
@@ -73,6 +80,12 @@ class _Sink:
         # the bbox in outer-SVG coords.
         if "polygon" in meta:
             meta["polygon"] = [(px + dx, py + dy) for px, py in meta["polygon"]]
+        # Multi-line text ships one quad per inked line under `lines`.
+        if "lines" in meta:
+            meta["lines"] = [[(px + dx, py + dy) for px, py in quad]
+                             for quad in meta["lines"]]
+        if self.structural_depth:
+            meta.setdefault("structural", True)
         self.regions.append(Region(kind=kind, bbox=(x + dx, y + dy, w, h),
                                    name=name, meta=meta))
 
@@ -85,7 +98,9 @@ _CURRENT: contextvars.ContextVar = contextvars.ContextVar(
 def record(kind: str, bbox, *, name: str, **meta) -> None:
     """Record a region into the active sink, if any. Called by
     `draw.*` primitives when they receive a `tag=` kwarg, and by
-    central code (`core.py`, `legend.py`) for chrome that has no
+    central code (`render/_chrome_emit.py`, `render/emit.py`,
+    `render/_legend.py`)
+    for chrome that has no
     primitive call to wrap (panel boundary, canonical legend swatch).
     No-op when no sink is active — the common render path."""
     sink = _CURRENT.get()
@@ -124,6 +139,26 @@ def suppressed():
         _CURRENT.reset(token)
 
 
+@contextmanager
+def structural():
+    """Mark every region recorded in the block as `structural=True` —
+    chrome that lives inside the panel rect *by design*, so its overlap
+    with the panel/spines is rendering geometry, not a layout bug.
+    Wrapped around coordinate-owned chrome emission (a circular chart's
+    angular tick labels and sector walls all sit inside the data ring)
+    and an inside-positioned legend's body. Overlap lint skips
+    structural-vs-container pairs. No-op when no sink is active."""
+    sink = _CURRENT.get()
+    if sink is None:
+        yield
+        return
+    sink.structural_depth += 1
+    try:
+        yield
+    finally:
+        sink.structural_depth -= 1
+
+
 @contextmanager
 def translate(dx: float, dy: float):
     """Push a translate offset onto the sink's transform stack for the