plesty-sdk 0.3.5.dev1__tar.gz → 0.4.0__tar.gz

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/CHANGELOG.md

@@ -2,6 +2,176 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com).
 
+## [Unreleased]
+
+## [0.4.0] — 2026-09-07
+
+A scaffolded device can now be driven by hand. `plesty init device` generates a
+`--gui` entry point that opens the module's control panel — every control built
+from the device schema, nothing hand-written — as an alternative to serving the
+instrument, so a new module is usable at the bench before anyone writes a client
+for it. Qt rides in a `gui` extra, so a headless bench that only ever serves the
+device pays nothing for the window it never opens. Generated projects pin
+`plesty-lib>=0.4.0`, the release `plesty.lib.ui` begins at.
+
+### Added
+- **A scaffolded device offers its control panel.** `plesty init device` now
+  generates `--gui` in the module's `__main__.py`: it opens plesty-lib's
+  `DevicePanel` over a `LocalHandle` on the instrument in this process, as an
+  alternative to serving it — both want the one session the instrument grants,
+  so `main()` does one or the other. Nothing about the window is hand-written;
+  the controls, their bounds, units and tooltips come from the device schema, so
+  a parameter added there appears in the panel.
+
+  The generated `open_panel()` calls `connect()` **before** the panel is built.
+  That ordering is the point of the entry point rather than an implementation
+  detail: what the instrument reports on connection narrows the schema's
+  device-wide envelope to the unit in front of the operator, and those are the
+  bounds worth typing into. On a PM100D the fitted head answers 400–1100 nm
+  against the 185–25000 nm the schema declares for every head.
+
+  Qt lands in a new `gui` extra (`plesty-lib[gui]`), not in `dependencies` — a
+  headless bench serves the device and never opens a window — and the
+  `plesty.lib.ui` import is local to `open_panel`, so serving pulls no toolkit.
+  Every module used to hand-add this entry point; `plesty-pm100d` was the last
+  to do it by hand.
+
+- The device template's note on `kind` now says what declaring `lifecycle` does
+  beyond the field test: an operation whose effect outlives the call is kept off
+  a control panel — the local one and the one a remote client renders. The
+  schema is the only place either can learn it.
+
+### Changed
+- `PLESTY_LIB_VERSION`, the `plesty-lib` floor a scaffold falls back to when
+  PyPI is unreachable, moves `0.3.6` → `0.4.0`. That is the release
+  `plesty.lib.ui` begins at, so it is the floor the generated `--gui` needs;
+  below it the panel path raises `ImportError`. The live PyPI lookup already
+  resolved 0.4.0 on any machine with a route out — this only changes the
+  offline case.
+
+### Fixed
+- **The pre-push hook no longer leaks git's hook variables into the gates.**
+  Git exports `GIT_DIR` and friends into every hook, and everything the hook
+  runs inherits them, so git work nested inside the gates resolves the pushing
+  repository instead of the one it is standing in. The hook now clears them
+  before running `plesty check`; nothing about what the gates check changes.
+
+  Two failures this had already caused. Gate 10 has pip clone each git-pinned
+  dependency into a temp directory, where versioningit read the outer
+  repository's tag and commit — on lightfield_spectrometer (2026-09-04) a
+  pinned `plesty-lib` came out as `0.1.0.dev65+<the module's sha>`, which
+  cannot satisfy the module's own floor, so the audit failed with a resolution
+  error unrelated to the code. That is enough to make anyone drop the pin
+  rather than debug it, and a dropped pin is a module quietly building against
+  the wrong dependency. Separately, a test suite that drives git could commit
+  into the real repository rather than its fixture, which is what made pushing
+  this repo from a worktree unsafe.
+
+  Existing modules keep the old hook until `plesty init` is re-run; the fix is
+  a one-line `unset` in `.git/hooks/pre-push` for anyone who does not want to.
+
+## [0.3.6] — 2026-09-03
+
+Everything the scaffolds generate now passes the gates the scaffolds ask for.
+Two generated files failed a check the SDK itself enforces — a field-test
+client with an import nothing used, and entry points on an event loop that
+Python 3.16 will not give them — and the version picker no longer strands a
+reader on a release it cannot leave. Generated projects pin `plesty-lib>=0.3.6`.
+
+### Fixed
+- Generated device and experiment entry points start through
+  `plesty.lib.service.run_server` instead of a bare `asyncio.run`. The bare
+  call worked on Windows only because importing `plesty.lib.service` installed
+  a global event-loop policy — deprecated in Python 3.14 (two warnings per
+  server start on benches already there) and removed in 3.16, where the entry
+  point would get a `ProactorEventLoop` and fail inside pyzmq for want of
+  `add_reader`. The `plesty-lib` pin floor moves to 0.3.6, the first release
+  carrying `run_server`. Existing modules keep working on 3.14 and 3.15 and
+  pick the swap up when they regenerate.
+- `plesty init field-test` no longer writes a client whose imports fail the
+  module's own lint gate. A module reached through its `DocDevice` — or through
+  any construction taking no arguments — gets a bare factory, and the generated
+  `tests/field_test_client.py` imported `functools.partial` anyway: F401, so
+  `plesty check` could not pass on a module that had just been field-tested.
+  The import is now emitted only in the branch that calls `partial`. Both
+  branches are linted in the tests; neither was before, because every fixture
+  probed into the "no hardware-free construction" path.
+  Generating against released 0.3.3 has a worse form of the same block — it
+  emits the `partial` import but not the device import, leaving `SPAWN_FACTORY`
+  an undefined name (F821). Add the `from plesty.<module> import <factory>`
+  line by hand, or regenerate once this ships.
+- The version picker no longer offers a version the reader cannot switch back
+  out of. A release built before the Read-the-Docs theme has no sidebar for the
+  picker to mount on and cannot be stamped, yet the manifest still listed it —
+  on the SDK's own docs, selecting 0.1 stranded the reader. The manifest now
+  advertises only releases that carry the picker; such a release stays
+  published and reachable at its own URL, and `/releases/` still redirects to
+  the newest one that exists. Stamping consequently runs before the manifest is
+  written, so the manifest sees the final state of every tree.
+- A module with no releases rendered a dropdown holding a single entry. The
+  picker now appears only when there is something to pick between.
+
+## [0.3.5] — 2026-08-24
+
+Documentation gains a version picker, and the two things standing between it
+and the published sites are fixed: the docs-deploy gate had been skipped since
+2026-08-21 behind a failing test collection, and releases built before the
+picker existed had no way back to the current docs.
+
+### Added
+- Every module's documentation carries a **version picker** in the sidebar.
+  Each module already deployed `latest/` from its default branch and
+  `releases/<major>.<minor>/` from each tag, but nothing linked them: a reader
+  on the release docs could not reach any other version. The picker is fed by
+  `versions.json`, fetched at page load rather than baked in — a page built
+  months ago cannot know which versions exist today. Switching versions keeps
+  the current page when the target has it, and falls back to that version's
+  index when it does not (pages come and go between releases). A deployment
+  without a manifest — a local `plesty docs serve` preview — renders no picker
+  at all.
+
+### Fixed
+- The version picker is no longer a one-way trip. Releases published before it
+  existed are never rebuilt, so switching to one landed the reader on pages
+  with no picker and no way back. Each deploy now stamps the picker's two
+  assets and the tags referencing them into any release tree that lacks them.
+  Only the `<head>` gains anything — the prose, the API reference and the
+  stylesheets a historical release was built with are untouched, which is why
+  the picker's styling moved out of `plesty-hub.css` into its own
+  `plesty-versions.css`. Idempotent, so re-running over a stamped tree does
+  nothing. A release predating the Read-the-Docs theme (plesty-sdk 0.1) has no
+  sidebar to mount on and is skipped.
+- The test suite no longer fails to collect in CI. `plesty-lib` is declared in
+  a `dev` dependency group: `tests/test_mock_test_scaffold.py` drives the
+  mock-test scaffold against a real `plesty.lib.sim.demo_device.DemoDevice`,
+  which it subclasses and runs, but nothing installed the library on a runner —
+  so `hub-check` had been failing with `ModuleNotFoundError: No module named
+  'plesty.lib'`, which in turn skipped `hub-deploy-docs` and froze the
+  published documentation. It is a group rather than a runtime dependency:
+  installing plesty-sdk must not pull the library it scaffolds modules for.
+- `versions.json` entries were origin-absolute (`"/0.3/"`), so they resolved
+  against the host rather than the module root, and the `releases/` redirect
+  stub built from them has been broken since it was written — on
+  docs.plesty.net it pointed at `docs.plesty.net/0.3/`. The manifest moves to
+  the module root, lists `latest` alongside the releases, and its URLs are
+  relative to that root, which is `/<slug>/` on docs.plesty.net and
+  `/<group>/<project>/` on GitLab Pages.
+
+### Changed
+- Both deploy modes rewrite the manifest, not only `--release`. This is what
+  gives a module that has never been tagged a picker, and what migrates
+  branches deployed by an older SDK — including their `.gitlab-ci.yml`, which
+  was previously written once at branch creation and never updated again.
+- The Pages job publishes the whole `html/` tree instead of `html/latest`, so
+  the releases the picker lists are reachable there too, and `html/index.html`
+  redirects the Pages root to `latest/`. The layout now matches what
+  docs.plesty.net already serves, so one picker runs unchanged on both.
+  **Deep links to `plesty.gitlab.io/<group>/<project>/<page>.html` move under
+  `/latest/`**; docs.plesty.net URLs are unaffected. The reference link
+  `plesty check` prints on a failing gate followed that move, so it now points
+  at docs.plesty.net — the site readers are sent to, and the one whose path is
+  independent of how Pages lays the tree out.
+
 ## [0.3.5.dev1] — 2026-08-21
 
 Development pre-release: the tutorial needs the pin option before 0.3.5 is

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plesty-sdk
-Version: 0.3.5.dev1
+Version: 0.4.0
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team, Yunshuang Yuan, Christopher Borchers, fvrehlinger, Maximilian Heller, Michael Zopf
 License-Expression: LGPL-3.0-or-later
