hyperview 0.4.2__tar.gz → 0.6.0__tar.gz

{hyperview-0.4.2 → hyperview-0.6.0}/.agents/skills/hyperview-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hyperview-cli
-description: Use HyperView's control-plane CLI for hyperview serve, dataset create, workspace create, embeddings compute, layouts compute, runtime jobs, ui layout set, ui selection set, ui panel add, extension add, tools run, native module panels, backend tools, and local HyperView plugin workflows.
+description: Use HyperView's control-plane CLI for hyperview serve, dataset create, workspace create, embeddings compute, layouts compute, browserless paper figure export, runtime jobs, ui layout set, ui selection set, ui panel add, extension add, tools run, panel modules, backend tools, and local HyperView extension workflows.
 license: MIT
 compatibility: Requires Python 3.10-3.13 and the hyperview CLI (`uv tool install --python 3.12 hyperview`). Runtime-control commands require a running HyperView server.
 metadata:
@@ -29,9 +29,10 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - Start or control a running HyperView runtime.
 - Register a custom embedding provider.
 - Compute embeddings or layouts without restarting the UI.
+- Export paper-ready static 3D embedding figures without a browser or Node runtime.
 - Switch the active workspace, layout, or selection in a running session.
-- Add or remove agent-authored native module panels from local files.
-- Create, install, reload, or test a local plugin/extension with Python backend tools and a frontend panel.
+- Add, remove, or compose extension-backed panel instances.
+- Create, install, reload, or test a local extension with Python backend tools and a frontend panel.
 
 ## Core workflow
 
@@ -41,7 +42,8 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 4. Register a provider if needed.
 5. Submit embedding or layout jobs through the runtime.
 6. Use `hyperview ui ...` commands to switch what the live UI shows.
-7. For plugins, create an extension folder and install it into the running workspace.
+7. Export paper figures with `hyperview figure export` when the user needs screenshots or publication diagrams.
+8. For extensions, create an extension folder and install it into the running workspace.
 
 ## Current model
 
@@ -49,32 +51,40 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - Datasets are created separately from workspaces.
 - The workspace owns the dataset selection.
 - `ui layout set` changes the active layout and the frontend opens the matching built-in scatter panel.
-- Runtime-added panels can be typed scatter instances bound to explicit layout keys, or native module panels loaded into the host React tree.
+- `ui similarity set` selects an anchor sample and pins the nearest-neighbor context to an explicit layout or space.
+- Runtime-added panels can be typed scatter instances bound to explicit layout keys, or extension-backed panel modules loaded into the host React tree.
 - Runtime-added panels use the stable `HyperViewPanelSDK` surface on `window`.
-- Plugins are repo-local extension folders with `extension.toml`, optional Python tools, and optional native panel modules.
-- Plugin panels call backend tools through `HyperViewPanelSDK.hooks.useTool()` or `hyperview tools run`.
+- Extensions are repo-local folders with `extension.toml`, optional Python tools, and optional panel modules.
+- Extension panels call backend tools through `HyperViewPanelSDK.hooks.useTool()` or `hyperview tools run`.
+- Extensions define reusable tools/panels; workspace views compose concrete panel instances and layout. In Python launch scripts, register extensions with `session.ui.add_extension(...)` and place panels with `hv.ui.ExtensionPanel(...)`.
 - In practice, create datasets and workspaces before starting the runtime for that workspace. The current runtime loads workspace registry state on startup.
+- `figure export` is browserless and supports 3D layouts only. It reuses the persisted 3D camera for the layout when available, otherwise it chooses a paper-oriented default view.
+- Paper figure defaults are square, white-background, opaque PNGs with a faint sphere guide and direct labels for small label sets.
 
