ocdkit 0.0.2__tar.gz → 0.0.4__tar.gz

{ocdkit-0.0.2 → ocdkit-0.0.4}/.github/workflows/test_and_deploy.yml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]  # macos-latest = Apple Silicon (MPS)
-        python_version: ['3.11', '3.12']
+        python_version: ['3.11', '3.12', '3.13']
     steps:
       - uses: actions/checkout@v4
         with:
@@ -85,8 +85,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: main
 
       - name: Download test artifacts
         uses: actions/download-artifact@v4

{ocdkit-0.0.2 → ocdkit-0.0.4}/.gitignore

@@ -6,6 +6,10 @@
 # Local tooling
 .claude/
 
+# Editor / NAS junk
+*.bak
+.!*
+
 # C extensions
 *.so
 

{ocdkit-0.0.2 → ocdkit-0.0.4}/MANIFEST.in

@@ -1,9 +1,13 @@
 include README.md
 include LICENSE
 recursive-include src *.py
+recursive-include src/ocdkit/viewer/web *.html *.css *.js *.svg *.c
 recursive-include tests *.py
 recursive-include tests/fixtures *
+prune src/ocdkit/viewer/web/icons/_unused
 prune tests/__pycache__
 prune **/__pycache__
 global-exclude ._*
 global-exclude .DS_Store
+global-exclude *.bak
+global-exclude .!*

{ocdkit-0.0.2/src/ocdkit.egg-info → ocdkit-0.0.4}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: ocdkit
-Version: 0.0.2
+Version: 0.0.4
 Summary: Obsessive Coder's Dependency Toolkit — Python utilities for array manipulation, GPU dispatch, image I/O, morphology, and plotting.
 License: BSD-3-Clause
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy
+Requires-Dist: numpy>=2.0
 Requires-Dist: scipy
-Requires-Dist: scikit-image
+Requires-Dist: scikit-image>=0.26
 Requires-Dist: tifffile
 Requires-Dist: imagecodecs
 Requires-Dist: matplotlib
@@ -18,16 +18,26 @@ Requires-Dist: torch>=1.12
 Requires-Dist: dask[array]
 Requires-Dist: natsort
 Requires-Dist: numba
-Requires-Dist: bioio
-Requires-Dist: bioio-czi
+Requires-Dist: aicspylibczi
 Requires-Dist: ncolor>=1.5.1
 Requires-Dist: cmap
 Requires-Dist: tqdm
+Requires-Dist: platformdirs
+Requires-Dist: cryptography
+Provides-Extra: viewer
+Requires-Dist: fastapi; extra == "viewer"
+Requires-Dist: uvicorn[standard]; extra == "viewer"
+Requires-Dist: imageio; extra == "viewer"
+Requires-Dist: python-multipart; extra == "viewer"
+Provides-Extra: desktop
+Requires-Dist: pywebview; extra == "desktop"
+Requires-Dist: pywin32; sys_platform == "win32" and extra == "desktop"
+Requires-Dist: pyobjc-framework-Cocoa; sys_platform == "darwin" and extra == "desktop"
 Dynamic: license-file
 
 # ocdkit
 
-**Obsessive Coder's Dependency Toolkit** — Python utilities for array manipulation, GPU dispatch, image I/O, spatial operations, morphology, and plotting.
+A toolkit for array manipulation, GPU dispatch, image I/O, spatial operations, morphology, and plotting. 
 
 ## Install
 
