feat: generate viewer links dynamically for Zarr datasets

.gitignore

@@ -143,6 +143,7 @@ style/tailwind_converted.css
 
 # Configs
 config.yaml
+frontend/viewers.config.yaml
 
 # Claude Code
 .claude

CLAUDE.md

@@ -169,6 +169,23 @@ Key settings:
 - `db_url`: Database connection string
 - SSL certificates for HTTPS mode
 
+## Viewers Configuration
+
+Fileglancer uses a manifest-based viewer configuration system. Each viewer is defined by a **capability manifest** (a YAML file describing the viewer's name, URL template, and capabilities). The config file lists manifest URLs and optional overrides.
+
+- **Configuration file**: `frontend/src/config/viewers.config.yaml` -- lists viewers by `manifest_url` with optional `instance_template_url` and `label` overrides
+- **Manifest files**: `frontend/public/viewers/*.yaml` -- capability manifest YAML files defining each viewer's identity and supported features
+- **Compatibility**: Handled by the `@bioimagetools/capability-manifest` library, which checks dataset metadata against manifest capabilities at runtime
+- **Documentation**: See `docs/ViewersConfiguration.md`
+
+To customize viewers:
+
+1. Copy `frontend/src/config/viewers.config.yaml` to `frontend/viewers.config.yaml`
+2. Edit `frontend/viewers.config.yaml` (add/remove `manifest_url` entries, override URLs or labels)
+3. Rebuild application: `pixi run node-build`
+
+`frontend/viewers.config.yaml` is gitignored so customizations do not conflict with upstream updates. When it exists, it takes precedence over the committed default at `frontend/src/config/viewers.config.yaml`. The config file is bundled at build time.
+
 ## Pixi Environments
 
 - `default`: Standard development

docs/Development.md

@@ -45,16 +45,16 @@ By default, Fileglancer provides access to each user's home directory without re
 
 ```yaml
 file_share_mounts:
-  - "~/" # User's home directory (default)
+  - "~/"                    # User's home directory (default)
 ```
 
 You can add additional file share paths by editing your `config.yaml`:
 
 ```yaml
 file_share_mounts:
-  - "~/" # User's home directory
-  - "/groups/scicomp/data" # Shared data directory
-  - "/opt/data" # Another shared directory
+  - "~/"                    # User's home directory
+  - "/groups/scicomp/data"  # Shared data directory
+  - "/opt/data"             # Another shared directory
 ```
 
 **How Home Directories Work:**
@@ -68,8 +68,24 @@ file_share_mounts:
 
 Instead of using the `file_share_mounts` setting, you can configure file share paths in the database. This is useful for production deployments where you want centralized management of file share paths. To use the paths in the database, set `file_share_mounts: []`. See [fileglancer-janelia](https://github.com/JaneliaSciComp/fileglancer-janelia) for an example of populating the file share paths in the database, using a private wiki source.
 
+### Viewers Configuration
 
-### Testing configuration
+Fileglancer supports dynamic configuration of OME-Zarr viewers through `viewers.config.yaml`. This allows you to customize which viewers are available in your deployment and configure custom viewer URLs. No configuration is required to use the default viewers defined in `frontend/src/config/viewers.config.yaml`.
+
+**To customize viewers:**
+
+1. Copy the default config: `cp frontend/src/config/viewers.config.yaml frontend/viewers.config.yaml`
+
+2. Edit `frontend/viewers.config.yaml` to enable/disable viewers or customize URLs
+
+3. Rebuild the application: `pixi run node-build` or use watch mode in development: `pixi run dev-watch`
+
+**Note:** The configuration file is bundled at build time, so changes require rebuilding the application. `frontend/viewers.config.yaml` is gitignored so your customizations will not conflict with upstream updates. The default configuration includes Neuroglancer, Avivator, OME-Zarr Validator, and Vol-E viewers.
+
+For detailed configuration options, examples, and documentation on adding custom viewers, see [ViewersConfiguration.md](ViewersConfiguration.md).
+
+
+### Testing Configuration
 
 Optionally, to run Playwright tests against a development deployment with OKTA authentication enabled, add the below to the configuration file.
 **Note:** Do NOT add this configuration to a production deployment.

docs/ViewersConfiguration.md

@@ -0,0 +1,173 @@
+# Viewers Configuration Guide
+
+Fileglancer supports dynamic configuration of OME-Zarr viewers. This allows administrators to customize which viewers are available in their deployment, override viewer URLs, and control how compatibility is determined.
+
+## Overview
+
+The viewer system is built on capability manifests:
+
+- **`viewers.config.yaml`**: Configuration file listing viewers and their manifest URLs
+- **Capability manifest files**: YAML files describing each viewer's name, URL template, and capabilities
+- **`@bioimagetools/capability-manifest`**: Library that loads manifests and checks dataset compatibility
+- **`ViewersContext`**: React context that provides viewer information to the application
+
+Each viewer is defined by a **capability manifest** hosted at a URL. The configuration file simply lists manifest URLs and optional overrides. At runtime, the manifests are fetched, and the `@bioimagetools/capability-manifest` library determines which viewers are compatible with a given dataset based on the manifest's declared capabilities.
+
+## Customize Viewers
+
+**Note:** No configuration is required to use the default viewers defined in `frontend/src/config/viewers.config.yaml`.
+
+1. Copy the default config: `cp frontend/src/config/viewers.config.yaml frontend/viewers.config.yaml`
+2. Edit `frontend/viewers.config.yaml` to customize viewers
+3. Rebuild the application: `pixi run node-build`
+
+## Runtime Configuration (System Deployments)
+
+For deployments where Fileglancer is installed from PyPI and the frontend is pre-built, you can override the viewers configuration at runtime without rebuilding.
+
+Set the `FGC_VIEWERS_CONFIG` environment variable (or `viewers_config` in `config.yaml`) to the absolute path of a `viewers.config.yaml` file on disk:
+
+```env
+FGC_VIEWERS_CONFIG=/opt/deploy/viewers.config.yaml
+```
+
+Or in `config.yaml`:
+
+```yaml
+viewers_config: /opt/deploy/viewers.config.yaml
+```
+
+When set, the application serves this file via the API and the frontend uses it instead of the bundled config. The file follows the same format as the build-time `viewers.config.yaml`.
+
+### Precedence
+
+The viewers configuration is resolved in the following order (highest priority first):
+
+1. **Runtime API config** — served from the path in `FGC_VIEWERS_CONFIG` (no rebuild required)
+2. **Build-time override** — `frontend/viewers.config.yaml` (requires rebuild)
+3. **Build-time default** — `frontend/src/config/viewers.config.yaml` (requires rebuild)
+
+## Configuration File
+
+### Location
+
+There are three config locations, resolved in order of precedence:
+
+| Location | Purpose |
+| -------- | ------- |
+| Path in `FGC_VIEWERS_CONFIG` | **Runtime override** — served via API, no rebuild required; ideal for system deployments |
+| `frontend/viewers.config.yaml` | **Build-time override** — gitignored, safe to customize without merge conflicts |
+| `frontend/src/config/viewers.config.yaml` | **Default config** — committed source file, used when no override exists |
+
+Copy `frontend/src/config/viewers.config.yaml` to `frontend/viewers.config.yaml` to create a local override. This file is listed in `.gitignore` so your customizations will not conflict with upstream updates.
+
+**Important:** The build-time configs are bundled at build time and changes require rebuilding the application. Runtime config via `FGC_VIEWERS_CONFIG` does **not** require rebuilding.
+
+### Structure
+
+The configuration file has a single top-level key, `viewers`, containing a list of viewer entries. Each entry requires a `manifest_url` and supports optional overrides.
+
+#### Viewer Entry Fields
+
+| Field                   | Required | Description                                                                      |
+| ----------------------- | -------- | -------------------------------------------------------------------------------- |
+| `manifest_url`          | Yes      | URL to a capability manifest YAML file                                           |
+| `instance_template_url` | No       | Override the viewer's `template_url` from the manifest                           |
+| `label`                 | No       | Custom tooltip text (defaults to "View in {Name}")                               |
+
+### Default Configuration
+
+The default `viewers.config.yaml` configures four viewers:
+
+```yaml
+viewers:
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/neuroglancer.yaml"
+
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/avivator.yaml"
+
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/validator.yaml"
+
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/vole.yaml"
+```
+
+## Capability Manifest Files
+
+Manifest files describe a viewer's identity and capabilities. The default manifests are hosted in the [`@bioimagetools/capability-manifest`](https://github.com/BioImageTools/capability-manifest) repository. You can host your own manifest files anywhere accessible via URL. See the [`@bioimagetools/capability-manifest`](https://github.com/BioImageTools/capability-manifest) repository for information on how to format a viewer manifest.
+
+## Configuration Examples
+
+### Minimal: single viewer
+
+```yaml
+viewers:
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/neuroglancer.yaml"
+```
+
+### Override a viewer's URL
+
+Use `instance_template_url` to point to a custom deployment of a viewer while still using its manifest for capability matching:
+
+```yaml
+viewers:
+  - manifest_url: "https://raw.githubusercontent.com/BioImageTools/capability-manifest/host-manifests-and-docs/manifests/avivator.yaml"
+    instance_template_url: "https://my-avivator-instance.example.com/?image_url={dataLink}"
+
+```
+
+### Add a custom viewer
+
+To add a new viewer, create a capability manifest YAML file, host it at a URL, and reference it in the config:
+
+1. Create a manifest file (e.g., `my-viewer.yaml`). Follow the format guidelines in the [`@bioimagetools/capability-manifest`](https://github.com/BioImageTools/capability-manifest) repository.
+
+2. Host the manifest at an accessible URL (e.g., on GitHub or any web server).
+
+3. Reference it in `viewers.config.yaml`:
+
+```yaml
+viewers:
+  - manifest_url: "https://example.com/manifests/my-viewer.yaml"
+    label: "Open in My Viewer"
+```
+
+## How Compatibility Works
+
+The `@bioimagetools/capability-manifest` library handles all compatibility checking. When a user views an OME-Zarr dataset:
+
+1. The application reads the dataset's metadata (OME-Zarr version, axes, codecs, etc.)
+2. For each registered viewer, the library's `validateViewer()` function compares the dataset metadata against the manifest's declared capabilities
+3. Only viewers whose capabilities match the dataset are shown to the user
+4. Incompatibility reasons (e.g., "Viewer does not support OME-Zarr v3") are logged to the browser console for debugging
+
+This replaces the previous system where `valid_ome_zarr_versions` was a global config setting and custom viewers used simple version matching. Now all compatibility logic is driven by the detailed capabilities declared in each viewer's manifest.
+
+## Viewer Logos
+
+Viewer logos are managed by the `@bioimagetools/capability-manifest` library. Logo resolution follows this order:
+
+1. **Override**: If the manifest includes a `viewer.logo` field, that URL is used directly
+2. **Convention-based**: Otherwise, the logo URL is derived from the viewer name (lowercased, spaces replaced with hyphens, e.g. "OME-Zarr Validator" → `ome-zarr-validator.png`) and hosted alongside the manifests
+3. **Fallback**: If the logo fails to load at runtime, a bundled fallback image is shown
+
+## Development
+
+When developing with custom configurations:
+
+1. Copy the default config: `cp frontend/src/config/viewers.config.yaml frontend/viewers.config.yaml`
+2. Edit `frontend/viewers.config.yaml`
+3. Rebuild frontend: `pixi run node-build` or use watch mode: `pixi run dev-watch`
+4. Check the browser console for viewer initialization messages
+
+### Validation
+
+The configuration is validated at build time using Zod schemas (see `frontend/src/config/viewersConfig.ts`). Validation enforces:
+
+- The `viewers` array must contain at least one entry
+- Each entry must have a valid `manifest_url` (a properly formed URL)
+- Optional fields (`instance_template_url`, `label`) must be strings if present
+
+At runtime, manifests that fail to load are skipped with a warning. If a viewer has no `template_url` (neither from its manifest nor from `instance_template_url` in the config), it is also skipped.
+
+## Copy URL Tool
+
+The "Copy data URL" tool is always available when a data URL exists, regardless of viewer configuration.

fileglancer/server.py

@@ -442,6 +442,22 @@ async def version_endpoint():
         return {"version": APP_VERSION}
 
 
+    @app.get("/api/viewers-config", include_in_schema=False)
+    async def get_viewers_config():
+        if not settings.viewers_config:
+            raise HTTPException(status_code=404, detail="No viewers configuration")
+
+        config_path = PathLib(settings.viewers_config)
+        if not config_path.exists() or not config_path.is_file():
+            logger.warning(f"Viewers config file not found: {settings.viewers_config}")
+            raise HTTPException(status_code=404, detail="Viewers configuration file not found")
+
+        return PlainTextResponse(
+            content=config_path.read_text(encoding="utf-8"),
+            media_type="text/yaml"
+        )
+
+
     # Authentication routes
     @app.get("/api/auth/login", include_in_schema=settings.enable_okta_auth,
              description="Initiate OKTA OAuth login flow")

fileglancer/settings.py

@@ -113,6 +113,11 @@ class Settings(BaseSettings):
     # Username used when creating a session via the test-login endpoint.
     test_login_username: str = "jacs"
 
+    # Optional path to a viewers configuration YAML file.
+    # When set, the file is served at GET /api/viewers-config, allowing
+    # runtime customization of OME-Zarr viewers without rebuilding the frontend.
+    viewers_config: Optional[str] = None
+
     model_config = SettingsConfigDict(
         yaml_file="config.yaml",
         env_file='.env',