-Read [references/commands.md](references/commands.md) for command recipes covering datasets, workspaces, providers, embeddings, layouts, runtime UI state, selections, and jobs.
-Read [references/native-panels.md](references/native-panels.md) when the task involves authoring or registering a custom panel.
-Read [references/plugins.md](references/plugins.md) when the task involves backend-plus-frontend plugins/extensions.
+Read [references/commands.md](references/commands.md) for command recipes covering datasets, workspaces, providers, embeddings, layouts, paper figures, runtime UI state, selections, and jobs.
+Read [references/panel-modules.md](references/panel-modules.md) when the task involves authoring a browser panel module.
+Read [references/extensions.md](references/extensions.md) when the task involves packaging or registering custom panel code or backend tools.
 
 ## Agent guidance
 
 - Prefer CLI commands over direct file edits when the goal is to operate a running HyperView session.
 - Treat dataset creation and workspace binding as separate steps when needed: `dataset create ...` creates persisted data, `workspace create --dataset ...` or `workspace set-dataset ...` binds it to a workspace.
 - Prefer `workspace create --dataset ...` over separate create and dataset-attach calls when setting up a new workspace.
-- For custom module panels, have the agent write panel modules outside the app source tree, for example under `agent-context/`, and then add them through `hyperview ui panel add --module-file ...`.
+- For custom panel code, create an extension under `.hyperview/extensions/<extension-name>/`; do not register arbitrary panel module files directly.
 - For side-by-side embedding comparisons, add typed scatter panels through `hyperview ui panel add --kind scatter --layout-key ... --reference-panel-id ... --direction right`.
-- For plugins, prefer `.hyperview/extensions/<plugin-name>/` in the project root. `hyperview serve` auto-discovers those folders and attaches them to the launched workspace, so they can live in version control with the dataset/project code.
+- For nearest-neighbor comparisons, use `hyperview ui similarity set --sample-id ... --layout-key ...` or panel SDK `commands.showSimilar(...)`; do not infer neighbor space from whichever scatter panel is focused.
+- For extensions, prefer `.hyperview/extensions/<extension-name>/` in the project root. `hyperview serve` auto-discovers those folders and attaches them to the launched workspace, so they can live in version control with the dataset/project code.
+- For demos/spaces that launch HyperView from Python, compose panels with `hv.ui.Horizontal`, `hv.ui.Vertical`, `hv.ui.Scatter`, and `hv.ui.ExtensionPanel`; keep extension manifests focused on reusable panel/tool definitions.
 - Tools can write files under `ctx.extension_storage` and return `ctx.url_for(path)` for panel-renderable artifact URLs.
-- Keep plugins self-contained: `extension.toml`, `tools.py`, `panel.js` or `panel.jsx`, and any local assets in the same folder.
+- Keep extensions self-contained: `extension.toml`, `tools.py`, `panel.js` or `panel.jsx`, and any local assets in the same folder.
 - Prefer `--json` output when chaining commands or inspecting results programmatically.
 - Wait for embedding/layout jobs to finish before issuing layout-switch commands that depend on their results.
 - Use `hyperview jobs list` or `hyperview jobs inspect <job-id>` if a compute command is long-running or you started it with `--no-wait`.
 - For provider args, use repeated `--provider-arg key=value` flags.
 - Treat the workspace as the durable unit. Changing datasets means setting a new workspace dataset, not switching among many datasets inside one workspace.
-- Prefer native module panels over raw HTML. The panel system no longer relies on iframes.
+- Prefer panel modules over raw HTML. The panel system no longer relies on iframes.
+- For paper diagrams, prefer `hyperview figure export` over browser screenshots unless the user explicitly needs exact UI chrome. It does not require Playwright, browser bundling, or Node at runtime.
+- For publication figures, keep the defaults first: `--theme light`, `--guide-style paper`, and `--legend auto`. Use `--show-selection` only when selected samples are meaningful and will be explained in the caption.
 - The first `uv run hyperview ...` invocation in a session can take 30+ seconds (torch/datasets imports). Allow generous timeouts and avoid sending SIGINT.
 
 ## Inspecting runtime state
@@ -85,4 +95,4 @@ The runtime exposes JSON discovery endpoints alongside the CLI. Use them to obta
 - `GET /api/embeddings?workspace_id=<ws>` &mdash; the active or default layout, including `layout_key`, `geometry`, and sample `ids`. Use the returned `layout_key` for `hyperview ui layout set --layout-key ...` and pick from `ids` for `hyperview ui selection set --ids ...`.
 - `GET /api/tools` &mdash; registered tool URIs (also returned by `hyperview tools list --json`).
 
