Skip to content

Release: dev into main - #167

Open
davehorsfall wants to merge 13 commits into
mainfrom
dev
Open

davehorsfall wants to merge 13 commits into
mainfrom
dev

Conversation

@davehorsfall

@davehorsfall davehorsfall commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Merging this publishes a release. dev is 13 commit(s) ahead of main.

Fixes

  • fix(viewer): stop caching a read that failed (aa06ef5)
  • fix(anndata): let one unreadable obs column cost only itself (cf5587e)
  • fix(viewer): measure the scale bar in a unit viv can read (bb6bbb4)
Every commit
  • fix(viewer): stop caching a read that failed (aa06ef5)
  • fix(anndata): let one unreadable obs column cost only itself (cf5587e)
  • fix(viewer): measure the scale bar in a unit viv can read (bb6bbb4)
  • docs: point the quick start at an image that exists (a521841)
  • docs: fold the docs workflows into the shared setup and naming (1ef524e)
  • docs: publish the API site on release, and make it look like vizarr (5e2d456)

davehorsfall and others added 6 commits October 30, 2026 11:47
The docs site has been stale since 16 September. `deploy-docs.yml` has run
twice in its life, and the one push since then that matched its path filter
produced no workflow runs at all, so nothing rebuilt and nothing could tell.
A push-triggered, path-filtered deploy has no way to notice it was missed.

So it now deploys on `release: published`, checking out the tag. Published
API documentation should describe the published package, and this removes
the "did that push match the filter?" question entirely. Same reasoning as
the app's own deploy. A manual trigger covers refreshing the site without
cutting a release.

The guard before the rsync checked that one file was non-empty, in front of
a `--delete-unmatched-destination-objects` that removes whatever the build
does not contain. A build that emitted an index page and lost the rest
would have passed it and emptied the bucket. It now checks file count and
total size against the 73 files and 2.4MB a real build produces.

Nothing built the docs before main, so a break arrived there first. A pull
request into any branch now builds them, which is nineteen seconds.

anndata-zarr had no API documentation at all -- it is a published package
with no reference pages. It is now an entry point like the other two.

Warnings are errors now, and making that pass meant exporting types that
exported API already referenced: Events, MultichannelConfig and
SingleChannelConfig from the viewer, and ObservationControlsProps,
ColourProps and ObservationMetadata from anndata-zarr. Each was reachable
from something public and documented as a dead link. This widens the
published type surface, additively.

The quick start documented a different package. It said to install
@hms-dbmi/vizarr and import a default export this package does not have,
and its example used a viewState it never defined -- every line of it was
wrong. Rewritten against the real exports, with createViewer, labels and
the theme escape hatch alongside.

The styling is layered over typedoc-github-theme as custom property
overrides rather than replacing it; that theme is a sound base and the only
thing wrong with it was that the site looked like GitHub. Accents come from
the three channels of the vizarr mark. Both colour schemes still work: the
viewer is dark because it wraps images in as little light as possible, but
documentation is long-form reading and the reader's preference should win.
The brand blue measures 2.65:1 on white, so light mode uses a darkened
version of the same hue at 5.72:1 and dark mode keeps the original at
6.89:1.

`build:docs` ran bare typedoc, and typedoc has to resolve `@biongff/vizarr`
because roi-selector and anndata-zarr import it for types. Those types only
exist once the viewer is built, so on a clean checkout there is no
viewer/dist and the run fails -- which it did, the first time this workflow
had fired since 16 September. It had been broken since 22 September, when
the logging refactor added that import; nothing noticed because the deploy
had not run in between. The stale site was hiding a broken build. The
script now builds the viewer first.

Lastly `pnpm docs:dev`, which serves the site and rebuilds as you edit. A
full typedoc pass is about twenty seconds, far too slow to iterate on a
stylesheet, so a CSS change is copied straight into the output instead --
measured at 255ms to live. The reload listener is injected as the page is
served, so the build output stays what gets published.

Closes #146

Co-Authored-By: Claude Opus 5 <[email protected]>
Merging dev brought in the workflow overhaul from #152, so the two docs workflows
now have a composite setup action to use and a naming convention to follow.

