Embedding API for host applications, CLI file argument, PNG-default preview

[BenHuddart]

What

Three related changes preparing gleplot's editor to serve as the figure editor inside host applications (concretely: Asymmetry, which ships gleplot as a library dependency and now opens exported .gle figures in this editor in-process).

1. Embedding API (feat)

• gleplot.gui.open_editor(path=None, *, parent=None, settings=None, gle_executable=None) — opens a shown MainWindow inside an existing QApplication (raises RuntimeError if there is none). Unlike main(), it never mutates app-global identity (name, organization, app icon — the window icon is set window-locally), and never runs an event loop. Lazily re-exported from gleplot.gui so importing the subpackage stays PySide6-free.
• MainWindow.open_path() — public wrapper over the File ▸ Open dispatch for embedders.
• MainWindow.apply_gle_executable() — session-only GLE-binary override + preview/status refresh, factored out of the GLE Setup accept path, so a host can impose its configured binary without overwriting the user's standalone preference.
• MainWindow.force_close() — closes without the dirty-document confirmation, for host shutdown (an unanswerable modal would hang a headless test run; pinned by a regression test).
• CLI: gleplot-gui figure.gle opens the file after show(); a nonexistent path exits 2 before any QApplication is created; --smoke-test ignores the file argument entirely.

2. PNG-default preview (fix)

The raster path has proven more robust than GLE's Cairo SVG backend, so PNG is now the startup render format unconditionally. SVG remains opt-in via View ▸ Vector preview (SVG); the probe compile that used to run synchronously at every controller construction now runs on the first opt-in instead (one less subprocess at startup). A failed probe routes through the existing sticky PNG fallback so the toggle unchecks/disables with the reason.

3. QtSvg occlusion-clip diagnosis (docs)

Investigating "SVG renders but elements are missing": GLE's Cairo backend implements box/legend occlusion by clipping underlying content out of the box rectangle (multi-subpath <clipPath>), not by painting over it. QtSvg has no real clip-path support, so occluded content bleeds through (or vanishes, with partial clipping). The SVG file is correct — browsers render it faithfully; only the QtSvg preview is wrong. No mechanical validation rule can catch this (empirically 100% of Cairo clip defs are multi-subpath in affected and visually-fine figures), so the opt-in toggle now carries a tooltip and shows a status-bar caveat steering users back to PNG when rendering looks wrong; the full analysis is in preview.py's design notes.

Reviewer notes

• Merging this triggers semantic-release: the feat commit cuts 1.6.0, which is the version gate Asymmetry's editor integration feature-detects against (gleplot.gui.open_editor present → editor opens in-app; absent → legacy static preview).
• Tests: full suite 1276 passed, 2 skipped (tests/gui/ offscreen). New coverage: tests/gui/test_app.py (9 tests: embedding API, app-identity preservation, GLE-override plumbing/non-persistence, CLI paths, open-after-show ordering, force_close) and reworked tests/gui/test_svg_preview.py (PNG default, opt-in probe, probe-failure fallback, live-render fallback).
• The no-QApplication guard test runs in a subprocess (every in-process test already shares a QApplication).

🤖 Generated with Claude Code