qmlmathplot 0.3.0__tar.gz → 0.4.1__tar.gz

{qmlmathplot-0.3.0 → qmlmathplot-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qmlmathplot
-Version: 0.3.0
+Version: 0.4.1
 Summary: Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)
 Author: I-AM-A-NOOB
 Author-email: I-AM-A-NOOB <suzc08@outlook.com>
@@ -126,6 +126,15 @@ PlotView {                       // inject a Plot, or let the component create i
 }
 ```
 
+For a standalone view with no injected model, the curve is explicit:
+
+```qml
+PlotView { defaultExpression: "sin(x)"; anchors.fill: parent }
+```
+
+There is no hidden default curve: the component creates its own empty `Plot` when none is
+injected, and `defaultExpression` is the only way it adds one.
+
 `PlotView` exposes `mapToScreen(x, y)` / `mapFromScreen(point)` plus the forwarders
 `camera` and `curves`; input handling (pan by left-drag, wheel zoom anchored at the cursor)
 is built in and switchable through `camera.panEnabled` / `camera.zoomEnabled`.
@@ -134,8 +143,9 @@ The model:
 
 | Object | Members |
 |---|---|
-| `Plot` | `camera`, `curves`, `xlim`/`ylim`/`aspect` (forwarded), `add_curve()` / `add_implicit()` / `remove_curve()`, `available_themes`, and the style properties: `background`, `grid`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `axis_color`, `axis_width`, `axes_position`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `font_size`, `tick_font_size`, `title`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
-| `Camera` | `centre`, `zoom` (world units per logical pixel), `aspect`, `xlim`/`ylim` (derived), `ticks_x`/`ticks_y`, `zoomStep` / `panEnabled` / `zoomEnabled`, slots `setViewport(w, h)` / `zoom_by(delta, u, v, w, h)` / `pan_pixels(dx, dy)` / `reset()` |
+| `Plot` | `camera`, `curves`, `xlim`/`ylim`/`aspect` (forwarded), `add_curve()` / `add_implicit()` / `remove_curve()`, `available_themes`, and the style properties: `background`, `grid`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `axis_color`, `axis_width`, `axes_position`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `font_size`, `tick_font_size`, `title`, `xlabel`, `ylabel`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
+| `Camera` | `centre`, `zoom` (world units per logical pixel), `aspect`, `xlim`/`ylim` (derived), `ticks_x`/`ticks_y`, `zoomStep` / `panEnabled` / `zoomEnabled`, `animationDuration`, `input` (a `ViewInput`), slots `set_viewport(w, h)` / `zoom_by(delta, u, v, w, h)` / `zoom_at(factor, u, v, w, h)` / `pan_pixels(dx, dy)` / `animate_zoom(...)` / `animate_pan(dx, dy, ms)` / `stop_animation()` / `reset()` |
+| `ViewInput` | `keyboardEnabled`, `keyPanStep`, `keyPanRepeatInterval`, `panLeftShortcut` / `panRightShortcut` / `panUpShortcut` / `panDownShortcut` / `zoomInShortcut` / `zoomOutShortcut`, `matches(key, modifiers, shortcut)` |
 | `Curve` | `expression` (string or sympy expression), `expr` (the parsed expression, read-only), `implicit`, `color`, `lineWidth`, `visible`, `label`, `error` (read-only), the baked `vertexShader` / `fragmentShader` |
 | `CurveListModel` | the curves as a model (`curve`, `expression`, `color`, `lineWidth`, `visible`, `vertexShader`, `fragmentShader` roles) so QML puts one `ShaderEffect` behind each |
 
@@ -150,11 +160,75 @@ QTimer.singleShot(1000, lambda: setattr(curve, "expression", "sin(3/x)"))
 
 The design — the camera model, the Qt property/signal contract, the object model and the
 build order — is specified in [`docs/api-design.md`](docs/api-design.md). In short: the
-Matplotlib *vocabulary* is kept where it is vocabulary (limits, grid, title, ticks, annotate),
-while the *mechanism* is refused — no `Figure`/`Axes`/`subplots` (one view per widget, no
-bounded page), no `FigureCanvas`/`draw()` (the scene is live), no toolbar and no legend (host
-chrome), and an export is a canvas region at a pixel size rather than a re-rendered page
-(§9, implemented — see *Export* below).
+Matplotlib *vocabulary* is kept where it is vocabulary (limits, grid, title, ticks), while the
+*mechanism* is refused — no `Figure`/`Axes`/`subplots` in the core (one view per widget, no
+bounded page), no redraw loop (the scene is live), no toolbar and no legend (host chrome), and
+an export is a canvas region at a pixel size rather than a re-rendered page (§9, implemented —
+see *Export* below). A **thin compatibility facade** (`Figure`, `Axes`, `FigureCanvasQt`,
+`qmlmathplot.pyplot`) provides the familiar names for porting scripts; it maps onto the same
+model and refuses the mechanisms that do not fit (see *Matplotlib-style facade* below).
+
+## Matplotlib-style facade
+
+For porting scripts and for code that expects Matplotlib's vocabulary, the package ships a
+**thin** compatibility layer. It maps onto the same `Plot`/`Camera` model and refuses the
+mechanisms that do not fit an infinite, live canvas.
+
+```python
+from qmlmathplot import Figure, FigureCanvasQt
+
+fig = Figure(figsize=(6.4, 4.8))       # stored for the window size only; no page is implied
+ax = fig.gca()                         # exactly one axes per figure
+ax.plot("sin(1/x)", label="sin(1/x)")
+ax.set_xlim(-1, 1)
+ax.set_ylim(-2, 2)
+ax.set_title("sin(1/x)")
+ax.set_xlabel("x")
+ax.set_ylabel("y")
+ax.grid(True)
+ax.set_aspect("equal")
+
+canvas = FigureCanvasQt(fig)           # a QWidget, like MathPlotWidget
+layout.addWidget(canvas)
+canvas.draw()                          # no-op: the Qt scene is already live
+```
+
+The same model through a pyplot-shaped module (global current figure, for scripts and
+notebooks; applications should keep the object API):
+
+```python
+import qmlmathplot.pyplot as plt
+
+plt.figure()
+plt.plot("sin(1/x)")
+plt.xlim(-1, 1)
+plt.title("sin(1/x)")
+plt.xlabel("x")
+plt.grid(True)
+plt.savefig("out.png")                 # Qt raster export
+plt.show()                             # blocks in a script; use block=False in a host
+```
+
+What maps: one figure/one axes (`subplots()` and `subplot(111)`), `plot(expression)`,
+`xlim`/`ylim`, `title`/`xlabel`/`ylabel`, `grid`, `aspect`, `savefig`/`to_image`, themes.
+`plt.gcf()`/`gca()`/`sca()`/`close()`/`show()` follow Matplotlib's current-figure shape.
+
+What is deliberately different:
+
+- **One view per figure.** `subplots(2, 1)`/`add_subplot(211)` raise `NotImplementedError`;
+  several panels are several `Figure` objects in a Qt layout, not a `GridSpec`.
+- **Expressions, not x/y arrays.** `ax.plot("sin(x)")` is native; `ax.plot(x, y)` is refused
+  because the Qt renderer evaluates an expression per pixel. For sampled data use
+  `Plot.to_matplotlib()` (the hand-off), or add a data-series artist.
+- **`draw()` / `draw_idle()` are no-ops.** The scene repaints from model signals; there is no
+  deferred renderer or blitting.
+- **`savefig` is a region at a pixel size**, not a page at a dpi. `width`/`height` are device
+  pixels and `dpi` is a multiplier; `backend="matplotlib"` is the vector route.
+- **No legends, annotations, log axes or manual ticks yet.** `legend()`, `annotate()`,
+  `set_xscale()` and `set_xticks()` raise with the reason; chrome belongs to the host.
+- **Themes are per figure**, not `rcParams`; `plt` has no global style state beyond the current
+  figure.
+- **`mpl_connect`/`blit` are absent.** Qt signals are the event system.
 
 ## Implicit curves
 
@@ -165,25 +239,52 @@ and `add_implicit` asks for the level-set artist explicitly — also for a funct
 which is a pair of vertical lines. Only a *third* free symbol is refused: substitute parameters
 first.
 
+A sympy `Eq(lhs, rhs)` is always a level set: it is normalized to `lhs - rhs = 0`, and an
+equation with only `x` still means the vertical lines where it holds (`Eq(x**2, 1)`), not
+`y = x**2 - 1`. The canonical `expression` keeps the `Eq(...)` text and `expr` is the normalized
+difference.
+
 ```python
