de-shell 0.2.1__tar.gz → 0.3.0__tar.gz

{de_shell-0.2.1 → de_shell-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: de-shell
-Version: 0.2.1
+Version: 0.3.0
 Summary: The Electron + Python desktop-app shell Direct Electron's apps (SpyDE, Ground Crew, Autopilot) are assembled from
 Author-email: Carter Francis <cartsfrancis@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/directelectron/de-shell
 Project-URL: Repository, https://github.com/directelectron/de-shell
 Project-URL: Issues, https://github.com/directelectron/de-shell/issues
-Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.rst
 Keywords: electron,desktop,anyplotlib,electron-microscopy,direct-electron
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
-Requires-Dist: anyplotlib>=0.8.0
+Requires-Dist: anyplotlib>=0.10.0
 Requires-Dist: pyyaml
 Provides-Extra: tests
 Requires-Dist: pytest>=3.6; extra == "tests"
@@ -122,9 +122,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE ([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
-are wired this way, pinned `de-shell>=0.2,<0.3`; Ground Crew still carries a
-copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -149,8 +150,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -190,6 +203,9 @@ SpyDE commit the app copies were taken from:
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.1 → de_shell-0.3.0}/README.md

@@ -87,9 +87,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE ([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
-are wired this way, pinned `de-shell>=0.2,<0.3`; Ground Crew still carries a
-copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -114,8 +115,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -155,6 +168,9 @@ SpyDE commit the app copies were taken from:
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/__init__.py

@@ -20,6 +20,6 @@ from __future__ import annotations
 
 #: The package version — the one place it is written. pyproject.toml reads it
 #: (dynamic version) and the release workflow refuses a tag that disagrees.
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 __all__ = ["ipc", "log_stream", "process_guard", "debug_flags", "compute"]

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/main/pythonEnv.test.ts

@@ -10,9 +10,9 @@
  * Run: `node --test src/pythonEnv.test.ts` (from packages/shell-main/), or via
  * the `test:unit` npm script.
  */
-import { test } from 'node:test'
+import { test, after } from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtempSync, writeFileSync, mkdirSync } from 'fs'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs'
 import { join } from 'path'
 import { tmpdir } from 'os'
 import { configureShell } from './config.ts'
@@ -24,17 +24,29 @@ configureShell({
   pythonModule: 'testapp',
 })
 
+/** Every temp directory these tests make, removed when the file is done. */
+const tempDirs: string[] = []
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix))
+  tempDirs.push(dir)
+  return dir
+}
+
 /** A directory containing a uv stub under both spellings, so these tests do not
  *  fork on the host platform. */
 function dirWithUv(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'uv-stub-'))
+  const dir = tempDir('uv-stub-')
   writeFileSync(join(dir, 'uv'), '')
   writeFileSync(join(dir, 'uv.exe'), '')
   return dir
 }
 
 function emptyDir(): string {
-  return mkdtempSync(join(tmpdir(), 'uv-none-'))
+  return tempDir('uv-none-')
 }
 
 /** An env whose PATH and every fallback root point somewhere we control. */

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/renderer/FigureFrame.tsx

@@ -24,7 +24,7 @@
  * the host page needs `script-src … blob:` for anyplotlib's ESM boot.
  */
 import React, { useEffect, useRef } from 'react'