docs.yml becomes build-docs.yml / "Build docs", pairing with deploy-docs.yml /
"Deploy docs", and takes the composite action instead of its own copy of the setup
block. Its path filter grows an entry for .github/actions/setup, because the build
now depends on it and a change there should not first show up at release. It also
gains concurrency, and narrows to pull requests into main and dev -- it said "any
branch" when test.yml only covered main, and it would be odd for a pull request
into a feature branch to have its docs checked but not its types.

deploy-docs.yml gains a comment above the Google authentication step rather than a
change. Moving it to the release trigger means it now runs at a tag ref, and this
workflow has only ever run from branches. That is the same change that broke the
Pages deploy, where the environment allowed main and dev and no tags, and every
release deploy was refused after a clean build. The equivalent gate here lives in
Google: the workload identity provider's attribute condition and the principalSet
on the service account. If either keys on the ref rather than the repository, this
will fail at the next release, and there is no way to test it short of one.

CLAUDE.md gains docs:dev and build:docs in the commands table.

Refs #146

Co-Authored-By: Claude Opus 5 <[email protected]>
The example used idr/zarr/v0.5/idr0062A/6001240.zarr, which 404s. The same image
is served under v0.4, which responds. Checked by fetching .zattrs rather than the
store root, since a bare zarr URL is a prefix and 404s even when the store is
there -- which is also why this was not obvious.

Co-Authored-By: Claude Opus 5 <[email protected]>
Publish the API docs on release, check them on pull requests, and make the site look like vizarr
Copilot AI balanced review requested due to automatic review settings November 3, 2026 13:11
@netlify

netlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for biongff-vizarr ready!

Name Link
🔨 Latest commit d5d1f2b
🔍 Latest deploy log https://app.netlify.com/projects/biongff-vizarr/deploys/6af6dbfd58fba5bc401cd857
😎 Deploy Preview https://deploy-preview-167--biongff-vizarr.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Documentation previews fail on fresh checkouts, manual deployments can publish unreleased content instead of main, and malformed URLs can crash the development server.

3 open issues
What changed in this PR

This release PR updates Vizarr’s API documentation, aligns publication with releases, and adds a local documentation preview workflow.

Changes:

  • Publish docs from release tags and validate documentation builds on pull requests using shared setup.
  • Add Vizarr styling, expand the quick start, and include the AnnData plugin in the API reference.
  • Export referenced public types and add a live-reloading documentation server.
File Description
viewer/​src/​index.tsx Re-exports event and image configuration types.
viewer/​src/​api.tsx Exports the viewer event type.
typedoc.json Adds AnnData docs, branding, and strict warning handling.
scripts/​docs-dev.mjs Adds local serving, rebuilds, and live reload.
package.json Builds the viewer before docs and adds docs:dev.
docs/​viewer/​theme.css Adds light and dark documentation styling.
docs/​viewer/​introduction.md Expands setup examples and corrects the example image URL.
CLAUDE.md Documents preview and documentation build commands.
anndata-zarr/​typedoc.json Configures the plugin’s documentation entry point.
anndata-zarr/​src/​index.ts Re-exports types used in the public API.
anndata-zarr/​src/​components/​ObsSelect.tsx Exports observation control props.
.github/​workflows/​deploy-docs.yml Deploys release documentation with build-size checks.
.github/​workflows/​build-docs.yml Adds pull-request documentation builds.

Review effort: Balanced