+x, y = sp.symbols("x y")
 plot.add_curve("x**2 + y**2 - 1")        # a circle: {x, y} routes to the level-set artist
-plot.add_implicit("x*y - 1")             # the same artist, asked for by name
+plot.add_curve(sp.Eq(x**2 + y**2, 1))    # the same circle in equation form
+plot.add_implicit(sp.Eq(x, sp.sin(y)))   # asked for by name, equation form
 plot.curves.at(0).expression = "x**2 + y**2 - 4"   # re-routes the curve that is already there
 plot.add_curve("a*sin(x)")               # ValueError: substitute `a` first
 ```
 
 The renderer is the same idea as the 1-D stroke, one dimension up: one evaluation of `F` and its
-two partials per pixel give the distance to the level set in *pixels*,
-`d = |F| / sqrt((Fx·dx)² + (Fy·dy)²)`, and the coverage is `clamp(lineWidth/2 + 0.5 - d, 0, 1)` —
-analytic antialiasing and a stroke width that does not depend on the angle, with no sampling grid
-(the unit circle measures the same 3 device pixels at 0°, 45°, 90° and 135° for `lineWidth=2` at
-DPR 1.5).
-
-Known limit: **smooth, single-sheet level sets**. Thin features and several branches through one
-pixel (`sin(1/(x*x + y*y))`), and 2-D domains/poles, are not handled yet — the assessment is
-`docs/api-design.md` §6b; pixels where `F` is undefined are dropped. The matplotlib hand-off
-skips implicit curves (a level set has no polyline to sample), while the Qt export renders them
-like anything else.
+two partials per pixel give a *candidate* distance to the level set in pixels,
+`d = |F| / sqrt((Fx·dx)² + (Fy·dy)²)`, and the coverage is
+`clamp(lineWidth/2 + 0.5 - d, 0, 1)` — analytic antialiasing and a stroke width that does not
+depend on the angle, with no sampling grid (the unit circle measures the same 3 device pixels at
+0°, 45°, 90° and 135° for `lineWidth=2` at DPR 1.5).
+
+That quotient is a pseudo-zero at a pole and at a diverging domain boundary, so it is
+**certified by projecting onto the level set**: two damped Newton steps from the pixel (or, for
+a pixel outside the domain, from the nearest in-domain sample), accepting only a converged
+residual (`|F| <= 0.25·R·|grad F|`) and using the distance to the projected point. The domain
+therefore clips the *curve*, not the stroke: the half of the band lying outside is painted, so
+`x-log(y-1)` does not thin out as it approaches `y = 1` and `y-log(x)` reaches `x = 0` in a deep
+view. A `POLE(x,y)` factor (e.g. `cos(y)` for `tan(y)`) rejects a normal probe that crosses a
+singularity, so `x-tan(y)` does not paint its asymptotes; far-out garbage lines are still
+refused (the stroke is allowed one radius outside the domain, no more).
+
+The pixel is also a **marching-squares cell**, borrowed from GeoGebra's
+`ImplicitCurveMarchingRect`/`AdaptiveQuadTree`: the four corner values are evaluated when every
+corner is in the domain and no pole factor changes sign between them; the edge crossings are
+interpolated and the cell's contour segment is stroked (the saddle case is paired using the cell
+centre's sign). The first-order/Newton path still supplies the sub-pixel width; the cell term
+adds the coverage of a thin or tangent branch whose centre projection fails. A **singular cell**
+(`|Fx| + |Fy| < 1e-3` in world units, plus `|F| < 0.05`) gets a small disc, so an isolated point
+such as `x**2 + y**2 = 0` is not left to the projection alone.
+
+Still not ported: GGB's Bernstein subdivision (**polynomial-only**), its adaptive quad-tree
+refinement and the `ContourAssembler`/`ContourLinker` (they exist to produce a selectable vector
+path, not to rasterise). A closed loop that fits entirely inside one pixel with no corner sign
+change is not seen by the four-corner test; the projection is the only fallback there. The
+matplotlib hand-off skips implicit curves (a level set has no polyline to sample), while the Qt
+export renders them like anything else.
 
 ## The camera (centre, zoom, aspect)
 
@@ -209,6 +310,38 @@ plot.aspect = "auto"                              # back to following the widget
 plot.plot.camera.zoom_by(120, 0.5, 0.5, w, h)     # one wheel notch, anchored at the centre
 ```
 
