Add discovery and asset-specific research pathways for federal collections

DESIGN.md

@@ -236,3 +236,46 @@ keep choices theme-driven. Support hover, click/touch, native radio keyboard
 navigation, Escape with focus restoration, and dismissal outside the control.
 Long labels wrap and the choices scroll when necessary. Keep provider credits
 outside this control and visible when it is expanded.
+
+### Collection portals
+
+The optional `homepage.collection_intro` uses a split introduction and an actual
+collection asset, followed by three compact discovery pathways and the existing
+interactive map. This is a reusable collection layout, not an agency-specific
+component. On small screens the introduction, image, pathways and map stack in
+reading order. Asset captions remain outside the image and carry attribution;
+links have visible focus states. Use stable facts about formats and coverage,
+not counts that could drift from the API.
+
+NASA GIBS uses navy navigation, cool blue surfaces and satellite imagery. The
+National Map uses USGS-inspired navy, restrained green accents and terrain.
+Historical Topographic Maps uses forest navigation, warm paper, rust accents
+and serif headings to complement the scanned sheets. The collection symbols
+are original navigation graphics, not official NASA or USGS insignia. Keep the
+community-prototype notice visible. Existing institutional heroes are unchanged.
+
+## Asset-specific research workspaces
+
+Federal research workspaces use a compact institutional header and task-specific
+workspaces. Imagery has a dark two-date comparison stage with a shared extent;
+elevation pairs a prominent tile-index map with a selection/download ledger;
+historical maps use paper tones, linked georeferenced views and edition chronology.
+Retain the existing theme colors, typography, source attribution and scoped catalog.
+These layouts are selected by workflow capability in config, never institution IDs.
+
+Keep asset meaning visible: exact imagery dates, nominal versus actual tile bounds,
+and edition versus printing years. Unsupported capabilities have explicit states.
+Use original services and georeferenced assets for research comparison; browse
+thumbnails are only discovery aids. On narrow screens, stack controls and views
+without hiding metadata or download access. Every shared label is localizable.
+
+### Two complementary collection pathways
+
+Keep the standard discovery home as each collection’s entry point. When a theme
+configures research tools, show the same two-link pathway navigation in both the
+standard header and the research header: “Search & browse” and “Research workspace.”
+Keep both links visible on mobile, indicate the current pathway with an underline
+and `aria-current`, and describe the research task using localized theme copy.
+The switch also belongs on search results and record pages so neither experience
+becomes a dead end. Keep conventional catalog filters and research URL parameters
+independent; both pathways remain shareable through static hash routes.

README.md

