feat: atlas pages: add cap (cell annotation platform) link at the atlas level, sourced from the atlas tracker api (#3179)

[frano-m]

Summary

Closes #3179

Surfaces the atlas's Cell Annotation Platform (CAP) link on atlas pages, sourced from the Atlas Tracker API rather than hardcoded in constants/networks.ts, and threads the per-entity capUrl we were already receiving but discarding.

Atlas level

• apis/tracker/types.ts — adds capId and cellxgeneAtlasCollection to PublishedAtlas (names match the merged tracker PR feat: expose atlas-level CAP and CELLxGENE collection links on /api/published-atlases (#1546) clevercanary/hca-atlas-tracker#1547).
• apis/tracker/api.ts — adds resolveTrackerAtlas, returning the full published-atlas record; resolveTrackerAtlasId becomes a thin wrapper, so its three existing callers are untouched.
• @types/network.ts — adds cap to Atlas, mirroring cxgDataPortal.
• utils/trackerAtlasPages.ts — carries CAP and CELLxGENE from the resolved tracker record onto processedAtlas.
• .../SideColumn/utils.ts — appends the CAP link in getDataExplorationTools. Order is CZ CELLxGENE Collection → Cell Annotation Platform → cell browser → BioTuring Collection.

The CELLxGENE collection now comes from the tracker for tracker atlases, falling back to the configured cxgId — the issue's final open question. The link label stays "CZ CELLxGENE Collection" in both cases, consistent with the other Data Exploration Tools entries, which all name the tool.

Per-entity

• @types/network.ts — adds capUrl: string | null to TrackerComponentAtlas and TrackerSourceDataset, plus ANALYSIS_PORTAL.CAP.
• constants/analysisPortals.ts — adds the CAP analysis portal, with a new public/hca-bio-networks/network/atlas/icons/cap.svg asset.
• utils/trackerNetwork.ts — buildTrackerAnalysisPortals(capUrl) builds tracker analysis portals CAP-only (tracker entities have no CELLxGENE explorer URL) and returns [] when capUrl is null.
• Integrated Objects table shows the Explore column for tracker atlases, but only when at least one object has a CAP link.
• Source Datasets table gains an Explore column, hidden via columnVisibility while every row's capUrl is null.

The table label is CAP rather than the full name — the full name overflowed the grid and pushed the Download column out of view, and abbreviating matches CZ CELLxGENE vs the side column's CZ CELLxGENE Collection.

Blocked on the tracker release

The atlas-level link cannot render until clevercanary/hca-atlas-tracker#1547 ships — it is merged, but the release PR (clevercanary/hca-atlas-tracker#1541, v1.82.0) is still open, so prod /api/published-atlases does not return capId yet.

Merging early does not break anything. Every consumer is truthiness-guarded and each false branch reproduces the previous behaviour exactly; the build was verified against prod tracker in this state. The atlas-level link is simply inert until the tracker deploys, with no further code change needed. Worth a quick check that capId is present on /api/published-atlases after the deploy before closing the issue.

The per-entity half is not blocked — capUrl is already populated on /api/atlases/{id}/component-atlases.

Verification

• npm run build-dev:data-portal passes; 65/65 pages generated.
• Gut v1.0 Overview shows five per-object CAP links resolving to https://celltype.info/project/1030/dataset/*; one was opened and loads the matching CAP page.
• Gut v1.0 Source Datasets tab shows no Explore column — all 27 datasets have capUrl: null today.
• Retina v1.0 (non-tracker) is unaffected: Data Exploration Tools renders as before, no CAP link.
• Atlas-level logic verified directly across five cases — CAP only, config cxgId fallback, tracker collection beating config, titled collection, and neither present (renders [], so no empty section).
• npx tsc --noEmit, npm run lint (0 errors) and prettier --check all clean.

Not in scope

Source studies carry a capId (null for all 22 gut studies today); the issue does not ask for it, so it is left for a follow-up. Non-tracker atlases have no config-level CAP fallback — the issue's other open question, deliberately left open.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Surfaces Cell Annotation Platform (CAP) links across atlas pages by consuming tracker-provided CAP metadata (atlas-level CAP project link and per-entity CAP dataset links), and updates tracker atlas resolution to return the full published-atlas record so those fields can be threaded into page props and UI.

Changes:

• Adds CAP support to tracker and network types, plus a CAP analysis-portal definition and icon asset.
• Threads tracker CAP fields into atlas page static props and renders the CAP project link under “Data Exploration Tools”.
• Enables “Explore” links for tracker integrated objects / source datasets when CAP URLs are present, including conditional column visibility.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
@types/network.ts	Adds ANALYSIS_PORTAL.CAP, atlas-level cap link, and per-entity capUrl fields.
apis/tracker/types.ts	Extends PublishedAtlas with capId and cellxgeneAtlasCollection.
apis/tracker/api.ts	Introduces resolveTrackerAtlas() (full record) and keeps resolveTrackerAtlasId() as a wrapper.
utils/network.ts	Adds builders for CAP analysis portal + CAP project link; centralizes CXG collection label constant.
utils/trackerNetwork.ts	Builds CAP-only analysis portals for tracker entities and prefers tracker CXG collection over config fallback.
utils/trackerAtlasPages.ts	Uses resolveTrackerAtlas() to populate cap and tracker-sourced CXG collection link on processed atlas.
constants/analysisPortals.ts	Adds the CAP analysis portal definition (icon/label/name).
public/hca-bio-networks/network/atlas/icons/cap.svg	Adds CAP icon asset.
components/.../SideColumn/utils.ts	Inserts CAP project link into “Data Exploration Tools” link list.
components/.../Overview/.../MainColumn/utils.ts	Adds shouldShowExplore() for tracker integrated objects table Explore-column gating.
components/.../Overview/.../MainColumn/mainColumn.tsx	Uses shouldShowExplore() to conditionally show Explore for tracker atlases.
components/.../Datasets/.../table/viewBuilder.ts	Adds Explore-cell renderer for tracker source datasets using CAP analysis portals.
components/.../Datasets/.../table/utils.ts	Adds conditional column visibility logic for the tracker source datasets table.
components/.../Datasets/.../table/hook.ts	Applies computed column visibility for tracker source datasets.
components/.../Datasets/.../table/columns.ts	Adds an “Explore” column to the tracker source datasets table.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[frano-m]

Code review pass

Ran a high-effort review over the branch diff. Two findings, one actioned:

Fixed — stale JSDoc (68dd7ed). viewModelBuilders.ts:368 still documented showExplore as "omitted for tracker atlases", which this PR makes false: tracker atlases now show the Explore column when at least one integrated object has a CAP link. Now reads "omitted when no atlas has an analysis portal to link to".

Not actioned — capId used verbatim as a link URL. Flagged on the theory that capId might be a bare id (e.g. 1030), which would render a broken relative <a href="1030">. It is a full URL, so no composition or guard is needed:

• GET /api/atlases/4d291476-9ba5-4bd1-8b6d-23f48765e365 on prod returns "capId":"https://celltype.info/project/1030".
• feat: expose atlas-level CAP and CELLxGENE collection links on /api/published-atlases (#1546) clevercanary/hca-atlas-tracker#1547 projects that same dbAtlas.overview.capId value onto /api/published-atlases unchanged; its test fixture is capId: "https://celltype.info/project/60582".
• Both tracker capId fields (atlas and source study) are validated by capProjectUrlSchema. The name is a known misnomer that feat: expose atlas-level CAP and CELLxGENE collection links on /api/published-atlases clevercanary/hca-atlas-tracker#1546 deliberately declined to rename, since a rename would break write bodies and need a JSONB key migration.

Verified as correct with no changes needed: grid-track count stays in sync with the visible columns for both the 5- and 6-column cases; the source datasets table derives its grid from getVisibleFlatColumns(), so hiding explore cannot desync it; { url, ...CAP } cannot clobber url because CAP is Omit<AnalysisPortal, "url">; and no undefined is introduced into getStaticProps props.

Copilot's review generated no comments.

Still blocked on the tracker release

Re-checked today: prod /api/published-atlases still returns only id, name, network, publishedAt, shortName, shortNameSlug, version — no capId — and chore(main): release 1.82.0 (clevercanary/hca-atlas-tracker#1541) is still open. The atlas-level CAP link stays inert until that ships; the per-object CAP links on the Overview table work today.

[NoopDog]

Reviewed with Claude Code (high effort). No correctness defects in the diff — verified the CAP URL contract, the conditional Explore column and grid track sizing, and the falsy spread guards.

Two notes, both accepted as-is:

• utils/trackerNetwork.ts: tracker cellxgeneAtlasCollection taking precedence over the curated cxgId (e.g. liver v1.0) is the intended behavior.
• apis/tracker/types.ts: capId/cellxgeneAtlasCollection are typed required but absent from the currently deployed tracker API; fine until the tracker release ships.