feat: generate viewer links dynamically for Zarr datasets by allison-truhlar · Pull Request #307 · JaneliaSciComp/fileglancer

allison-truhlar · 2026-02-02T21:27:51Z

Clickup id: 86advt10e

This PR implements dynamic viewer configuration for Zarr datasets via a build-time viewers.config.yaml file and integration of the @bioimagetools/capability-manifest library for automatic dataset-viewer compatibility detection.

Changes

Created viewers.config.yaml with documentation for customizing viewer configuration. This file specifies available viewers for a Fileglancer deployment. The default configuration is our current viewers: Neuroglancer, Avivator, Vol-E, and OME-Zarr Validator. Configuration is bundled at build time.
Added ViewersContext for managing viewer configuration. This context:
- Loads and validates viewer configuration from YAML at initialization
- Fetches capability manifests using @bioimagetools/capability-manifest library
- Provides getCompatibleViewers() function to determine dataset-viewer compatibility
  - For viewers with manifests: uses capability-manifest library for compatibility detection
  - For custom viewers: uses user-supplied OME-Zarr versions and requires multiscales metadata
Refactored useZarrMetadata to dynamically generate openWithToolUrls using ViewersContext. URLs are generated only for compatible viewers based on the getCompatibleViewers function.
Updated DataToolLinks to render viewer buttons dynamically by mapping over valid viewers from ViewersContext. The "Copy URL" tool is always available when a data link is available.
Added logo management system with convention-based naming ({name}.png), custom logo override support, and fallback logo for missing assets.
Added unit tests for config parsing and component tests for DataToolLinks.
Updated documentation with a ViewersConfiguration.md guide and updated CLAUDE.md with viewer configuration instructions.

Added dependencies

@bioimagetools/capability-manifest (^0.2.0) for viewer capability detection
js-yaml (^4.1.1) and @types/js-yaml (^4.0.9) for YAML parsing

- Custom viewers (validator, vol-e) now check for multiscales - Ensures viewers only display for OME-Zarr datasets, not plain Zarr arrays - Update DataToolLinks alt text to use displayName for E2E test compatibility

Add useCallback to memoize the getCompatibleViewers function in ViewersContext to prevent unnecessary recalculations and improve performance when filtering compatible viewers based on metadata.

Add more detailed error logging and ensure graceful degradation when: - Capability manifests fail to load - Viewer configuration parsing fails - No valid viewers are configured The application will continue with an empty viewer list and clear console messages to help users troubleshoot configuration issues.

neomorphic

Looks good to me. I was able to enable and disable a viewer using the viewers.config.yaml. I added a few comments about some the code I wasn't sure on.

frontend/src/config/viewerLogos.ts

neomorphic · 2026-02-02T22:32:37Z

frontend/src/queries/n5Queries.ts

 export type N5OpenWithToolUrls = {
  copy: string;
  neuroglancer: string;
-  validator: null;


I don't know what this data structure is doing? Why did three of the viewers get removed, but not neuroglancer?

This is only tangentially related to the purpose of this PR - when the support for N5 metadata was added, this type was added and exactly matched the the OpenWithToolUrls type used for the Zarr metadata URL tools display. However, of these tools, N5s can only be opened in Neuroglancer (or copied), so I removed the unneeded tool keys that will never be populated for N5s.

neomorphic · 2026-02-02T22:34:52Z

frontend/src/hooks/useN5Metadata.ts

-      validator: null,
-      vole: null,
-      avivator: null
+      neuroglancer: ''


Again, I am not sure what this dict is doing, but why does neuroglacer remain and not the others?

See this reply: #307 (comment)

frontend/src/config/viewersConfig.ts

neomorphic · 2026-02-02T22:49:00Z

frontend/src/config/viewersConfig.ts

There is a lot of custom code validation going on here. Have you looked at zod as a way to do the validation? I understand if we don't want to introduce another module, but if there are other places where we do validation, this might be worth it.

I had asked Claude about using zod at one point, but due to the conditional validation for certain fields based on whether a viewer has a capability manifest or not, Claude said it wasn't worth it. Checking with Claude again today, it said it was so I added a commit of what the validation looks like with zod to test it out. It's still a little complex due to needing a second pass of custom validation for the capability manifests, and also because I wanted to keep more helpful error messages with the viewer name where the validation failed, where possible: 7ec34ec.

I think it's worth keeping with the advantage being that if we want to add another field that has straightforward validation (ie., doesn't need to be validated differently if the parent viewer has a capability manifest or not), it's very easy to add this validation by just adding the field to the zod schema. And, to your point, if we end up needing validation elsewhere in the app, zod will already be installed.

frontend/src/contexts/ViewersContext.tsx

- previously, if a logo path wasn't found, a 404 URL was still created, so it was never falling through to the fallback_logo.

- includes checking that a fallback_logo is used when no logo is found for a viewer

- this minimizes the number of files we need to edit to change anything related to the viewers

- still requires some custom validation related to the capability manifests

allison-truhlar · 2026-02-03T20:56:15Z

frontend/src/hooks/useZarrMetadata.ts