-import { attachFigure, type FigureBridge } from './figureBridge'
+import { attachFigure, readoutListener, type FigureBridge, type ReadoutInfo } from './figureBridge'
 import { createSizeReporter } from './sizeReporter'
 
 export interface FigureFrameProps {
@@ -37,13 +37,16 @@ export interface FigureFrameProps {
   title?: string
   /** Called with the frame's pixel size whenever it changes. */
   onResize?: (width: number, height: number) => void
+  /** The hover readout, on the shown grid; null when the cursor leaves. Pair it
+   *  with `FigureView.set_readout_visible(False)` to replace the on-image pill. */
+  onReadout?: (info: ReadoutInfo | null) => void
   className?: string
   style?: React.CSSProperties
   'data-testid'?: string
 }
 
 export function FigureFrame({
-  bridge, figId, html, fileUrl, title, onResize, className, style,
+  bridge, figId, html, fileUrl, title, onResize, onReadout, className, style,
   'data-testid': testId,
 }: FigureFrameProps) {
   const ref = useRef<HTMLIFrameElement | null>(null)
@@ -71,6 +74,16 @@ export function FigureFrame({
     return () => ro.disconnect()
   }, [figId])
 
+  // In a ref for the same reason as onResize: an inline prop must not re-run this.
+  const onReadoutRef = useRef(onReadout)
+  onReadoutRef.current = onReadout
+  useEffect(() => {
+    const listen = readoutListener(() => ref.current?.contentWindow,
+                                   (info) => onReadoutRef.current?.(info))
+    window.addEventListener('message', listen)
+    return () => window.removeEventListener('message', listen)
+  }, [figId])
+
   // REGISTRATION IS OWNED BY AN EFFECT, not by the ref callback alone, and it
   // re-registers on every run — see `attachFigure`, which holds the reason and
   // is where the StrictMode double-invoke is pinned by a test.

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/renderer/figureBridge.test.ts

@@ -10,7 +10,7 @@
 import { test, describe } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { attachFigure, createFigureBridge } from './figureBridge.ts'
+import { attachFigure, createFigureBridge, readoutListener } from './figureBridge.ts'
 
 /** A stand-in iframe that records what was posted into it. */
 function fakeIframe(testid = 'frame') {
@@ -245,3 +245,31 @@ describe('attachFigure — the mount lifecycle a figure has to survive', () => {
     assert.equal(bridge.iframes.current.get('f1'), frame.el)
   })
 })
+
+describe('readoutListener — one frame\'s relayed readout', () => {
+  const mine = {} as Window
+  const other = {} as Window
+  const info = { col: 3, row: 4, value: 7.5, exact: true, text: 'x:3  y:4  v:7.5' }
+  const msg = (data: unknown, source: unknown) =>
+    ({ data, source }) as unknown as MessageEvent
+
+  test('the frame\'s readout reaches the host, and null clears it', () => {
+    const heard: unknown[] = []
+    const listen = readoutListener(() => mine, (i) => { heard.push(i) })
+    listen(msg({ type: 'apl_readout', info }, mine))
+    listen(msg({ type: 'apl_readout', info: null }, mine))
+    assert.deepEqual(heard, [info, null])
+  })
+
+  test('another frame\'s readout, another message, or no frame is ignored', () => {
+    // A figure mounted twice: each mount hears only its own iframe.
+    const heard: unknown[] = []
+    readoutListener(() => mine, (i) => { heard.push(i) })(
+      msg({ type: 'apl_readout', info }, other))
+    readoutListener(() => mine, (i) => { heard.push(i) })(
+      msg({ type: 'awi_event', figId: 'f1', data: '{}' }, mine))
+    readoutListener(() => null, (i) => { heard.push(i) })(
+      msg({ type: 'apl_readout', info }, mine))
+    assert.deepEqual(heard, [])
+  })
+})

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/renderer/figureBridge.ts

@@ -90,6 +90,36 @@ export function attachFigure(bridge: FigureBridge, figId: string,
   }
 }
 