@@ -230,6 +230,19 @@ npm run scaffold        # create a starter themes/<theme-id>.yaml file
 npm run deploy          # publish dist/ with gh-pages
 ```
 
+### Matching CI locally
+
+CI runs on the current Node LTS release. Verify its reported Node version when
+reproducing a failure; a passing run on a different runtime is not a CI result.
+Run `npm ci`, `npm run lint -- --max-warnings=0`, `npm run typecheck`,
+`npm run test:ci`, and `npm run build`. The coverage command enforces the existing
+80% line and statement thresholds; a plain `vitest run` does not.
+
+Vitest workers disable Node's native Web Storage with
+`--no-experimental-webstorage` so happy-dom and jsdom provide isolated browser
+storage. This avoids the Node 25+ / Vitest 3 global collision without a shared
+storage file or changing application behavior.
+
 ## Creating A New Institution Theme
 
 Use the scaffold helper to create a starter theme file:
@@ -414,3 +427,63 @@ resource thumbnails before deployment. A cold render still depends on remote
 basemap data and available worker capacity. The local preview harness now loads
 missing public resource geometry into its isolated test database on demand;
 this behavior is not installed in the production API.
+
+### Federal collection prototypes
+
+The theme selector includes three collection portals, also available at stable
+static paths (append to your deployment base URL):
+
+| Theme                            | Home path    | Catalog scope                                        |
+| -------------------------------- | ------------ | ---------------------------------------------------- |
+| NASA GIBS                        | `nasa-gibs/` | `pcdm_memberOf_sm = nasa-gibs`                       |
+| USGS The National Map            | `usgs-tnm/`  | USGS provider + `dcat_keyword_sm = The National Map` |
+| USGS Historical Topographic Maps | `usgs-htmc/` | `pcdm_memberOf_sm = usgs-htmc`                       |
+
+For example, `https://opengeometadata.github.io/ogm-discovery/nasa-gibs/`
+and `https://opengeometadata.github.io/ogm-discovery/usgs-htmc/#/resources/usgs-htmc-314262`.
+The existing `?ogm_theme=<id>` entry point also works. Selecting a theme opens
+its home URL and clears the previous collection's route and filters. These are
+community prototypes, not official agency websites.
+
+Set the optional `homepage.collection_intro` to use an asset-led collection
+home above the interactive discovery map. Existing themes keep their current
+hero layout when the field is absent. All copy fields accept localized objects:
+
+- `eyebrow`: short collection identifier above the existing `institution.hero_text`
+  and `institution.hero_description`.
+- `image`: `src` (bundled or remote), localized `alt` and `caption`, and an internal
+  `href` to a record or search. The caption should include source attribution.
+- `facts`: an array of localized `value` / `label` pairs. Use stable collection
+  characteristics, not hardcoded live record counts.
+- `pathways`: an array of localized `label`, `title`, `description`, plus an internal
+  `href` for a curated discovery route.
+- `map_heading` and `map_description`: localized context for the live map.
+
+Reuse `homepage.hero_actions`, `hero_map`, `featured_items`, and branding tokens
+for actions, map coverage, previews and palette. Local images resolve against the
+Vite base path. No new API or server is required. See
+[the collection research and asset notes](docs/federal-collection-themes.md)
+for source provenance, preview limitations and screenshots.
+
+### Asset-specific research workspaces
+
+An optional top-level `research` configuration enables an asset-specific workspace
+at `#/research` alongside the standard discovery experience. Every collection
+home (`#/`) retains its search, browse and map interface. A shared “Search & browse” /
+“Research workspace” switch appears in both interfaces, including catalog results
+and record pages. Themes without `research` keep their existing navigation.
+The older `#/about-collection` link remains a compatible alias for the discovery home.
+
+- `kind`: `imagery`, `elevation`, or `editions` (workflow capabilities, not institution IDs).
+- `title`, `description`, `note`: localized text objects.
+- `records`: initial metadata record IDs with localized `label` objects.
+- `bbox`: default `[west, south, east, north]` geographic study area.
+- `search`: optional collection metadata search; optional `resource_type` adds an existing API facet filter.
+- Imagery: `dates` and `imagery.map_endpoint`, `imagery.domain_endpoint`, `imagery.tile_matrix_set` configure a daily WMS/WMTS adapter.
+- Editions: `sheet` and `editions` select the initial sheet name and pair of record IDs.
+
+See the federal YAML presets for complete examples and
+[research pathways and API gaps](docs/federal-research-pathways.md) for semantics,
+supported assets, URL state, and limitations. The elevation example deliberately
+supports the configured rectangular DEM index rather than treating every TNM
+asset as an elevation raster.

docs/federal-collection-themes.md