+        if (viewer.key === 'neuroglancer') {
+          // Extract base URL from template (everything before #!)
+          const neuroglancerBaseUrl = viewer.urlTemplate.split('#!')[0] + '#!';
+          if (disableNeuroglancerStateGeneration) {


We are generating state for Neuroglancer links in Fileglancer, but the Neuroglancer template url currently used in the bioimagetools/capability-manifests assumes you're not https://github.com/BioImageTools/capability-manifest/blob/9e65138b0608b31c886e7a4ec7f54782794b6256/public/viewers/neuroglancer.yaml#L5C3-L5C123. This is just a temporary fix for now - we should think about whether it makes sense to rely on those template urls, how they need to be formatted, and, in the case of Neuroglancer, if it will expect generated state or not

allison-truhlar · 2026-02-03T20:56:34Z

frontend/src/hooks/useZarrMetadata.ts

+          if (url) {
+            // Extract base URL from template (everything before #!)
+            const neuroglancerBaseUrl =
+              viewer.urlTemplate.split('#!')[0] + '#!';


see comment above - this is a temporary fix

allison-truhlar added 21 commits February 2, 2026 11:26

feat: add viewers configuration template

5f1a624

feat: add viewer configuration types and YAML parser

d0bf67c

feat: add ViewersContext for dynamic viewer configuration

6620486

refactor: make OpenWithToolUrls dynamic using Record type

24e030e

docs: add comment explaining type assertion in parseViewersConfig

9f5d1eb

refactor: use ViewersContext in useZarrMetadata for dynamic viewer URLs

28173ea

refactor: use ViewersContext in DataToolLinks for dynamic viewer icons

3fd00d7

chore: prettier formatting

9160eb4

chore: update logo names; add fallback logo

ecf1b62

docs: add viewers configuration guide

7698348

fix: require OME metadata for custom viewers without manifests

69ae1b6

- Custom viewers (validator, vol-e) now check for multiscales - Ensures viewers only display for OME-Zarr datasets, not plain Zarr arrays - Update DataToolLinks alt text to use displayName for E2E test compatibility

fix: update locators to match new defaults

3e15ae7

efactor: use committed config file instead of template

4292cdf

docs: add viewers configuration to CLAUDE.md

d545e28

refactor: remove unused keys from N5OpenWithToolUrls type

d5c24e9

perf: memoize getCompatibleViewers function

e6e1cd4

Add useCallback to memoize the getCompatibleViewers function in ViewersContext to prevent unnecessary recalculations and improve performance when filtering compatible viewers based on metadata.

chore: fix eslint warnings

58d163d

fix: add validation for ome-zarr verison numbers

5ae87ae

tests: unit tests for the viewer config parsing func

4b6db2e

tests: component tests for DataToolLinks

fef30cd

allison-truhlar requested review from krokicki and neomorphic February 2, 2026 21:28

allison-truhlar mentioned this pull request Feb 2, 2026

wip: add capability manifest pkg #305

Closed

Merge branch 'main' into viewers-config

82b9cfb

neomorphic approved these changes Feb 2, 2026

View reviewed changes

allison-truhlar added 4 commits February 3, 2026 10:10

fix: add ViewersProvider to unit test setup for zarr tests

d2a4e84

fix: change how logos urls are found

b0e97a3

- previously, if a logo path wasn't found, a 404 URL was still created, so it was never falling through to the fallback_logo.

tests: add unit tests for the getViewerLogo func

8b2af82

- includes checking that a fallback_logo is used when no logo is found for a viewer

chore: prettier formatting

1ebfb3e

allison-truhlar added 5 commits February 3, 2026 12:49

refactor: move valid ome zarr versions to config file

5cacb67

- this minimizes the number of files we need to edit to change anything related to the viewers

refactor: add zod for viewer config validation

7ec34ec

- still requires some custom validation related to the capability manifests

refactor: update tests for ome zarr version in config; zod error msgs

30f0853

docs: add valid_ome_zarr_versions to viewer config docs

bc867c8

refactor: move metadata.multiscale check back to useZarrMetadata hook

83dd34f

allison-truhlar commented Feb 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: generate viewer links dynamically for Zarr datasets#307

feat: generate viewer links dynamically for Zarr datasets#307
allison-truhlar wants to merge 31 commits intomainfrom
viewers-config

allison-truhlar commented Feb 2, 2026

Uh oh!

neomorphic left a comment

Uh oh!

Uh oh!

neomorphic Feb 2, 2026

Uh oh!

allison-truhlar Feb 3, 2026

Uh oh!

neomorphic Feb 2, 2026

Uh oh!

allison-truhlar Feb 3, 2026

Uh oh!

Uh oh!

neomorphic Feb 2, 2026

Uh oh!

allison-truhlar Feb 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

allison-truhlar Feb 3, 2026 •

edited

Loading

Uh oh!

allison-truhlar Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

allison-truhlar commented Feb 2, 2026

Changes

Added dependencies

Uh oh!

neomorphic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

neomorphic Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

allison-truhlar Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

neomorphic Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

allison-truhlar Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

neomorphic Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

allison-truhlar Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

allison-truhlar Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

allison-truhlar Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

allison-truhlar Feb 3, 2026 •

edited

Loading

allison-truhlar Feb 3, 2026 •

edited

Loading