Name the HyperView home directory and let a re-authored Samples collection win

Two footguns from the Precision Regions rebuild. The workspace registry was
the parent of the datasets directory, so runs with sibling datasets dirs
shared workspaces.json and stale panel state leaked into an export.
HYPERVIEW_HOME now names the directory that holds datasets, media, and the
registries; HYPERVIEW_DATASETS_DIR alone behaves as before.

Re-applying a view over a persisted workspace kept the previous run's panel
state even when the view authored a different collection_id for a Samples
panel. A changed authored collection now reopens the panel on it, the same
way authored initial state already wins; an unchanged view still leaves a
visitor's navigation alone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7Xrrx3fhVzCCSZSBGjEDa

Author: mnm-matin

docs/architecture-plan-2026-09.md

@@ -247,12 +247,13 @@ collection when the workspace stores it and falls back to every sample.
 
 Two operational facts that came out of the same debugging:
 
-- The workspace registry lives in the parent of `HYPERVIEW_DATASETS_DIR`
+- The workspace registry lived in the parent of `HYPERVIEW_DATASETS_DIR`
   (`<parent>/workspaces.json`), so two datasets dirs with the same parent
-  share workspaces. A reproducible export needs its own parent directory, not
-  just its own datasets dir.
-- Re-applying a view over a persisted workspace keeps the previous run's panel
-  state when the panel id already exists, even if the authored `collectionId`
-  prop changed. Authored *initial state* wins over a previous run; authored
-  *props* do not. Whether the Samples collection prop should be treated as
-  initial state is open.
+  shared workspaces. Fixed by naming the home directory: `HYPERVIEW_HOME`
+  holds datasets, media, and the registries; `HYPERVIEW_DATASETS_DIR` alone
+  keeps the old parent rule. Build-then-export runs set `HYPERVIEW_HOME`.
+- Re-applying a view over a persisted workspace kept the previous run's panel
+  state even when the authored `collectionId` prop changed. Now a changed
+  authored collection reopens the Samples panel on it, the same way authored
+  initial state wins over a previous run; an unchanged view still leaves a
+  visitor's navigation alone.

docs/datasets.md

