Add configurable Cartesian teleoperation and a simulator lab

.github/workflows/ci.yml

@@ -28,6 +28,7 @@ jobs:
       - run: python -m ruff format --check src tests examples tools/build_runtime_release.py tools/configure_release.py tools/check_release.py tools/probe_private_runtime.py tools/benchmark_latest.py
       - run: source-leap --demo --frames 3 --json
       - run: source-leap --demo --latest --health --frames 3 --json
+      - run: source-leap teleop --demo --headless --auto-arm --frames 3 --json
   build:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -4,26 +4,43 @@ A Python package for the **Original Leap Motion Controller**, with owned hand da
 recording/replay, and configurable coordinate mapping for custom robot integrations.
 It runs on current Python without `LeapPython.pyd` or a Python 3.8 process.
 
-Beta **0.1.0b2** is published on [PyPI](https://pypi.org/project/source-robotics-leap-motion/).
-Install it, then start tracking:
+Install the package from [PyPI](https://pypi.org/project/source-robotics-leap-motion/),
+then start tracking:
 
 ```powershell
-python -m pip install source-robotics-leap-motion
+python -m pip install --upgrade source-robotics-leap-motion
 source-leap
 ```
 
 The Windows engine downloads automatically when needed. First-use driver setup may
-require Windows approval. See [release status and validation](docs/BETA_VALIDATION.md)
-and [publication steps](docs/RELEASING.md). Linux/macOS currently use an installed
+require Windows approval. See [release status and validation](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/BETA_VALIDATION.md)
+and [publication steps](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/RELEASING.md). Linux/macOS currently use an installed
 vendor tracking service and remain experimental for hardware use.
 
-Version **0.1.0b2** includes latest-frame acquisition and tracking health. Both are
-available in the published package. See [the latest-frame guide](docs/LATEST_FRAMES.md).
+Version **0.1.0b3** adds configurable Cartesian teleoperation, callback integration,
+and a browser lab with simulated output. It includes latest-frame acquisition and
+tracking health. See
+[the teleoperation guide](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/TELEOPERATION.md) and [latest-frame guide](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/LATEST_FRAMES.md).
 
-**Try it in this project's virtual environment.** Python 3.15.2 and the package are
-already installed in `.venv`. No activation is necessary:
+Try the simulated robot target with a synthetic hand, or with your Leap controller:
 
 ```powershell
+source-leap teleop --demo
+source-leap teleop
+```
+
+The local browser viewer starts disarmed. Arm to calibrate, clutch to reposition
+your hand, and disarm to hold output. Both commands use a simulated Cartesian arm.
+The callback API accepts your own controller; joint-only arms supply their kinematics
+in the adapter. Configure workspace, speed limits, axes, gains, smoothing, rotation,
+and gripper mapping in [teleoperation.toml](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/examples/teleoperation.toml).
+
+**Run from a source checkout.** Create a virtual environment with Python 3.10 or
+newer. No activation is necessary when calling its executables directly:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install .
 .\.venv\Scripts\source-leap.exe --demo
 .\.venv\Scripts\source-leap.exe setup
 .\.venv\Scripts\source-leap.exe doctor --probe
@@ -41,14 +58,20 @@ python -m pip install .
 source-leap --demo
 ```
 
-Python **3.10 or newer** is required. The published b2 wheel was installed and tested on
+Python **3.10 or newer** is required. The b3 wheel was installed and tested on
 **CPython 3.10.11, 3.11.9, 3.12.10, 3.13.17, 3.14.10, and 3.15.2, Windows x64**.
-Each version passed all 107 tests, received live camera frames, and replayed a recorded
+Each version passed all 180 tests, received live camera frames, and replayed a recorded
 real hand. Python 3.10 additionally uses small `tomli` and `typing-extensions`
 backports, installed automatically by pip. All versions use `websocket-client`.
 Python 3.9 and earlier are not supported by the new package.
 
-The [compatibility and performance report](docs/COMPATIBILITY_PERFORMANCE.md) explains
+The live b3 acceptance run checked calibration, clutch/resume, loss of a visible hand,
+explicit rearming, disarming, and shutdown against simulated output. Clean-Windows
+driver setup and real robot-controller validation remain separate hardware checks.
+See the [b3 acceptance evidence](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/B3_VALIDATION.md) and
+[clean-machine checklist](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/CLEAN_MACHINE_CHECK.md).
+
+The [compatibility and performance report](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/COMPATIBILITY_PERFORMANCE.md) explains
 the test matrix, measured stream rate, comparison with the original Python 3.8 SDK,
 and remaining limits. The tracking engine and driver are unchanged; no improvement
 in tracking accuracy or camera frame rate is claimed.
@@ -65,7 +88,7 @@ On this PC, the fallback was verified with service `3.2.1+45911` on
 `127.0.0.1:6437` and the actual Original Leap Motion Controller. A 30-second check
 captured 3,399 frames, including 53 frames containing a left hand with all five
 fingers and four bones per finger. Recording and replay also passed. See
-[the hardware validation notes](docs/HARDWARE_VALIDATION.md).
+[the hardware validation notes](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/HARDWARE_VALIDATION.md).
 
 An existing working legacy service can therefore be used without upgrading it.
 The native LeapC loader supports Windows x64, Linux x64, and macOS Intel/Apple
@@ -115,9 +138,9 @@ The project owner confirmed redistribution permission on 5 November 2026. The
 installed beta wheel also passed two-client sharing, repeated startup, crash cleanup,
 and a live-frame check of the restored installed service. Clean-PC USB setup and
 other-platform hardware tests remain pending.
-See [the prototype, evidence, and bounded test command](docs/MINIMAL_RUNTIME.md).
+See [the prototype, evidence, and bounded test command](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/MINIMAL_RUNTIME.md).
 The proposed first-use flow and Windows/Linux/macOS targets are documented in
-[installation and platforms](docs/INSTALLATION_PLATFORMS.md).
+[installation and platforms](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/INSTALLATION_PLATFORMS.md).
 
 **Read hand data.** The same API accepts live, synthetic, and replay sources:
 
@@ -164,7 +187,7 @@ The default remains sequential, which is appropriate when recording every frame.
 received/delivered/skipped/duplicate counts, timeouts, timestamp resets, and hand
 count. No hands still means the camera is streaming. Age is measured **since Python
 received the frame**, not end-to-end camera latency. It cannot detect every delay
-inside a service or transport. See [semantics and validation](docs/LATEST_FRAMES.md).
+inside a service or transport. See [semantics and validation](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/LATEST_FRAMES.md).
 
 ```powershell
 .\.venv\Scripts\source-leap.exe --latest --health --duration 10
@@ -244,6 +267,6 @@ falls back to another backend. Normal users should not need either option.
 ```
 
 The original scripts and binaries remain historical references. The original README
-is preserved in [docs/LEGACY_README.md](docs/LEGACY_README.md). Current scope and design
+is preserved in [docs/LEGACY_README.md](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/LEGACY_README.md). Current scope and design
 are in [PACKAGE_DESIGN.md](PACKAGE_DESIGN.md); native-interface verification is described
-in [docs/NATIVE_ABI.md](docs/NATIVE_ABI.md).
+in [docs/NATIVE_ABI.md](https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/blob/main/docs/NATIVE_ABI.md).

docs/B3_VALIDATION.md

@@ -0,0 +1,55 @@
+**b3 acceptance evidence — 6 November 2026**
+
+The Original Leap Motion Controller was tested on the development Windows x64 PC,
+using CPython 3.15.2 and its existing legacy 3.2.1 service. Control output went to
+the simulated Cartesian arm. No physical robot was commanded or driver replaced.
+
+**Guided live-hand run.** A 34.3-second run processed
+2,777 frames, including 2,369 complete hand
+samples (five fingers, four bones per finger), and generated 979
+simulated targets. Calibration, clutch hold, re-anchoring without a command on the
+re-anchor frame, removal of a visible hand, latched hold after its return, explicit
+rearming with a new session, disarming, and adapter/tracker shutdown passed.
+
+Preliminary runs also held output when a hand briefly disappeared. The successful
+run used a stable-hand warmup and a shorter guided cycle to complete each transition.
+The test harness changed; the product's conservative loss/rearm policy did not.
+
+The Python control client used 2.87% of one
+core averaged over this mixed hand-present/hand-absent run. Local receipt age at
+sampling was 0.085 ms median and
+0.205 ms p95. These ages start when Python receives
+a distinct frame; they are not exposure-to-command or camera latency measurements.
+CPU figures exclude the vendor service and are not a matched comparison with the old SDK.
+
+**Twenty-minute camera soak.** 1200.0 seconds processed
+115,180 frames, including 7,179 complete hand
+samples. The camera continued streaming with the hand absent for much of the run.
+There were 0 read timeouts. Average delivery was
+96.0 FPS; Python-client CPU averaged
+2.51% of one core.
+
+Final working set was 31.66 MiB and lifetime peak
+working set was 31.66 MiB. These are Windows
+process counters for this Python client, collected with
+[GetProcessMemoryInfo](https://learn.microsoft.com/en-us/windows/win32/api/psapi/nf-psapi-getprocessmemoryinfo),
+not the vendor engine or total system footprint. History in the runner was bounded.
+The tracker closed and left 0 reader threads.
+
+**Package checks.** The installed b3 code passed 180 tests on each Windows CPython
+3.10–3.15 environment, plus all 18 Windows/Linux/macOS CI matrix jobs and the build.
+The existing real-hand recording passed simulated control checks on each interpreter.
+A fresh Python 3.10 candidate installation passed the headless control demo, packaged
+HTML/JavaScript/CSS serving, dependency checks, and thread-free import. Artifact
+inspection found no native binaries or personal recordings. Release documentation
+updates leave the tested package code, assets, and pinned runtime unchanged.
+
+**Remaining hardware evidence.** The owner has no spare clean Windows PC available
+and chose to continue with the simulator. Clean-PC USB driver setup, actual robot
+adapter/controller behavior, and Linux/macOS USB operation remain unverified.
+The [clean-machine checklist](CLEAN_MACHINE_CHECK.md) records the test procedure.
+Fresh venv and hosted software CI results are not a substitute for those device tests.
+
+Raw local evidence is retained in `.tools/live-b3-acceptance.json`, its earlier-attempt
+reports, `.tools/soak-b3-result.json`, `.tools/b3-candidate-install.json`,
+`.tools/b3-artifact-audit.json`, and `.tools/compatibility-results-0.1.0b3.json`.

docs/CLEAN_MACHINE_CHECK.md

@@ -0,0 +1,58 @@
+**Clean Windows installation acceptance — Original Leap Motion Controller**
+
+This check requires a separate Windows x64 PC with no previous Leap/Ultraleap
+installation or driver. A fresh venv on the development PC does not provide that
+evidence. Hosted CI verifies clean software installation and simulated behavior,
+but has no USB controller attached.
+
+Use a supported 64-bit CPython 3.10–3.15 installation. Create a fresh venv outside
+the source checkout, then install by package name from PyPI. Record the actual
+package version before testing.
+
+```powershell
+python -m venv leap-check
+.\leap-check\Scripts\python.exe -m pip install source-robotics-leap-motion
+.\leap-check\Scripts\source-leap.exe --version
+.\leap-check\Scripts\source-leap.exe teleop --demo --headless --auto-arm --frames 30
+.\leap-check\Scripts\source-leap.exe doctor --json
+```
+
+The demo command requires b3 or later. If it is not yet published, use the prepared
+release-candidate wheel explicitly and record that fact; a local-wheel test is not
+the same as verifying the public package-name installation.
+
+Follow these steps with the physical controller:
+
+1. Start with the camera unplugged. Run `source-leap setup --json`. It should report
+   the absent camera distinctly from a missing driver; it must not install a driver
+   just because no frames arrived.
+2. Plug in the Original controller. Inspect setup's device status. If Windows reports
+   a missing driver, run `source-leap setup --install-driver` and approve Windows'
+   administrator prompt. Record the driver publisher/version and every manual step.
+3. Run `source-leap doctor --probe --json`, then `source-leap --latest --health --duration 10`.
+   Confirm live frames with no hands, then full hand data when a hand is visible.
+4. Run `source-leap teleop`. Arm, clutch, resume, remove the hand, and return it.
+   Confirm a returning hand stays held until explicit rearming. Output goes to the
+   simulated Cartesian arm.
+5. Close all package clients. Confirm the private engine shuts down after its final
+   client. Reopen tracking and repeat the frame probe. Check repeated startups and
+   one abrupt client exit.
+6. Reuse the populated cache with network access unavailable. Tracking should work
+   without another download. Reboot and repeat the probe to verify driver persistence.
+
+Keep the console reports locally. Capture the package/interpreter versions, whether a vendor
+service was present, runtime download/cache behavior, device/driver state, live frame
+and skeleton counts, shutdown/restart outcome, and any unexpected errors.
+
+Passing means the package installs without a compiler or Python 3.8, first use obtains
+the pinned runtime, setup diagnoses the device correctly, the minimum driver path
+works, and tracking/restart/cache reuse succeed. A GUI vendor installation used to
+make the test work must be recorded as an additional prerequisite rather than called
+driver-only success.
+
+**Current evidence.** Package-name installation and live frames were verified in fresh
+project-local venvs on an already working Windows PC. Private-engine startup/sharing/
+crash cleanup was tested separately with its existing driver. No separate clean
+Windows USB installation has passed yet. This PC has no Windows Sandbox executable,
+no installed WSL distribution, and no running Docker engine. Linux/macOS USB and actual
+robot-controller checks also remain pending; their software CI results are separate.