feat(2.0): pane handles — named panes, whole-render state, pane-scoped events & export [D145]–[D150]

[jawjay]

What this is

The downstream-use half of the plot-organization arc: every surface of a render (grid cell, tab, splitter pane — or the whole plot) becomes an addressable pane with a stable label, and that label carries through state capture/restore, event scoping, the native escape hatch, and export. Design docs: design/layout-panes-plan.md (review + [D145]–[D151]) and design/pane-handles.md (detailed design; §5 status). One commit per step S1–S5.

lay = qv.Layout.grid({"price": price_plot, "volume": volume_plot})
view = qv.View(lay)

view.pane("price").set_range(x=(0, 10))          # programmatic pan/zoom
view.on(qv.RangeEvent, on_zoom, pane="price")     # pane-scoped events
view.pane("price").export("png", "price.png")     # per-pane export
view.set_root(view.root.with_pane("volume", new)) # declarative pane swap

Fixes (S1, bug tier)

• Multi-pane view state was silently lost — every backend captured only pane 0 (_plots[0] / _surfaces[0]); composites captured nothing. Zoom pane 2, switch theme/backend → snap back to autorange. Now capture_state() returns a LayoutState covering every pane, restored by label.
• Nested homogeneous grids crashed (AttributeError: 'Layout' has no attribute 'lower') — now routed through the LayoutHost.

Architecture

• State ownership inverted: backends implement a _panes() factory (one PaneHandle facade per surface); whole-render capture/restore is written once in core on top of it. ViewState unchanged as the per-surface record; LayoutState adds first-pane passthroughs so single-surface reads keep working.
• PaneHandle — the "Axes of qtviz" ([D147]): interaction-side verbs only (set_range/autorange/select/capture/restore/.native/.elements/.export). Describe-side config stays on the node (.opts(), with_pane + set_root) — one-way data flow preserved. Facades are owned by their render: a pane kept across a rebuild goes dead (alive) and raises the new qtviz.errors.DisposedError.
• Pane identity is a core concept ([D145]): Layout.labels (value-hashed) + flat_pane_labels() as the single source of truth — shared by backends, the composite host, state keys, and event stamping.
• Event stamping layer ([D149]): Event.pane (kw-only), a per-surface PaneBus proxy in pg/mpl (element emit sites inherit pane identity with zero signature changes), and a local→flat label shim on the composite bus — third-party single-surface backends get pane-correct events with no edits ([D125] holds).
• Host routing: a grid containing a Layout child now hosts per-pane; can_host("grid") means a flat grid (all the cell renderers ever supported).

Creation-side sugar ([D145]/[D148])

Mapping children (Layout.grid({"price": p, ...}), tabs/splitter too), retained mosaic labels + the subplot_mosaic list form with multi-char labels, explicit cells= with mosaic-grade overlap validation, layout[label], Layout.with_pane.

Behavior changes (CHANGELOG'd)

• capture_state() returns LayoutState (was ViewState); restore_state accepts both (bare ViewState = first-pane shorthand).
• RangeEvent/TapEvent.source_id is the pane label (was a per-render uuid — never exposed, nothing could depend on it).

FROZEN_2_0 is untouched — PaneHandle/LayoutState follow the [D135] return-type convention; docs get a Panes section in api.md.

Testing

+53 tests across test_pane_state.py / test_pane_labels.py / test_pane_handle.py / test_pane_events.py (tier-1 core + tier-2 parametrized over pyqtgraph/matplotlib, composite/splitter/nested cases; webengine display-gated as usual). Full suite 1037 passed; ruff/mypy/mkdocs --strict clean. Both export approaches (pg ImageExporter(plotItem), mpl tightbbox crop) were spiked before landing.

Not in this PR

The sharing track — [D146] link_x="col"/"row" + mixed-pane honor-or-warn, then the [D151] cross-backend linking gate (event-loop/throttle risk; own go/no-go).

🤖 Generated with Claude Code

[jawjay]

Added the sharing track (34af96d) — the arc's final piece:

• [D146] link_x/link_y now accept "col"/"row" alongside bools. Groups derive from the grid cells (spanning panes merge groups transitively — the subplot_mosaic rule), applied natively per group: pg setXLink to the group leader, mpl sharex/sharey. "col"/"row" on a non-grid kind raises at construction.
• [D151] Linking now crosses host panes (mixed backends, splitter/tabs, nested grids) — previously warned-and-ignored. A _LinkController on the composite handle propagates RangeEvents within groups via pane.set_range, echo-guarded by a reentrancy flag (synchronous emits) plus a value guard (async webengine round-trips converge instead of ping-ponging). Nested-layout panes are excluded from cross-pane groups with a warning; the host honors link_x/link_y.

+12 tests (test_pane_linking.py + a flipped host-honesty contract test). Suite at 1048 green; ruff/mypy/mkdocs clean. This completes [D145]–[D151].