+## Keyboard, touch and animation
+
+Clicking the plot gives it focus; while it has focus the arrow keys pan (10% of the viewport
+per press by default), `+`/`=` zooms in and `-`/`_` zooms out. Held keys advance continuously:
+one `keyPanStep` per `keyPanRepeatInterval` (100 ms by default), integrated every frame, so
+there is no OS key-repeat delay or granular stepping. Several arrows combine, so `Left+Up`
+moves diagonally at the normal speed. Every command is a property on the camera's `input`
+object, so a host can rebind it — the value is a `QKeySequence` string, and `|` separates
+alternatives (empty disables the command). `input.keyPanStep`, `input.keyPanRepeatInterval`,
+`input.keyboardEnabled`, `panEnabled` and `zoomEnabled` shape the behaviour the same way.
+
+```python
+camera = plot.plot.camera
+input = camera.input
+input.panLeftShortcut = "A"           # rebind one arrow
+input.panRightShortcut = "D"
+input.zoomInShortcut = "Ctrl+="
+input.zoomOutShortcut = "Ctrl+-"
+input.keyPanStep = 0.2                # 20% of the viewport per step
+input.keyPanRepeatInterval = 80       # ms per step; smaller = faster pan/zoom
+camera.animationDuration = 220        # ms; tap easing
+```
+
+Wheel and keyboard moves are **eased** (scale interpolates geometrically, so a zoom feels like
+a constant rate); repeated wheel notches accumulate onto the in-flight target instead of
+restarting from the last frame. Mouse drags and touch gestures are deliberately direct — the
+pointer or the fingers are the animation.
+
+Touch is built in: one finger pans, two fingers pinch to magnify and pan together, keeping the
+world point under the finger centroid. They need no focus and work in both embedding modes;
+like the mouse, they cancel an in-flight eased move as soon as they start.
+
 ## Themes
 
 `Plot.theme` applies a style sheet to the style properties above; the default is
@@ -325,16 +458,21 @@ conversion) and `mpl.py` (the sampled hand-off) import no Qt at all** — they a
 without a `QApplication`. `Camera`, `Curve` and `Plot` are the **ViewModel**: `QObject`s whose
 `Property`es carry notify signals, which is precisely what the QML component binds to — and why
 a Python-side assignment updates the view with no call in between. `view.py`, `PlotView.qml`,
-`export.py` and `widget.py` are the View/embedding layer and do need Qt; `export.py` and
-`widget.py` import QtWidgets lazily, so a pure-QML host never loads it.
+`export.py`, `widget.py` and `canvas.py` are the View/embedding layer and do need Qt; the last
+three import QtWidgets lazily, so a pure-QML host never loads it.
 
 | Layer | File | Responsibility |
 |---|---|---|
 | Model | `src/qmlmathplot/model.py` | expression → GLSL, shader source template (no Qt dependency, unit-testable) |
 | Camera | `src/qmlmathplot/camera.py` | `Camera`: centre / zoom / aspect, the derived ranges, pan/zoom/reset, the nice-number tick algorithm |