@@ -12,7 +12,7 @@ dataset = hv.Dataset("my_dataset")
 dataset = hv.Dataset("my_dataset", persist=False)
 ```
 
-**Storage location:** `~/.hyperview/datasets/` (configurable via `HYPERVIEW_DATABASE_DIR`)
+**Storage location:** `~/.hyperview/datasets/`. `HYPERVIEW_HOME` moves the whole `~/.hyperview` tree (datasets, media, and the workspace registry together); `HYPERVIEW_DATASETS_DIR` moves only the datasets.
 
 Internally, each dataset is stored as two Lance tables (directories) inside that folder:
 - `hyperview_{dataset_name}.lance/` (samples)

docs/static-spaces.md

@@ -192,6 +192,15 @@ the image and passes the flag, so the container keeps one copy of the media
 instead of two. Do not use it on a workstation, where the bundle can be moved,
 deleted, or exported over.
 
+HyperView keeps its state under one home directory: `~/.hyperview`, or
+`HYPERVIEW_HOME` when set. Datasets, media, and the workspace registry
+(`workspaces.json`) all live there. `HYPERVIEW_DATASETS_DIR` moves the datasets
+alone; without `HYPERVIEW_HOME` the registry then sits in that directory's
+parent, so two datasets directories with the same parent share one registry.
+A reproducible build-then-export run should set `HYPERVIEW_HOME` to a fresh
+directory, so nothing a previous run persisted (panel state included) leaks
+into the bundle.
+
 Restore is idempotent. A container that restarts against the same datasets
 directory reuses the dataset it finds rather than re-ingesting, and
 re-registering vectors and coordinates is an upsert.

src/hyperview/runtime.py

@@ -7,6 +7,7 @@
 import importlib
 import inspect
 import json
+import os
 import queue
 import threading
 import time
@@ -33,7 +34,7 @@
     merge_default_props,
     validate_json_contract,
 )
-from hyperview.storage.config import StorageConfig
+from hyperview.storage.config import StorageConfig, get_default_home_dir
 from hyperview.storage.schema import (
     index_id_for_space_key,
     parse_layout_dimension,
@@ -156,8 +157,19 @@ def _json_merge_patch(current: dict[str, Any], patch: dict[str, Any]) -> dict[st
 
 
 def get_runtime_config_dir() -> Path:
-    datasets_dir = StorageConfig.default().datasets_dir
-    config_dir = datasets_dir.parent
+    """Where the workspace, provider, and job registries live.
+
+    ``HYPERVIEW_HOME`` when set. Otherwise the parent of the datasets
+    directory, which is ``~/.hyperview`` by default -- and, when only
+    ``HYPERVIEW_DATASETS_DIR`` is set, whatever directory contains it. Two
+    datasets directories with the same parent therefore share one registry;
+    set ``HYPERVIEW_HOME`` to keep a run fully separate.
+    """
+
+    if os.environ.get("HYPERVIEW_HOME"):
+        config_dir = get_default_home_dir()
+    else:
+        config_dir = StorageConfig.default().datasets_dir.parent
     config_dir.mkdir(parents=True, exist_ok=True)
     return config_dir
 
@@ -752,6 +764,15 @@ def to_dict(self) -> dict[str, Any]:
         }
 
 
+def _authored_collection_id(panel: CustomPanelSpec) -> str | None:
+    """The collection a view authored for a Samples panel, if any."""
+
+    authored = panel.props.get("collectionId", panel.props.get("collection_id"))
+    if isinstance(authored, str) and authored.strip():
+        return authored.strip()
+    return None
+
+
 def _samples_collection_state(collection: CollectionState) -> dict[str, Any]:
     return {
         "collection_id": collection.id,
@@ -1619,13 +1640,43 @@ def _opening_samples_collection_locked(
         know -- opens on every sample, as before.
         """
 
-        authored = panel.props.get("collectionId", panel.props.get("collection_id"))
-        if isinstance(authored, str) and authored.strip():
-            stored = workspace.collections.get(authored.strip())
+        authored = _authored_collection_id(panel)
+        if authored is not None:
+            stored = workspace.collections.get(authored)
             if stored is not None:
                 return stored
         return self._build_all_collection_locked(workspace)
 
+    def _reopen_samples_collection_locked(
+        self,
+        workspace: WorkspaceState,
+        panel: CustomPanelSpec,
+    ) -> None:
+        """Move a Samples panel the workspace already knows onto its newly authored collection.
+
+        A previous run's state normally survives re-applying a view, so a
+        visitor's navigation is not undone by a restart. Changing the authored
+        ``collection_id`` is the author speaking again, and it wins the same
+        way authored initial state does.
+        """
+
+        definition = self._definition_for_panel_spec_locked(panel)
+        if definition is None or definition.panel_type != "samples" or not workspace.dataset_name:
+            return
+        existing = workspace.ui.panels.get(panel.id)
+        if existing is None:
+            return
+        state = dict(existing.state)
+        state.update(
+            _samples_collection_state(self._opening_samples_collection_locked(workspace, panel))
+        )
+        if state == existing.state:
+            return
+        workspace.ui.panels[panel.id] = PanelStateEntry(
+            state=state,
+            state_revision=existing.state_revision + 1,
+        )
+
     def _apply_initial_panel_states_locked(
         self,
         workspace: WorkspaceState,
@@ -2814,6 +2865,7 @@ def replace_custom_panels(
                     self._bump_version()
                 return workspace
 
+            previous_panels = {panel.id: panel for panel in workspace.ui.custom_panels}
             workspace.ui.custom_panels = next_panels
             workspace.ui.has_explicit_view = next_has_explicit_view
             workspace.ui.active_panel_id = next_active_panel_id
@@ -2823,6 +2875,11 @@ def replace_custom_panels(
             self._prune_panel_states_locked(workspace)
             for panel in next_panels:
                 self._seed_default_panel_state_locked(workspace, panel)
+                previous = previous_panels.get(panel.id)
+                if previous is not None and _authored_collection_id(
+                    previous
+                ) != _authored_collection_id(panel):
+                    self._reopen_samples_collection_locked(workspace, panel)
             self._apply_initial_panel_states_locked(
                 workspace,
                 next_panels,

src/hyperview/storage/config.py

@@ -5,28 +5,42 @@
 from pathlib import Path
 
 
+def get_default_home_dir() -> Path:
+    """The directory HyperView keeps its state in.
+
+    ``HYPERVIEW_HOME`` when set, otherwise ``~/.hyperview``. Datasets, media,
+    and the workspace, provider, and job registries all live under it unless
+    an individual ``HYPERVIEW_*_DIR`` variable moves one of them. Point two
+    processes at different homes and they share nothing.
+    """
+    env_dir = os.environ.get("HYPERVIEW_HOME")
+    if env_dir:
+        return Path(env_dir)
+    return Path.home() / ".hyperview"
+
+
 def get_default_datasets_dir() -> Path:
     """Get the default datasets directory.
 
-    Uses HYPERVIEW_DATASETS_DIR env var if set, otherwise ~/.hyperview/datasets/
+    Uses HYPERVIEW_DATASETS_DIR env var if set, otherwise <home>/datasets/
     Each dataset gets its own subdirectory with isolated LanceDB tables.
     """
     env_dir = os.environ.get("HYPERVIEW_DATASETS_DIR")
     if env_dir:
         return Path(env_dir)
-    return Path.home() / ".hyperview" / "datasets"
+    return get_default_home_dir() / "datasets"
 
 
 def get_default_media_dir() -> Path:
     """Get the default media directory for downloaded images.
 
-    Uses HYPERVIEW_MEDIA_DIR env var if set, otherwise ~/.hyperview/media/
+    Uses HYPERVIEW_MEDIA_DIR env var if set, otherwise <home>/media/
     Similar to FiftyOne's ~/fiftyone/huggingface/hub/ pattern.
     """
     env_dir = os.environ.get("HYPERVIEW_MEDIA_DIR")
     if env_dir:
         return Path(env_dir)
-    return Path.home() / ".hyperview" / "media"
+    return get_default_home_dir() / "media"
 
 
 @dataclass

tests/conftest.py

@@ -7,10 +7,9 @@
 registry the demos and Static Space exports read from, where a test's workspace
 id can collide with a real one.
 
-Redirecting both storage roots at a per-session temporary directory pins every
-registry path with them: `get_runtime_config_dir()` derives the config directory
-from `datasets_dir.parent`, so workspaces.json, providers.json and jobs.json all
-follow the datasets directory here.
+Redirecting `HYPERVIEW_HOME` and both storage roots at a per-session temporary
+directory pins every registry path with them: `get_runtime_config_dir()` is the
+home directory, so workspaces.json, providers.json and jobs.json all land there.
 """
 
 from __future__ import annotations
@@ -30,9 +29,11 @@ def isolate_hyperview_store(tmp_path_factory: pytest.TempPathFactory):
     media_dir.mkdir()
 
     previous = {
+        "HYPERVIEW_HOME": os.environ.get("HYPERVIEW_HOME"),
         "HYPERVIEW_DATASETS_DIR": os.environ.get("HYPERVIEW_DATASETS_DIR"),
         "HYPERVIEW_MEDIA_DIR": os.environ.get("HYPERVIEW_MEDIA_DIR"),
     }
+    os.environ["HYPERVIEW_HOME"] = str(root)
     os.environ["HYPERVIEW_DATASETS_DIR"] = str(datasets_dir)
     os.environ["HYPERVIEW_MEDIA_DIR"] = str(media_dir)
     try:

tests/test_public_panel_api.py

@@ -175,6 +175,46 @@ def test_a_samples_panel_opens_on_its_authored_collection_whatever_its_id() -> N
     assert panels["everything"].state["collection"]["kind"] == "all"
 
 
+def test_reauthoring_the_samples_collection_moves_a_persisted_panel() -> None:
+    session, runtime, workspace_id = _make_session()
+    first = session.create_collection(["sample-4", "sample-2"], name="A", workspace_id=workspace_id)
+    second = session.create_collection(["sample-1"], name="B", workspace_id=workspace_id)
+
+    session.ui.apply_view(
+        hv.ui.View(hv.ui.Samples(id="samples", mode="results", collection_id=first)),
+        workspace_id=workspace_id,
+    )
+    # A visitor navigates elsewhere; re-applying the same view must not undo that.
+    runtime.patch_panel_state(
+        workspace_id,
+        "samples",
+        _samples_state_for(runtime, workspace_id, second),
+    )
+    session.ui.apply_view(
+        hv.ui.View(hv.ui.Samples(id="samples", mode="results", collection_id=first)),
+        workspace_id=workspace_id,
+    )
+    assert runtime.get_workspace(workspace_id).ui.panels["samples"].state["collection_id"] == second
+
+    # The author changing the collection is a new statement, and it wins.
+    session.ui.apply_view(
+        hv.ui.View(hv.ui.Samples(id="samples", mode="results", collection_id=second)),
+        workspace_id=workspace_id,
+    )
+    session.ui.apply_view(
+        hv.ui.View(hv.ui.Samples(id="samples", mode="results", collection_id=first)),
+        workspace_id=workspace_id,
+    )
+    state = runtime.get_workspace(workspace_id).ui.panels["samples"].state
+    assert state["collection_id"] == first
+    assert state["collection"]["id"] == first
+
+
+def _samples_state_for(runtime, workspace_id: str, collection_id: str) -> dict:
+    collection = runtime.get_workspace(workspace_id).collections[collection_id]
+    return {"collection_id": collection.id, "collection": collection.to_dict()}
+
+
 def test_an_unknown_authored_collection_falls_back_to_every_sample() -> None:
     session, runtime, workspace_id = _make_session()
 

tests/test_workspace_layout_and_registry.py

@@ -257,3 +257,29 @@ def read_registry() -> None:
         reader.join(timeout=5)
 
     assert not parse_errors
+
+
+def test_runtime_config_dir_follows_hyperview_home(monkeypatch, tmp_path) -> None:
+    from hyperview.runtime import get_runtime_config_dir
+    from hyperview.storage.config import get_default_datasets_dir, get_default_media_dir
+
+    home = tmp_path / "home"
+    monkeypatch.setenv("HYPERVIEW_HOME", str(home))
+    monkeypatch.delenv("HYPERVIEW_DATASETS_DIR", raising=False)
+    monkeypatch.delenv("HYPERVIEW_MEDIA_DIR", raising=False)
+
+    assert get_default_datasets_dir() == home / "datasets"
+    assert get_default_media_dir() == home / "media"
+    assert get_runtime_config_dir() == home
+
+    # A datasets dir elsewhere moves the data, not the registries.
+    monkeypatch.setenv("HYPERVIEW_DATASETS_DIR", str(tmp_path / "elsewhere" / "datasets"))
+    assert get_runtime_config_dir() == home
+
+
+def test_runtime_config_dir_without_home_is_the_datasets_parent(monkeypatch, tmp_path) -> None:
+    from hyperview.runtime import get_runtime_config_dir
+
+    monkeypatch.delenv("HYPERVIEW_HOME", raising=False)
+    monkeypatch.setenv("HYPERVIEW_DATASETS_DIR", str(tmp_path / "run" / "datasets"))
+    assert get_runtime_config_dir() == tmp_path / "run"