hyperview 0.6.0__tar.gz → 0.6.2__tar.gz

{hyperview-0.6.0 → hyperview-0.6.2}/.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, 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.
+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/update, extension add, tools run, panel modules, Python 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,10 +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.
+- Export paper-ready static 3D embedding figures without opening the UI.
 - Switch the active workspace, layout, or selection in a running session.
 - Add, remove, or compose extension-backed panel instances.
-- Create, install, reload, or test a local extension with Python backend tools and a frontend panel.
+- Create, install, reload, or use a local extension with Python tools and browser panels.
 
 ## Core workflow
 
@@ -50,32 +50,42 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - One dataset per workspace.
 - 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.
+- `ui layout set` changes the active layout and opens the matching built-in scatter panel.
 - `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 can be built-in samples panels, 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`.
 - 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`.
+- Extension panels call Python 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.
+- In practice, create datasets and workspaces before starting the runtime for that workspace.
 - `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, 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.
+Read [references/extensions.md](references/extensions.md) when the task involves packaging or registering custom panel code or Python tools.
 
 ## Agent guidance
 
-- Prefer CLI commands over direct file edits when the goal is to operate a running HyperView session.
+- Prefer CLI commands 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.
+- In Python dataset setup code, use public ingestion helpers such as `dataset.add_samples([...])` or `dataset.add_images_dir(...)`.
+- Prefer built-in providers before registering custom providers. For Hyper3-CLIP, use `dataset.compute_embeddings(model="hyper3-clip-v0.5", provider="hyper-models")`.
+- When a project truly needs a custom Python provider, use `hyperview provider register ...` from the CLI or `hv.register_provider(...)` in Python.
 - 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`.
+- Use first-class view layout fields for panel sizing and visibility: `hv.ui.PanelLayout(width=..., min_width=...)` in Python, or `hyperview ui panel resize/move/focus/close/show` from the CLI. Do not pass Dockview-specific sizing through panel props.
+- To retitle an existing runtime panel or replace its props, use `hyperview ui panel update --panel-id ... --title ... --props-json ...` instead of remove/re-add when preserving panel identity matters.
 - 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.
+- For demos/spaces that launch HyperView from Python, compose panels with `hv.ui.Horizontal`, `hv.ui.Vertical`, `hv.ui.Tabs`, `hv.ui.Grid`, `hv.ui.Scatter`, `hv.ui.Samples`, `hv.ui.ExtensionPanel`, and `hv.ui.PanelLayout`; keep extension manifests focused on reusable panel/tool definitions.
+- Keep layout orchestration out of panel modules. A panel should not close, hide, or rearrange sibling panels on mount; use `hv.ui.View(...)` or `hyperview ui panel ...` to compose the workspace.
+- Treat local `focusPanel` and `closePanel` as transient user-action helpers, not as startup layout machinery. For durable control from a panel, use SDK commands such as `setActivePanel`, `setPanelVisible`, `resizePanel`, and `movePanel`.
+- Pass only documented panel props through `hv.ui.ExtensionPanel(..., props=...)`.
 - Tools can write files under `ctx.extension_storage` and return `ctx.url_for(path)` for panel-renderable artifact URLs.
+- Put query results, benchmark tables, contact sheets, and other generated artifacts behind extension tools or compact panel props. Do not embed large base64 payloads or generated datasets inside panel JavaScript.
+- Keep cross-panel coordination in host/runtime state. Do not use `window.dispatchEvent` / `window.addEventListener` as shared panel state.
 - 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.
@@ -83,7 +93,7 @@ Read [references/extensions.md](references/extensions.md) when the task involves
 - 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 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 paper diagrams, prefer `hyperview figure export` over browser screenshots unless the user explicitly needs exact UI chrome.
 - 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.
 
@@ -95,4 +105,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.
+Prefer layout metadata over parsing layout-key strings. Use `/api/dataset`, `usePanelLayouts()`, or `dataset.list_layouts()` when filtering by geometry, dimension, model, or space.

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

@@ -95,13 +95,29 @@ hyperview status --json
 
 ## Providers, Embeddings, and Layouts
 
-Register a custom provider:
+Use built-in providers directly when possible. Hyper3-CLIP is available through
+the `hyper-models` provider:
+
+```python
+dataset.compute_embeddings(model="hyper3-clip-v0.5", provider="hyper-models")
+```
+
+Register a custom provider only when the model is not available through a
+built-in provider:
 
 ```bash
 hyperview provider register my-provider \
   --import-path my_pkg.provider:MyProvider
 ```
 
+The same registration is available from Python:
+
+```python
+import hyperview as hv
+
+hv.register_provider("my-provider", "my_pkg.provider:MyProvider", overwrite=True)
+```
+
 Compute checkpoint-backed embeddings and a layout:
 
 ```bash
