hyperview 0.6.2__tar.gz → 1.0.0__tar.gz

{hyperview-0.6.2 → hyperview-1.0.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, 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.
+description: Use HyperView's control-plane CLI for hyperview serve, static workspace export, 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:
@@ -30,6 +30,7 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 - Register a custom embedding provider.
 - Compute embeddings or layouts without restarting the UI.
 - Export paper-ready static 3D embedding figures without opening the UI.
+- Export read-only static demo bundles with `hyperview export`.
 - Switch the active workspace, layout, or selection in a running session.
 - Add, remove, or compose extension-backed panel instances.
 - Create, install, reload, or use a local extension with Python tools and browser panels.
@@ -43,7 +44,8 @@ HyperView currently supports Python 3.10 through 3.13; `--python 3.12` keeps the
 5. Submit embedding or layout jobs through the runtime.
 6. Use `hyperview ui ...` commands to switch what the live UI shows.
 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.
+8. Export read-only static demos with `hyperview export <workspace-id> --out bundle/`.
+9. For extensions, create an extension folder and install it into the running workspace.
 
 ## Current model
 
@@ -51,15 +53,36 @@ 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 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.
+- Samples retrieval state lives under the runtime-managed Samples panel state. `ui samples retrieval set-anchor` selects an anchor sample and pins nearest-neighbor context to an explicit layout or space.
 - 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`.
+- Runtime control commands use canonical namespaced ids: `workspace.*`, `panel.<type>.*`, and `collection.*`. Older command ids remain deprecated aliases for compatibility only.
+- Command results carry the runtime snapshot in a `CommandResult` envelope (`ok`, `command`, `result`, `workspace`, `snapshot`, `revision`, `error`). Frontends and agents should apply the returned snapshot instead of doing an immediate `/api/runtime` refetch.
+- Runtime-added panels use the stable thin `HyperViewPanelSDK` surface on `window`.
 - Extensions are repo-local folders with `extension.toml`, optional Python tools, and optional panel modules.
-- Extension panels call Python tools through `HyperViewPanelSDK.hooks.useTool()` or `hyperview tools run`.
+- Extension panels run control commands through the SDK command client; Python tools are still reachable through `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(...)`.
+- Extensions distributed with HyperView use the same manifest and source format as repo-local extensions. Install them with `hyperview extension add --shipped <name>` or `session.ui.add_shipped_extension(...)`; promotion must not require panel/tool source changes.
 - 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.
+- `hyperview export <workspace-id> --out bundle/` writes a self-contained **Shared Space**: a static frontend + JSON/API/media bundle. It is intentionally read-only with respect to durable workspace and backend/model operations, while keeping normal local exploration available: visitors can browse, select, pan/zoom, switch prepared cases, inspect panels, and use exported precomputed data. Backend-only affordances such as arbitrary text inference are hidden when unavailable. The host identifies this mode with the concise `Shared Space` label.
+
+## Session authentication
+
+A running server mints a session token. Reads are open; runtime commands that
+mutate state answer `401 Missing or invalid HyperView session token` without
+it. This bites agents that talk to `/api/control/commands/run` directly.
+
+- The CLI resolves the token itself, from `HYPERVIEW_API_TOKEN` or from the
+  discovery file `server-<port>.json` next to the datasets directory. Prefer
+  the CLI over raw HTTP and this stays invisible.
+- For raw HTTP, send `Authorization: Bearer <token>` or `?token=<token>`.
+- Set `HYPERVIEW_NO_AUTH=1` to declare the server public — a Hugging Face
+  Space has no way to hand a visitor a token, so panel adds 401 without it.
+  Public is not open: anonymous callers keep the viewer commands
+  (`workspace.panel.*`, `panel.*`, `collection.*`, selection, active layout)
+  and get 403 on provider registration, extension install, `tools run`, and
+  embedding/layout compute. Drive those with a token, not by widening the flag.
 
 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.
@@ -72,28 +95,41 @@ Read [references/extensions.md](references/extensions.md) when the task involves
 - 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")`.
+- In comparison demos, fail fast when a required model/provider cannot compute embeddings; do not silently substitute the baseline model as a "candidate" fallback.
 - 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.
+- Runtime panel add/update/remove, sizing, placement, focus, visibility, and state commands share the same control path in CLI and Python. Use `hyperview ui panel ...` or `session.ui`/`session.control`; do not call raw panel-control HTTP routes from examples or demos.
+- Live text retrieval is available only when `/api/dataset` exposes an index whose `query_modes` includes `text`. HyperView derives this from the provider attached to the current runtime, so a stored space labelled multimodal is not sufficient by itself. Use `Session.ui.query_by_text(...)` or the native Samples search box; both resolve to a text-capable index and reject an explicitly requested image-only space.
+- When invoking raw commands, prefer canonical command names: `workspace.panel.add/update/remove/resize/move/focus/close/show`, `workspace.panel.state.get/patch`, `panel.samples.retrieval.*`, `collection.neighbors.create`, and `collection.filter.set`. Treat legacy `ui.*` command ids as deprecated aliases.
 - 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 nearest-neighbor comparisons, use `hyperview ui samples retrieval set-anchor --sample-id ... --layout-key ...` or run `panel.samples.retrieval.set-anchor` / `collection.neighbors.create` through the SDK command client; do not infer neighbor space from whichever scatter panel is focused.
+- For collection-backed Samples panel actions, use `hyperview panel samples show-results ...`, `hyperview panel samples reset`, `hyperview panel samples show-neighbors ...`, and `hyperview panel labels filter ...`; read the returned `result.collection_id` and `result.collection` when relevant. Use the canonical panel id `samples` for the primary shared search/result surface. When a prepared static workspace needs two independent result panes, bind each `hv.ui.Samples` panel with `props={"mode": "results", "collectionId": collection_id}` and update that documented prop through `usePanelActions()`.
+- Use `hyperview ui panel state get/patch` or SDK `usePanelState()` when a panel needs durable panel-owned state. Keep durable state under runtime panel state instead of browser local storage or ad hoc events.
+- For reset controls in panels, run the relevant runtime command through the SDK command client when both selection and nearest-neighbor context should be cleared.
+- Do not use timers or browser storage to wait for panel readiness or guard startup state. Write the intended state through runtime commands or `usePanelState()`.
+- In panel modules, use `hooks.useSampleResults()` to present a curated set in the canonical Samples panel and synchronize selection/focus. Use `hooks.usePanelActions().updateProps(panelId, props)` when one panel needs to update another panel's documented props, and `hooks.usePanelActions().focusPanel(panelId)` when a user action should activate the relevant sibling panel. These helpers work as durable runtime mutations in full mode and ephemeral client-side interactions in static mode; do not hand-roll panel-control requests or raw command envelopes for these common flows.
 - 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.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.
+- An explicit Samples- or Extension-only `hv.ui.View` can launch from dataset records without an embedding or layout. Only include a Scatter panel when the demo genuinely needs a visualization; Scatter views still require a layout or embedding space.
 - 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`.
+- Treat host focus/resize helpers as transient user-action helpers, not as startup layout machinery. For durable control from a panel, run the corresponding `workspace.panel.*` command.
 - 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.
+- Keep extensions self-contained: `extension.toml`, tools, a `panel.jsx` module (preferred over `.js`), 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 panel modules over raw HTML. The panel system no longer relies on iframes.
+- Author custom panels as `panel.jsx` using `window.HyperViewPanelSDK` public hooks only. HyperView standardizes the data and interaction contract (props, selection, collections, sample results, sibling `updateProps`, panel state), not the panel's visual design. A panel is free to render any JSX, CSS, SVG, Canvas, or WebGL experience that fits its purpose.
+- Do not reach for private runtime/frontend APIs from extension panels. If a behavior is not on the public SDK or CLI/API surface, do not invent a side channel.
 - For paper diagrams, prefer `hyperview figure export` over browser screenshots unless the user explicitly needs exact UI chrome.
+- For public, read-only examples-gallery demos, create a Shared Space with `hyperview export <workspace-id> --out bundle/` instead of keeping a Python server awake. When a bundle belongs below a containing static site, pass its exact URL prefix with `--mount-path /spaces/<slug>` and copy the resulting bundle into that path. Use **Live Space** for the runtime-connected deployment that can run new queries, providers, and workspace mutations.
 - 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.
 
@@ -101,8 +137,8 @@ Read [references/extensions.md](references/extensions.md) when the task involves
 
 The runtime exposes JSON discovery endpoints alongside the CLI. Use them to obtain layout keys, sample IDs, and registered tools/panels for follow-up commands:
 
-- `GET /api/runtime?workspace_id=<ws>` &mdash; full snapshot. Read `workspace.ui.active_layout_key`, `workspace.ui.selected_ids`, `workspace.ui.custom_panels[*].data.module_src`, and registered `extensions`/`tools`.
+- `GET /api/runtime?workspace_id=<ws>` &mdash; full snapshot. Read `workspace.ui.active_layout_key`, `workspace.ui.selected_ids`, `workspace.ui.panels`, `workspace.ui.custom_panels[*].state`, `workspace.ui.custom_panels[*].data.module_src`, and registered `extensions`/`tools`.
 - `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`).
 
-Prefer layout metadata over parsing layout-key strings. Use `/api/dataset`, `usePanelLayouts()`, or `dataset.list_layouts()` when filtering by geometry, dimension, model, or space.
+Prefer layout metadata over parsing layout-key strings. Use `/api/dataset`, exported runtime snapshots, or `dataset.list_layouts()` when filtering by geometry, dimension, model, or space.

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

@@ -60,6 +60,17 @@ hyperview dataset create cifar10_demo \
   --label-key label
 ```
 
+Create a multimodal dataset with captions:
+
+```bash
+hyperview dataset create coco_captions_demo \
+  --hf-dataset HuggingFaceM4/COCO \
+  --split train \
+  --image-key image \
+  --text-key sentences \
+  --samples 500
+```
+
 Create a persisted dataset from a local image directory:
 
 ```bash
@@ -204,6 +215,71 @@ hyperview figure export figures/embedding-panel-a.png \
   --title "ArcFace spherical embeddings"
 ```
 
+## Shared Spaces
+
+Export a read-only, self-contained Shared Space for a workspace:
+
+```bash
+hyperview export research --out dist/research-demo
+```
+
+When the bundle will be copied below another static site, declare its stable
+mount path during export:
+
+```bash
+hyperview export research \
+  --out dist/research-demo \
+  --mount-path /spaces/research
+```
+
+The exporter rebases the frontend shell and records `/spaces/research` in
+`hyperview-static.json`. Copy the bundle contents into that exact directory
+inside the containing site's document root. Static API, media, and panel-module
+requests remain scoped to the mounted bundle; no proxy, cookie, or referrer
+routing is required.
+
+Sample similarity is omitted by default. Enable a bounded precomputed index
+when the demo exposes nearest-neighbor browsing:
+
+```bash
+hyperview export research --out dist/research-demo --similarity-k 25
+```
+
+The bundle contains the packaged static frontend, `api/runtime.json`,
+`api/dataset.json`, sample shards under `api/samples/`, media and thumbnails,
+layout coordinate JSON under `api/embeddings/`, materialized collection items
+under `api/collections/`, and extension panel modules under
+`api/panels/content/`. It also writes a versioned `hyperview-static.json`
+manifest and a static-assets-only `wrangler.jsonc` configuration. Deploy the
+bundle to Cloudflare from its output directory with:
+
+```bash
+npx wrangler deploy --config wrangler.jsonc
+```
+
+The generated `index.html` sets `window.__HYPERVIEW_STATIC__ = true`. In this
+mode the frontend reads JSON files from the bundle. Selection, prepared-case
+panel prop changes, panel state, filtering, and result presentation remain
+ephemeral client-side interactions. Durable workspace writes, Python tools,
+model execution, and arbitrary inference/search are unavailable; controls for
+those capabilities are hidden. The host shows the notice
+`Shared Space`.
+
+Python launch/session code can export the same bundle:
+
+```python
+session = hv.launch(dataset, block=False)
+session.export("dist/research-demo", workspace_id="research", similarity_k=25)
+```
+
+For persisted workspaces, use the top-level API:
+
+```python
+import hyperview as hv
+
+hv.export_workspace("research", "dist/research-demo")
+```
+
 ## Runtime UI
 
 Discover an existing layout key and sample IDs before mutating runtime state:
@@ -215,6 +291,17 @@ curl --max-time 2 'http://127.0.0.1:6262/api/embeddings?workspace_id=research' |
 
 If no layout exists yet (`active_layout_key` is `null` and `/api/embeddings` returns nothing), create one with `hyperview embeddings compute ... --layout euclidean:2d` (creates embeddings + layout) or `hyperview layouts compute ... --space-key <space-key> --layout euclidean:2d` (adds a layout to an existing embedding space).
 
+Runtime command ids are namespaced:
+
+- `workspace.*` for workspace/view/panel placement and panel-owned state storage
+- `panel.<type>.*` for panel-owned transitions such as Samples retrieval
+- `collection.*` for materialized filters, neighbors, and query result sets
+
+Every control command returns a `CommandResult` envelope with `ok`, `command`,
+`result`, `workspace`, `snapshot`, `revision`, and optional `error`. Apply the
+returned `snapshot` when present. Do not issue an immediate `/api/runtime`
+refetch unless a legacy endpoint did not return a snapshot.
+
 Switch the live UI to a layout and selection:
 
 ```bash
@@ -224,12 +311,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 custom panel through an extension:
+Add a custom panel through an extension. Panel add/update/remove and panel
+layout controls share HyperView's public control command path; prefer these CLI
+commands or the matching Python `session.ui` helpers in examples.
 
 ```bash
 hyperview extension add .hyperview/extensions/label-histogram \
   --workspace research
 
+# The same manifest/source format can be distributed with HyperView.
+hyperview extension add --shipped <extension-name> \
+  --workspace research
+
 hyperview ui panel add \
   --workspace research \
   --panel-id label-histogram \
@@ -328,6 +421,22 @@ hyperview ui panel close --workspace research --panel-id notes
 hyperview ui panel show --workspace research --panel-id notes
 ```
 
+Read or patch durable panel-owned state:
+
+```bash
+hyperview ui panel state get \
+  --workspace research \
+  --panel-id samples \
+  --json
+
+hyperview ui panel state patch \
+  --workspace research \
+  --panel-id samples \
+  --state-json '{"settings":{"density":"compact"}}' \
+  --expected-revision 0 \
+  --json
+```
+
 Remove a runtime panel by id:
 
 ```bash
@@ -336,20 +445,60 @@ hyperview ui panel remove \
   --panel-id hycoclip-poincare
 ```
 
-Pin nearest-neighbor results to a specific embedding layout:
+Pin nearest-neighbor results to the Samples panel state for a specific embedding layout:
 
 ```bash
-hyperview ui similarity set \
+hyperview ui samples retrieval set-anchor \
   --workspace research \
   --sample-id <sample-id> \
-  --layout-key <layout-key> \
+  --index-id space:<space-key> \
+  --k 18
+
+hyperview ui samples retrieval set-k \
+  --workspace research \
+  --k 36
+
+hyperview ui samples retrieval set-text \
+  --workspace research \
+  --query "a dog playing in the park" \
+  --index-id space:<space-key> \
   --k 18
 ```
 
-Clear the explicit nearest-neighbor context:
+Clear the explicit Samples retrieval context:
 
 ```bash
-hyperview ui similarity clear --workspace research
+hyperview ui samples retrieval clear --workspace research
+```
+
+Use `hyperview ui samples retrieval ...` for compatibility with existing CLI
+flows. Raw commands should use the canonical `panel.samples.retrieval.*`
+command ids.
+
+Use panel collection shortcuts when the desired outcome is a Samples panel collection:
+
+```bash
+hyperview panel samples show-results \
+  --workspace research \
+  --sample-id sample-1 \
+  --sample-id sample-8 \
+  --json
+
+hyperview panel samples reset --workspace research --json
+
+hyperview panel samples show-neighbors \
+  --workspace research \
+  --sample-id <sample-id> \
+  --index-id space:<space-key> \
+  --k 18 \
+  --json
+
+hyperview panel labels filter \
+  --workspace research \
+  --value cat \
+  --json
+
+hyperview panel labels filter --workspace research --clear
 ```
 
 ## Extensions and Tools

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

@@ -45,6 +45,15 @@ position = "right"
 file = "panel.jsx"
 ```
 
+Browser-only panels are static-compatible by default. A panel that requires a
+live API or Python tool must declare that requirement so static exports can keep
+the panel in the view without publishing an unusable module:
+
+```toml
+static_compatible = false
+static_reason = "Requires the selection_profile.summarize Python tool."
+```
+
 Valid panel positions are `right`, `bottom`, and `center`.
 
 Treat `position` as a weak default for where the panel usually belongs. Cross-panel
@@ -101,65 +110,64 @@ Use `ctx.dataset` for active dataset reads, `ctx.workspace` for workspace UI sta
 
 ## Browser Panel
 
-Panel modules must be browser-loadable JavaScript modules. They export a default React component or named `Panel`, and use `globalThis.HyperViewPanelSDK`.
+Prefer `panel.jsx`. Modules export a default React component or named `Panel`,
+and must use only `globalThis.HyperViewPanelSDK` public hooks. Prioritize the
+data/interaction contract (props, selection, collections, sample results,
+sibling prop updates, panel state) over visual polish.
 
-```js
+```jsx
 const sdk = globalThis.HyperViewPanelSDK;
 if (!sdk) throw new Error("HyperViewPanelSDK is not available on window.");
 
-const { React, components, hooks } = sdk;
-const { Panel, PanelToolbar, PanelToolbarButton } = components;
-const { usePanelSelection, useTool } = hooks;
+const { React, hooks } = sdk;
+const { useSelection, usePanelState } = hooks;
 
 export default function SelectionProfilePanel() {
-  const { selectedIds } = usePanelSelection();
-  const profile = useTool("selection_profile.summarize");
+  const { selectedIds } = useSelection();
+  const { state, patchState } = usePanelState();
   const selectionKey = selectedIds.join("|");
 
   React.useEffect(() => {
-    profile.run({ sample_ids: selectedIds });
-  }, [profile.run, selectionKey]);
-
-  const result = profile.result;
-
-  return React.createElement(
-    Panel,
-    { className: "h-full" },
-    React.createElement(PanelToolbar, {
-      items: [
-        { id: "selection", label: "Selection", value: String(selectedIds.length) },
-        { id: "status", label: "Status", value: profile.loading ? "running" : result ? "ready" : "idle" },
-      ],
-      actions: React.createElement(PanelToolbarButton, { onClick: () => profile.run({ sample_ids: selectedIds }) }, "Refresh"),
-    }),
-    React.createElement("pre", { style: { padding: 12, overflow: "auto" } }, JSON.stringify(result, null, 2))
+    patchState({ last_selection: selectedIds });
+  }, [patchState, selectionKey]);
+
+  return (
+    <main style={{ padding: 12, font: "12px system-ui" }}>
+      <div>{`Selected: ${selectedIds.length}`}</div>
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+    </main>
   );
 }
 ```
 
-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 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 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
-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.
+Available SDK hooks are intentionally thin: `useCommandClient`, `usePanelState`,
+`usePanelActions`, `useSelection`, `useSampleResults`, `useCollection`,
+`useSamples`, `useTool`, `listTools`, and `useHostAdapter`. See
+[panel-modules.md](panel-modules.md) for return shapes.
+
+For dataset-wide panel behavior, prefer runtime collections and
+`useSamples(collectionId)` over scanning a fixed page or hand-building API URLs
+in the browser. When a panel needs a new filtered or nearest-neighbor result
+set, run `collection.filter.set`, `collection.neighbors.create`, or
+`panel.samples.retrieval.*` through `useCommandClient()`.
+
+Use `useSelection()` for synchronized selection state. Use `usePanelState()` for
+panel-owned props/state. Use `usePanelActions().updateProps(...)` for documented
+sibling panel prop changes (including prepared-case switching in static exports).
+For two independent prepared result panes, construct each native Samples panel
+with `props={{"mode": "results", "collectionId": collection_id}}`; then switch
+the bound collection with `updateProps(panelId, { mode: "results", collectionId })`.
+Result mode preserves prepared order, shows rank numbers, and suppresses the
+live text-search bar. Use `useSampleResults()` instead when one canonical
+Samples panel should own the shared result surface.
+Use `useHostAdapter()` only for transient host actions such as focus; durable
+layout/state changes should go through `workspace.*` commands. In static
+exports, mutating backend commands are disabled, while selection and panel
+state patches remain client-side and ephemeral.
 
 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.
+and use SDK commands for control-plane writes. Python tools are invoked with
+`hyperview tools run` or from the panel via `useTool()` when the host exposes it.
 
 ## CLI Workflow
 
@@ -180,6 +188,19 @@ hyperview extension add .hyperview/extensions/selection-profile \
 Installing an extension registers its tools and panel definitions. To instantiate
 a panel from the CLI, add an extension-backed panel instance:
 
+Extensions distributed with HyperView use the same folder, manifest, panel,
+tool, props, state, command, query, and static-export contracts. Install one by
+name without locating its package folder:
+
+```bash
+hyperview extension add --shipped <extension-name> \
+  --workspace research \
+  --json
+```
+
+Promotion from repo-local to shipped distribution must not require changes to
+the extension's panel or tool source.
+
 ```bash
 hyperview ui panel add \
   --workspace research \