-| Curves | `src/qmlmathplot/curve.py` | `Curve` (expression → baked `.qsb`, style, error) and `CurveListModel` |
+| Input | `src/qmlmathplot/input.py` | `ViewInput`: keyboard switch, pan step, rebindable shortcuts, key matching |
+| Animation | `src/qmlmathplot/animation.py` | `CameraAnimator`: the one eased interpolator behind wheel/keyboard moves |
+| Curves | `src/qmlmathplot/curve.py` | `Curve` (expression → baked `.qsb`, style, error; later edits bake on the thread pool) and `CurveListModel` |
 | Plot | `src/qmlmathplot/plot.py` | `Plot`: the camera, the curves and the styling the view binds to |
-| View | `src/qmlmathplot/qml/PlotView.qml` (+ `view.py`) | QML: background, grid, ticks/title, one `ShaderEffect` per curve, pan/zoom input; `view.py` registers the types and yields the component path |
+| Facade | `src/qmlmathplot/figure.py` | `Figure` / `Axes`: Matplotlib-shaped names over one `Plot` (no Qt beyond the model) |
+| Facade host | `src/qmlmathplot/canvas.py` | `FigureCanvasQt`: a `MathPlotWidget` attached to a `Figure` (QtWidgets, lazy) |
+| Facade scripting | `src/qmlmathplot/pyplot.py` | `qmlmathplot.pyplot`: current figure, `plot`/`xlim`/`show`/`savefig` for scripts |
+| View | `src/qmlmathplot/qml/PlotView.qml` (+ `PlotCurves.qml`, `PlotFurniture.qml`, `PlotInput.qml`, `view.py`) | composition: model injection, camera mapping and keyboard focus; curves, furniture and pointer input live in the three child components (one `ShaderEffect` per curve) |
 | Themes | `src/qmlmathplot/themes.py` + `themes/` | the vendored Matplotlib style sheets, resolved onto the `Plot`'s properties |
 | Export | `src/qmlmathplot/export.py` | `Plot.savefig()` / `to_image()`: the canvas region rendered offscreen at a pixel size (QtWidgets is imported lazily) |
 | Hand-off | `src/qmlmathplot/mpl.py` | `Plot.to_matplotlib()` / `to_sympy()` / `savefig(backend="matplotlib")`: a sampled second renderer for vector output (matplotlib is an optional extra, imported lazily) |