@@ -144,7 +160,7 @@ hyperview figure export figures/embedding-sphere.png \
 
 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.
+The export path does not require opening the UI. It supports 3D layouts only; 2D layouts are rejected with a validation message.
 
 Paper defaults are tuned for academic figures:
 
@@ -220,6 +236,20 @@ hyperview ui panel add \
   --extension label-histogram \
   --extension-panel label-histogram \
   --position right \
+  --width 340 \
+  --min-width 280 \
+```
+
+Add the built-in samples panel through the same runtime panel API:
+
+```bash
+hyperview ui panel add \
+  --workspace research \
+  --panel-id samples \
+  --kind builtin \
+  --builtin-panel samples \
+  --props-json '{"mode":"browse"}' \
+  --position right
 ```
 
 Add two runtime scatter panels bound to explicit layouts, side by side:
@@ -244,8 +274,7 @@ hyperview ui panel add \
   --direction right
 ```
 
-Python launch scripts can encode the same composition without calling runtime
-internals:
+Python launch scripts can encode the same composition:
 
 ```python
 view = hv.ui.View(
@@ -253,13 +282,52 @@ view = hv.ui.View(
         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"),
+    hv.ui.ExtensionPanel(
+        "notes",
+        extension="notes",
+        panel="notes",
+        position="right",
+        layout=hv.ui.PanelLayout(width=340, min_width=280),
+    ),
+    active_panel="notes",
 )
 session = hv.launch(dataset, block=False)
 session.ui.add_extension(".hyperview/extensions/notes")
 session.ui.apply_view(view)
 ```
 
+Update an existing runtime panel title or props without changing its identity:
+
+```bash
+hyperview ui panel update \
+  --workspace research \
+  --panel-id samples \
+  --title "Ranked Samples" \
+  --props-json '{"mode":"ranked","rank":{"anchorSampleId":"<sample-id>","layoutKey":"<layout-key>","k":18}}' \
+  --json
+```
+
+Resize, move, focus, hide, or show a runtime panel through durable view state:
+
+```bash
+hyperview ui panel resize \
+  --workspace research \
+  --panel-id notes \
+  --width 380 \
+  --min-width 300
+
+hyperview ui panel move \
+  --workspace research \
+  --panel-id notes \
+  --position right \
+  --reference-panel-id samples \
+  --direction right
+
+hyperview ui panel focus --workspace research --panel-id notes
+hyperview ui panel close --workspace research --panel-id notes
+hyperview ui panel show --workspace research --panel-id notes
+```
+
 Remove a runtime panel by id:
 
 ```bash
@@ -286,7 +354,7 @@ hyperview ui similarity clear --workspace research
 
 ## Extensions and Tools
 
-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:
+Create 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 \

{hyperview-0.6.0 → hyperview-0.6.2}/.agents/skills/hyperview-cli/references/extensions.md

@@ -1,6 +1,6 @@
 # Extensions
 
-Use this guide when creating a HyperView extension that includes backend Python tools and a frontend panel.
+Use this guide when creating a HyperView extension that includes Python tools and a browser panel.
 
 ## Model
 
@@ -11,6 +11,11 @@ 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 ...`.
 