+/** The hover readout anyplotlib computes on the SHOWN grid: `col`/`row` index the
+ *  array the figure holds, `value` is its value there. */
+export interface ReadoutInfo {
+  panel_id: string
+  img_x: number
+  img_y: number
+  col: number
+  row: number
+  xdata: number
+  ydata: number
+  units: string
+  value: number | null
+  exact: boolean
+  rgba: number[] | null
+  text: string
+}
+
+/** A window `message` listener passing on the readouts ONE frame relays
+ *  (`fill_iframe_html`'s relay); `null` means the cursor left the image. */
+export function readoutListener(
+  frame: () => Window | null | undefined,
+  onReadout: (info: ReadoutInfo | null) => void,
+): (e: MessageEvent) => void {
+  return (e) => {
+    const src = frame()
+    if (e.data?.type !== 'apl_readout' || !src || e.source !== src) return
+    onReadout(e.data.info ?? null)
+  }
+}
+
 
 export function createFigureBridge(
   log: (label: string, detail: Record<string, unknown>) => void = () => {},

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/renderer/index.ts

@@ -11,7 +11,7 @@
 export {
   createFigureBridge, useFigureBridge, useFigureEventForwarding,
 } from './figureBridge.react'
-export type { FigureBridge, BinaryFrame, RefLike } from './figureBridge'
+export type { FigureBridge, BinaryFrame, RefLike, ReadoutInfo } from './figureBridge'
 
 export { FigureFrame } from './FigureFrame'
 export type { FigureFrameProps } from './FigureFrame'

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/testing/harness.cjs

@@ -30,7 +30,7 @@ function appRequire(name) {
 }
 const { _electron: electron } = appRequire('@playwright/test')
 const { spawnSync } = require('child_process')
-const { mkdtempSync } = require('fs')
+const { mkdtempSync, rmSync } = require('fs')
 const { join } = require('path')
 const { tmpdir } = require('os')
 
@@ -51,6 +51,7 @@ async function launchApp(opts) {
     env = {}, timeout = 60_000,
   } = opts
   if (!appDir || !appId) throw new Error('launchApp needs { appDir, appId }')
+  const profileDir = mkdtempSync(join(tmpdir(), `${appId}-e2e-profile-`))
 
   const app = await electron.launch({
     // Resolve Electron from the APP's tree, not Playwright's. Without an
@@ -63,7 +64,7 @@ async function launchApp(opts) {
     executablePath: require(require.resolve('electron/index.js', { paths: [appDir] })),
     args: [
       join(appDir, 'out', 'main', 'index.js'),
-      `--user-data-dir=${mkdtempSync(join(tmpdir(), `${appId}-e2e-profile-`))}`,
+      `--user-data-dir=${profileDir}`,
     ],
     env: { ...process.env, ...env },
   })
@@ -80,9 +81,9 @@ async function launchApp(opts) {
   for (const type of readyMessages) await backend.waitForMessage(type, timeout)
 
   return {
-    app, page, backend, jsErrors,
+    app, page, backend, jsErrors, profileDir,
     assertNoJsErrors: () => assertNoJsErrors(jsErrors),
-    close: (opts) => closeApp(app, opts),
+    close: (opts) => closeApp(app, { profileDir, ...opts }),
   }
 }
 
@@ -109,23 +110,37 @@ async function firstWindowWithLog(app, logBuffer, timeout = 60_000) {
  * runner's timeout, leaving an Electron tree alive that (for a DE app) still
  * owns the server's single connection — every later launch then hangs on a
  * connection that cannot be made. Returns 'closed' | 'killed' | 'noop' so a
- * caller can log what teardown actually did.
+ * caller can log what teardown actually did. `opts.profileDir` (the launch's
+ * temp profile) is removed once the process is down, on every path.
  */
 async function closeApp(app, opts = {}) {
-  const { timeout = 15_000, killTree = hardKillTree } = opts
-  if (!app) return 'noop'
-  const pid = app.process()?.pid
-  const closed = await new Promise((resolve) => {
-    const timer = setTimeout(() => resolve(false), timeout)
-    timer.unref?.()
-    Promise.resolve()
-      .then(() => app.close())
-      .then(() => { clearTimeout(timer); resolve(true) },
-            () => { clearTimeout(timer); resolve(false) })
-  })
-  if (closed) return 'closed'
-  if (pid) killTree(pid)
-  return pid ? 'killed' : 'noop'
+  const { timeout = 15_000, killTree = hardKillTree, profileDir = null } = opts
+  try {
+    if (!app) return 'noop'
+    const pid = app.process()?.pid
+    const closed = await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(false), timeout)
+      timer.unref?.()
+      Promise.resolve()
+        .then(() => app.close())
+        .then(() => { clearTimeout(timer); resolve(true) },
+              () => { clearTimeout(timer); resolve(false) })
+    })
+    if (closed) return 'closed'
+    if (pid) killTree(pid)
+    return pid ? 'killed' : 'noop'
+  } finally {
+    if (profileDir) removeProfileDir(profileDir)
+  }
+}
+
+/** Remove a launch's temp profile. Retries cover a handle Chromium is still
+ *  letting go of on Windows; a directory that still will not go is left for the
+ *  OS rather than failing the spec's teardown. */
+function removeProfileDir(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })
+  } catch { /* left behind; not the spec's failure */ }
 }
 
 /** Force-kill `pid` AND everything under it (the Python sidecar and its
@@ -240,5 +255,5 @@ async function countColorPixels(page, kind) {
 
 module.exports = {
   launchApp, createBackend, countColorPixels, assertNoJsErrors, errorLines,
-  firstWindowWithLog, closeApp, hardKillTree,
+  firstWindowWithLog, closeApp, hardKillTree, removeProfileDir,
 }

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/js/testing/harness.test.cjs

@@ -15,6 +15,9 @@
  */
 const { test } = require('node:test')
 const assert = require('node:assert/strict')
