Render-ready codec: fix save() call, store data-only Zarr, add FigpackRef.serve_under

[MilagrosMarin]

Makes the codec usable end-to-end against figpack ≥ 0.3 and DataJoint ≥ 2.3, and adds the
serving seam that dash-datajoint-components' PlotGrid consumes (design of record:
docs/design-specs/figpack-integration.md in dj-sciops/dash-datajoint-components, merged as #106).

Fixes

• encode() raised TypeError on every insert: figpack ≥ 0.3 made title a required
  keyword-only argument of FigpackView.save(). The suite's own test_encode_produces_metadata
  reproduced this once the fixtures were updated to figpack 0.3.20 (views no longer take
  title/description constructor kwargs either — the codec reads them from optional view
  attributes via getattr, which now the fixtures exercise).
• Store holds figure data only: encode() now uploads just the data.zarr/ subtree of
  figpack's save output (consolidated .zmetadata carries title/description), not the full
  viewer bundle — the viewer is laid over the data at render time, so the store never
  duplicates ~2 MB of viewer code per figure. This follows the direction from the #106 design
  review; please confirm this is the storage shape you want.
• validate() rejects extension-based views (ExtensionView): their JavaScript lives
  outside data.zarr, so data-only storage would silently drop it and serve broken figures.
  Note this includes figpack.views.PlotlyFigure, which subclasses ExtensionView — a test
  canary documents that. Open question: acceptable v1 policy, or should extension files be
  stored alongside the Zarr?

New: FigpackRef.serve_under(base_dir) -> str

Materializes a self-contained, servable viewer bundle under base_dir/<sha1(path)[:16]>/
(viewer dist from the installed figpack package + downloaded data.zarr + extension manifest)
and returns /<id>/index.html. Idempotent; concurrency-tolerant (a worker losing the publish
race to a byte-equivalent bundle treats it as success); staged + os.replace-published so a
half-written bundle is never served; refreshes the directory mtime for TTL-based cache
cleaners; sweeps staging dirs orphaned by killed processes. Downloads use
StorageBackend.fs.get(..., recursive=True) for non-file protocols (StorageBackend has no
get_folder) — the S3 path is covered by a mocked test but not yet validated against a real
remote store.

Flagged, unchanged (proposing a follow-up issue)

FigpackRef.load() has two pre-existing defects: figpack.view_figure() serves the figure
over HTTP and returns None (it never reconstructs a view, so load() blocks and caches
None), and its remote branch calls backend.get_folder, which DataJoint 2.3's
StorageBackend does not provide. The dashboard path never calls load(); left untouched
here to keep this PR focused.

Notes

• Carries over the applicable items from the dj-canvasxpress-codecs#1 review: the LICENSE
  body is restored byte-verbatim from the official Apache-2.0 text (this repo carried the
  same two deviations and was named there as the likely copy source), storage-path docs now
  describe a framework-owned schema-addressed layout, and validate() raises TypeError
  for unsupported types per the codec convention (the missing-figpack branch stays a
  DataJointError — an environment problem, not a value problem).
• Dashboards installing this package get figpack transitively (it is a hard dependency), so
  the viewer dist is always importable serve-side. If a figpack-free dashboard is ever wanted,
  figpack could become an optional extra.
• Tests: 23 passed, 2 skipped (live-DB round-trip incl. to_arrays returns the ref — needs
  DJ_HOST/DJ_USER/DJ_PASS; plotly canary needs plotly). Includes a round-trip through the
  real file-protocol StorageBackend with no DB, guarding against backend API drift.
• Version 0.1.0 → 0.2.0.

[dimitri-yatsenko]

Strong PR — approving in spirit, with a few small fixes to land first. It fixes a real total breakage (encode() raised TypeError on every insert under figpack ≥ 0.3), the data-only storage shape is well-reasoned, and serve_under is carefully built: the staged-build + atomic os.replace publish, race-loser detection, orphan sweep, and TTL touch are all correct and genuinely well-covered (the monkeypatched publish-race test is a nice touch).

I verified the backend-API claims against datajoint 2.3: put_folder, _full_path, fs, and protocol all exist, and get_folder really does not exist anywhere — so the diagnosis of the broken load() path is accurate.

Should-fix before merge

1. __version__ not bumped. src/dj_figpack_codecs/__init__.py still declares __version__ = "0.1.0" while pyproject.toml is now 0.2.0. It's exported in __all__, so dj_figpack_codecs.__version__ disagrees with the installed metadata.

2. Docstring examples break on the version this PR targets. __init__.py (vv.TimeseriesGraph(title="My Plot")) and the codec.py class docstring (TimeseriesGraph(title="Spike Raster")) still pass title= to the view constructor — but the premise of this PR is that figpack ≥ 0.3 removed title/description from view constructors (the fixtures now set fig.title after construction). These snippets would raise TypeError on 0.3. Please update them to the getattr-based attribute path.