+Extensions should also keep generated data out of panel source. If a panel
+needs ranked query results, benchmark summaries, contact sheets, or other
+artifacts, generate or read them from an extension tool and return compact JSON or
+URLs from `ctx.url_for(...)`.
+
 Preferred shape for agent-authored, project-versioned extensions:
 
 ```text
@@ -46,7 +51,7 @@ Treat `position` as a weak default for where the panel usually belongs. Cross-pa
 relationships such as "this scatter is right of that scatter" belong to the
 workspace view/composition layer, not the extension manifest.
 
-## Backend Tools
+## Python Tools
 
 Tools are plain Python functions decorated with `@tool("namespace.name")`. The first argument is a `RunContext`.
 
@@ -94,9 +99,9 @@ Use `ctx.dataset` for active dataset reads, `ctx.workspace` for workspace UI sta
 - `sample.label: str | None`
 - `sample.metadata: dict[str, Any]`
 
-## Frontend Panel
+## Browser Panel
 
-Panel modules must be browser-loadable JavaScript modules. They export a default React component or named `Panel`, and use `globalThis.HyperViewPanelSDK` rather than importing from app internals.
+Panel modules must be browser-loadable JavaScript modules. They export a default React component or named `Panel`, and use `globalThis.HyperViewPanelSDK`.
 
 ```js
 const sdk = globalThis.HyperViewPanelSDK;
@@ -136,16 +141,23 @@ Available SDK hooks include `usePanelRuntimeState`, `usePanelHostState`, `usePan
 
 For dataset-wide panel behavior, prefer `usePanelClient().querySamples(...)`,
 `aggregateSamples(...)`, `selectSamples(...)`, `getSamplesByIds(...)`,
-`searchSimilar(...)`, or a backend tool over scanning a fixed
+`searchSimilar(...)`, or an extension tool over scanning a fixed
 `listSamples({ limit: ... })` page or hand-building API URLs in the browser.
+Sample reads default to `includeThumbnails: false`; use each sample's
+`thumbnail_url` for images, and request inline thumbnails only when a panel
+explicitly needs base64 data.
 
-Use `usePanelHostState()` for low-level synchronized host state instead of
-importing frontend internals. Use narrower hooks such as `usePanelSelection()`,
+Use `usePanelHostState()` for synchronized host state. 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.
+update host state immediately and persist to runtime UI state in the
+background by default. Pass `{ persist: true }` only when the caller must wait
+for durable runtime state, and pass `{ persist: false }` for local transient UI
+changes.
+
+Do not use browser globals such as `window.dispatchEvent` to synchronize panels,
+and use SDK commands for control-plane writes.
 
 `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.
 
@@ -195,13 +207,13 @@ hyperview tools run selection_profile.summarize \
   --json
 ```
 
-Reload after editing files:
+Reload an installed extension:
 
 ```bash
 hyperview extension reload selection-profile --json
 ```
 
-Compose a demo view from Python instead of importing runtime internals:
+Compose a demo view from Python:
 
 ```python
 import hyperview as hv
@@ -216,7 +228,9 @@ view = hv.ui.View(
         extension="catalog-readout",
         panel="readout",
         position="right",
+        layout=hv.ui.PanelLayout(width=340, min_width=280),
     ),
+    active_panel="readout",
 )
 
 session = hv.launch(dataset, block=False)
@@ -224,21 +238,9 @@ session.ui.add_extension(".hyperview/extensions/catalog-readout")
 session.ui.apply_view(view)
 ```
 
-## Verification
-
-A good extension smoke test proves all of these paths:
-
-- `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(...)`.
-- `GET /api/runtime?workspace_id=<workspace>` includes the panel under `workspace.ui.custom_panels[*]` with `data.module_src` set to a `/api/panels/content/<workspace>/<panel-id>/<file>` URL.
-- Fetching `data.module_src` returns `application/javascript` with your module body.
-- In the browser, the panel imports successfully and a `useTool()` call returns a result.
-
 ## Constraints
 
 - 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 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.
+- Panel modules should use the SDK global and extension-local assets.
+- Keep extension files under `.hyperview/extensions/<name>/`.
+- Keep extension examples small and high-level. Use documented HyperView APIs.

{hyperview-0.6.0 → hyperview-0.6.2}/.agents/skills/hyperview-cli/references/panel-modules.md

@@ -11,17 +11,16 @@ 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
+- HyperView loads that module through the host panel system
 - 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
+Use this surface for browser 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.
+commands.
 
 ## Panel Module Contract
 
@@ -89,16 +88,16 @@ Current global SDK fields:
 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 }`.