-Layout keys encode geometry and dimension as a substring (e.g. `..._euclidean_umap__2d_...`, `..._hyperbolic_umap__3d_...`). Match on those substrings when filtering by geometry/dimension.
+Layout keys encode geometry and dimension as a substring (e.g. `..._euclidean_umap__2d_...`, `..._hyperbolic_umap__3d_...`). Match on those substrings when filtering by geometry/dimension.

{hyperview-0.4.2 → hyperview-0.6.0}/.agents/skills/hyperview-cli/references/commands.md

@@ -46,7 +46,7 @@ Preview destinations without writing files:
 hyperview skill install --dry-run --json
 ```
 
-This is different from `hyperview extension add`, which installs a runtime plugin into a running HyperView workspace.
+This is different from `hyperview extension add`, which installs a runtime extension into a running HyperView workspace.
 
 ## Datasets and Workspaces
 
@@ -131,6 +131,63 @@ hyperview jobs list --json
 hyperview jobs inspect <job-id> --json
 ```
 
+## Paper Figures
+
+Export a browserless, paper-ready PNG from the active 3D layout:
+
+```bash
+hyperview figure export figures/embedding-sphere.png \
+  --workspace research \
+  --layout active \
+  --json
+```
+
+If `--layout` is omitted, HyperView uses the active 3D layout when one is set, otherwise the first available 3D layout. Use `--layout active` when you specifically want the live UI's active layout and want the command to fail if none is active.
+
+The export path is pure Python and does not require Playwright, browser bundling, Node, or a running frontend. It supports 3D layouts only; 2D layouts are rejected with a validation message.
+
+Paper defaults are tuned for academic figures:
+
+- `--width 900 --height 900 --scale 2`
+- `--theme light`
+- `--guide-style paper`
+- `--legend auto` (direct labels for small label sets)
+- opaque PNG output
+- selection rings hidden unless explicitly requested
+
+Use the 3D view selected in the UI by rotating the scatter panel first. HyperView persists the layout camera and `figure export` reuses it for that layout.
+
+Common variants:
+
+```bash
+# Cleanest sphere context: silhouette only.
+hyperview figure export figures/embedding-outline.png \
+  --workspace research \
+  --layout active \
+  --guide-style outline
+
+# No sphere guide, useful when the embedding separation is the whole message.
+hyperview figure export figures/embedding-clean.png \
+  --workspace research \
+  --layout active \
+  --guide-style none \
+  --legend direct
+
+# Browser-like guide rings and current selection markers.
+hyperview figure export figures/embedding-ui-like.png \
+  --workspace research \
+  --layout active \
+  --guide-style rings \
+  --legend on \
+  --show-selection
+
+# Add a short panel title when the figure will stand alone.
+hyperview figure export figures/embedding-panel-a.png \
+  --workspace research \
+  --layout active \
+  --title "ArcFace spherical embeddings"
+```
+
 ## Runtime UI
 
 Discover an existing layout key and sample IDs before mutating runtime state:
@@ -151,15 +208,18 @@ hyperview ui selection set --workspace research --ids sample-1,sample-8
 
 `--layout-key` must be an existing layout (use the `layout_key` returned by `/api/embeddings`). When the chosen layout is Euclidean 3D, HyperView opens or focuses the Euclidean 3D scatter panel.
 
-Add a native panel from a local JavaScript module file:
+Add a custom panel through an extension:
 
 ```bash
+hyperview extension add .hyperview/extensions/label-histogram \
+  --workspace research
+
 hyperview ui panel add \
   --workspace research \
   --panel-id label-histogram \
-  --title "Label Histogram" \
+  --extension label-histogram \
+  --extension-panel label-histogram \
   --position right \
-  --module-file agent-context/panels/label-histogram/index.js
 ```
 
 Add two runtime scatter panels bound to explicit layouts, side by side:
@@ -184,6 +244,22 @@ hyperview ui panel add \
   --direction right
 ```
 
+Python launch scripts can encode the same composition without calling runtime
+internals:
+
+```python
+view = hv.ui.View(
+    hv.ui.Horizontal(
+        hv.ui.Scatter("uncha-poincare", title="UNCHA", layout_key=uncha_layout),
+        hv.ui.Scatter("hycoclip-poincare", title="HyCoCLIP", layout_key=hycoclip_layout),
+    ),
+    hv.ui.ExtensionPanel("notes", extension="notes", panel="notes", position="right"),
+)
+session = hv.launch(dataset, block=False)
+session.ui.add_extension(".hyperview/extensions/notes")
+session.ui.apply_view(view)
+```
+
 Remove a runtime panel by id:
 
 ```bash
@@ -192,9 +268,25 @@ hyperview ui panel remove \
   --panel-id hycoclip-poincare
 ```
 
-## Plugins and Tools
+Pin nearest-neighbor results to a specific embedding layout:
+
+```bash
+hyperview ui similarity set \
+  --workspace research \
+  --sample-id <sample-id> \
+  --layout-key <layout-key> \
+  --k 18
+```
+
+Clear the explicit nearest-neighbor context:
+
+```bash
+hyperview ui similarity clear --workspace research
+```
+
+## Extensions and Tools
 
-Create backend-plus-frontend plugins under `.hyperview/extensions/<name>/` so they can be versioned with the project and auto-attached on `hyperview serve`. For a server that is already running, install one explicitly:
+Create backend-plus-frontend extensions under `.hyperview/extensions/<name>/` so they can be versioned with the project and auto-registered on `hyperview serve`. For a server that is already running, install one explicitly:
 
 ```bash
 hyperview extension add .hyperview/extensions/selection-profile \
@@ -202,11 +294,11 @@ hyperview extension add .hyperview/extensions/selection-profile \
   --json
 ```
 
-Inspect and run installed plugin tools:
+Inspect and run installed extension tools:
 
 ```bash
 hyperview extension list --json
-# => {"extensions":[{"name":"selection-profile","folder":"...","workspace_id":"research","panels":["selection-profile"],"tools":[{"uri":"selection_profile.summarize",...}]}]}
+# => {"extensions":[{"name":"selection-profile","folder":"...","workspace_id":"research","panel_definitions":[{"id":"selection-profile",...}],"tools":[{"uri":"selection_profile.summarize",...}]}]}
 
 hyperview tools list --json
 hyperview tools run selection_profile.summarize \
@@ -220,4 +312,4 @@ hyperview tools run selection_profile.summarize \
 - `--param 'top_k=5'` for numbers
 - `--param 'enabled=true'` for booleans
 - `--param 'name=foo'` for short strings (raw fallback) or `--param 'name="foo bar"'` for explicit JSON strings
-- `--param 'ids=["a","b"]'` or `--param 'opts={"k":1}'` for arrays/objects
+- `--param 'ids=["a","b"]'` or `--param 'opts={"k":1}'` for arrays/objects

hyperview-0.4.2/.agents/skills/hyperview-cli/references/plugins.md → hyperview-0.6.0/.agents/skills/hyperview-cli/references/extensions.md

@@ -1,12 +1,17 @@
-# Plugins
+# Extensions
 
-Use this guide when creating a HyperView plugin that includes backend Python tools and a frontend panel.
+Use this guide when creating a HyperView extension that includes backend Python tools and a frontend panel.
 
 ## Model
 
-A plugin is a local extension folder with an `extension.toml` manifest. One folder can register Python tools, native panel modules, or both.
+An extension is a local folder with an `extension.toml` manifest. One folder can register Python tools, panel modules, or both.
 
-Preferred shape for agent-authored, project-versioned plugins:
+Extensions define reusable capabilities. They should not encode a whole workspace
+layout or know about sibling panels. Compose concrete demo/workspace layouts
+from Python with `hv.ui.View(...)` and `session.ui.apply_view(...)`, or from
+the CLI with `hyperview ui panel add --extension ...`.
+
+Preferred shape for agent-authored, project-versioned extensions:
 
 ```text
 .hyperview/extensions/selection-profile/
@@ -37,6 +42,10 @@ file = "panel.jsx"
 
 Valid panel positions are `right`, `bottom`, and `center`.
 
+Treat `position` as a weak default for where the panel usually belongs. Cross-panel
+relationships such as "this scatter is right of that scatter" belong to the
+workspace view/composition layer, not the extension manifest.
+
 ## Backend Tools
 
 Tools are plain Python functions decorated with `@tool("namespace.name")`. The first argument is a `RunContext`.
@@ -69,13 +78,13 @@ def summarize_selection(ctx: RunContext, *, sample_ids: list[str] | None = None)
     }
 ```
 