@@ -61,6 +71,33 @@ from ocdkit.plot import figure, image_grid
 device = resolve_device()  # auto-detect CUDA / MPS / CPU
 ```
 
+## Performance tips
+
+### Pin numba's JIT cache to local disk
+
+If your project source lives on a network filesystem (SMB / NFS), set
+`NUMBA_CACHE_DIR` to a local-disk location. By default numba writes its
+JIT cache to `__pycache__` next to the source file, which on a
+NAS-mounted tree means dozens of small SMB ops per fresh subprocess —
+several seconds of overhead on every cold import.
+
+ocdkit auto-applies `$HOME/.cache/numba` as the default if you haven't
+set it (see `src/ocdkit/__init__.py`), but for shells, test runners, and
+non-ocdkit code, set it explicitly:
+
+```bash
+# Linux / macOS — add to ~/.zshrc, ~/.bashrc, or ~/.profile
+export NUMBA_CACHE_DIR="$HOME/.cache/numba"
+```
+
+```powershell
+# Windows — add to $PROFILE
+[Environment]::SetEnvironmentVariable('NUMBA_CACHE_DIR', "$env:USERPROFILE\.cache\numba", 'User')
+```
+
+Compiled artifacts are machine-local anyway (CPU- and Python-version
+specific), so they don't belong on shared NAS regardless of perf.
+
 ## License
 
 BSD-3-Clause

ocdkit-0.0.2/PKG-INFO → ocdkit-0.0.4/README.md

@@ -1,33 +1,6 @@
-Metadata-Version: 2.4
-Name: ocdkit
-Version: 0.0.2
-Summary: Obsessive Coder's Dependency Toolkit — Python utilities for array manipulation, GPU dispatch, image I/O, morphology, and plotting.
-License: BSD-3-Clause
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: scipy
-Requires-Dist: scikit-image
-Requires-Dist: tifffile
-Requires-Dist: imagecodecs
-Requires-Dist: matplotlib
-Requires-Dist: fastremap
-Requires-Dist: edt
-Requires-Dist: torch>=1.12
-Requires-Dist: dask[array]
-Requires-Dist: natsort
-Requires-Dist: numba
-Requires-Dist: bioio
-Requires-Dist: bioio-czi
-Requires-Dist: ncolor>=1.5.1
-Requires-Dist: cmap
-Requires-Dist: tqdm
-Dynamic: license-file
-
 # ocdkit
 
-**Obsessive Coder's Dependency Toolkit** — Python utilities for array manipulation, GPU dispatch, image I/O, spatial operations, morphology, and plotting.
+A toolkit for array manipulation, GPU dispatch, image I/O, spatial operations, morphology, and plotting. 
 
 ## Install
 
@@ -61,6 +34,33 @@ from ocdkit.plot import figure, image_grid
 device = resolve_device()  # auto-detect CUDA / MPS / CPU
 ```
 
+## Performance tips
+
+### Pin numba's JIT cache to local disk
+
+If your project source lives on a network filesystem (SMB / NFS), set
+`NUMBA_CACHE_DIR` to a local-disk location. By default numba writes its
+JIT cache to `__pycache__` next to the source file, which on a
+NAS-mounted tree means dozens of small SMB ops per fresh subprocess —
+several seconds of overhead on every cold import.
+
+ocdkit auto-applies `$HOME/.cache/numba` as the default if you haven't
+set it (see `src/ocdkit/__init__.py`), but for shells, test runners, and
+non-ocdkit code, set it explicitly:
+
+```bash
+# Linux / macOS — add to ~/.zshrc, ~/.bashrc, or ~/.profile
+export NUMBA_CACHE_DIR="$HOME/.cache/numba"
+```
+
+```powershell
+# Windows — add to $PROFILE
+[Environment]::SetEnvironmentVariable('NUMBA_CACHE_DIR', "$env:USERPROFILE\.cache\numba", 'User')
+```
+
+Compiled artifacts are machine-local anyway (CPU- and Python-version
+specific), so they don't belong on shared NAS regardless of perf.
+
 ## License
 
 BSD-3-Clause

ocdkit-0.0.4/badges/coverage.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 43.71%"><title>coverage: 43.71%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#e05d44"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">43.71%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">43.71%</text></g></svg>

ocdkit-0.0.4/badges/tests.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="68" height="20" role="img" aria-label="tests: 400"><title>tests: 400</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="68" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="37" height="20" fill="#555"/><rect x="37" width="31" height="20" fill="#4c1"/><rect width="68" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="195" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="270">tests</text><text x="195" y="140" transform="scale(.1)" fill="#fff" textLength="270">tests</text><text aria-hidden="true" x="515" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="210">400</text><text x="515" y="140" transform="scale(.1)" fill="#fff" textLength="210">400</text></g></svg>

ocdkit-0.0.4/docs/plot-backend-roadmap.md

@@ -0,0 +1,96 @@
+# Plot backend roadmap
+
+**Status:** Design discussion / pending decision.
+**Owner:** kevin@kanvasbio.com
+**Driver:** matplotlib accounts for ~80% of warm-call time in `hiprpy.plot.plot_spectra` (~115 ms of ~140 ms) and ~1.5 s of cold-import overhead. We also want native hover/tooltip behavior like the classification-debugger GUI, which matplotlib can't deliver inline.
+
+## Context
+
+`ocdkit.plot` and `hiprpy.plot` already own ~10 K LOC of plotting code:
+
+| Package | LOC |
+|---|---|
+| `ocdkit.plot` (figure, grid, label, color, defaults, display, contour, export) | 1,935 |
+| `hiprpy.plot` non-WGPU (datashade, cell, text, barcode, line, background, …) | 4,641 |
+| `hiprpy.plot.wgpu` (lines, scatter, aggregators — already custom GPU primitives) | 4,783 |
+
+What we still depend on matplotlib for is narrow: 2D Cartesian axes, ticks, labels, legends, image display, save-to-PNG/PDF/SVG, inline-in-Jupyter. **Not** 3D, animation, multi-backend abstraction (Qt/GTK/MacOSX), most chart types, complex tick locators/formatters, or any of the other ~180 K LOC of matplotlib's surface.
+
+The driver question: replace matplotlib with what?
+
+## Library survey (2026-05-07)
+
+Shallow-cloned each candidate, counted Python LOC excluding tests, sphinx, sample data, and auto-generated validators:
+
+| Library | Repo | Relevant Py LOC | Native code | Notes |
+|---|---|---|---|---|
+| matplotlib | — | 186 K | C extensions | What we're replacing |
+| bokeh | 120 MB | 64 K | 150 K TypeScript | UI lives in TS frontend; Py is scene graph + serialization |
+| plotly | 66 MB | 13 K relevant (+ ~600 K autogen) | JS bundle as data | Most LOC is auto-generated trait validators |
+| datoviz | 137 MB | 8 K Py wrapper | 140 K C++ Vulkan engine | Heaviest binary footprint, fastest renderer |
+| vispy | 11 MB | 32 K | None — pure Py + OpenGL | OpenGL stack, not WGPU |
+| pygfx | 84 MB | 20 K | None — uses `wgpu-py` | Same backend ocdkit/hiprpy already use |
+
+## Tradeoff summary
+
+**Bokeh** — toolbar/logo *can* be removed (`figure(toolbar_location=None)`, `fig.toolbar.logo = None`), but the interaction model lives in a separate TypeScript frontend. To customize hover/zoom UX we'd be writing or forking TypeScript, not Python. The 150 K-LOC TS frontend is essentially the part we'd want to control, and it's the part we can't easily touch.
+
+**Plotly** — same shape. Most LOC is auto-generated validators; the actual rendering and interaction is in the JS bundle. `displayModeBar=False` removes the toolbar but customizing hover beyond what their config exposes means reaching into JS.
+
+**Datoviz** — Vulkan engine is fast and well-architected, but adds a 137 MB binary dependency and a different graphics stack from our existing wgpu-py code. Two graphics backends to maintain instead of one.
+
+**Vispy** — pure Python and has scene + visuals modules that overlap heavily with what we want. But it's OpenGL via PyOpenGL, not WebGPU. We'd be running a second graphics stack alongside our wgpu-py code.
+
+**pygfx** — uses *exactly* the `wgpu-py` we already depend on. Its `gfx.Lines`, `gfx.Mesh`, `gfx.Text`, `gfx.OrthographicCamera` primitives compose directly with our `DensityLineRenderer`. The most architecturally compatible third-party option.
+
+**Roll our own** — given that we already have ~10 K LOC of plotting infrastructure, including a working WGPU line/scatter rasterizer, the increment to "complete 2D plotting library covering our actual needs" is roughly 3–5 K LOC. The scope is well-defined: axes, ticks, labels, legend, image display, hover, export.
+
+## Recommendation
+
+**Two-step.**
+
+### Step 1: pygfx prototype (1 day)
+
+Spike a `plot_spectra_pygfx` that uses `pygfx.Lines` + `pygfx.Text` + an `OrthographicCamera` to reproduce the current spectra layout. This is cheap because pygfx and our existing WGPU code share the same `wgpu-py` device — they can literally run in the same process without backend conflict.
+
+What to evaluate:
+- Visual quality vs. our current WGPU-rendered density lines (especially anti-aliasing)
+- Text rendering quality (pygfx uses FreeType-rendered SDFs)
+- Hover/picking — does pygfx's built-in picking suffice for our tooltip needs?
+- Export — pygfx renders to a wgpu canvas; PNG export is straightforward, PDF/SVG would need our own rasterize-and-vectorize path
+
+If pygfx covers ≥80% of our needs at ≥80% of the visual quality, **adopt pygfx**. We get hover, zoom, pan, picking essentially for free, plus the `pygfx` ecosystem (geometries, materials, post-processing).
+
+### Step 2 (only if pygfx is insufficient): roll our own
+
+Estimated scope, building on existing `hiprpy.plot.wgpu.lines`:
+
+| Module | LOC est. | Notes |
+|---|---|---|
+| `ocdkit.plot.figure_v2` | 400 | New `Figure` class owning the wgpu canvas + axes layout; coexists with current matplotlib `figure()` so migration is piecewise |
+| `ocdkit.plot.axis` | 800 | `LinearAxis`, `LogAxis` — tick locator + formatter + render-time placement. The matplotlib equivalent is ~3 K LOC; we don't need most of it |
+| `hiprpy.plot.wgpu.text` | 600 | FreeType-rendered glyph atlas + WGSL textured-quad shader. The one piece of genuinely new rasterization work |
+| `ocdkit.plot.legend` | 200 | Boxed layout: text + marker swatches |
+| `ocdkit.plot.hover` | 300 | Mouse → data-coord lookup → DOM/Jupyter tooltip overlay. Generalize the classification-debugger pattern |
+| `ocdkit.plot.export` | 400 | PNG (numpy→PIL), SVG (string templates), maybe PDF (skip if PIL→PNG covers science exports) |
+| Migration: rewrite `plot_spectra`, `plot_image_grid`, `key_slice_grid`, `label_axes` against new primitives | ~600 | Mostly drop-in replacements at the call sites |
+| **Total** | **~3.3 K** | New code, all in our control |
+
+Plus: deletion of matplotlib-specific code paths in `hiprpy.plot` (~1 K LOC saved) and removal of matplotlib runtime dep.
+
+### Why not pygfx + own axes?
+
+A hybrid path is also viable: use pygfx for the rasterization layer (lines/text/transform/camera) and write our own axis/tick/legend/hover layer on top. That'd be the best of both — pygfx handles the rendering substrate, we own the plotting semantics. Estimated ~1.5 K LOC of new code on top of pygfx.
+
+## Open questions
+
+1. **Hover semantics** — does the classification-debugger tooltip pattern generalize cleanly, or do different plots need different hover content models?
+2. **Export fidelity** — do we need true vector PDF, or is high-DPI PNG enough? Vector requires re-rasterizing axes/text on the CPU side, which is non-trivial.
+3. **Notebook + standalone parity** — pygfx renders to a wgpu canvas that displays inline in Jupyter via `wgpu_jupyter`. Does that path work in VS Code's Jupyter extension and in standalone scripts (`savefig`-equivalent)?
+4. **Remoting** — if we ever want a server-side render pipeline (for cloud GUIs), pygfx's WGPU backend can render headlessly; matplotlib `Agg` does the same. Bokeh/plotly's JS-frontend assumption is harder to remote.
+
+## Concrete next action
+
+Spike `plot_spectra_pygfx` using `scope.mixed_spectra[-1]` from `notebooks/hiprpy_demo_notebook.ipynb` as the test case. Compare visual output side-by-side with `plot_spectra_wgpu` and `plot_spectra_cpu`. Decide pygfx-vs-roll-own from that single comparison.
+
+If the answer ends up being "pygfx + own axis layer", the new module structure would live in `ocdkit.plot.gfx_*` (parallel to the current matplotlib-based modules) so the migration is a per-call-site flip rather than a big-bang rewrite.

ocdkit-0.0.4/docs/plugin-authoring.md

@@ -0,0 +1,220 @@
+# Authoring an ocdkit.viewer plugin
+
+This document is the source-of-truth contract for adding a new segmentation
+backend to the ocdkit viewer. It is written so an LLM can read it and produce
+a working plugin in one shot.
+
+## What a plugin is
+
+A plugin wires a segmentation tool (Cellpose, StarDist, SAM, your own model,
+…) into the ocdkit viewer. The viewer handles:
+
+- Image loading, display, panning, zooming
+- Mask rendering (n-coloring, opacity, color tables)
+- Manual mask editing (brush, fill, split, merge)
+- Affinity-graph editing
+- Session persistence
+
+Your plugin only needs to:
+
+1. Declare the parameters the user can tune.
+2. Provide a `run(image, params) -> mask` function.
+3. (Optionally) declare lifecycle hooks: model loading, GPU toggle, cache.
+
+## The `SegmentationPlugin` contract
+
+```python
+from ocdkit.viewer import SegmentationPlugin, WidgetSpec
+
+plugin = SegmentationPlugin(
+    name="my_tool",                # stable plugin id (lowercase, no spaces)
+    version="0.1.0",
+    description="Brief one-line description.",
+    homepage="https://github.com/you/my_tool",
+    widgets=[
+        WidgetSpec(
+            name="threshold",        # key passed into params
+            label="Threshold",       # UI label
+            kind="slider",           # widget kind (see below)
+            default=0.5,
+            min=0.0, max=1.0, step=0.01,
+            help="Pixels above this become foreground.",
+            group="Detection",        # subsection header
+        ),
+        # ... more WidgetSpec entries ...
+    ],
+    run=my_segmentation_function,
+    # optional:
+    load_models=lambda: ["model_a", "model_b"],
+    warmup=lambda model_id: None,
+    set_use_gpu=lambda enabled: None,
+    clear_cache=lambda: None,
+)
+```
+
+## `run(image, params) -> mask` contract
+
+```python
+def my_segmentation_function(image: np.ndarray, params: dict) -> np.ndarray:
+    """
+    image: uint8 numpy array.
+        - Shape (H, W) for grayscale.
+        - Shape (H, W, C) for multichannel/RGB. C is 1, 2, 3, or 4.
+    params: dict whose keys are the WidgetSpec.name strings you declared.
+        Values are typed: numbers for slider/number, bool for toggle, str for
+        dropdown/text/file/color/colormap.
+    returns: 2D int32 (or smaller int) numpy array, shape (H, W).
+        0 = background. Positive integers are instance ids.
+        The viewer takes care of n-coloring and rendering.
+    """
+    ...
+```
+
+## Widget kinds
+
+| `kind`        | Type    | Required fields            | Notes                                           |
+| ------------- | ------- | -------------------------- | ----------------------------------------------- |
+| `slider`      | float   | `min`, `max` (`step`)      | Continuous range with handle                    |
+| `slider_log`  | float   | `min` > 0, `max` (`step`)  | Log-scaled slider                               |
+| `number`      | float   | `min`, `max` (`step`)      | Plain number input box                          |
+| `toggle`      | bool    | `default` must be bool     | Checkbox / switch                               |
+| `dropdown`    | str     | `choices`                  | Single-select from list of strings              |
+| `text`        | str     | —                          | Free-form text input                            |
+| `file`        | str     | —                          | File path picker                                |
+| `color`       | str     | —                          | Hex color string (`"#ff0000"`)                  |
+| `colormap`    | str     | —                          | Colormap name from ocdkit.cmap                  |
+
+### Conditional visibility
+
+A widget can be hidden until other widgets have specific values:
+
+```python
+WidgetSpec(
+    name="manual_value",
+    label="Manual value",
+    kind="slider", default=0.5, min=0.0, max=1.0,
+    visible_when={"method": "manual"},   # show only when method == "manual"
+)
+```
+
+Multiple keys are AND-ed: the widget shows only when all entries match.
+
+### Grouping
+
+`group="Detection"` puts widgets under a collapsible "Detection" section in
+the pane. Widgets without `group` go into a default top section.
+
+## Lifecycle hooks
+
+All optional. Skip the ones you don't need.
+
+| Hook            | Signature              | When called                                          |
+| --------------- | ---------------------- | ---------------------------------------------------- |
+| `load_models`   | `() -> list[str]`      | Once on plugin selection — populates the model list. |
+| `warmup`        | `(model_id) -> None`   | When the user picks a model — preload it.            |
+| `set_use_gpu`   | `(enabled: bool) -> None` | When the user toggles the GPU switch.             |
+| `clear_cache`   | `() -> None`           | When the user clicks "Clear cache".                  |
+
+If `load_models` is provided, the viewer renders a model dropdown at the top
+of the pane and passes the chosen `model` value in `params["model"]` on each
+`run()` call — you do not need to declare a `WidgetSpec` for it.
+
+## Registering the plugin
+
+### Option A — entry point (recommended for installed packages)
+
+In your `pyproject.toml`:
+
+```toml
+[project.entry-points."ocdkit.plugins"]
+my_tool = "my_tool.ocdkit_plugin:plugin"
+```
+
+Where `my_tool/ocdkit_plugin.py` contains:
+
+```python
+from ocdkit.viewer import SegmentationPlugin, WidgetSpec
+plugin = SegmentationPlugin(name="my_tool", ..., run=...)
+```
+
+The viewer auto-discovers all `ocdkit.plugins` entry points at startup.
+
+### Option B — explicit registration (for in-process or tests)
+
+```python
+from ocdkit.viewer import register_plugin
+register_plugin(plugin)
+```
+
+## Validation
+
+Both `WidgetSpec(...)` and `SegmentationPlugin(...)` validate their arguments
+in `__post_init__`. Common errors raised at construction time:
+
+- `WidgetSpec.name` empty or non-string → `ValueError`
+- numeric kinds without `min`/`max` → `ValueError`
+- `slider_log` with `min <= 0` → `ValueError`
+- `dropdown` without `choices` → `ValueError`
+- `dropdown` whose `default` is not in `choices` → `ValueError`
+- `toggle` with non-bool `default` → `ValueError`
+- duplicate widget `name` within one plugin → `ValueError`
+
+Programmatic schemas for tools and tests:
+
+```python
+from ocdkit.viewer.plugins.schema import (
+    widget_spec_schema,        # JSON Schema for one WidgetSpec
+    plugin_manifest_schema,    # JSON Schema for plugin.manifest()
+)
+```
+
+## Minimal complete example
+
+```python
+# my_tool/ocdkit_plugin.py
+import numpy as np
+from skimage.filters import threshold_otsu
+from skimage.measure import label
+from ocdkit.viewer import SegmentationPlugin, WidgetSpec
+
+
+def _run(image: np.ndarray, params: dict) -> np.ndarray:
+    if image.ndim == 3:
+        image = image.mean(axis=-1).astype(image.dtype)
+    cutoff = float(params["threshold"]) * 255.0
+    if params.get("method") == "otsu":
+        cutoff = float(threshold_otsu(image))
+    binary = (image > cutoff)
+    if params.get("invert"):
+        binary = ~binary
+    return label(binary).astype(np.int32)
+
+
+plugin = SegmentationPlugin(
+    name="simple_threshold",
+    version="0.1.0",
+    description="Otsu / manual threshold + connected components.",
+    widgets=[
+        WidgetSpec("method", "Method", "dropdown",
+                   default="otsu", choices=["otsu", "manual"]),
+        WidgetSpec("threshold", "Threshold", "slider",
+                   default=0.5, min=0.0, max=1.0, step=0.01,
+                   visible_when={"method": "manual"}),
+        WidgetSpec("invert", "Invert", "toggle", default=False),
+    ],
+    run=_run,
+)
+```
+
+That's the entire plugin. Once entry-pointed, it appears in the viewer's
+plugin dropdown automatically.
+
+## Conventions
+
+- Plugin `name` is lowercase, snake_case. It appears in URLs.
+- Widget `name`s are also snake_case and are the keys in `params`.
+- Don't mutate `image` in `run()`; return a new array.
+- Return masks as 2D `int32` (or `uint16`/`int64` work too). Background = 0.
+- Lifecycle hooks should be cheap or fork to a worker thread internally.
+- Heavy imports (torch, your model library) belong **inside** `run()` or
+  inside `warmup()`, not at module top — keeps viewer startup fast.