+- `usePanelHostState()` gives read access to the same host state used by built-in panels.
+- `usePanelClient()` is an escape hatch for API data reads that are not already exposed through host state or commands.
+- `useTool(uri)` calls an installed Python tool registered by an extension and returns `{ loading, result, error, run, reset }`.
 
 ### Hook return shapes
 
-Verified against the current `panel-sdk` surface:
+Current hook return shapes:
 
 - `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 }`
+- `usePanelCommands()` → `{ setLabelFilter, setHoveredId, clearLassoSelection, clearSelection(): void, setSelection(ids, { source?, persist?, clearLasso? }): Promise<RuntimeSnapshot | null>, showSimilar({ sampleId, layoutKey, k?, source?, focus?, persist? }): Promise<RuntimeSnapshot | null>, setActiveLayout(layoutKey, { persist? }): Promise<RuntimeSnapshot | null>, setLayoutViewCamera(layoutKey, camera3d): void, setLayoutViewCameraPersisted(layoutKey, camera3d): Promise<null>, setPanelLayout(panelId, { width?, height?, minWidth?, minHeight?, maxWidth?, maxHeight? }), resizePanel(panelId, { width?, height?, minWidth?, minHeight?, maxWidth?, maxHeight? }), movePanel(panelId, { position, referencePanelId?, direction? }), setPanelVisible(panelId, visible), setActivePanel(panelId), focusPanel(panelId): boolean, focusBuiltin(role): boolean, focusPanelByRole(role): boolean, closePanel(panelId): boolean }`. `showSimilar` is layout-scoped: pass the layout key and HyperView resolves the associated embedding space automatically. `persist` accepts `true`, `false`, or `"background"` for selection/layout/similarity commands; omitted/`"background"` updates local state immediately and writes runtime state asynchronously, `true` waits for runtime persistence, and `false` is local-only.
 - `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`.
@@ -109,9 +108,13 @@ Verified against the current `panel-sdk` surface:
 - `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`.
+- `usePanelClient()` → API data client. Prefer host hooks and `usePanelCommands()` for UI state; useful data methods include `querySamples`, `aggregateSamples`, `getSamplesByIds`, `searchSimilar`, 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.
+Sample reads default to `includeThumbnails: false` and return `thumbnail_url`
+for image rendering. Request inline thumbnails only when the panel specifically
+needs base64 thumbnail payloads.
+
+To clear the current selection from a panel and enqueue runtime persistence, use `await usePanelCommands().setSelection([])`. Pass `{ persist: true }` when the code must wait for runtime persistence, and pass `{ persist: false }` only for local transient UI changes.
 
 ## Placement
 
@@ -141,14 +144,6 @@ hyperview ui panel add \
   --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.
@@ -160,12 +155,17 @@ After `hyperview ui panel add --extension ...`:
 - 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.
+- Use `commands.showSimilar({ sampleId, layoutKey })` for nearest-neighbor UI state; pass the layout key and let HyperView resolve the embedding space.
+- Use SDK commands or client methods for control-plane writes.
+- Use `setActivePanel`, `setPanelVisible`, `resizePanel`, and `movePanel` when a panel needs to durably control panel view state. Use local `focusPanel` and `closePanel` only for transient user actions.
+- Do not use `window.dispatchEvent` / `window.addEventListener` to synchronize panel state. Keep shared state in the host/runtime model, or keep the interaction inside one owner panel until a public shared-state hook exists.
+- Do not use `focusPanel` or `closePanel` from mount effects to create the initial workspace layout. Compose startup layout with `hv.ui.View(...)` or CLI panel commands.
+- Pass only documented panel props.
+- Do not embed large generated result sets, base64 contact sheets, or evaluation artifacts in panel JavaScript. Use compact props, extension assets, or extension tools that return artifact 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.
+- Avoid duplicate title/header rows unless the panel has a specific reason. 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.
+Panel modules must be browser-loadable JavaScript modules.

