From e94e6cd01b2576cda74868002e3c15c07c495ebc Mon Sep 17 00:00:00 2001
From: MilagrosMarin <milmarina02@gmail.com>
Date: Wed, 16 Sep 2026 14:21:50 +0200
Subject: [PATCH 1/3] feat!: store the whole figpack bundle as the object
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A figpack figure is the folder. Storing only data.zarr and reassembling a viewer
at render time made the stored object pure Zarr with a figpack marker on it, and
cost three things: the serving container needed a compatible figpack installed,
extension views had nowhere to keep their JavaScript and were refused at insert,
and serve_under() had to assume a layout figpack does not promise — a custom view
may name its Zarr folder differently or carry several.

Settled with Jeremy Magland (Flatiron Institute) on 2026-09-04. Closes #7, the
design half of #4, and #3.

- encode() uploads the bundle value.save() produced, not a subtree of it.
- validate() no longer rejects ExtensionView; extension JavaScript now travels
  with the figure. A round-trip test proves the JS survives.
- serve_under() downloads and publishes the stored bundle. No viewer overlay, no
  import figpack, no reach into the private figpack-figure-dist path, no
  synthesized extension manifest. Its guard moves from data.zarr/.zmetadata to
  index.html, which is what a servable bundle must have at its root.
- show() serves the bundle over HTTP on an ephemeral port and returns the URL. A
  figpack viewer fetches Zarr chunks by range request, so file:// cannot work.
- load() is removed. Its contract was to reconstruct a FigpackView from stored
  data, which no longer describes what is stored; is_loaded went with it, since
  nothing caches a view any more.

Storage grows by the viewer dist, about 2.2 MB per figure. Deliberately accepted:
at realistic figure sizes the data dwarfs it, and content-addressed sharing is an
optimization layer to add later if a pipeline shows the small-figure, high-count
profile — never a change to what the object is.

Breaking: figures written by earlier versions store bare Zarr and will not serve.
Only demo pipelines hold figpack data; reseed rather than convert.
---
 README.md                      |  27 +++---
 src/dj_figpack_codecs/codec.py |  29 +++---
 src/dj_figpack_codecs/ref.py   | 130 +++++++++++----------------
 tests/test_bundle_storage.py   | 160 +++++++++++++++++++++++++++++++++
 tests/test_codec.py            |  67 ++------------
 tests/test_config_threading.py |   2 +-
 tests/test_serve_under.py      |  38 ++++----
 7 files changed, 269 insertions(+), 184 deletions(-)
 create mode 100644 tests/test_bundle_storage.py

diff --git a/README.md b/README.md
index 173e161..21e29a1 100644
--- a/README.md
+++ b/README.md
@@ -69,11 +69,8 @@ ref = (RasterPlot & key).fetch1('visualization')
 print(ref.title)        # "Spike Raster"
 print(ref.description)  # "Unit activity over time"
 
-# Display in browser
+# Serve it over HTTP and open it in a browser
 ref.show()
-
-# Or load the full FigpackView
-view = ref.load()
 ```
 
 ### Jupyter Integration
@@ -86,7 +83,11 @@ ref  # Shows title, description, and action hints
 
 ### Storage Structure
 
-Visualizations are stored as Zarr folders under a **schema-addressed path chosen by the
+A figpack figure is its bundle — viewer, data and extension manifest together — and the
+whole folder is what gets stored. That is what lets a figure be served without `figpack`
+installed, and what gives an extension view somewhere to keep its JavaScript.
+
+Bundles are stored under a **schema-addressed path chosen by the
 framework** (DataJoint's `build_object_path`): it mirrors the schema/table structure,
 encodes primary keys as `attr=value` segments, and ends in a tokenized filename
 (`{attribute}_{token}.zarr`), subject to the store's prefix/partitioning configuration —
@@ -96,6 +97,10 @@ for example:
 {store_location}/demo_showcase/fluorescence_figpack/session_id=4/fig_NPhczfGY.zarr/
 ```
 
+The stored folder holds `index.html`, `assets/`, `data.zarr/` and
+`extension_manifest.json` — exactly what `FigpackView.save()` produced. Treat it as
+opaque: a custom view may name its data folder differently or carry several.
+
 The layout is browsable but framework-owned — do not hand-build or rely on exact paths;
 the database column's metadata (`path`, `store`) is the source of truth.
 
@@ -114,18 +119,16 @@ Lazy reference returned when fetching `<figpack@>` attributes.
 - `description` - Visualization description (no I/O)
 - `path` - Storage path
 - `store` - Store name
-- `is_loaded` - Whether data has been cached
 
 **Methods:**
-- `load()` - Download and return the `FigpackView`
-- `show(**kwargs)` - Download and display in browser
-- `serve_under(base_dir)` - Materialize a servable viewer bundle; returns its relative URL
+- `show(open_browser=True)` - Serve the figure over HTTP; returns its URL
+- `serve_under(base_dir)` - Publish the stored bundle; returns its relative URL
 
 ### Serving a figure in a dashboard
 