@@ -55,10 +55,14 @@ plesty init device --author "Jane Doe" --email jane@example.com
 
 # 2. Develop your module — the pre-push hook runs compliance checks automatically
 
-# 3. Run the full [SDK] compliance check manually at any time
+# 3. Drive the instrument from a control panel built out of your device schema
+uv sync --extra gui
+python -m plesty.power_meter --gui
+
+# 4. Run the full [SDK] compliance check manually at any time
 plesty check
 
-# 4. Preview the documentation locally
+# 5. Preview the documentation locally
 plesty docs serve
 ```
 

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/README.md

@@ -23,10 +23,14 @@ plesty init device --author "Jane Doe" --email jane@example.com
 
 # 2. Develop your module — the pre-push hook runs compliance checks automatically
 
-# 3. Run the full [SDK] compliance check manually at any time
+# 3. Drive the instrument from a control panel built out of your device schema
+uv sync --extra gui
+python -m plesty.power_meter --gui
+
+# 4. Run the full [SDK] compliance check manually at any time
 plesty check
 
-# 4. Preview the documentation locally
+# 5. Preview the documentation locally
 plesty docs serve
 ```
 

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/docs/architecture.md

@@ -187,6 +187,21 @@ have already diverged. The cost is a coupling to the component's ref and input c
 a rename or ref change in plesty-ci breaks scaffolds (see technical debt below) — which we
 accept because centralised evolution has proven far cheaper than fleet-wide file surgery.
 