+const { mkdtempSync, existsSync, writeFileSync } = require('fs')
+const { join } = require('path')
+const { tmpdir } = require('os')
 const { firstWindowWithLog, closeApp } = require('./harness.cjs')
 
 test('a missing first window reports the backend log, not a bare timeout', async () => {
@@ -71,3 +74,30 @@ test('closeApp tolerates a missing app', async () => {
   assert.equal(await closeApp(null), 'noop')
   assert.equal(await closeApp(undefined), 'noop')
 })
+
+/** A stand-in for the launch's --user-data-dir, with something inside it. */
+function fakeProfileDir() {
+  const dir = mkdtempSync(join(tmpdir(), 'harness-test-profile-'))
+  writeFileSync(join(dir, 'Preferences'), '{}')
+  return dir
+}
+
+test('a clean close removes the profile dir', async () => {
+  const profileDir = fakeProfileDir()
+  const app = { process: () => ({ pid: 4242 }), close: async () => {} }
+  assert.equal(await closeApp(app, { timeout: 1000, killTree: () => {}, profileDir }), 'closed')
+  assert.equal(existsSync(profileDir), false, 'profile dir left behind')
+})
+
+test('a hard-killed close removes the profile dir too', async () => {
+  const profileDir = fakeProfileDir()
+  const app = { process: () => ({ pid: 4242 }), close: () => new Promise(() => {}) }
+  assert.equal(await closeApp(app, { timeout: 100, killTree: () => {}, profileDir }), 'killed')
+  assert.equal(existsSync(profileDir), false, 'profile dir left behind')
+})
+
+test('closeApp with no app still removes the profile dir', async () => {
+  const profileDir = fakeProfileDir()
+  assert.equal(await closeApp(null, { profileDir }), 'noop')
+  assert.equal(existsSync(profileDir), false, 'profile dir left behind')
+})

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell/plotting/figure.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import logging
 import warnings
+from collections.abc import Sequence
 
 import numpy as np
 
@@ -140,6 +141,15 @@ PIN_SCROLL = (
     "},{capture:true,passive:true})</script>"
 )
 
+#: Relays anyplotlib's hover readout (`apl:readout`, which fires whether or not
+#: the pill is shown) to the host page, for `FigureFrame`'s `onReadout`.
+#: `info` is null when the cursor leaves the image.
+RELAY_READOUT = (
+    "<script>document.addEventListener('apl:readout',function(e){"
+    "if(parent!==window)parent.postMessage({type:'apl_readout',info:e.detail},'*')"
+    "})</script>"
+)
+
 
 def fill_iframe_html(html: str, *, background: str = FIGURE_BACKGROUND,
                      extra_head: str = "") -> str:
@@ -161,7 +171,8 @@ def fill_iframe_html(html: str, *, background: str = FIGURE_BACKGROUND,
              f"#widget-root{{background:{background} !important;"
              "width:100% !important;height:100% !important;display:block !important}"
              "</style>")
-    return html.replace("<body>", style + PIN_SCROLL + extra_head + "<body>", 1)
+    return html.replace("<body>",
+                        style + PIN_SCROLL + RELAY_READOUT + extra_head + "<body>", 1)
 
 
 class FigureView:
@@ -454,6 +465,19 @@ class FigureView:
             log.debug("set_clim(%s, %s) failed: %s", vmin, vmax, e)
             return False
 
+    def set_readout_visible(self, visible: bool) -> bool:
+        """Show or hide the on-image hover pill. Hidden, the readout still reaches
+        the host through `FigureFrame`'s `onReadout`, so an app can print it in
+        its own units."""
+        if not self.is_open:
+            return False
+        try:
+            self._plot2d.set_readout_visible(bool(visible))
+            return True
+        except Exception as e:
+            log.debug("set_readout_visible(%s) failed: %s", visible, e)
+            return False
+
     def on_event(self, *event_types: str):
         """Register a handler for anyplotlib pointer/key events on this figure.
 
@@ -574,6 +598,61 @@ class FigureView:
                 log.warning("could not observe line widget: %s", e)
         return w
 
+    def add_rectangle_widget(self, *, x: float, y: float, w: float, h: float,
+                             color: str = "#00e5ff", on_change=None,
+                             max_extent=None, show_handles: bool = True,
+                             linewidth: float = 2):
+        """A draggable rectangle overlay. Returns the widget, or None.
+
+        `x, y` is the top-left corner. `max_extent` (a scalar, or
+        `(max_w, max_h)`) stops growth at the cap while a corner is dragged.
+        `on_change(x, y, w, h)` fires when a drag settles.
+        """
+        if not self.is_open:
+            return None
+        try:
+            rect = self._plot2d.add_rectangle_widget(
+                x=float(x), y=float(y), w=float(w), h=float(h), color=color,
+                linewidth=float(linewidth), show_handles=bool(show_handles),
+                max_extent=max_extent)
+        except Exception as e:
+            log.warning("could not add rectangle widget: %s", e)
+            return None
+
+        def _settled(_event, _w=rect):
+            try:
+                if on_change is not None:
+                    on_change(float(_w.x), float(_w.y),
+                              float(_w.w), float(_w.h))
+            except Exception as e:
+                log.debug("rectangle widget callback failed: %s", e)
+
+        if on_change is not None:
+            try:
+                rect.add_event_handler(_settled, "pointer_up")
+            except Exception as e:
+                log.warning("could not observe rectangle widget: %s", e)
+        return rect
+
+    def add_texts(self, offsets, texts, *, name: str | None = None,
+                  color: str | Sequence[str] = "#ffffff", fontsize: int = 12,
+                  fontweight: str = "normal", outline_color: str | None = None):
+        """Text labels at image-pixel positions (top-left anchors). Returns the
+        group, or None. The same `name` again replaces it in place;
+        `remove_widget` drops it. `color` is one colour or one per text.
+        `outline_color` draws a legibility halo.
+        """
+        if not self.is_open:
+            return None
+        try:
+            return self._plot2d.add_texts(
+                offsets, [str(t) for t in texts], name=name, color=color,
+                fontsize=fontsize, fontweight=fontweight,
+                outline_color=outline_color)
+        except Exception as e:
+            log.warning("could not add texts: %s", e)
+            return None
+
     @staticmethod
     def set_widget_geometry(widget, **geometry) -> bool:
         """Move an overlay from Python. Returns whether it landed.

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: de-shell
-Version: 0.2.1
+Version: 0.3.0
 Summary: The Electron + Python desktop-app shell Direct Electron's apps (SpyDE, Ground Crew, Autopilot) are assembled from
 Author-email: Carter Francis <cartsfrancis@gmail.com>
 License: MIT
 Project-URL: Homepage, https://github.com/directelectron/de-shell
 Project-URL: Repository, https://github.com/directelectron/de-shell
 Project-URL: Issues, https://github.com/directelectron/de-shell/issues
-Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.rst
 Keywords: electron,desktop,anyplotlib,electron-microscopy,direct-electron
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
-Requires-Dist: anyplotlib>=0.8.0
+Requires-Dist: anyplotlib>=0.10.0
 Requires-Dist: pyyaml
 Provides-Extra: tests
 Requires-Dist: pytest>=3.6; extra == "tests"
@@ -122,9 +122,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE ([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
-are wired this way, pinned `de-shell>=0.2,<0.3`; Ground Crew still carries a
-copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -149,8 +150,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -190,6 +203,9 @@ SpyDE commit the app copies were taken from:
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.1 → de_shell-0.3.0}/de_shell.egg-info/requires.txt

@@ -1,5 +1,5 @@
 numpy>=1.20.0
-anyplotlib>=0.8.0
+anyplotlib>=0.10.0
 pyyaml
 
 [tests]

{de_shell-0.2.1 → de_shell-0.3.0}/pyproject.toml

@@ -42,7 +42,10 @@ dependencies = [
     # the frame's shape, given a tile source on its zeros placeholder, then
     # painted. On 0.7.3 a state push landing between the open and the first
     # frame could leave the pane showing the placeholder.
-    "anyplotlib>=0.8.0",
+    #
+    # 0.10.0 for the hover readout's `apl:readout` event and `set_readout_visible`
+    # (0.9.0), and `add_texts`' `outline_color` halo (0.10.0).
+    "anyplotlib>=0.10.0",
     "pyyaml",
 ]
 
@@ -56,7 +59,7 @@ tests = [
 Homepage = "https://github.com/directelectron/de-shell"
 Repository = "https://github.com/directelectron/de-shell"
 Issues = "https://github.com/directelectron/de-shell/issues"
-Changelog = "https://github.com/directelectron/de-shell/blob/main/CHANGELOG.md"
+Changelog = "https://github.com/directelectron/de-shell/blob/main/CHANGELOG.rst"
 
 # One version, in one place: de_shell.__version__. The release workflow refuses
 # a tag that does not match it.
@@ -87,3 +90,68 @@ de_shell = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 timeout = 120
+
+# ---------------------------------------------------------------------------
+# Changelog management (towncrier)
+# ---------------------------------------------------------------------------
+# towncrier assembles CHANGELOG.rst from one fragment file per PR, written while
+# the change is fresh. The alternative — deriving notes from commit subjects at
+# release time — reads like a commit log, because that is what it is: it cannot
+# say what a change means to an app upgrading, only what the author was doing.
+# It also stops two pull requests conflicting over the same few changelog lines.
+#
+# `package` is set: this repo's version of record IS de_shell.__version__ (the
+# publish workflow refuses a tag that disagrees with it), so towncrier can read
+# the version itself and `--version` is only needed to build notes for a bump
+# that has not been written yet. See upcoming_changes/README.rst.
+[tool.towncrier]
+package          = "de_shell"
+package_dir      = "."
+directory        = "upcoming_changes"
+filename         = "CHANGELOG.rst"
+start_string     = ".. towncrier release notes start\n"
+issue_format     = "`#{issue} <https://github.com/directelectron/de-shell/pull/{issue}>`_"
+title_format     = "{version} ({project_date})"
+underlines       = ["=", "-", "~"]
+
+# Behaviour changes lead the notes: they are the entries an app upgrading has
+# to ACT on, and they are easy to miss filed under "Bug Fixes".
+[[tool.towncrier.type]]
+directory    = "api_change"
+name         = "API and Behaviour Changes"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "new_feature"
+name         = "New Features"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "bugfix"
+name         = "Bug Fixes"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "performance"
+name         = "Performance"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "deprecation"
+name         = "Deprecations"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "removal"
+name         = "Removals"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "doc"
+name         = "Documentation"
+showcontent  = true
+
+[[tool.towncrier.type]]
+directory    = "maintenance"
+name         = "Maintenance"
+showcontent  = true

{de_shell-0.2.1 → de_shell-0.3.0}/tests/test_figure.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import numpy as np
 import pytest
 
-from de_shell.plotting.figure import FigureView, robust_levels
+from de_shell.plotting.figure import FigureView, fill_iframe_html, robust_levels
 
 
 class TestRobustLevels:
@@ -156,3 +156,84 @@ class TestTileQuantisationBand:
     def test_small_frame_stays_untiled_and_unaffected(self):
         v, _ = self._open_and_show((64, 64))
         assert not v._plot2d._state.get("tile_enabled")
+
+
+class TestOverlays:
+    """Widgets and labels on a real, open figure."""
+
+    @staticmethod
+    def _open():
+        v = FigureView(0, title="t")
+        v.open((64, 64))
+        return v
+
+    def test_a_rectangle_carries_its_geometry_style_and_cap(self):
+        w = self._open().add_rectangle_widget(
+            x=1, y=2, w=3, h=4, color="#123456", max_extent=10,
+            show_handles=False, linewidth=1)
+        assert (w.x, w.y, w.w, w.h) == (1.0, 2.0, 3.0, 4.0)
+        assert w.color == "#123456" and w.linewidth == 1.0
+        assert w.show_handles is False and (w.max_w, w.max_h) == (10.0, 10.0)
+
+    def test_a_rectangle_reports_where_a_drag_settles(self):
+        heard = []
+        w = self._open().add_rectangle_widget(
+            x=1, y=2, w=3, h=4, on_change=lambda *g: heard.append(g))
+        w._update_from_js({"x": 5.0, "y": 6.0}, "pointer_move")
+        assert heard == []                    # once per drag, not per frame
+        w._update_from_js({"w": 7.0, "h": 8.0}, "pointer_up")
+        assert heard == [(5.0, 6.0, 7.0, 8.0)]
+
+    def test_a_rectangle_moved_from_python_lands_without_a_callback(self):
+        heard = []
+        w = self._open().add_rectangle_widget(
+            x=1, y=2, w=3, h=4, on_change=lambda *g: heard.append(g))
+        assert FigureView.set_widget_geometry(w, x=9, y=9, w=5, h=5)
+        assert (w.x, w.y, w.w, w.h) == (9.0, 9.0, 5.0, 5.0) and heard == []
+
+    def test_a_rectangle_on_a_closed_figure_is_none(self):
+        assert FigureView(0).add_rectangle_widget(x=0, y=0, w=1, h=1) is None
+
+    def test_a_refused_rectangle_is_none_and_a_warning(self, monkeypatch, caplog):
+        v = self._open()
+
+        def boom(**_kw):
+            raise RuntimeError("boom")
+
+        monkeypatch.setattr(v._plot2d, "add_rectangle_widget", boom)
+        assert v.add_rectangle_widget(x=0, y=0, w=1, h=1) is None
+        assert "rectangle" in caplog.text
+
+    def test_texts_are_drawn_and_a_name_replaces_them_in_place(self):
+        v = self._open()
+        v.add_texts([[4, 5]], ["edge (auto)"], name="labels",
+                    outline_color="#000000")
+        g = v.add_texts([[6, 7]], ["noise"], name="labels")
+        texts = v._plot2d.markers["texts"]
+        assert len(texts) == 1 and g._data["texts"] == ["noise"]
+        v.remove_widget(g)
+        assert "labels" not in texts
+
+    def test_texts_accept_one_colour_per_text(self):
+        v = self._open()
+        g = v.add_texts([[4, 5], [6, 7]], ["a", "b"],
+                         color=["#ff0000", "#00ff00"])
+        assert g._data["color"] == ["#ff0000", "#00ff00"]
+
+    def test_texts_on_a_closed_figure_are_none(self):
+        assert FigureView(0).add_texts([[0, 0]], ["x"]) is None
+
+
+class TestReadout:
+    def test_the_pill_can_be_hidden_for_the_host_to_draw_its_own(self):
+        v = FigureView(0)
+        v.open((64, 64))
+        assert v.set_readout_visible(False) is True
+        assert v._plot2d._state["readout_visible"] is False
+
+    def test_hiding_the_pill_on_a_closed_figure_is_a_no_op(self):
+        assert FigureView(0).set_readout_visible(False) is False
+
+    def test_every_figure_frame_relays_its_readout_to_the_host(self):
+        head = fill_iframe_html("<head></head><body></body>").split("<body>")[0]
+        assert "apl:readout" in head and "apl_readout" in head