-`FigpackRef.serve_under(base_dir)` materializes a self-contained, servable viewer
-bundle (figpack's viewer + the stored `data.zarr`) under `base_dir/<id>/` and returns
-the relative URL `/<id>/index.html`. Dashboards (e.g. dash-datajoint-components'
+`FigpackRef.serve_under(base_dir)` downloads the stored bundle into `base_dir/<id>/`
+and returns the relative URL `/<id>/index.html`. Nothing is assembled and `figpack`
+need not be installed in the serving process. Dashboards (e.g. dash-datajoint-components'
 `PlotGrid`) serve `base_dir` over HTTP and embed the URL in an `<iframe>`; repeated
 calls are idempotent and refresh the directory mtime for TTL-based cache cleaners.
 
diff --git a/src/dj_figpack_codecs/codec.py b/src/dj_figpack_codecs/codec.py
index 395f4a1..37b5dee 100644
--- a/src/dj_figpack_codecs/codec.py
+++ b/src/dj_figpack_codecs/codec.py
@@ -35,11 +35,11 @@ class FigpackCodec(SchemaCodec):
     Store only - requires ``@`` modifier.
 
     Key Features:
-        - **Native format**: Stores as Zarr folder (figpack's native format)
+        - **Native format**: stores figpack's own bundle — viewer, data and
+          extension manifest together, so the object is what figpack produced
         - **Lazy loading**: Metadata available without download
-        - **Dashboard serving**: ``ref.serve_under(base_dir)`` materializes a
-          self-contained viewer bundle (``ref.load()``/``ref.show()`` are not yet
-          implemented — see issue #3)
+        - **Serving**: ``ref.serve_under(base_dir)`` publishes the stored bundle and
+          ``ref.show()`` serves it over HTTP; neither needs ``figpack`` installed
         - **Jupyter integration**: Rich HTML display in notebooks
         - **Schema-addressed**: Browsable paths that mirror database structure
 
@@ -100,8 +100,7 @@ def validate(self, value: Any) -> None:
         Raises
         ------
         TypeError
-            If value is not a FigpackView instance, or is an extension-based
-            view (unsupported in data-only storage).
+            If value is not a FigpackView instance.
         DataJointError
             If the figpack package is not installed.
         """
@@ -119,14 +118,6 @@ def validate(self, value: Any) -> None:
         if not isinstance(value, FigpackView):
             raise TypeError(f"<figpack> requires figpack.FigpackView, got {type(value).__name__}")
 
-        from figpack.core.extension_view import ExtensionView
-
-        if isinstance(value, ExtensionView):
-            raise TypeError(
-                "<figpack> stores figure data only (data.zarr) and cannot yet preserve "
-                "extension JavaScript; extension-based views are not supported."
-            )
-
     def encode(
         self,
         value: "FigpackView",
@@ -184,13 +175,15 @@ def encode(
             bundle_path = Path(tmpdir) / "bundle"
 
             # figpack >= 0.3: save() requires keyword-only `title`. It emits a full
-            # viewer bundle (index.html + assets/ + data.zarr + extension manifest);
-            # we store ONLY data.zarr — the viewer is laid over it at render time by
-            # FigpackRef.serve_under(), so the store never duplicates viewer code.
+            # viewer bundle (index.html + assets/ + data.zarr + extension manifest)
+            # and the whole folder is the object: a figpack figure is not data with a
+            # viewer laid over it at render time, it is the bundle. Storing all of it
+            # is what lets the serving container render without figpack installed, and
+            # what gives an extension view somewhere to keep its JavaScript.
             value.save(str(bundle_path), title=title, description=description)
 
             backend = self._get_backend(store_name, config=config)
-            backend.put_folder(str(bundle_path / "data.zarr"), path)
+            backend.put_folder(str(bundle_path), path)
 
         # Return metadata
         return {
diff --git a/src/dj_figpack_codecs/ref.py b/src/dj_figpack_codecs/ref.py
index 9a1c30b..908d7f2 100644
--- a/src/dj_figpack_codecs/ref.py
+++ b/src/dj_figpack_codecs/ref.py
@@ -63,7 +63,7 @@ class FigpackRef:
     ``NotImplementedError`` pointing at ``serve_under``.
     """
 
-    __slots__ = ("_meta", "_backend", "_cached")
+    __slots__ = ("_meta", "_backend")
 
     def __init__(self, metadata: dict, backend: Any):
         """
@@ -78,7 +78,6 @@ def __init__(self, metadata: dict, backend: Any):
         """
         self._meta = metadata
         self._backend = backend
-        self._cached: FigpackView | None = None
 
     @property
     def title(self) -> str:
@@ -100,41 +99,12 @@ def store(self) -> str | None:
         """Store name (None for default store)."""
         return self._meta.get("store")
 
-    @property
-    def is_loaded(self) -> bool:
-        """True if visualization has been downloaded and cached."""
-        return self._cached is not None
-
-    def load(self) -> "FigpackView":
-        """
-        Download and return the FigpackView. **Not yet implemented.**
-
-        figpack does not currently expose an API that reconstructs a
-        ``FigpackView`` from a stored ``data.zarr`` tree (``figpack.view_figure``
-        is a CLI helper that launches a local HTTP server and returns ``None``),
-        and the previous remote path relied on a ``StorageBackend.get_folder``
-        method that does not exist on DataJoint 2.3. Tracked in issue #3.
-
-        Raises
-        ------
-        NotImplementedError
-            Always. Use :meth:`serve_under` to materialize a servable viewer
-            bundle for browser display.
-        """
-        raise NotImplementedError(
-            "FigpackRef.load() is not yet implemented (see "
-            "https://github.com/datajoint/dj-figpack-codecs/issues/3). "
-            "Use ref.serve_under(base_dir) to materialize a servable viewer "
-            "bundle instead."
-        )
-
     def serve_under(self, base_dir) -> str:
-        """Materialize a servable viewer bundle under ``base_dir`` and return its URL.
+        """Publish the stored bundle under ``base_dir`` and return its URL.
 
-        Assembles ``base_dir/<id>/`` = figpack's viewer dist (shipped inside the
-        installed ``figpack`` package) + this ref's ``data.zarr`` (downloaded from the
-        store) + an empty extension manifest, then returns the leading-"/" relative URL
-        ``/<id>/index.html``. ``<id>`` is a stable hash of the ref's schema-addressed
+        Downloads the stored object — the whole figpack bundle, viewer included — into
+        ``base_dir/<id>/`` and returns the leading-"/" relative URL ``/<id>/index.html``.
+        Nothing is assembled and ``figpack`` need not be installed. ``<id>`` is a stable hash of the ref's schema-addressed
         OAS path — no I/O to compute, distinct primary keys map to distinct directories.
 
         Idempotent and concurrency-tolerant: if ``index.html`` already exists the build
@@ -148,8 +118,6 @@ def serve_under(self, base_dir) -> str:
         This is the ``MaterializableRef`` seam consumed by dash-datajoint-components'
         ``PlotGrid`` (structural typing — no import of the dashboard package here).
         """
-        import figpack  # the viewer dist ships inside the figpack package
-
         base_dir = Path(base_dir)
         fig_id = hashlib.sha1(self.path.encode("utf-8")).hexdigest()[:16]
         dest = base_dir / fig_id
@@ -170,33 +138,27 @@ def serve_under(self, base_dir) -> str:
 
             tmp = Path(tempfile.mkdtemp(dir=str(base_dir), prefix=f".{fig_id}-"))
             try:
-                # 1) figure data (schema-addressed zarr) from the store
-                zarr_dest = tmp / "data.zarr"
+                # The stored object is the whole bundle, so serving is a download.
+                # Nothing here knows figpack's internal layout: a custom view may name
+                # its Zarr folder differently or carry several, and an extension view
+                # brings JavaScript that exists only in the bundle.
                 full_path = self._backend._full_path(self.path)
                 if self._backend.protocol == "file":
-                    shutil.copytree(full_path, zarr_dest)
+                    shutil.copytree(full_path, tmp, dirs_exist_ok=True)
                 else:
-                    self._backend.fs.get(full_path, str(zarr_dest), recursive=True)
+                    self._backend.fs.get(full_path, str(tmp), recursive=True)
 
-                # fsspec's recursive get lands contents *as* dst only when dst
-                # does not pre-exist (guaranteed here by the fresh mkdtemp) —
-                # fail loud if a backend/version ever nests them instead.
-                if not (zarr_dest / ".zmetadata").exists():
+                # fsspec's recursive get lands contents *as* dst only when dst does not
+                # pre-exist; tmp does. Fail loud rather than publish a bundle with no
+                # entry point, which would serve as an unexplained 404.
+                if not (tmp / "index.html").exists():
                     raise DataJointError(
-                        f"figure download produced an unexpected layout under "
-                        f"{zarr_dest} (no data.zarr/.zmetadata) — fsspec "
-                        f"recursive-get semantics may have changed for protocol "
-                        f"{self._backend.protocol!r}"
+                        f"figure download produced an unexpected layout under {tmp} "
+                        f"(no index.html) — fsspec recursive-get semantics may have "
+                        f"changed for protocol {self._backend.protocol!r}, or the "
+                        f"stored object predates bundle storage (issue #7)"
                     )
 
-                # 2) viewer dist (index.html + assets/) from the installed figpack
-                dist = Path(figpack.__file__).parent / "figpack-figure-dist"
-                shutil.copytree(dist, tmp, dirs_exist_ok=True)
-
-                # 3) bundles always carry an extension manifest; data-only storage has
-                #    no extensions (validate() rejects ExtensionView)
-                (tmp / "extension_manifest.json").write_text('{"extensions": []}')
-
                 try:
                     if dest.exists() and not index.exists():
                         shutil.rmtree(dest)  # stale partial build (no index.html)
@@ -219,24 +181,43 @@ def serve_under(self, base_dir) -> str:
             pass  # concurrent rebuild swapped the dir this instant; next call repairs
         return f"/{fig_id}/index.html"
 
-    def show(self, **kwargs) -> None:
-        """
-        Download and display the visualization in browser. **Not yet
-        implemented** — depends on :meth:`load` (tracked in issue #3).
+    def show(self, *, open_browser: bool = True) -> str:
+        """Serve this figure over HTTP and return its URL.
+
+        A figpack viewer fetches its Zarr chunks with HTTP range requests, so
+        opening ``index.html`` from the filesystem does not work — the bundle has to
+        be served. The server runs on an ephemeral port in a daemon thread and lives
+        as long as the process, which suits a notebook or a script; nothing has to be
+        cleaned up.
 
         Parameters
         ----------
-        **kwargs
-            Additional arguments passed to FigpackView.show().
-
-        Raises
-        ------
-        NotImplementedError
-            Always. Use :meth:`serve_under` to materialize a servable viewer
-            bundle for browser display.
+        open_browser : bool, optional
+            Open the URL in the default browser. Default True.
+
+        Returns
+        -------
+        str
+            The figure's URL.
         """
-        view = self.load()
-        view.show(**kwargs)
+        import functools
+        import http.server
+        import socketserver
+        import threading
+        import webbrowser
+
+        served = Path(tempfile.mkdtemp(prefix="figpack-show-"))
+        url_path = self.serve_under(served)
+
+        handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(served))
+        # 0 = ephemeral port, so concurrent shows never collide
+        httpd = socketserver.TCPServer(("127.0.0.1", 0), handler)
+        threading.Thread(target=httpd.serve_forever, daemon=True).start()
+
+        url = f"http://127.0.0.1:{httpd.server_address[1]}{url_path}"
+        if open_browser:
+            webbrowser.open(url)
+        return url
 
     def _repr_html_(self) -> str:
         """
@@ -253,22 +234,19 @@ def _repr_html_(self) -> str:
         desc_html = html.escape(
             self.description[:200] + "..." if len(self.description) > 200 else self.description
         )
-        status = "loaded" if self.is_loaded else "not loaded"
-
         return f"""
         <div style="border: 1px solid #ccc; padding: 10px; border-radius: 5px; max-width: 400px;">
             <div style="font-size: 14px; margin-bottom: 5px;">{title_html}</div>
             <div style="font-size: 12px; color: #666; margin-bottom: 8px;">{desc_html}</div>
             <div style="font-size: 11px; color: #999;">
-                FigpackRef ({status}) | <code>.show()</code> to display | <code>.load()</code> to get view
+                FigpackRef | <code>.show()</code> to display | <code>.serve_under()</code> to publish
             </div>
         </div>
         """
 
     def __repr__(self) -> str:
-        status = "loaded" if self.is_loaded else "not loaded"
         title_preview = f'"{self.title[:30]}..."' if len(self.title) > 30 else f'"{self.title}"'
-        return f"FigpackRef(title={title_preview}, {status})"
+        return f"FigpackRef(title={title_preview})"
 
     def __str__(self) -> str:
         return repr(self)
diff --git a/tests/test_bundle_storage.py b/tests/test_bundle_storage.py
new file mode 100644
index 0000000..9d2f867
--- /dev/null
+++ b/tests/test_bundle_storage.py
@@ -0,0 +1,160 @@
+"""The stored object is the whole figpack bundle, not just its data.
+
+A figpack figure is the folder: viewer, data, and extension manifest together.
+Storing only ``data.zarr`` made the render path depend on a compatible ``figpack``
+being installed in the serving container, and left extension views nowhere to put
+their JavaScript. See issue #7.
+"""
+
+import hashlib
+
+import pytest
+
+
+def _extension_view(js="// demo extension"):
+    from figpack.core.extension_view import ExtensionView
+    from figpack.core.figpack_extension import FigpackExtension
+
+    return ExtensionView(
+        extension=FigpackExtension(name="demo-ext", javascript_code=js),
+        view_type="demo-ext.DemoView",
+    )
+
+
+def test_encode_stores_the_whole_bundle(
+    sample_figpack_view, sample_context, mock_backend, default_store_config, temp_store, mocker
+):
+    """The store holds what ``value.save()`` produced — viewer included."""
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+
+    meta = codec.encode(sample_figpack_view, key=sample_context, store_name="default")
+
+    stored = temp_store / meta["path"]
+    assert (stored / "index.html").exists()
+    assert (stored / "assets").is_dir()
+    assert (stored / "data.zarr" / ".zmetadata").exists()
+    assert (stored / "extension_manifest.json").exists()
+
+
+def test_validate_accepts_extension_view():
+    """Extension JS travels inside the bundle, so extension views are storable.
+
+    The extension is installed on the machine that populates the table and would
+    never exist in the serving container — storing the bundle is what makes such a
+    view portable at all.
+    """
+    from dj_figpack_codecs import FigpackCodec
+
+    FigpackCodec().validate(_extension_view())  # no raise
+
+
+def test_extension_javascript_survives_the_round_trip(
+    sample_context, mock_backend, default_store_config, temp_store, mocker
+):
+    """Storing the bundle has to actually carry the extension's JavaScript."""
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+
+    meta = codec.encode(
+        _extension_view("// SENTINEL-EXT-JS"), key=sample_context, store_name="default"
+    )
+
+    stored = temp_store / meta["path"]
+    manifest = (stored / "extension_manifest.json").read_text()
+    assert "demo-ext" in manifest
+    js = [p for p in stored.rglob("*.js") if "SENTINEL-EXT-JS" in p.read_text(errors="ignore")]
+    assert js, f"extension JS not found under {stored}"
+
+
+def test_serve_under_serves_the_stored_bundle_verbatim(
+    sample_figpack_view,
+    sample_context,
+    mock_backend,
+    default_store_config,
+    temp_store,
+    tmp_path,
+    mocker,
+):
+    """No viewer overlay: what was stored is what gets served.
+
+    Marking the stored viewer proves the served copy came from the store rather
+    than from the installed figpack package's dist.
+    """
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+    meta = codec.encode(sample_figpack_view, key=sample_context, store_name="default")
+
+    stored = temp_store / meta["path"]
+    (stored / "index.html").write_text("<!-- SENTINEL-FROM-STORE -->")
+
+    ref = codec.decode(meta)
+    url = ref.serve_under(tmp_path)
+
+    fig_id = hashlib.sha1(ref.path.encode("utf-8")).hexdigest()[:16]
+    assert url == f"/{fig_id}/index.html"
+    assert (tmp_path / fig_id / "index.html").read_text() == "<!-- SENTINEL-FROM-STORE -->"
+
+
+def test_serve_under_does_not_import_figpack(
+    sample_figpack_view,
+    sample_context,
+    mock_backend,
+    default_store_config,
+    tmp_path,
+    mocker,
+    monkeypatch,
+):
+    """The render path is static file serving — the serving container needs no figpack."""
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+    ref = codec.decode(codec.encode(sample_figpack_view, key=sample_context, store_name="default"))
+
+    import builtins
+
+    real_import = builtins.__import__
+
+    def no_figpack(name, *args, **kwargs):
+        if name == "figpack" or name.startswith("figpack."):
+            raise AssertionError(f"serve_under imported {name}")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", no_figpack)
+    ref.serve_under(tmp_path)
+
+
+def test_show_serves_the_bundle_over_http(
+    sample_figpack_view, sample_context, mock_backend, default_store_config, mocker
+):
+    """show() serves rather than opening a file:// path — a figpack viewer fetches
+    its Zarr chunks over HTTP and cannot load from the filesystem."""
+    import urllib.request
+
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+    ref = codec.decode(codec.encode(sample_figpack_view, key=sample_context, store_name="default"))
+
+    url = ref.show(open_browser=False)
+
+    assert url.startswith("http://127.0.0.1:")
+    with urllib.request.urlopen(url, timeout=10) as r:
+        assert r.status == 200
+        assert b"<!doctype html" in r.read(200).lower()
+
+
+def test_load_is_gone():
+    """load() described reconstructing a FigpackView from stored data. The stored
+    object is a bundle, so that contract no longer describes anything (issue #3)."""
+    from dj_figpack_codecs import FigpackRef
+
+    assert not hasattr(FigpackRef, "load")
diff --git a/tests/test_codec.py b/tests/test_codec.py
index ccb4e42..d7d8df0 100644
--- a/tests/test_codec.py
+++ b/tests/test_codec.py
@@ -21,7 +21,6 @@ def test_metadata_access(self, sample_metadata, mock_backend):
         assert ref.description == "A test plot"
         assert ref.path == "_schema/test_schema/test_table/id=1/visualization.zarr"
         assert ref.store == "default"
-        assert not ref.is_loaded
 
     def test_repr(self, sample_metadata, mock_backend):
         """Test string representation."""
@@ -32,7 +31,6 @@ def test_repr(self, sample_metadata, mock_backend):
 
         assert "FigpackRef" in repr_str
         assert "Test Visualization" in repr_str
-        assert "not loaded" in repr_str
 
     def test_repr_html(self, sample_metadata, mock_backend):
         """Test HTML representation for Jupyter."""
@@ -44,7 +42,7 @@ def test_repr_html(self, sample_metadata, mock_backend):
         assert "Test Visualization" in html
         assert "A test plot" in html
         assert ".show()" in html
-        assert ".load()" in html
+        assert ".serve_under()" in html
 
     def test_empty_metadata(self, mock_backend):
         """Test handling of missing metadata fields."""
@@ -76,20 +74,6 @@ def test_repr_html_escapes_untrusted_metadata(self, mock_backend):
         assert "<img" not in out and "<script>" not in out
         assert "&lt;img" in out and "&lt;script&gt;" in out
 
-    def test_load_and_show_raise_legibly(self, sample_metadata, mock_backend):
-        """load()/show() are not yet implementable (figpack has no view-from-zarr
-        API; DJ 2.3 has no StorageBackend.get_folder) — they must fail with a
-        clear error pointing at serve_under, not an AttributeError. Issue #3."""
-        from dj_figpack_codecs import FigpackRef
-
-        ref = FigpackRef(sample_metadata, mock_backend)
-
-        with pytest.raises(NotImplementedError, match="serve_under"):
-            ref.load()
-        with pytest.raises(NotImplementedError, match="serve_under"):
-            ref.show()
-        assert not ref.is_loaded  # failed load must not poison the cache flag
-
 
 class TestFigpackCodec:
     """Tests for FigpackCodec."""
@@ -146,22 +130,6 @@ def test_validate_rejects_non_figpack_view(self):
         with pytest.raises(TypeError, match="requires figpack.FigpackView"):
             codec.validate(None)
 
-    def test_validate_rejects_extension_view(self):
-        """v1 stores data-only Zarr; extension JS lives outside data.zarr and would be
-        silently dropped — so extension-based views are rejected at insert time."""
-        pytest.importorskip("figpack")
-        from figpack.core.extension_view import ExtensionView
-        from figpack.core.figpack_extension import FigpackExtension
-
-        from dj_figpack_codecs import FigpackCodec
-
-        ext_view = ExtensionView(
-            extension=FigpackExtension(name="demo-ext", javascript_code="// noop"),
-            view_type="demo.View",
-        )
-        with pytest.raises(TypeError, match="extension"):
-            FigpackCodec().validate(ext_view)
-
     def test_validate_accepts_plain_core_view(self):
         """Core (non-extension) views validate — the reference figure type included."""
         pytest.importorskip("figpack")
@@ -177,26 +145,6 @@ def test_validate_accepts_plain_core_view(self):
         )
         FigpackCodec().validate(view)  # no raise
 
-    def test_validate_rejects_plotly_figure_extension_view(self):
-        """Canary: figpack's PlotlyFigure IS an ExtensionView (its JS lives outside
-        data.zarr), so data-only storage must reject it. If figpack ever rebases
-        PlotlyFigure onto a core view, this test flags the policy for re-evaluation."""
-        pytest.importorskip("figpack")
-        plotly = pytest.importorskip("plotly")
-        import plotly.graph_objects as go
-
-        from dj_figpack_codecs import FigpackCodec
-
-        from figpack.views import PlotlyFigure
-
-        fig = PlotlyFigure(fig=go.Figure(data=[go.Scatter(x=[1, 2], y=[3, 4])]))
-        with pytest.raises(TypeError, match="extension"):
-            FigpackCodec().validate(fig)
-
-
-class TestCodecEncodeDecode:
-    """Integration tests for encode/decode cycle."""
-
     def test_encode_produces_metadata(
         self, sample_figpack_view, sample_context, mock_backend, default_store_config, mocker
     ):
@@ -224,7 +172,7 @@ def test_encode_produces_metadata(
         assert metadata["store"] == "default"
         assert ".zarr" in metadata["path"]
 
-    def test_encode_stores_data_only_zarr(
+    def test_encode_stores_the_bundle_with_titled_zarr(
         self,
         sample_figpack_view,
         sample_context,
@@ -233,8 +181,8 @@ def test_encode_stores_data_only_zarr(
         default_store_config,
         mocker,
     ):
-        """encode() uploads figpack's data.zarr only — no viewer files — and the
-        consolidated zarr metadata carries the title."""
+        """encode() uploads the whole bundle, and the consolidated zarr metadata
+        inside it carries the title."""
         import json
 
         from dj_figpack_codecs import FigpackCodec
@@ -245,10 +193,9 @@ def test_encode_stores_data_only_zarr(
         metadata = codec.encode(sample_figpack_view, key=sample_context, store_name="default")
 
         stored = temp_store / metadata["path"]
-        assert (stored / ".zmetadata").exists()  # consolidated zarr metadata
-        assert not (stored / "index.html").exists()  # no viewer in the store
-        assert not (stored / "assets").exists()
-        zmeta = json.loads((stored / ".zmetadata").read_text())
+        assert (stored / "index.html").exists()  # the viewer travels with the figure
+        assert (stored / "data.zarr" / ".zmetadata").exists()  # consolidated zarr metadata
+        zmeta = json.loads((stored / "data.zarr" / ".zmetadata").read_text())
         assert zmeta["metadata"][".zattrs"]["title"] == "Test Visualization"
         assert zmeta["metadata"][".zattrs"]["description"] == "A test plot"
 
diff --git a/tests/test_config_threading.py b/tests/test_config_threading.py
index c521943..8f318cb 100644
--- a/tests/test_config_threading.py
+++ b/tests/test_config_threading.py
@@ -108,7 +108,7 @@ def test_encode_writes_through_connection_config(
         sample_figpack_view, key={**sample_context, "_config": cfg}, store_name="general"
     )
 
-    assert (temp_store / metadata["path"] / ".zmetadata").exists()
+    assert (temp_store / metadata["path"] / "data.zarr" / ".zmetadata").exists()
 
 
 def test_encode_builds_path_from_connection_config(
diff --git a/tests/test_serve_under.py b/tests/test_serve_under.py
index 697b428..ec9369f 100644
--- a/tests/test_serve_under.py
+++ b/tests/test_serve_under.py
@@ -1,4 +1,4 @@
-"""FigpackRef.serve_under(): materialize a servable viewer bundle from stored data.zarr."""
+"""FigpackRef.serve_under(): publish the stored bundle as a servable figure."""
 
 import hashlib
 import os
@@ -20,7 +20,7 @@ def stored_ref(sample_figpack_view, sample_context, mock_backend, default_store_
     return codec.decode(metadata)
 
 
-def test_serve_under_assembles_viewer_bundle(stored_ref, tmp_path):
+def test_serve_under_publishes_the_stored_bundle(stored_ref, tmp_path):
     url = stored_ref.serve_under(tmp_path)
 
     fig_id = hashlib.sha1(stored_ref.path.encode("utf-8")).hexdigest()[:16]
@@ -28,10 +28,10 @@ def test_serve_under_assembles_viewer_bundle(stored_ref, tmp_path):
     assert re.fullmatch(r"/[0-9a-f]{16}/index\.html", url)  # hex id — path-safe by construction
 
     dest = tmp_path / fig_id
-    assert (dest / "index.html").exists()  # viewer dist
+    assert (dest / "index.html").exists()  # viewer, from the store
     assert (dest / "assets").is_dir()
     assert (dest / "data.zarr" / ".zmetadata").exists()  # figure data
-    assert (dest / "extension_manifest.json").read_text() == '{"extensions": []}'
+    assert (dest / "extension_manifest.json").exists()  # written by figpack at encode time
 
 
 def test_serve_under_is_idempotent_and_touches_for_ttl(stored_ref, tmp_path):
@@ -150,9 +150,10 @@ def test_serve_under_remote_backend_uses_fs_get(sample_metadata, tmp_path):
 
     from dj_figpack_codecs import FigpackRef
 
-    remote_zarr = tmp_path / "remote-data.zarr"  # what the fake fs.get delivers
-    remote_zarr.mkdir()
-    (remote_zarr / ".zmetadata").write_text("{}")
+    remote_bundle = tmp_path / "remote-bundle"  # what the fake fs.get delivers
+    (remote_bundle / "data.zarr").mkdir(parents=True)
+    (remote_bundle / "data.zarr" / ".zmetadata").write_text("{}")
+    (remote_bundle / "index.html").write_text("<!-- stored viewer -->")
 
     backend = MagicMock()
     backend.protocol = "s3"
@@ -160,7 +161,7 @@ def test_serve_under_remote_backend_uses_fs_get(sample_metadata, tmp_path):
 
     def fake_get(src, dst, recursive=False):
         assert recursive is True
-        shutil.copytree(remote_zarr, dst)
+        shutil.copytree(remote_bundle, dst, dirs_exist_ok=True)
 
     backend.fs.get.side_effect = fake_get
 
@@ -172,30 +173,33 @@ def fake_get(src, dst, recursive=False):
     fig_id = hashlib.sha1(sample_metadata["path"].encode("utf-8")).hexdigest()[:16]
     assert url == f"/{fig_id}/index.html"
     assert (serve / fig_id / "data.zarr" / ".zmetadata").exists()
+    # the viewer is the one that was stored, not one assembled from a local figpack
+    assert (serve / fig_id / "index.html").read_text() == "<!-- stored viewer -->"
 
 
 def test_serve_under_rejects_nested_download_layout(sample_metadata, tmp_path):
     """fsspec's recursive get is destination-sensitive: if a backend/version ever
-    nests the source dir INSIDE dst (data.zarr/data.zarr/...) instead of landing
-    contents AS dst, serve_under must fail loud — never publish a bundle that
-    serves a broken figure."""
+    nests the source dir INSIDE dst instead of landing contents AS dst, the published
+    bundle would have no index.html at its root. serve_under must fail loud rather
+    than publish a figure that serves as an unexplained 404."""
     from unittest.mock import MagicMock
 
     from datajoint.errors import DataJointError
 
     from dj_figpack_codecs import FigpackRef
 
-    remote_zarr = tmp_path / "remote-data.zarr"
-    remote_zarr.mkdir()
-    (remote_zarr / ".zmetadata").write_text("{}")
+    remote_bundle = tmp_path / "remote-bundle"
+    (remote_bundle / "data.zarr").mkdir(parents=True)
+    (remote_bundle / "data.zarr" / ".zmetadata").write_text("{}")
+    (remote_bundle / "index.html").write_text("<!-- stored viewer -->")
 
     backend = MagicMock()
     backend.protocol = "s3"
     backend._full_path.return_value = "bucket/loc/" + sample_metadata["path"]
 
     def nesting_get(src, dst, recursive=False):
-        # the wrong layout: source dir nested inside dst
-        shutil.copytree(remote_zarr, Path(dst) / "data.zarr")
+        # the wrong layout: source dir nested inside dst, so no index.html at the root
+        shutil.copytree(remote_bundle, Path(dst) / "bundle")
 
     backend.fs.get.side_effect = nesting_get
 
@@ -212,7 +216,7 @@ def nesting_get(src, dst, recursive=False):
     # Recovery: the failed attempt must not wedge the destination — once the
     # backend delivers the correct layout, the same ref publishes normally.
     def correct_get(src, dst, recursive=False):
-        shutil.copytree(remote_zarr, dst)
+        shutil.copytree(remote_bundle, dst, dirs_exist_ok=True)
 
     backend.fs.get.side_effect = correct_get
     url = ref.serve_under(serve)

From a59c12ee174849f4720fea9ab696247b19e8c577 Mon Sep 17 00:00:00 2001
From: MilagrosMarin <milmarina02@gmail.com>
Date: Wed, 16 Sep 2026 14:41:12 +0200
Subject: [PATCH 2/3] fix: honour Range in show(), and clean up its temp
 directory
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

show() served the bundle with Python's stock SimpleHTTPRequestHandler, which has
no Range support. figpack packs many small chunks into large consolidated files
and the viewer ranges into them, so a browser would have pulled whole files —
the difference between a few kilobytes and a gigabyte. figpack's own server
subclasses the stock handler to add exactly this; adding it here rather than
importing theirs keeps the dependency out of the render path.

The first version passed its test only because the sample figure is tiny and
fetching index.html needs no range. The new test asks for a prefix range, a
suffix range, and one past the end, and asserts 206 / Content-Range / 416.

show()'s temp directory is now removed at exit rather than left behind.

The dashboard path was never affected: dash-datajoint-components serves through
Flask's send_from_directory, and Werkzeug handles Range.
---
 src/dj_figpack_codecs/ref.py | 78 ++++++++++++++++++++++++++++++++----
 tests/test_bundle_storage.py | 42 +++++++++++++++++++
 2 files changed, 113 insertions(+), 7 deletions(-)

diff --git a/src/dj_figpack_codecs/ref.py b/src/dj_figpack_codecs/ref.py
index 908d7f2..45ec6c8 100644
--- a/src/dj_figpack_codecs/ref.py
+++ b/src/dj_figpack_codecs/ref.py
@@ -11,8 +11,10 @@
 from __future__ import annotations
 
 import hashlib
+import http.server
 import html
 import os
+import re
 import shutil
 import tempfile
 import time
@@ -184,11 +186,11 @@ def serve_under(self, base_dir) -> str:
     def show(self, *, open_browser: bool = True) -> str:
         """Serve this figure over HTTP and return its URL.
 
-        A figpack viewer fetches its Zarr chunks with HTTP range requests, so
-        opening ``index.html`` from the filesystem does not work — the bundle has to
-        be served. The server runs on an ephemeral port in a daemon thread and lives
-        as long as the process, which suits a notebook or a script; nothing has to be
-        cleaned up.
+        A figpack viewer fetches its data with HTTP range requests, so opening
+        ``index.html`` from the filesystem does not work — the bundle has to be
+        served, by something that honours ``Range``. The server runs on an ephemeral
+        port in a daemon thread and lives as long as the process, which suits a
+        notebook or a script.
 
         Parameters
         ----------
@@ -200,16 +202,17 @@ def show(self, *, open_browser: bool = True) -> str:
         str
             The figure's URL.
         """
+        import atexit
         import functools
-        import http.server
         import socketserver
         import threading
         import webbrowser
 
         served = Path(tempfile.mkdtemp(prefix="figpack-show-"))
+        atexit.register(shutil.rmtree, served, True)
         url_path = self.serve_under(served)
 
-        handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(served))
+        handler = functools.partial(_RangeRequestHandler, directory=str(served))
         # 0 = ephemeral port, so concurrent shows never collide
         httpd = socketserver.TCPServer(("127.0.0.1", 0), handler)
         threading.Thread(target=httpd.serve_forever, daemon=True).start()
@@ -250,3 +253,64 @@ def __repr__(self) -> str:
 
     def __str__(self) -> str:
         return repr(self)
+
+
+class _RangeRequestHandler(http.server.SimpleHTTPRequestHandler):
+    """Static file handler that honours ``Range``.
+
+    figpack packs many small chunks into large consolidated files and the viewer
+    ranges into them, so a handler that ignores ``Range`` makes a browser pull whole
+    files — which is the difference between a few kilobytes and a gigabyte. Python's
+    stock handler has no range support, so it is added here rather than by importing
+    figpack's, which would put the dependency back.
+    """
+
+    def end_headers(self):
+        self.send_header("Accept-Ranges", "bytes")
+        super().end_headers()
+
+    def log_message(self, *args):
+        pass  # a figure viewer issues hundreds of requests; do not narrate them
+
+    def do_GET(self):  # noqa: N802 — http.server's casing
+        header = self.headers.get("Range")
+        if not header:
+            return super().do_GET()
+
+        match = re.fullmatch(r"bytes=(\d*)-(\d*)", header.strip())
+        if not match:
+            return super().do_GET()  # multipart/unsatisfiable syntax: serve whole
+
+        path = self.translate_path(self.path)
+        if os.path.isdir(path):
+            return super().do_GET()
+        try:
+            size = os.path.getsize(path)
+        except OSError:
+            self.send_error(404)
+            return
+
+        first, last = match.group(1), match.group(2)
+        if first == "":
+            if last == "":
+                return super().do_GET()
+            length = min(int(last), size)
+            start, end = size - length, size - 1
+        else:
+            start = int(first)
+            end = min(int(last), size - 1) if last else size - 1
+
+        if start >= size or start > end:
+            self.send_response(416)
+            self.send_header("Content-Range", f"bytes */{size}")
+            self.end_headers()
+            return
+
+        self.send_response(206)
+        self.send_header("Content-Type", self.guess_type(path))
+        self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+        self.send_header("Content-Length", str(end - start + 1))
+        self.end_headers()
+        with open(path, "rb") as f:
+            f.seek(start)
+            self.wfile.write(f.read(end - start + 1))
diff --git a/tests/test_bundle_storage.py b/tests/test_bundle_storage.py
index 9d2f867..020a39e 100644
--- a/tests/test_bundle_storage.py
+++ b/tests/test_bundle_storage.py
@@ -158,3 +158,45 @@ def test_load_is_gone():
     from dj_figpack_codecs import FigpackRef
 
     assert not hasattr(FigpackRef, "load")
+
+
+def test_show_honours_range_requests(
+    sample_figpack_view, sample_context, mock_backend, default_store_config, mocker
+):
+    """figpack packs chunks into large consolidated files and the viewer ranges into
+    them. A handler that ignores Range would make the browser pull whole files."""
+    import urllib.error
+    import urllib.request
+
+    from dj_figpack_codecs import FigpackCodec
+
+    codec = FigpackCodec()
+    mocker.patch.object(codec, "_get_backend", return_value=mock_backend)
+    ref = codec.decode(codec.encode(sample_figpack_view, key=sample_context, store_name="default"))
+
+    url = ref.show(open_browser=False)
+
+    with urllib.request.urlopen(url, timeout=10) as r:
+        whole = r.read()
+        assert r.headers.get("Accept-Ranges") == "bytes"
+
+    req = urllib.request.Request(url, headers={"Range": "bytes=0-9"})
+    with urllib.request.urlopen(req, timeout=10) as r:
+        assert r.status == 206
+        assert r.headers["Content-Range"] == f"bytes 0-9/{len(whole)}"
+        assert r.read() == whole[:10]
+
+    # a suffix range, which is how a reader pulls a trailing index
+    req = urllib.request.Request(url, headers={"Range": "bytes=-5"})
+    with urllib.request.urlopen(req, timeout=10) as r:
+        assert r.status == 206
+        assert r.read() == whole[-5:]
+
+    # past the end is 416, not a silent whole-file send
+    req = urllib.request.Request(url, headers={"Range": f"bytes={len(whole) + 10}-"})
+    try:
+        urllib.request.urlopen(req, timeout=10)
+        raise AssertionError("expected 416")
+    except urllib.error.HTTPError as e:
+        assert e.code == 416
+        assert e.headers["Content-Range"] == f"bytes */{len(whole)}"

From 89e3236a2be888bfdb772ad73c70f5575d644ad6 Mon Sep 17 00:00:00 2001
From: MilagrosMarin <milmarina02@gmail.com>
Date: Wed, 16 Sep 2026 14:42:52 +0200
Subject: [PATCH 3/3] docs: describe the stored object as a bundle, not a Zarr
 folder

Module, class and encode docstrings still said the codec stores Zarr folders,
which described the old design. Also drops the FigpackView type import that
removing load() orphaned.
---
 src/dj_figpack_codecs/__init__.py |  4 ++--
 src/dj_figpack_codecs/codec.py    | 11 ++++++-----
 src/dj_figpack_codecs/ref.py      |  5 +----
 3 files changed, 9 insertions(+), 11 deletions(-)

diff --git a/src/dj_figpack_codecs/__init__.py b/src/dj_figpack_codecs/__init__.py
index 61119da..dc3588a 100644
--- a/src/dj_figpack_codecs/__init__.py
+++ b/src/dj_figpack_codecs/__init__.py
@@ -6,7 +6,7 @@
 
 This package provides a codec for storing figpack FigpackView objects
 in DataJoint's schema-addressed object storage (OAS). Visualizations
-are stored as Zarr folders and fetched lazily via FigpackRef.
+are stored as self-contained bundles and fetched lazily via FigpackRef.
 
 Usage::
 
@@ -34,7 +34,7 @@ def make(self, key):
     # Fetch returns FigpackRef (lazy)
     ref = Visualization.fetch1('figure')
     print(ref.title)                        # No download
-    url = ref.serve_under("assets/serve")   # Materialize a servable viewer bundle
+    url = ref.serve_under("assets/serve")   # Publish the stored bundle, get its URL
 """
 
 from .codec import FigpackCodec
diff --git a/src/dj_figpack_codecs/codec.py b/src/dj_figpack_codecs/codec.py
index 37b5dee..bb10a82 100644
--- a/src/dj_figpack_codecs/codec.py
+++ b/src/dj_figpack_codecs/codec.py
@@ -4,7 +4,7 @@
 """
 FigpackCodec for storing figpack visualizations in DataJoint OAS.
 
-This codec enables storing FigpackView objects as Zarr folders in
+This codec enables storing FigpackView objects as self-contained bundles in
 schema-addressed object storage, with lazy loading via FigpackRef.
 """
 
@@ -24,9 +24,9 @@
 
 class FigpackCodec(SchemaCodec):
     """
-    Schema-addressed storage for figpack visualizations as Zarr folders.
+    Schema-addressed storage for figpack visualizations as self-contained bundles.
 
-    The ``<figpack@>`` codec stores FigpackView objects as Zarr folders under a
+    The ``<figpack@>`` codec stores FigpackView objects as figpack bundles under a
     schema-addressed path chosen by the framework (mirrors schema/table, encodes
     primary keys as ``attr=value``, tokenized ``{attribute}_{token}.zarr`` filename).
     Visualizations are fetched lazily via ``FigpackRef``, which provides
@@ -76,7 +76,8 @@ def make(self, key):
         url = ref.serve_under("assets/serve")
 
     Storage Details:
-        - File format: Zarr folder (figpack native)
+        - File format: figpack bundle — index.html, assets/, data.zarr/ and the
+          extension manifest, exactly as ``FigpackView.save()`` emits them
         - Path: schema-addressed, framework-chosen (e.g. ``{schema}/{table}/{pk_attr}={val}/{attribute}_{token}.zarr/``)
         - Database column: JSON with ``{path, store, title, description}``
 
@@ -126,7 +127,7 @@ def encode(
         store_name: str | None = None,
     ) -> dict:
         """
-        Save FigpackView as Zarr folder and upload to storage.
+        Save FigpackView as a bundle and upload the whole folder to storage.
 
         Parameters
         ----------
diff --git a/src/dj_figpack_codecs/ref.py b/src/dj_figpack_codecs/ref.py
index 45ec6c8..bf04790 100644
--- a/src/dj_figpack_codecs/ref.py
+++ b/src/dj_figpack_codecs/ref.py
@@ -19,13 +19,10 @@
 import tempfile
 import time
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from datajoint.errors import DataJointError
 
-if TYPE_CHECKING:
-    from figpack import FigpackView
-
 
 class FigpackRef:
     """