+**A generated device carries its own control panel, with Qt in an extra.** A device can be
+reached two ways — served over TCP for a client to drive, or opened in a window on the
+machine it is plugged into — and the scaffold generates the second as `--gui` on the module's
+existing entry point rather than shipping a separate console or leaving each module to
+hand-write one. The controls are derived from the device schema, so a module gets a usable
+window the moment its schema is right, and it is the same serialized `describe` payload a
+remote client renders: a hole in the payload surfaces at the bench instead of only across a
+network. Operations are filtered by their declared `kind`, which makes the schema the single
+place that decides what a panel offers, local or remote. Qt lives in a generated `gui` extra
+rather than in the generated `dependencies` — a headless bench serves the device and never
+opens a window — which is why `plesty.lib.ui` is imported inside the panel path and not at
+module scope. The tradeoff is that the two modes are alternatives rather than layers: both
+claim the single session most instruments grant, so a module cannot serve and show a local
+panel at the same time.
+
 **`plesty update --install-hook` for cloned projects.** Git hooks live in `.git/` and are
 never cloned, so `plesty init`'s pre-push hook silently vanishes for every contributor
 after the first. Rather than adopting a hook-manager dependency (pre-commit) or committing

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/docs/commands/check.md

@@ -146,7 +146,7 @@ failures and their guidance always print:
     Error: [Coverage] total coverage 62% below threshold
     This gate verifies: the pytest suite passes with at least 80% line coverage.
     How to fix: Reproduce with 'uv run pytest --cov=plesty' and add tests ...