3. load() / show() are non-functional — make the failure legible. The class's headline API (featured in the __init__ example as ref.show()) is broken: the remote branch calls self._backend.get_folder(...) → AttributeError (no such method in dj 2.3), and the file branch caches whatever view_figure() returns. Deferring the real fix is fine to keep scope tight (see the follow-up issue), but at minimum have load() raise a clear NotImplementedError/DataJointError that points at serve_under, rather than an AttributeError or a silently cached None.

Top thing to verify (already flagged in the description)

4. fs.get(full_path, dst, recursive=True) remote semantics are unvalidated. fsspec's recursive get is trailing-slash-sensitive about whether contents land as dst or nested inside it. The remote test mocks fs.get and asserts the call, not the resulting on-disk layout — so a real S3/GCS store could produce data.zarr/<name>/... and serve a broken figure. Worth a real-remote smoke test before relying on remote serve_under.

Nits

• mock_backend still defines get_folder (conftest) — a method the real backend lacks. Harmless today (nothing exercises load()), but it perpetuates the illusion the API exists and would mask #3. Drop it or mirror the real fs.get.
• Unused DataJointError imports in the test_codec.py cases that assert pytest.raises(TypeError, ...).
• validate() docstring still says "Raises DataJointError if value is not a FigpackView", but the body now raises TypeError.
• LICENSE now matches canonical Apache-2.0 (the "to Licensor" and §8 corrections are right), but the diff adds a leading blank line at the very top; the canonical text has none — trivial to drop, and worth it given the byte-verbatim intent.

The two decisions you asked about

• data.zarr-only storage shape → confirmed, yes. Matches the #106 design, avoids duplicating the viewer per figure, and the viewer-over-data-at-render-time seam is clean.
• Rejecting ExtensionView (incl. PlotlyFigure) in v1 → agree with fail-closed: silently dropping extension JS would serve broken figures, so rejecting at insert time is correct. Filing a follow-up to track extension-file storage, since PlotlyFigure is a plausible ask — not a blocker.

[MilagrosMarin]

Thanks for the thorough review, @dimitri-yatsenko — all items are addressed in f8b5572 + 35192f4. Suite is green (25 passed, black clean). Point by point:

1. __version__ — synced to 0.2.0 (35192f4).

2. Docstring examples — both examples now follow the figpack ≥ 0.3 pattern (construct bare, set fig.title as an attribute, matching the fixtures), and lead with serve_under instead of the not-yet-functional show(). Also fixed while in there: the codec.py example imported figpack_datajoint — a package name that never existed here — now dj_figpack_codecs (35192f4).

3. load()/show() legible failure — both now raise NotImplementedError pointing at serve_under and #3 (f8b5572), with a regression test. One sharpening of the diagnosis for the record (added to the load() docstring and relevant to #3): the file branch was worse than a silently-cached None — figpack.view_figure is a CLI helper that launches a local HTTP server with open_in_browser=True, returns None, and calls sys.exit(1) on a missing path. So there is currently no figpack API that reconstructs a view from a stored data.zarr; #3 will need one (or a different reconstruction strategy) before load() can be real.

4. Remote fs.get semantics — verified empirically against the real client stack (fsspec/s3fs 2026.7.0, S3-compatible endpoint) through this exact code path: the nesting hazard is real but destination-existence-sensitive. Contents land as dst when dst does not pre-exist — which serve_under guarantees via its fresh mkdtemp staging — and nest inside (data.zarr/data.zarr/…) only when dst already exists. So current versions behave correctly here; the residual risk is version drift/provider quirks. Two mitigations landed in f8b5572: a post-download runtime guard (data.zarr/.zmetadata must exist, else a descriptive DataJointError with staging cleaned and nothing half-published) and a regression test that a nesting backend is rejected and a subsequent correct download still publishes.

Remaining question — where should the durable real-client check live? (a) a smoke test in this suite using moto[server] (in-process S3 endpoint, real s3fs stack, no Docker; adds moto/s3fs/boto3 to the test extra), or (b) defer genuine-remote validation to the dashboard integration (dj-sciops/dash-datajoint-components#112 gets validated against a real S3-backed store as part of its deployment testing). cc @ttngu207 since (b) rides on the Dashboard path. Preference?

Nits — all four done: get_folder dropped from the mock backend (it was contradicting the suite's own comment that the real API lacks it); the three unused DataJointError imports removed (the fourth, in test_get_dtype_requires_store, is used); validate() docstring now says TypeError for bad values with DataJointError reserved for the missing-package case, matching the body; LICENSE first line restored — the body is again byte-identical to the official Apache-2.0 text.

The two confirmed decisions — no changes needed; #3 and #4 track the follow-ups. On #4, agreed PlotlyFigure is a plausible ask — the fail-closed canary test will flag if figpack ever rebases it onto a core view.