Comment on lines +33 to +35
# An empty ref is the default branch, which is what an unqualified manual
# run should get.
ref: ${{ github.event.release.tag_name || inputs.tag }}
Comment thread scripts/docs-dev.mjs
building = true;
const started = Date.now();
process.stdout.write("building... ");
const child = spawn("npx", ["typedoc"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
Comment thread scripts/docs-dev.mjs

http
.createServer((req, res) => {
const url = decodeURIComponent((req.url ?? "/").split("?")[0]);
davehorsfall and others added 4 commits November 4, 2026 20:53
The bar was a fixed 5% of the viewport labelled with whatever that
happened to measure, to five significant figures. On an IDR image it read
"8.6721micrometer" -- correct, and useless, because a scale bar exists so
a round length can be laid against the image by eye.

That followed from the unit. NGFF spells units as UDUNITS-2 names and
viv's `sizeToMeters` reads SI symbols, so `micrometer` could not be
measured and `snap` had to stay off. Mapping the names onto symbols is
what makes snapping possible; `snap: true` on its own throws
`Received unknown unit` from inside `renderLayers`, which our own
fixtures would trigger.

Two things are now refused rather than drawn. A unit viv cannot express
as metres -- `foot`, `inch`, `mile`, `yard`, `parsec`, and `angstrom`,
which is 10^-10 and has no SI prefix. And a unit that is absent, because
`sizeToMeters` returns the size unchanged for an empty unit, which is to
say it reads it as metres: the Xenium images that declare no unit would
carry an authoritative-looking bar out by six orders of magnitude.

Nothing here asks viv to reject what it cannot measure. Its prefix test
is `unit.substring(0, unit.length - 1)` and never checks that what
remains is `m`, so `ft` parses as femto and renders `25fm`. Measured, and
kept as a test.

Measured on idr0062A/6001240_labels.zarr at the same view:
"8.6721micrometer" before, "10µm" after.

Refs #176. The mapping and `snap: true` are ported from
BioNGFF/biongff-viewer#46; the guard is what keeps them from throwing.

Co-Authored-By: Claude Opus 5 <[email protected]>
The Observations panel came up empty whenever any single column could not
be read, showing two headings with nothing under either. Columns that had
been read perfectly well were discarded along with the one that had not.

`Promise.all` is fail-fast: one rejection rejects the batch, and the outer
catch turned that into `[]`. Settling each column on its own keeps the
rest, and each rejection is now logged with the column's name -- a column
absent from both the panel and the log is indistinguishable from one the
table never had.

The dividers are drawn only when something falls under them. That was
cosmetic before and is not now: partial lists become the ordinary case
rather than the exception.

Measured against the new fixtures, before and after:

  table-zarr2  ["region", "area", "passed"]  ->  unchanged
  table-zarr3  []                            ->  ["area", "passed"]

Adds the first offline tests this package has had; everything in
`anndata-zarr/tests/` needed a server we do not run, so none of it ran on
a pull request. The two failing columns in the zarr v3 fixture fail for
reasons no zarrita version papers over -- a node that is not there, and a
dtype in nobody's table. That is deliberate: this package declares zarrita
0.5.0 and the viewer declares 0.6.2, and the application bundles one copy
for both, so a fixture turning on a dtype only one of them supports would
assert something no user could meet.

The tables are named for the zarr format rather than a version number,
because unlike the images beside them they answer to no OME-NGFF version
at all.

Refs #178. Ported from BioNGFF/biongff-viewer#44, which catches per column
and guards the same dividers.

Co-Authored-By: Claude Opus 5 <[email protected]>
A rejected promise is a perfectly good cache entry as far as QuickLRU is
concerned, so a read that failed was returned for the rest of the session
and the store never asked again. Measured against a server made to refuse
and then relent, which is what re-authenticating or a restarted backend
looks like from the client:

  1st: Unexpected response status 403 Forbidden
  2nd after re-auth: still fails -- "403 Forbidden"
  requests the server saw on the 2nd attempt: 0

The server was willing. Nothing asked it.

`getRange` already dropped its entry on failure; `get` did not. This gives
`get` the same `.catch`, which is the whole change. Everything that is not
"absent" lands there -- a 401, a 403, a 502, a dropped connection -- so a
blip during a load used to cost that chunk until the page was reloaded.

An absent key still caches. A 404 is how zarrita discovers a node is not
there, a group with no labels or a well with no image, and asking twice
would cost a request for every one of them.

The tests count what the server receives, because that is the only way to
tell a cached answer from a fresh one. Reverting the fix fails exactly one
of them.

Closes #182. Unblocks #181: no sign-in-and-retry design can work while the
retry never reaches the network.

Co-Authored-By: Claude Opus 5 <[email protected]>
fix(viewer): stop caching a read that failed
@codecov

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.76923% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
anndata-zarr/tests/fixture-server.ts 85.00% 3 Missing ⚠️
viewer/src/components/Viewer.tsx 0.00% 2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

AlexSurtees and others added 3 commits November 13, 2026 08:32
fix(anndata): let one unreadable obs column cost only itself
fix(viewer): measure the scale bar in a unit viv can read

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants