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, or load from the /public folder bundled into the application during the build (this is currently the case since the manifests are not present on our main branch, only in this PR branch)
- Provides getCompatibleViewers() function to determine dataset-viewer compatibility using the capability-manifest library for compatibility detection
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.

- 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

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

test: refine error message expectations in viewersConfig tests

test: fix mock hoisting in DataToolLinks test test: simplify capability manifest mock structure test: update tests for new capability-manifest API test fix test fix

docs fix

…e → Vol-E)

…atch

…to mimic intended setup

…iewers confi

krokicki · 2026-03-02T14:44:35Z

docs/Development.md

-  - "/opt/data"                       # Another shared directory
+  - "~/" # User's home directory
+  - "/groups/scicomp/data" # Shared data directory
+  - "/opt/data" # Another shared directory


The whitespace was useful here, I think?

krokicki · 2026-03-02T15:31:09Z

.devcontainer/devcontainer.json

    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind",
-    "source=fileglancer-pixi,target=${containerWorkspaceFolder}/.pixi,type=volume"
+    "source=fileglancer-pixi,target=${containerWorkspaceFolder}/.pixi,type=volume",
+    "source=/groups/scicompsoft/home/truhlara/gh-repos/capability-manifest,target=/workspaces/capability-manifest,type=bind"


We shouldn't add personal paths like this to git. Maybe there is another way to mount this directory?

krokicki · 2026-03-02T15:33:51Z

docs/Development.md

+
+**Quick Setup:**
+
+1. Edit the configuration file at `frontend/src/config/viewers.config.yaml` to enable/disable viewers or customize URLs


It's best not to edit committed source code to change configuration. If users change version controlled code then they will have problems staying up to date with upstream changes. One alternative pattern for this would be to allow users to copy this file into the main directory with their own changes, and then during the build use it to override the default config.

krokicki · 2026-03-02T15:40:08Z

frontend/src/contexts/ViewersContext.tsx

+    return config.viewers;
+  } catch (error) {
+    log.error('Error parsing viewers configuration:', error);
+    throw error;


I think that in most cases we should either handle an error or throw it. If the error is logged and then rethrown, it will likely be logged again, creating duplicate logs. But I might be missing something.

krokicki · 2026-03-02T15:42:23Z

frontend/src/contexts/ViewersContext.tsx

+        } catch (manifestError) {
+          log.error('Failed to load capability manifests:', manifestError);
+          throw new Error(
+            `Failed to load viewer manifests: ${manifestError instanceof Error ? manifestError.message : 'Unknown error'}`


This is another case where we likely want to pick where this error should get logged, and not propagate errors that were already handled.

krokicki · 2026-03-02T15:55:19Z

frontend/src/hooks/useZarrMetadata.ts

-          openWithToolUrls.avivator = null;
+      // Convert our metadata to OmeZarrMetadata format for capability checking
+      const omeZarrMetadata = {
+        version: effectiveZarrVersion === 3 ? '0.5' : '0.4',


This is extremely fragile code from my original vibe-coded prototype. We need a better way to get the NGFF version.

Starting in NGFF 0.5, there is an attribute that specifies the version (https://ngff.openmicroscopy.org/specifications/0.5/index.html#ome-zarr-metadata).

I'm not sure if there's a reliable way to tell for versions prior to 0.5. @mkitti do you know? We could take a look at the OME-NGFF Validator, which somehow prints the version.

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

allison-truhlar added 20 commits February 9, 2026 21:39

feat: add capability manifest files for all viewers

da8dd86

refactor: simplify viewers config to manifest_url entries

10bafa7

refactor: update ViewersContext for new capability-manifest API

cd05c36

test: rewrite viewersConfig unit tests for manifest_url API

d892ca1

test: refine error message expectations in viewersConfig tests

test: rewrite DataToolLinks component tests for manifest_url API

d5261a5

test: fix mock hoisting in DataToolLinks test test: simplify capability manifest mock structure test: update tests for new capability-manifest API test fix test fix

docs: update viewer configuration docs for manifest-based system

05957ba

docs fix

chore: prettier formatting

0fce05c

chore: bump capability-manifest version

4ab4fe6

fix: update capability-manifest in package-lock.json

d7ea968

tests: fix vole to vol-e in expected text

c104803

test: remove timeout to rely on longer global timeout value

0bd1731

chore: bump capability-manifest version

2f86cab

fix: use relative paths for viewer manifest URLs to fix CI failures

9c629d2

fix: capitalize viewer names in manifests (validator → Validator, vol…

f4e7f51

…e → Vol-E)

fix: use viewer label for logo alt text and update test locators to m…

3080e8a

…atch

chore: prettier formatting

06c0ab1

Merge branch 'main' into viewers-config

7e46003

refactor: change manifest_urls in viewers config to the GH repo urls …

1a3dff9

…to mimic intended setup

fix: decouple DataToolLinks tests from exact manifest_url values in v…

77502ae

…iewers confi

fix: correct templating for avivator/vizarr instance_template_url

f024930

krokicki reviewed Mar 2, 2026

View reviewed changes


		Quick Setup:

		1. Edit the configuration file at `frontend/src/config/viewers.config.yaml` to enable/disable viewers or customize URLs

Conversation

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

Uh oh!

Changes

Uh oh!

neomorphic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

allison-truhlar commented Feb 2, 2026 •

edited

Loading

allison-truhlar Feb 3, 2026 •

edited

Loading