-Use `ctx.dataset` for active dataset reads, `ctx.workspace` for workspace UI state, `ctx.extension_storage` for per-plugin writable files, `ctx.url_for(path)` for renderable artifact URLs, and `ctx.submit_job(...)` for long-running work.
+Use `ctx.dataset` for active dataset reads, `ctx.workspace` for workspace UI state, `ctx.extension_storage` for per-extension writable files, `ctx.url_for(path)` for renderable artifact URLs, and `ctx.submit_job(...)` for long-running work.
 
 ### RunContext and Sample shapes
 
 - `ctx.dataset` — the active `Dataset`. Iterate samples with `for s in ctx.dataset.samples:` (returns `list[Sample]`). Look up by id with `ctx.dataset.get_samples_by_ids(ids)`.
 - `ctx.workspace.ui.selected_ids` — current selection (`list[str]`).
-- `ctx.extension_storage` — `pathlib.Path` to a writable per-plugin folder.
+- `ctx.extension_storage` — `pathlib.Path` to a writable per-extension folder.
 - `ctx.url_for(path)` — returns a fetchable URL for a file under `extension_storage`.
 - `ctx.submit_job(...)` — schedule long-running work; returns a job handle.
 
@@ -123,9 +132,22 @@ export default function SelectionProfilePanel() {
 }
 ```
 
-Available SDK hooks include `usePanelRuntimeState`, `usePanelDatasetInfo`, `usePanelSamplesView`, `usePanelSelection`, `usePanelCommands`, `usePanelUiState`, `usePanelClient`, and `useTool`.
+Available SDK hooks include `usePanelRuntimeState`, `usePanelHostState`, `usePanelDatasetInfo`, `usePanelSamplesView`, `usePanelSelectedSamples`, `usePanelSelection`, `usePanelHover`, `usePanelLayouts`, `usePanelLayoutView`, `usePanelCommands`, `usePanelUiState`, `usePanelClient`, and `useTool`.
+
+For dataset-wide panel behavior, prefer `usePanelClient().querySamples(...)`,
+`aggregateSamples(...)`, `selectSamples(...)`, `getSamplesByIds(...)`,
+`searchSimilar(...)`, or a backend tool over scanning a fixed
+`listSamples({ limit: ... })` page or hand-building API URLs in the browser.
+
+Use `usePanelHostState()` for low-level synchronized host state instead of
+importing frontend internals. Use narrower hooks such as `usePanelSelection()`,
+`usePanelSelectedSamples()`, `usePanelHover()`, `usePanelLayouts()`, and
+`usePanelLayoutView()` when the panel only needs one part of that state. Use
+`usePanelCommands()` for host writes. Selection and active-layout changes
+persist to runtime UI state by default; pass `{ persist: false }` only for
+local transient UI changes.
 
-`useTool(uri)` returns `{ run, result, loading, error, reset }`. Call `run(params)` to invoke the tool; `result` holds the last successful return value, `loading` is true while a call is in flight, and `error` is the last failure message (or `null`). See [native-panels.md](native-panels.md#hook-return-shapes) for the full hook return shape table.
+`useTool(uri)` returns `{ run, result, loading, error, reset }`. Call `run(params)` to invoke the tool; `result` holds the last successful return value, `loading` is true while a call is in flight, and `error` is the last failure message (or `null`). See [panel-modules.md](panel-modules.md#hook-return-shapes) for the full hook return shape table.
 
 ## CLI Workflow
 
@@ -135,7 +157,7 @@ Start a runtime for an existing workspace and dataset:
 hyperview serve --workspace research --dataset cifar10_demo --no-browser
 ```
 
-If the plugin already exists under `.hyperview/extensions/`, starting `hyperview serve` attaches it automatically. For a server that is already running, install or reload the plugin explicitly:
+If the extension already exists under `.hyperview/extensions/`, starting `hyperview serve` registers it automatically. For a server that is already running, install or reload the extension explicitly:
 
 ```bash
 hyperview extension add .hyperview/extensions/selection-profile \
@@ -143,6 +165,19 @@ hyperview extension add .hyperview/extensions/selection-profile \
   --json
 ```
 
+Installing an extension registers its tools and panel definitions. To instantiate
+a panel from the CLI, add an extension-backed panel instance:
+
+```bash
+hyperview ui panel add \
+  --workspace research \
+  --panel-id selection-profile \
+  --extension selection-profile \
+  --extension-panel selection-profile \
+  --position right \
+  --json
+```
+
 Inspect the result:
 
 ```bash
@@ -166,11 +201,34 @@ Reload after editing files:
 hyperview extension reload selection-profile --json
 ```
 
+Compose a demo view from Python instead of importing runtime internals:
+
+```python
+import hyperview as hv
+
+view = hv.ui.View(
+    hv.ui.Horizontal(
+        hv.ui.Scatter("clip-map", title="CLIP", layout_key=clip_layout),
+        hv.ui.Scatter("hycoclip-map", title="HyCoCLIP", layout_key=hycoclip_layout),
+    ),
+    hv.ui.ExtensionPanel(
+        "readout",
+        extension="catalog-readout",
+        panel="readout",
+        position="right",
+    ),
+)
+
+session = hv.launch(dataset, block=False)
+session.ui.add_extension(".hyperview/extensions/catalog-readout")
+session.ui.apply_view(view)
+```
+
 ## Verification
 
-A good plugin smoke test proves all of these paths:
+A good extension smoke test proves all of these paths:
 
-- `extension add` returns the plugin with expected tools and panels.
+- `extension add` returns the extension with expected tools and panel definitions.
 - `GET /api/tools` (or `hyperview tools list --json`) includes the tool URI.
 - `hyperview tools run ...` returns data from the active dataset.
 - Tool-generated files under `ctx.extension_storage` are fetchable from URLs returned by `ctx.url_for(...)`.
@@ -180,7 +238,7 @@ A good plugin smoke test proves all of these paths:
 
 ## Constraints
 
-- Treat plugins as trusted local code. Python tools are imported and executed in the HyperView runtime process.
+- Treat extensions as trusted local code. Python tools are imported and executed in the HyperView runtime process.
 - Do not use bare npm imports in panel modules unless you bundle first.
-- Keep plugin source outside `frontend/src`; the runtime loads it from local files.
-- Keep plugin examples small and high-level. Avoid private HyperView APIs in user-facing examples.
+- Keep extension source outside `frontend/src`; the runtime loads panel modules from local extension files.
+- Keep extension examples small and high-level. Avoid private HyperView APIs in user-facing examples.

hyperview-0.6.0/.agents/skills/hyperview-cli/references/panel-modules.md