{hyperview-0.6.0 → hyperview-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperview
-Version: 0.6.0
+Version: 0.6.2
 Summary: Open-source dataset curation with hyperbolic embeddings visualization
 Project-URL: Homepage, https://github.com/Hyper3Labs/HyperView
 Project-URL: Documentation, https://github.com/Hyper3Labs/HyperView#readme
@@ -28,8 +28,8 @@ Requires-Dist: embed-anything>=0.7.0
 Requires-Dist: esbuild-py>=0.1.6
 Requires-Dist: fastapi>=0.128.0
 Requires-Dist: huggingface-hub<2.0,>=1.11.0
-Requires-Dist: hyper-models>=0.2.0
-Requires-Dist: lancedb>=0.26.1
+Requires-Dist: hyper-models>=0.3.0
+Requires-Dist: lancedb>=0.33.0
 Requires-Dist: numpy<2.4,>=1.26.4
 Requires-Dist: pillow>=12.1.0
 Requires-Dist: pyarrow>=22.0.0
@@ -44,6 +44,7 @@ Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
 Requires-Dist: ruff>=0.14.13; extra == 'dev'
 Provides-Extra: ml
+Requires-Dist: hyper-models[ml]>=0.3.0; extra == 'ml'
 Requires-Dist: timm>=1.0.0; extra == 'ml'
 Requires-Dist: torch>=2.9.1; extra == 'ml'
 Requires-Dist: torchvision>=0.24.1; extra == 'ml'
@@ -155,7 +156,7 @@ If you use HyperView in research, please cite:
   author  = {{Hyper3Labs}},
   title   = {HyperView: An Interactive Geometric Workbench for Embedding Space Analysis},
   year    = {2026},
-  version = {0.5.0},
+  version = {0.6.2},
   url     = {https://github.com/Hyper3Labs/HyperView}
 }
 ```

{hyperview-0.6.0 → hyperview-0.6.2}/README.md

@@ -104,7 +104,7 @@ If you use HyperView in research, please cite:
   author  = {{Hyper3Labs}},
   title   = {HyperView: An Interactive Geometric Workbench for Embedding Space Analysis},
   year    = {2026},
-  version = {0.5.0},
+  version = {0.6.2},
   url     = {https://github.com/Hyper3Labs/HyperView}
 }
 ```

{hyperview-0.6.0 → hyperview-0.6.2}/pyproject.toml

@@ -28,14 +28,14 @@ dependencies = [
     "uvicorn[standard]>=0.40.0",
     "embed-anything>=0.7.0",
     "huggingface-hub>=1.11.0,<2.0",
-    "hyper-models>=0.2.0",  # PyPI package: https://pypi.org/project/hyper-models/
+    "hyper-models>=0.3.0",  # PyPI package: https://pypi.org/project/hyper-models/
     "numpy>=1.26.4,<2.4",
     "umap-learn>=0.5.11",
     "pillow>=12.1.0",
     "pydantic>=2.12.5",
     "aiofiles>=25.1.0",
     "datasets>=4.5.0",
-    "lancedb>=0.26.1",
+    "lancedb>=0.33.0",
     "pyarrow>=22.0.0",
     "esbuild-py>=0.1.6",
     "tomli>=2.0; python_version<'3.11'",
@@ -50,6 +50,7 @@ dev = [
     "ruff>=0.14.13",
 ]
 ml = [
+    "hyper-models[ml]>=0.3.0",
     "torch>=2.9.1",
     "torchvision>=0.24.1",
     "timm>=1.0.0",

{hyperview-0.6.0 → hyperview-0.6.2}/src/hyperview/__init__.py

@@ -7,12 +7,16 @@ from . import ui as ui
 Dataset = _api.Dataset
 Session = _api.Session
 launch = _api.launch
+register_provider = _api.register_provider
+unregister_provider = _api.unregister_provider
 __version__ = _version.__version__
 
 __all__ = [
     "Dataset",
     "Session",
     "launch",
+    "register_provider",
+    "unregister_provider",
     "ui",
     "__version__",
 ]

{hyperview-0.6.0 → hyperview-0.6.2}/src/hyperview/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.6.0'
-__version_tuple__ = version_tuple = (0, 6, 0)
+__version__ = version = '0.6.2'
+__version_tuple__ = version_tuple = (0, 6, 2)
 
 __commit_id__ = commit_id = None