-    Reference: https://plesty.gitlab.io/core/plesty-sdk/commands/check.html
+    Reference: https://docs.plesty.net/plesty-sdk/latest/commands/check.html
 ```
 
 ## Examples

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/docs/commands/init.md

@@ -184,6 +184,38 @@ python -m plesty.foo_bar --host 10.0.0.5 --tcp-port 6000   # CLI overrides env
 variables, so one `.env` drives both the server and the tests. It is skipped unless
 `DEVICE_HOST` is set.
 
+## The control panel (device only)
+
+The same entry point opens the device's control panel instead of serving it:
+
+```bash
+uv sync --extra gui
+python -m plesty.foo_bar --gui
+```
+
+Serving and `--gui` are alternatives — both want the one session the instrument
+grants, so `main()` does one or the other. The panel is
+[`plesty.lib.ui.DevicePanel`](https://gitlab.com/plesty/core/plesty-lib) over a
+`LocalHandle`, which builds every control from the device schema; a parameter
+added to the schema appears in the window with no GUI code written. The
+generated `open_panel()` calls `connect()` **before** the panel is built,
+because it is what the instrument reports on connection — a fitted sensor head's
+wavelength range, say — that narrows the schema's device-wide envelope to the
+unit in front of the operator.
+
+Operations are filtered by their `kind`: one whose effect outlives the call is
+declared `@expose_to_api(kind="lifecycle")`, and that keeps it off this panel
+*and* off the one a remote client renders, since the schema is the only place
+either can learn it.
+
+Qt goes in a `gui` extra rather than in `dependencies` — a headless bench serves
+the device and never opens a window:
+
+```toml
+[project.optional-dependencies]
+gui = ["plesty-lib[gui]>=0.4.0"]
+```
+
 ## Rig start-up and the shared disk (experiment only)
 
 The generated `__main__.py` does not open device clients itself. It declares

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/docs/getting-started.md

@@ -35,6 +35,23 @@ Use `--standard` to choose the compliance standard the generated CI pipeline enf
 (default `pixel` — a fresh scaffold is a prototype; bump it alongside your releases), or
 `--no-ci` to omit the CI file entirely.
 
+### Running what you scaffolded
+
+A device module's entry point does one of two things, and they are alternatives —
+both want the one session the instrument grants:
+
+```bash
+python -m plesty.power_meter --tcp-port 5555   # serve it for clients to drive
+uv sync --extra gui
+python -m plesty.power_meter --gui             # drive it yourself, in a window
+```
+
+The panel is built from the device schema, so the parameters and operations you
+declare are the controls you get — there is no GUI code to write. Qt lives in the
+`gui` extra, so a headless bench that only ever serves the device never installs
+it. See [`plesty init`](commands/init.md) for how the panel picks up an
+instrument's real limits, and which operations it leaves out.
+
 ## 2. Check compliance
 
 Navigate into the project and run the compliance checker:

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/gl-secret-detection-report.json

@@ -7,7 +7,7 @@
       "vendor": {
         "name": "GitLab"
       },
-      "version": "7.38.1"
+      "version": "7.39.0"
     },
     "scanner": {
       "id": "gitleaks",
@@ -19,19 +19,19 @@
       "version": "8.30.1"
     },
     "type": "secret_detection",
-    "start_time": "2026-08-21T18:31:49",
-    "end_time": "2026-08-21T18:31:49",
+    "start_time": "2026-09-07T14:07:04",
+    "end_time": "2026-09-07T14:07:04",
     "status": "success",
     "observability": {
       "events": [
         {
           "event": "collect_secrets_analyzer_scan_metrics_from_pipeline",
-          "time_s": 0.480570925,
+          "time_s": 0.467099461,
           "exit_code": 0,
           "git_strategy": "FetchShallow",
-          "repo_size_kb": 468,
+          "repo_size_kb": 500,
           "commit_count": 1,
-          "bytes_scanned": 136,
+          "bytes_scanned": 1215,
           "pipeline_type": "Tag"
         },
         {
@@ -40,7 +40,7 @@
           "passthrough_types": null,
           "passthrough_count": 0,
           "passthrough_auth_used": false,
-          "rules_version": "0.25.0"
+          "rules_version": "0.25.1"
         }
       ]
     }

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/check/guidance.yaml

@@ -1,6 +1,8 @@
 # Per-gate failure guidance echoed by `plesty check` (issue sdk#26).
 # Keys match the gate keys used in check_command; text is plain CLI prose.
-docs_url: https://plesty.gitlab.io/core/plesty-sdk/commands/check.html
+# docs.plesty.net, not the Pages mirror: it is the site readers are sent to,
+# and its /<slug>/latest/ path is unaffected by how Pages lays the tree out.
+docs_url: https://docs.plesty.net/plesty-sdk/latest/commands/check.html
 
 gates:
   metadata:

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/docs-build-gitlab-ci.yml

@@ -4,7 +4,7 @@ pages:
   stage: deploy
   rules:
     # The gate for creating the job, not a selector of what is published —
-    # `publish: html/latest` below uploads the whole directory. exists
+    # `publish: html` below uploads the whole directory. exists
     # matches FILE globs: the bare directory path "html/latest/" stopped
     # matching on gitlab.com between 2026-07-21 and 2026-08-10, every
     # docs-build pipeline failed with "no jobs", and Pages froze while the
@@ -14,4 +14,8 @@ pages:
   script:
     - echo "Serving documentation on GitLab pages..."
   pages:
-    publish: html/latest
+    # The whole tree, not just html/latest: the sidebar version picker needs
+    # versions.json and the releases/ it lists to be reachable from the same
+    # site. html/index.html forwards the Pages root to latest/, and the layout
+    # then matches docs.plesty.net, where the same picker runs unchanged.
+    publish: html

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/hub-theme/plesty-hub.css

@@ -24,6 +24,8 @@
 
 /* The sidebar header keeps the stock Read-the-Docs styling. */
 
+/* The version picker styles itself from plesty-versions.css. */
+
 /* Schema shields → soft rounded pills. */
 .rst-content .sd-badge {
   border-radius: 999px;

plesty_sdk-0.4.0/plesty/sdk/assets/hub-theme/plesty-versions.css

@@ -0,0 +1,49 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Plesty Development Team
+ * SPDX-FileContributor: Yunshuang Yuan
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * Styling for the sidebar version picker (plesty-versions.js).
+ *
+ * Separate from plesty-hub.css because it is also stamped into release docs
+ * built before the picker existed. Those trees carry their own copy of
+ * plesty-hub.css, and replacing it would change how a historical page looks
+ * beyond adding the dropdown; dropping one more file in beside it does not.
+ */
+
+/* Sits at the foot of the sidebar header, under the search box. Added by the
+ * script, so a deployment without a versions.json shows no empty slot. */
+.wy-side-nav-search .plesty-versions {
+  margin: 0.75rem 0 0;
+  text-align: left;
+}
+.wy-side-nav-search .plesty-versions label {
+  display: block;
+  margin-bottom: 0.3rem;
+  color: #d9d9d9;
+  font-size: 80%;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+.wy-side-nav-search .plesty-versions select {
+  width: 100%;
+  padding: 0.3rem 0.5rem;
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 4px;
+  background: rgba(0, 0, 0, 0.2);
+  color: #fff;
+  font-size: 90%;
+  cursor: pointer;
+}
+.wy-side-nav-search .plesty-versions select:focus {
+  /* Plesty cyan, spelled out: the historical trees this file is stamped into
+     carry a plesty-hub.css from before the custom property existed. */
+  border-color: #0891b2;
+  outline: none;
+}
+/* The dropdown list itself renders in the OS palette, not the sidebar's —
+   without this the options are white-on-white on most platforms. */
+.wy-side-nav-search .plesty-versions option {
+  color: #404040;
+  background: #fff;
+}

plesty_sdk-0.4.0/plesty/sdk/assets/hub-theme/plesty-versions.js

@@ -0,0 +1,110 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Plesty Development Team
+ * SPDX-FileContributor: Yunshuang Yuan
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * Version picker for the Read-the-Docs sidebar.
+ *
+ * Every module is deployed as a tree of independently built docs — `latest/`
+ * from the default branch, `releases/<major>.<minor>/` from each tag — under
+ * one module root, and `versions.json` at that root lists them. A page built
+ * months ago cannot know which versions exist today, so the list is read at
+ * page load rather than baked in at build time.
+ *
+ * The module root is not derivable from the URL: docs.plesty.net serves the
+ * tree at /<slug>/ and GitLab Pages at /<group>/<project>/. It is derived
+ * from this script's own location instead — the file is always at
+ * <docs-root>/_static/plesty-versions.js, and `data-root-prefix` (set by
+ * sphinx_builder) is the hop from the docs root up to the module root.
+ */
+(() => {
+  // Read synchronously: document.currentScript is null once the DOM is ready.
+  const script = document.currentScript;
+  if (!script) return;
+  const rootPrefix = script.dataset.rootPrefix;
+  const current = script.dataset.version || "latest";
+  if (!rootPrefix) return;
+
+  const docsRoot = new URL("../", script.src);
+  const moduleRoot = new URL(rootPrefix, docsRoot);
+  // Page path within this version's docs, carried across when the target
+  // version has the same page.
+  const pagePath = decodeURIComponent(location.href.slice(docsRoot.href.length));
+
+  const label = (version) =>
+    version === "latest" ? "latest (development)" : version;
+
+  /* Navigate to `path` under `target`, falling back to the target's index
+     when the page does not exist there — pages come and go between versions,
+     and a picker that lands on a 404 is worse than one that lands on a
+     landing page. A HEAD request that cannot run at all (file:// origin)
+     falls back the same way. */
+  const goTo = async (target, path) => {
+    const home = new URL(target, moduleRoot);
+    if (!path) {
+      location.assign(home);
+      return;
+    }
+    const exact = new URL(path, home);
+    try {
+      const response = await fetch(exact, { method: "HEAD" });
+      location.assign(response.ok ? exact : home);
+    } catch {
+      location.assign(home);
+    }
+  };
+
+  const render = (versions) => {
+    const container = document.querySelector(".wy-side-nav-search");
+    if (!container) return;
+
+    const picker = document.createElement("div");
+    picker.className = "plesty-versions";
+
+    const caption = document.createElement("label");
+    caption.textContent = "Version";
+    caption.htmlFor = "plesty-version-select";
+    picker.appendChild(caption);
+
+    const select = document.createElement("select");
+    select.id = "plesty-version-select";
+    for (const entry of versions) {
+      const option = document.createElement("option");
+      option.value = entry.url;
+      option.textContent = label(entry.version);
+      option.selected = entry.version === current;
+      select.appendChild(option);
+    }
+    // The running version is missing from versions.json when this build has
+    // not been indexed yet (a local preview, a tag mid-deploy). Show it so the
+    // picker never reads as if the reader were somewhere else.
+    if (!versions.some((entry) => entry.version === current)) {
+      const option = document.createElement("option");
+      option.textContent = label(current);
+      option.selected = true;
+      option.disabled = true;
+      select.insertBefore(option, select.firstChild);
+    }
+    select.addEventListener("change", () => goTo(select.value, pagePath));
+    picker.appendChild(select);
+
+    // Below the search box, so the picker does not push the search field out
+    // of its usual place under the logo.
+    container.appendChild(picker);
+  };
+
+  const ready = (run) =>
+    document.readyState === "loading"
+      ? document.addEventListener("DOMContentLoaded", run)
+      : run();
+
+  fetch(new URL("versions.json", moduleRoot))
+    .then((response) => (response.ok ? response.json() : null))
+    .then((versions) => {
+      // Nothing to pick between — no manifest (a local `plesty docs serve`
+      // preview), or a module with no releases yet, whose manifest holds only
+      // `latest`. A dropdown with one entry is furniture, not navigation.
+      if (Array.isArray(versions) && versions.length > 1) ready(() => render(versions));
+    })
+    .catch(() => {});
+})();

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/init/next-steps.yaml

@@ -13,6 +13,7 @@ device:
   - "Expose your custom operations with @expose_to_api and declare what each one does (kind=motion/acquire/lifecycle/control/configure) — the field test drives them by kind instead of asking you about every call."
   - "Copy .env.example to .env and set DEVICE_HOST/DEVICE_PORT (never commit .env)."
   - "Try it live: uv run python -m plesty.{module_name} --tcp-port 5555."
+  - "Or drive it by hand: uv sync --extra gui, then uv run python -m plesty.{module_name} --gui — the control panel is built from your schema, so every parameter and operation you declare shows up in it."
 
 analyzer:
   - "Declare your input/output schemas and implement analyze() in plesty/{module_name}/analyzer.py."

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/templates/extras/device/device.py

@@ -58,3 +58,9 @@ class Device(BaseDevice):
     ## motion is driven one `step` out from what `position_key` reports and put
     ## back, a lifecycle operation runs once, a control operation once at rest
     ## after the motions, and a configure operation is never called.
+    ##
+    ## The field test is not the only reader. An operation whose effect
+    ## outlives the call — homing, zeroing an offset, a reset — is declared
+    ## `lifecycle`, and that is what keeps it off a control panel: the one
+    ## `--gui` opens here, and the one a remote client renders over the wire.
+    ## The schema is the only place either of them can learn it.

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/templates/template/README.md.jinja

@@ -17,7 +17,18 @@ uv sync
 Make sure the device is connected and powered on.
 
 ```bash