@@ -343,24 +481,60 @@ a Python-side assignment updates the view with no call in between. `view.py`, `P
 | Entry | `src/qmlmathplot/app.py` | command line / standalone window (the `qmlmathplot` script, `examples/minimal.py`) |
 | Examples | `examples/` | `minimal.py` (minimal), `explorer_qtwidgets.py` (input box + widget coexistence), `explorer_qtquick.py` (Qt Quick) |
 
-## Algorithm (the two pieces that make it visually "perfect")
-
-1. **Screen-space distance stroke**: for every pixel, compute its first-order
-   distance to the curve from `f` and `f'`,
-   `cov = clamp(lineWidth/2 + 0.5 − d, 0, 1)`. Equal width at any slope, naturally
-   antialiased, and correct by construction at poles (`tan(x)`) and jumps.
-2. **Undersampled envelope band**: when a pixel's x interval holds several
-   oscillations (local period < 1 pixel), the per-pixel distance is meaningless
-   (it renders as moiré). In that case the column's `[min, max]` is filled as a
-   solid band — for `sin(1/x)` this equals filling its true ±1 envelope.
-
-Both criteria are **scale-independent** and are unioned: (a) ≥ 2 direction
-reversals within the column (8 sample points for an ordinary pixel, topped up to 16
-inside the band region); (d) the derivative prediction `|f'|·dx` far exceeds the
-measured spread (hard threshold 16× and `pred ≥ 4px`). One gate: a spread < 1.5 px
-is not filled (do not turn peak ripple into a block of colour). An ordinary pixel
-costs 1 `f` + 1 `f'` + 8 narrow-window samples; the wide window (±8 columns, 16
-points) is only evaluated inside the band region.
+## Algorithm (fixed-x sampled polyline + the interval column)
+
+The supported path is GeoGebra's column idea implemented on the GPU: sample the function on a
+sub-pixel x grid, stroke the polyline, and fill the exact interval enclosure where a column
+cannot be represented by a line.
+
+1. **Sub-pixel polyline stroke.** Each pixel evaluates `F` at **16 samples over ±2 columns**
+   (0.25 logical-px spacing). Adjacent valid samples form a polyline, and coverage is
+   `R - distance to the nearest segment` — Desmos' stroke rule. The sample spacing is
+   sub-pixel, so the vertices themselves are sub-pixel and the segments are diagonal: the
+   edge is smooth at any zoom, not a per-column staircase. ±2 columns (rather than the old
+   ±1) cover the perpendicular foot, which a steep line displaces along x by up to the
+   stroke radius; measured `k·x` 3.00/3.00/3.00/2.94 device px at screen slopes
+   2/10/40/200 against a nominal 3.0.
+2. **Pole/jump segment guard.** A segment is skipped when the expression's pole factor
+   changes sign between its endpoints (`POLE(prev_x) * POLE(xi) <= 0`) — the branches of
+   `tan`/`1/x` never join across a pole — and, for a dependent quotient such as
+   `x/sqrt(x**2)`, when the endpoint jump exceeds the join radius. The flat branches are
+   still drawn; measured `x/sqrt(x**2)` draws its ±1 branches without the old 454-px
+   connector at x = 0.
+3. **Interval topology — GeoGebra's column rules on the GPU.** The expression is evaluated
+   in interval arithmetic over the pixel's column (generated from sympy in `interval.py`,
+   compiled to the GLSL `IVal FI(xlo, xhi)`): a conservative y-enclosure with topology
+   **connected / two rays around a gap / whole / empty**. The shader reproduces the reference
+   plotter's rules:
+   - **connected, sub-column oscillation** (`smoothstep(1.5, 3.0, sturns)`): GeoGebra's
+     `DrawInterval.drawJoined` path — the vertical join at `x.low` and the diagonal across
+     the column, choosing `drawUp`/`drawDown` from the high edge; an independent column is a
+     vertical at `x.high`. These are **strokes**, not a filled rectangle.
+   - **divergence** (`log`'s boundary): `IntervalPath.drawNormalInfinity` →
+     `leftToBottom`/`leftToTop`, only when the finite bound is on screen: one segment from
+     `(x.low, finite bound)` to `(x.middle, viewport edge)`. If the interval covers the
+     viewport but the finite bound is above/below it (the deep `log` view), the column is
+     effectively `whole` and gets `drawWhole` (a vertical at `x.low`) — an extension needed
+     because the Java branch draws nothing there although the visible curve lies inside the
+     column.
+   - **inverted** (`tan`/`1/x` poles): `DrawInvertedInterval` — the top segment at `x.high`
+     from the viewport top to the gap's high, the bottom at `x.low` from the gap's low to the
+     viewport bottom; no filled ray.
+   - **whole**: `DrawInterval.drawWhole` — one vertical segment at `x.low`.
+   Deliberate deviations, because this is a fragment shader and not the Java tuple list: the
+   16-sample polyline supersamples GGB's one interval per column for resolved stretches; a
+   dependent quotient's whole column is still suppressed (the fixed-x polyline draws the real
+   branches, avoiding the `x/sqrt(x**2)` connector); and a joined inverted column uses those
+   sample branches instead of replaying `JoinLines.inverted`'s neighbour decisions.
+4. **Domain.** `DOM`/`DOMS` (from sympy) guard every `F` evaluation, so `log(negative)` is
+   never evaluated; a pixel just outside the domain still gets the band, which is centred
+   on the boundary.
+
+An ordinary pixel costs **16 `F` evaluations** plus two interval evaluations; there is no
+march, no tangent-foot projection and no column probe on the supported path. Expressions
+with an operation the interval backend does not implement (`floor`, `sign`, …) compile the
+legacy sampled band + ray + march path (`#define USE_INTERVAL 0`); it is the only user of
+the arc-length march now.
 
 ## Tests
 
@@ -368,6 +542,7 @@ points) is only evaluated inside the band region.
 uv run pytest                      # everything
 uv run pytest -m "not gui"         # skip the render smoke tests that open a window
 QSG_RHI_BACKEND=opengl uv run pytest -m gui