@@ -0,0 +1,127 @@
+# Federal collection prototypes
+
+The collection homes retain standard discovery alongside [asset-specific research workspaces](federal-research-pathways.md), with a visible switch between both pathways.
+This document records the initial branding/source review; its original landing-page
+screenshots remain useful for reviewing `#/about-collection`. Current workflow
+screenshots are in `screenshots/research-pathways/`.
+
+Reviewed November 4, 2026. These are OpenGeoMetadata community interfaces, not
+agency websites. All three use the existing API, record viewer, search and map
+components. No metadata mirror, proxy, dependency or agency-specific component
+branch is introduced.
+
+## Source and asset review
+
+### NASA Global Imagery Browse Services
+
+Reviewed the [repository README](https://github.com/OpenGeoMetadata/gov.nasa.gibs),
+Terra/MODIS true-color and VIIRS city-lights Aardvark records, their service
+references, [Worldview](https://worldview.earthdata.nasa.gov/) in the browser, and
+[GIBS documentation](https://nasa-gibs.github.io/gibs-api-docs/).
+
+The repository builds one record per visualization layer from capabilities,
+layer metadata, Worldview configuration and CMR. These are visualization services,
+not a uniform collection of downloadable source datasets. Raster layers can link
+XYZ, WMTS and WMS; vectors use geographic WMS; polar-only layers may have no
+compatible Web Mercator preview. Default imagery dates can be partly filled.
+Worldview is the appropriate destination for time exploration.
+
+Worldview's dark controls and image-dominated map informed the navy header,
+blue accents and night-imagery introduction. The pathways lead to an actual
+true-color record, the exact `Climate` facet, and a 2012 night-time composite.
+The still image is explicitly dated; it is not advertised as a live observation.
+
+### USGS The National Map
+
+Reviewed the [repository README](https://github.com/OpenGeoMetadata/gov.usgs.tnm),
+Iowa NHD package, Iowa 3DEP tile, 1/3 arc-second index record and GeoJSON, and
+[The National Map website](https://www.usgs.gov/programs/national-geospatial-program/national-map)
+in the browser. Its navy federal header, white reading surfaces and green program
+accents informed the palette.
+
+The repository organizes 17 datasets into packages, with multiple downloads on
+one record. The inspected NHD package has GeoPackage, geodatabase and shapefile
+ZIPs plus FGDC metadata and an ArcGIS dynamic map service. Services display more
+than a package footprint. Elevation tiles link directly to COGs. The inspected
+DEM index contains 1,449 polygon features with `recId`, `download`, `thumbUrl`
+and `websiteUrl`; its internal record route is the tile-discovery entry point.
+Combined vector packages and some other datasets have no service preview.
+
+The terrain image comes from the official USGS shaded-relief service, not the
+Iowa tile. Its caption identifies the Colorado Plateau and the service credits.
+Pathways lead to the elevation index, NHD packages and boundary packages.
+
+### USGS Historical Topographic Map Collection
+
+Reviewed the [repository README](https://github.com/OpenGeoMetadata/gov.usgs.htmc),
+Bright Angel 1906 / printed 1918 record and its GeoPDF, the Arizona 1:48,000 index
+record and GeoJSON, and [topoView](https://ngmdb.usgs.gov/topoview/) in the browser.
+The [USGS collection overview](https://www.usgs.gov/programs/national-geospatial-program/historical-topographic-maps-preserving-past)
+is linked from the portal. Automated retrieval of that overview timed out;
+topoView and the repository provided the review evidence.
+
+The repository describes scans from the 1884–2006 collection era. The sample
+sheet links a COG, GeoTIFF/GeoPDF downloads, FGDC metadata, a thumbnail and a
+ScienceBase landing page. Edition, survey, revision and printing dates have
+different meanings. The Arizona index has 31 map features across 15 sheets;
+editions overlap, and `datePub`, `dateSurvey` and `dateReprnt` preserve chronology.
+
+Warm paper, brown contour ink and the source site's editorial serif treatment
+informed the historical theme. The featured image retains its edition and print
+dates in its caption. Pathways offer the gallery, an actual sheet index and
+oldest-first browsing. They reuse the record viewer; this PR does not implement
+a separate time slider or comparison engine.
+
+## Scope and API evidence
+
+Live checks of `https://ogm.geo4lib.app/api/v1/` returned:
+
+| Portal               | Always-on filters                  | Observed count |
+| -------------------- | ---------------------------------- | -------------: |
+| NASA GIBS            | `pcdm_memberOf_sm=nasa-gibs`       |          1,241 |
+| HTMC                 | `pcdm_memberOf_sm=usgs-htmc`       |        177,788 |
+| National Map keyword | `dcat_keyword_sm=The National Map` |         91,969 |
+
+Counts are review-time observations, not promises or UI constants. The TNM preset
+also restricts `schema_provider_s` to `U.S. Geological Survey`; a provider-only
+scope would mix historical maps into this portal. Collection records without
+membership are still accessible by direct resource links. TNM uses the existing
+keyword/provider contract rather than inventing a repository filter. A future
+backend repository facet would provide a more explicit scope if these terms are
+reused by additional USGS repositories.
+
+Browser checks confirmed the NHD pathway returns 2,715 packages and theme
+selection changes the path and clears the old search. Resource-class caches are
+partitioned by theme so switching from NASA to HTMC cannot retain imagery tabs. NASA topic labels come
+from the live facet API (`Climate`, not a guessed ISO category name).
+
+## Bundled image provenance
+
+- `earth-at-night.jpg`: NASA GIBS `VIIRS_CityLights_2012`, from the WMS reference in
+  [`nasa-gibs-viirs_citylights_2012`](https://github.com/OpenGeoMetadata/gov.nasa.gibs/blob/main/metadata-aardvark/gibs/viirs/nasa-gibs-viirs_citylights_2012.json).
+  [WMS request](https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.1&LAYERS=VIIRS_CityLights_2012&STYLES=&SRS=EPSG:4326&BBOX=-130,10,-60,60&WIDTH=1200&HEIGHT=800&FORMAT=image/jpeg).
+  Acknowledgement appears in the portal footer and image caption.
+- `usgs-shaded-relief.jpg`: public-domain image from
+  [USGS Shaded Relief](https://basemap.nationalmap.gov/arcgis/rest/services/USGSShadedReliefOnly/MapServer),
+  exported for bounds `-115,34,-109,39`, geographic input / Web Mercator output,
+  1,200 × 900 pixels. Credits: USGS The National Map / 3DEP and USGS EROS / GMTED2010.
+- `bright-angel-1906.jpg`: rendered from the original public-domain
+  [USGS GeoPDF](https://prd-tnm.s3.amazonaws.com/StagedProducts/Maps/HistoricalTopo/PDF/AZ/48000/AZ_Bright%20Angel_314262_1906_48000_geo.pdf),
+  linked by [`usgs-htmc-314262`](https://github.com/OpenGeoMetadata/gov.usgs.htmc/blob/main/metadata-aardvark/htmc/314/usgs-htmc-314262.json).
+  The introduction crops the sheet photographically; the record links the full map.
+- The three SVG collection symbols are original simple line graphics (globe,
+  terrain and contours), not official seals or logos.
+
+Bundling keeps the first view independent of third-party thumbnail availability.
+Interactive maps and record previews continue to load directly from their service
+providers, and remain subject to upstream availability and browser CORS support.
+
+## Review screenshots
+
+Captured from the local application with live API data. Desktop and mobile
+screenshots cover each preset; no mock metadata or fabricated result counts.
+
+| NASA GIBS                                                              | The National Map                                                     | Historical Maps                                                        |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| ![NASA desktop](screenshots/federal-collections/nasa-gibs-desktop.jpg) | ![TNM desktop](screenshots/federal-collections/usgs-tnm-desktop.jpg) | ![HTMC desktop](screenshots/federal-collections/usgs-htmc-desktop.jpg) |
+| ![NASA mobile](screenshots/federal-collections/nasa-gibs-mobile.jpg)   | ![TNM mobile](screenshots/federal-collections/usgs-tnm-mobile.jpg)   | ![HTMC mobile](screenshots/federal-collections/usgs-htmc-mobile.jpg)   |