@@ -0,0 +1,171 @@
+# Panel Modules
+
+Use this guide when writing a custom HyperView panel module that should behave like a built-in panel. Panel modules are shipped through [extensions.md](extensions.md).
+
+## Model
+
+HyperView no longer treats runtime-added panels as iframe HTML pages.
+
+Runtime custom panels are now panel modules:
+
+- the user writes a local JavaScript module file
+- the module is declared in an extension manifest
+- the module is instantiated through `hv.ui.ExtensionPanel(...)` or `hyperview ui panel add --extension ...`
+- HyperView loads that module directly into the host React tree
+- the module can use the stable `window.HyperViewPanelSDK` surface
+
+Built-in panels and runtime panels now share the same host panel system.
+
+Use this surface for frontend-only panel code. Package it as an extension even
+when it does not need Python tools. If the task is to open several panels in a
+particular arrangement, use a workspace view from Python
+(`hv.ui.View(...)` with `hv.launch(..., view=...)`) or the CLI `hyperview ui ...`
+commands. Do not import `HyperViewRuntime`, `CustomPanelSpec`, or `Session` from
+demo/user-facing scripts just to arrange panels.
+
+## Panel Module Contract
+
+A runtime panel module must export either:
+
+- a default React component
+- or a named export `Panel`
+
+The module runs in the browser and should use the SDK from `window.HyperViewPanelSDK`.
+When a Python view provides panel `props`, HyperView passes them to the component
+as the `props` prop, alongside `panel` and `panelId`; panel code can also read
+them with `HyperViewPanelSDK.hooks.usePanelProps()`.
+
+Minimal example:
+
+```js
+const sdk = globalThis.HyperViewPanelSDK;
+const { React, components, hooks } = sdk;
+const { Panel, PanelToolbar } = components;
+const { usePanelRuntimeState } = hooks;
+
+export default function MyPanel() {
+  const { runtimeDatasetName } = usePanelRuntimeState();
+
+  return React.createElement(
+    Panel,
+    { className: "h-full" },
+    React.createElement(PanelToolbar, {
+      items: [{ id: "dataset", label: "Dataset", value: runtimeDatasetName || "unknown" }],
+    }),
+    React.createElement("div", { style: { padding: 12 } }, "Hello from a panel module")
+  );
+}
+```
+
+## Stable SDK Surface
+
+Current global SDK fields:
+
+- `React`
+- `components.Panel`
+- `components.PanelHeader`
+- `components.PanelTitle`
+- `components.PanelToolbar`
+- `components.PanelToolbarButton`
+- `components.PanelToolbarMenu`
+- `hooks.usePanelClient()`
+- `hooks.usePanelCommands()`
+- `hooks.usePanelDatasetInfo()`
+- `hooks.usePanelHostState()`
+- `hooks.usePanelHover()`
+- `hooks.usePanelInstance()`
+- `hooks.usePanelLayouts()`
+- `hooks.usePanelLayoutView()`
+- `hooks.usePanelProps()`
+- `hooks.usePanelRuntimeState()`
+- `hooks.usePanelSamples()`
+- `hooks.usePanelSamplesView()`
+- `hooks.usePanelSelectedSamples()`
+- `hooks.usePanelSelection()`
+- `hooks.usePanelUiState()`
+- `hooks.useTool(uri)`
+- `createClient(workspaceId)`
+
+Important distinction:
+
+- `usePanelSamplesView()` gives access to host-managed collection state and is the best hook for panels that should stay synchronized with the visible HyperView UI.
+- `usePanelHostState()` gives low-level read access to the same host state used by built-in panels, without importing frontend internals.
+- `usePanelClient()` or `createClient()` is the escape hatch for direct backend reads and control-plane calls.
+- `useTool(uri)` calls an installed backend tool registered by an extension and returns `{ loading, result, error, run, reset }`.
+
+### Hook return shapes
+
+Verified against the current `panel-sdk` surface:
+
+- `usePanelSelection()` → `{ selectedIds: string[], selectionSource: SelectionUpdateSource }`
+- `usePanelCommands()` → `{ setLabelFilter, setHoveredId, clearLassoSelection, clearSelection(): void, setSelection(ids, { source?, persist?, clearLasso? }): Promise<RuntimeSnapshot | null>, showSimilar({ sampleId, layoutKey?, spaceKey?, k?, source?, focus?, persist? }): Promise<RuntimeSnapshot | null>, setActiveLayout(layoutKey, { persist? }): Promise<RuntimeSnapshot | null>, setLayoutViewCamera(layoutKey, camera3d): void, setLayoutViewCameraPersisted(layoutKey, camera3d): Promise<null>, focusPanel(panelId): boolean, focusBuiltin(role): boolean, focusPanelByRole(role): boolean, closePanel(panelId): boolean }`
+- `usePanelHover()` → `{ hoveredId, setHoveredId(id), clearHover() }`
+- `usePanelLayoutView(layoutKey?)` → `{ layoutKey, view, camera3d, setCamera3d(camera3d) }`
+- `usePanelLayouts()` → `{ layouts, spaces, get(layoutKey), getSpace(spaceKey), find(query), filter(query) }`; query supports `layoutKey`, `spaceKey`, `geometry`, `modelId`, and `dimension`.
+- `usePanelSelectedSamples({ includeThumbnails? })` → `{ selectedIds, samples, loading, error }`
+- `usePanelRuntimeState()` → `{ activeWorkspaceId, runtimeDatasetName, activeLayoutKey, activeSimilarityQuery, requestedLayoutKey, workspaces, customPanels, viewRevision, layoutViews }`
+- `usePanelHostState()` → grouped low-level host state: `{ instance, runtime, datasetInfo, samples, samplesView, selection, hover, ui, filters, lasso, neighbors }`
+- `usePanelProps()` → props supplied by the concrete `hv.ui.ExtensionPanel(...)` instance
+- `usePanelUiState()` → `{ sampleGridSize, setSampleGridSize, scatterLabelOverlayMode, setScatterLabelOverlayMode }`
+- `usePanelDatasetInfo()` / `usePanelSamples()` / `usePanelSamplesView()` → host-managed dataset and view state
+- `useTool(uri)` → `{ loading: boolean, result: TResult | null, error: string | null, run(params?): Promise<TResult | null>, reset(): void }`
+- `usePanelClient()` → low-level client; pair with `createClient(workspaceId)` for direct API calls. Useful methods include `querySamples`, `aggregateSamples`, `getSamplesByIds`, `searchSimilar`, `setSimilarityQuery`, `clearSimilarityQuery`, `setSelection`, and `selectSamples`.
+
+To clear the current selection from a panel and persist it to the runtime, use `await usePanelCommands().setSelection([])`. Pass `{ persist: false }` only for local transient UI changes.
+
+## Placement
+
+Extension-backed panel instances can be added in:
+
+- `right`
+- `bottom`
+- `center`
+
+Center placement lets a runtime panel behave like a normal center tab.
+
+## CLI Registration
+
+Register the extension, then instantiate a panel module into a running workspace:
+
+```bash
+hyperview extension add .hyperview/extensions/label-histogram \
+  --workspace imagenette-cli-20260412
+
+hyperview ui panel add \
+  --host 127.0.0.1 \
+  --port 6262 \
+  --workspace imagenette-cli-20260412 \
+  --panel-id label-histogram \
+  --extension label-histogram \
+  --extension-panel label-histogram \
+  --position right
+```
+
+## Verification
+
+After `hyperview ui panel add --extension ...`:
+
+- `curl 'http://127.0.0.1:6262/api/runtime?workspace_id=<ws>'` should list the panel under `workspace.ui.custom_panels[*]` with `data.module_src` set to a `/api/panels/content/<ws>/<panel-id>/<file>` URL.
+- Fetching `data.module_src` should return `application/javascript` with your module body.
+- The panel should appear in the live UI in the requested `position` slot.
+
+## Good Practices
+
+- Prefer panel modules over HTML or iframe content.
+- Use `usePanelSamplesView()` for view-synchronized behavior.
+- Use `usePanelCommands()` for host interactions such as label filtering or selection changes.
+- Use `usePanelHostState()` when a custom panel needs low-level synchronized host state such as hover, selection, lasso, neighbors, layout views, or active workspace context.
+- Use `usePanelLayouts()` for layout/space lookup instead of scanning `datasetInfo.layouts` by hand.
+- Use `usePanelSelectedSamples()` for selected sample metadata instead of manually watching selected ids and fetching samples.
+- Use `usePanelClient()` only for data that is not already available through the host state.
+- Use `usePanelClient().querySamples(...)`, `aggregateSamples(...)`, or `selectSamples(...)` for dataset-wide behavior instead of fixed-limit client scans.
+- Use `usePanelClient().searchSimilar(...)` instead of hand-building `/api/search/similar/...` URLs.
+- Keep the panel self-contained under `.hyperview/extensions/<extension-name>/`.
+- If the panel needs sibling assets, keep them next to the module and reference them with relative URLs.
+- Do not render a second title/header inside a normal Dockview runtime panel unless there is a strong reason. Dockview already provides the tab title. Built-in center and runtime panels should usually start with the standardized `PanelToolbar` row.
+
+## Current Limitation
+
+Panel modules should currently be authored as browser-loadable JavaScript modules.
+
+If an agent wants TypeScript or JSX ergonomics, it should bundle or transpile to JavaScript before registration.