+uv run ruff check src tests examples   # bug-level lint (undefined names, unused imports)
 ```
 
 - `test_model.py`: GLSL generation (small integer powers as repeated
@@ -379,14 +554,19 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
   setters are idempotent, and the list model reports the right roles — plus the
   `Expr`/string round-trip accounting (a string is parsed once, an expression never).
 - `test_implicit.py`: the routing by free symbols (and the `ValueError` for a third symbol), the
-  level-set shader text (same uniform block as the 1-D one, no sampling loop), and the rendered
-  geometry of a unit circle: crossings a quarter of the height from each edge, a blank middle,
-  radius 1 on both axes, and a stroke of the same width at 0°/45°/90°/135°.
+  level-set shader text (same uniform block as the 1-D one, no sampling loop), the rendered
+  geometry of a unit circle (crossings a quarter of the height from each edge, a blank middle,
+  radius 1 on both axes, and a stroke of the same width at 0°/45°/90°/135°), and the two
+  domain/pole guards: `x-tan(y)` has no connector at its poles or far pixels in a wide view,
+  `x-log(y-1)` keeps its stroke on both sides of `y = 1`, and `y-log(x)` reaches the axis in a
+  deep view.
 - `test_plot.py`: the plot's properties convert, notify exactly once and are wired
   (a PySide property with an unresolved notify name silently loses it), the defaults are
   matplotlib's default style, the limits are forwarded to the camera, and a theme applies
   (and re-applies as a reset) while an unknown name is rejected.
 - `test_themes.py`: the vendored style sheets resolve to this library's properties.
+- `test_qsb_cache.py`: the cache location/info/clear API and the age + LRU prune; unrelated
+  files in the temp directory are not touched.
 - `test_shader_bake.py`: the stage of a baked `.qsb` must match its purpose, and
   the four backend targets GLSL/HLSL/MSL/SPIR-V must all be covered.
 - `test_render_smoke.py`: open a window, render, read pixels; verify the thin-line
@@ -410,6 +590,12 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
   `.pdf` and `.png`; `to_sympy().save()` writes a file and keeps per-curve colours; importing
   `qmlmathplot` does not import matplotlib, and hiding matplotlib produces an error naming the
   extra.
+- `test_async_bake.py`: a later expression assignment bakes on the thread pool, a stale bake
+  is discarded, and a failed bake keeps the drawn curve.
+- `test_compat.py`: the Matplotlib-shaped facade — expressions (and the refusal of x/y arrays),
+  limits/title/labels/grid/aspect, the single-axes rule, `pyplot` current-figure semantics,
+  `FigureCanvasQt` rendering and export, and that importing `qmlmathplot` does not load
+  QtWidgets.
 - `test_export.py`: `to_image()`/`savefig()` — the image is exactly the requested device size
   (`dpi` multiplies it), the no-argument form reproduces the live centre and scale, the three
   `adjustable` modes reconcile range and size as documented (a world 45-degree line stays at 45
@@ -418,78 +604,63 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
 
 ## Pitfalls near the `sin(1/x)` singularity (fixed — do not repeat)
 
-All of them (macro arguments, GPU `sin`/`cos`, stroke saturation on steep columns,
-per-column phase noise) are recorded in `AGENTS.md` as symptom → cause → fix with
-the measurements that settled them. After the fixes (1350×900, default view, D3D11
-and OpenGL pixel-for-pixel identical): the singularity column of `sin(1/x)` is lit
+All of them (macro arguments, GPU `sin`/`cos`, the fixed-x-grid sampling era's stroke
+saturation, per-column phase noise, the jump-discontinuity connector) are recorded in
+`AGENTS.md` as symptom → cause → fix with the measurements that settled them. After
+the fixes (900×600 logical, default view): the singularity column of `sin(1/x)` is lit
 over a ratio of 0.50 (= half a column filling the ±1 envelope) with flat edges, and
-inside the central 41 columns no solid pixel falls outside |y|>1 (7961 before).
+inside the central 41 columns no solid pixel falls outside |y|>1 (7961 before the
+envelope band existed).
 
 - Macro arguments must be parenthesized.
 - GPU `sin`/`cos` are unreliable for large arguments.
 - Tangent-based distance saturates on steep columns.
 - Per-column sampling is phase noise for oscillating functions.
+- The **join invariant** replaces pole detection: tangent-foot seeding and arc-length
+  marching, so a connector of *any* origin (poles, jumps) cannot be formed
+  (`AGENTS.md` item 44).
 
 ## Domain, poles and stroke (Desmos-style)
 
 [Desmos's engineering blog](https://engineering.desmos.com/articles/press-a-key-in-the-calculator/)
 spells it out: **sample** the function into points, join them into **segments**,
-stroke along the segments; "break where neighbouring points suggest a jump"; refine
-extrema/zeros by bisection. The same approach is used here:
-
-- **Stroke = distance to the sampled polyline segments** (not to the tangent). The
-  tangent approximation overestimates the distance on steep or strongly curved
-  parts, so the stroke thins out or even fades away (`log(x)` as x→0+, the steep
-  stretch of `sin(1/x)`); measuring to the segment is **equal width everywhere**.
-  Sampled over ±1 column: the polyline must be wide enough that a pixel's
-  perpendicular foot lands on a segment (on a sloped line it is displaced along x
-  by `m·d/√(1+m²)`); with a narrower window the distance degraded to "distance to
-  the nearest endpoint" and steep parts looked thin and ragged.
-- **Break on jumps**: a denominator sign change (world units) decides, in three places,
-  that nothing joins the branches — the polyline segment that straddles the pole is not
-  stroked, a straddling pair does not count as a turn in the band's turn count (it used to
-  fill the pole column solid), and the unbounded-boundary ray is not drawn there. No vertical
-  connector at the asymptotes of `1/x`, `tan(x)`. (An earlier "adjacent samples differ by
-  more than 4 viewport heights" criterion was pixel-/viewport-relative, so under magnification
-  it also cut legitimate steep segments; it was removed. The remaining "spread beyond 32
-  viewport heights" gap is a second line of defence only — at `tan`'s pole column the spread
-  is ~15 viewports, so it never fires there.)
-- **Domain** (derived by sympy, injected as `DOM`): denominator ≠ 0, `log` argument
-  > 0, `sqrt` argument ≥ 0, `asin/acos` argument ∈ [−1,1]; pixels outside the domain
-  are discarded outright — except for the **boundary ray** of a slowly diverging edge
-  (`log(x)` as x→0+), which is a band centred *on* the boundary and therefore paints the few
-  pixels outside the domain that it covers (the whole outer half of that band, otherwise).
-  NaN/inf samples take part in neither the envelope nor segment joining.
-- **Undersampled columns** (several oscillations inside one column) are replaced
-  wholesale by the envelope band: a polyline is random sawtooth in such columns.
-  There are two criteria, both **scale-independent**: (a) ≥ 2 direction reversals
-  within the column — 8 points in the narrow window for an ordinary pixel, and
-  inside the band region 8 additional interleaved points make it 16 (with 8 points,
-  random sampling misses the reversals in ~11% of columns, showing up as residual
-  vertical stripes; sampling 16 points globally would cost 8 extra `f` evaluations
-  for every pixel, not worth paying for a few columns); (d) the distance `pred` a
-  column should traverse according to the derivative far exceeds the measured
-  `spread` (hard threshold 16×, and `pred ≥ 4px`) — sub-pixel oscillation sampling
-  necessarily misses reversals (it may even come out monotone), and this criterion
-  does not depend on sampling randomness. Pixel-unit gates are avoided here (a
-  spread measured in pixels stops being meaningful once the viewport is deep);
-  poles are handled by the analytic gap instead.
-- **Infinite extension at unbounded domain boundaries** (`unbounded_edges()`, sympy
-  one-sided limits): `log(x)` **diverges slowly** (logarithmically) as x→0+, so a
-  fixed-width sampling window never reaches deep enough values — in a deep viewport
-  the visible curve lies at x≈e^y (e.g. for y∈[-16,-12], x∈[1e-7,6e-6]), while the
-  leftmost sample only reaches log≈-7, so the **whole segment disappears**. Fix:
-  when the window crosses such a boundary, extend the polyline along the boundary x
-  into a vertical ray out to ±1e12, which draws at any depth (the ray lies on the
-  boundary x, so the width is constant and the columns align; the x<0 half is cut
-  away by the domain, leaving exactly half a stroke visible). `1/x` and `tan(x)`
-  diverge fast, so their sampled values naturally exceed any viewport and no ray is
-  needed; `sqrt` (limit 0) and `sin(1/x)` (no limit) are not on the list either.
-
-Measured: the steep stretch of `log(x)` has a constant horizontal width of 1~2
-device pixels (previously a tapering gradient); the thin line of `sin(1/x)` is
-uniform in width; `1/x` and `tan(x)` are not connected across their poles;
-`sin(x)`/`x^2`/`exp(-x²)sin(10x)` are unaffected.
+stroke along the segments; "break where neighbouring points suggest a jump". The same
+approach, with the sampling made uniform in *arc length* (the march above):
+
+- **Stroke = distance to the joined polyline segments** (not to the tangent), plus the
+  stroked **column segments** for what the march cannot reach: a pixel also measures the
+  vertical y-range of the two neighbouring columns and strokes it with the same ramp. That
+  is GeoGebra's per-column segment with a vector line width, on the GPU; a steep wall
+  (`1/x`/`tan` at large |y|, `log`'s descent) keeps its nominal width even though its x span
+  is narrower than a pixel and its march seed is a whole view up the arc.
+- **Break on jumps — by construction, not by detection**. The join invariant (a segment
+  only joins samples within 2.5 px) refuses a connector of any origin: the poles of
+  `1/x`/`tan(x)` and plain jump discontinuities alike (`x/sqrt(x**2)` had no pole
+  denominator for the old guards to find; measured: a 454-px column at x=0). The
+  interval band does not reintroduce one: a dependent quotient (`x/sqrt(x**2)`) is left to
+  the march, and a sign-changing pole (`tan`, `1/x`) is a gap or a `whole` column, not a
+  chord.
+- **Domain** (derived by sympy, injected as `DOM` for the scalar march): denominator ≠ 0,
+  `log` argument > 0, `sqrt`/even-root ≥ 0 (a negative power also excludes 0), `asin/acos`
+  ∈ [−1,1], `x**(1/3)` all reals. The *interval* evaluator is authoritative for the band:
+  it returns empty outside the domain, `[-∞, log h]` at a `log` boundary, and the half-open
+  values at a root endpoint. A pixel just outside the boundary is painted from the stroke
+  footprint (`x ± R`) and the neighbouring column segments — not by a symbol-derived ray.
+  The legacy ray remains only in the fallback shader (`USE_INTERVAL 0`).
+- **Undersampled columns** use the interval enclosure of the pixel's column: no ±8-column
+  window, no violation count, no chord-stroke. The midpoint probe survives only as an
+  **interval-dependency check** for a wide finite column (`x * 1/[a,b]` overestimation);
+  the band and the neighbour column segments are always the exact interval ranges.
+
+Measured: `sin(1/x)`'s transition overfill went from 1.66 to **0.0099 world units**
+(threshold-20 pixels; the remaining edge is the stroke/AA radius); `x**(1/3)` draws both
+branches; the `log(x)` descent measures **3.00 device px at every sampled row** without the
+ray; `1/x`/`tan(x)` in a y∈[50,60] view are **3 full columns** (2 before the neighbour
+segments); `x/sqrt(x**2)` still draws no connector (worst column 4 px); `k·x` holds one
+width at every slope (the slope test at 2/10/40/200); `tan(x)` at an enormous y span fills
+the screen (the interval is `whole`, matching GeoGebra); `sin(x)`/`x^2`/`exp(-x²)sin(10x)`
+are unaffected.
+
 
 ## Performance (measured)
 
@@ -500,13 +671,55 @@ Startup to the first frame is about **230 ms**, attributed as follows
 |---|---|---|
 | Qt graphics device init (RHI/D3D11) | **~160 ms** | exactly what the first window's `show→expose` costs; a **bare window (no ShaderEffect) is the same**, so it is not the shader's fault |
 | Window creation + QML load + first frame | ~80 ms | from the second window on (device already created) this is the order of magnitude |
-| `qsb` bake | 0 / ~126 ms | cached by source hash: 0.15 ms on a hit; after a source change (code edit) it must re-bake once |
+| `qsb` bake | 0 / ~126 ms | cached by source hash: 0.15 ms on a hit; later `expression` assignments bake on Qt's thread pool, so only the first curve construction blocks (tests force the synchronous path) |
 | Expression analysis (sympy) | 0.6~3 ms | `unbounded_edges` only analyses **polynomial** boundaries (`tan(x)`'s `cos(x)=0` takes 94 ms via solve+limit, while tan diverges fast and sampling is naturally deep enough, so that ray is not needed) |
 
-Per-frame GPU cost (2400×1500, extreme zoom, worst case) is **31 ms**; about 1/7 of
-that at 900×600, far below the 16.7 ms of 60 Hz. The shader source is about 6.9 KB.
-Every visible curve is one full-screen fragment pass, so `Curve.visible` is the lever
-when a figure carries many of them.
+Per-frame grab cycles (900×600, `grabToImage` — frame + readback, so an upper bound on
+the GPU cost), steady state on the same window: `sin(1/x)` default **13.6 ms**, `tan(x)`
+default **12.4 ms**, `sin(1/x)` at zoom 90 (worst case) **12.5 ms**. The previous
+march/interval renderer measured 27/34/33 ms on the same machine: 16 samples are cheaper
+than the march's seed + tangent projection + walk + probe, and the march is now compiled
+only for the legacy path. The 1-D fragment source is about 21 KB.
+
+**Per-pixel `F` evaluations.** The supported path is fixed: 16 samples for the polyline
+(plus two interval evaluations for the column and the stroke footprint); there is no
+march budget and no band-window evaluation. The old fixed-grid/march table is superseded
+and no longer describes the shipped path.
+
+## Shader cache
+
+`qsb` binaries are cached in the platform temp directory:
+
+```python
+import qmlmathplot
+
+qmlmathplot.cache_dir()    # e.g. C:\Users\me\AppData\Local\Temp\qmlmathplot-qsb
+qmlmathplot.cache_info()   # {'path': ..., 'files': ..., 'bytes': ...}
+qmlmathplot.clear_cache()  # remove this package's entries, returns bytes freed
+```
+
+The location is `tempfile.gettempdir()/qmlmathplot-qsb`: `%TEMP%` on Windows, the per-user
+`/var/folders/.../T` on macOS, and `$TMPDIR` or `/tmp` on Linux. Set
+`QMLMATHPLOT_QSB_CACHE` to use another directory.
+
+**It is not left to grow without bound.** The first bake in a process, and at most once per
+minute afterwards, runs `prune_cache()`:
+
+- entries older than **30 days** are removed;
+- if the cache is over **32 MiB** (default), the least-recently-used `.qsb` files are removed
+  until it is at 75% of the cap — so an existing 60 MB cache drops to about 24 MB on the next
+  bake;
+- interrupted-bake leftovers (`*.qsb.tmp`, `*.vert`, `*.frag`) older than an hour are removed.
+
+Both knobs are overridable: `QMLMATHPLOT_QSB_CACHE_MB` (size cap) and
+`qmlmathplot.prune_cache(max_bytes=..., max_age_days=...)` for an explicit pass. The cache
+contains compiled shaders only; the GLSL source and temporary outputs are deleted after each
+bake. Concurrent processes share the directory safely: writes use unique temp names and an
+atomic replace, and pruning only removes entries by age/LRU.
+
+On macOS/Linux `qsb` is looked up in the PySide6 package (`Qt/bin`, `Qt/libexec`) and on
+`PATH`; if the wheel does not ship it, install Qt Shader Tools (`qt6-shadertools` on most
+distributions) or add `qsb` to `PATH`. Only the Windows wheel has been confirmed to ship it.
 
 ## Pitfalls already hit (do not repeat)
 
@@ -521,9 +734,11 @@ measurement that settled each one). The Qt/packaging ones that shaped the code:
   same x 9 times, and macros are preprocessor expansion with no call semantics.
 - PySide ties a property's notify signal to the `Signal` **object**; a name string
   silently leaves the property without one (and QML bindings then never refresh).
-- Snap **hairlines** (grid) to a half pixel, but never a **styled** line: rounding the
-  axis position put the 1.07 px y-axis half off the centre column, so the line came out
-  pale where it should be black.
+- Screen-space furniture is QML: background `Rectangle`, grid `Canvas`, axes/ticks
+  `Rectangle`s, labels/title `Text`; curves are `ShaderEffect` passes. Snap its lines to
+  **device** pixels with an integral device width (`_deviceWidth`/`_snapLine`), not logical
+  half-pixels: the 1.07-logical axis is 2 device px at DPR 1.5 and otherwise alternated
+  between one and two rows as it drifted with the zoom.
 - `QQuickWidget.setProperty(name, …)` sets it on the **widget**, not on the QML root (the
   widget has no such property, so it silently does nothing): inject the model with
   `widget.rootObject().setProperty("plot", plot)`, as `MathPlotWidget` does.