-uv run python -m {{ module_name }} --tcp-port 5555
+uv run python -m plesty.{{ module_name }} --tcp-port 5555
+```
+
+## Open The Control Panel
+
+`--gui` drives the instrument from this process instead of serving it — the two
+are alternatives, since one session is all the instrument grants. The controls
+are built from the device schema, so nothing here is hand-written.
+
+```bash
+uv sync --extra gui
+uv run python -m plesty.{{ module_name }} --gui
 ```
 {% elif project_type == 'experiment' %}
 

{plesty_sdk-0.3.5.dev1 → plesty_sdk-0.4.0}/plesty/sdk/assets/templates/template/docs/index.md.jinja

@@ -25,6 +25,22 @@ Make sure the device is connected and powered on, then:
 ```bash
 uv run python -m plesty.{{ module_name }} --tcp-port 5555
 ```
+
+## Opening the control panel
+
+```bash
+uv sync --extra gui
+uv run python -m plesty.{{ module_name }} --gui
+```
+
+`--gui` and serving are alternatives: both want the one session the instrument
+grants, so the process does one or the other. The panel derives its controls —
+the parameters, their bounds and units, the operations — from the device
+schema, and it connects before it builds them, so the bounds shown are the ones
+this unit reports rather than the envelope the schema carries for every unit.
+
+An operation whose effect outlives the call belongs to `kind="lifecycle"`; that
+is what keeps it off the panel here and off the one a remote client renders.
 {% elif project_type == 'experiment' %}
 
 ## Running the experiment