feat(docs): GH Pages material-catalog gallery — filterable, searchable, with /tst preview

[gerchowl]

Motivation

We now have all the ingredients for a public material-catalog gallery (~5200 materials across 4 sources):

• HF substrate catalogs with full `mat_vis` block: PBR scalars (`metalness`, `roughness`, `ior`, `transmission`, `color_rgb`, etc.), attribution (`authors`, `license_spdx`, `source_url`), `category`, `tags`, `dates`, `physical.dimensions_m`
• 256² thumbnails published per material (feat(ci): derive matrix — kind: thumb (wire #361 thumb-bake into derive.yml) #402/feat(ci): derive matrix — kind: thumb (#402) #403; ambientcg shipped, polyhaven/gpuopen/physicallybased baking)
• Validated client API (`VisAsset.thumb`, `repr_html`) end-to-end

Today the only consumer surface is `VisAsset.repr_html` (Jupyter rich-repr from #363) — one material at a time, not a hosted gallery. Researchers, build123d users, and CG hobbyists have no browsable index.

Proposed approach

A statically-generated site published to GitHub Pages at `https://morepet.github.io/mat-vis/\` with a `/tst/` parallel-preview instance for staging-substrate validation before promoting to prod.

Data layer

Build-time fetch of `huggingface.co/datasets/gerchowl/mat-vis/resolve//release-manifest.json` + per-source catalogs + thumb URLs. No runtime HF API calls — site is fully static, browser doesn't hit HF except to load images (which CDN-cache).

Catalog data: ship as DuckDB-WASM in-browser DB OR pre-built Pagefind index OR JSON + FlexSearch/MiniSearch. Spike to decide — see scope.

UX

• Grid view: thumb + material name + source badge + license SPDX badge + category tag. Filterable by source, category, license, has-thumb, scalar-only, etc.
• Per-material detail page: full PBR scalar dump + attribution + texture-tier availability + direct HF download links + "Use in build123d" code snippet
• Search: fuzzy by name, by tag, by upstream URL. Type-ahead.
• Side-by-side compare (P1): pick 2-4 materials, see their PBR scalars + thumbs in a table
• Categories: drill down by category (metal / wood / fabric / etc.)
• Permalinks: `/material//` URLs

Parallel /tst preview

Two parallel hosted instances:

• `/` — built from current prod release tag (`gerchowl/mat-vis`)
• `/tst/` — built from the latest `gerchowl/mat-vis-tst` cut, lets us eyeball a re-bake before promoting

Mechanism TBD by spike — candidates: GH Pages with subdir publishing, Cloudflare Pages preview deploys, Netlify deploy previews, GitHub Pages deployment environments.

CI

• New workflow `pages.yml` triggered by:
  • `workflow_dispatch` (manual rebuild)
  • On `release` event (auto-rebuild on substrate-tag bump)
  • Scheduled cron (catch substrate hot-fix re-bakes)
• Builds site, publishes to `gh-pages` branch (or via `actions/deploy-pages`)

Scope

P0 (working prototype)

• Spike 1: data + search architecture (DuckDB-WASM vs Pagefind vs FlexSearch/MiniSearch)
• Spike 2: parallel /tst preview mechanism (the GH-native or third-party app)
• Spike 3: static-site framework (Astro / SvelteKit / Vite vanilla / Eleventy)
• Build script: fetch HF manifest+catalogs → emit JSON/index/DB for the site
• Page: grid view with filter sidebar
• Page: per-material detail
• Search: fuzzy by name + tag
• Source/license badges
• `pages.yml` workflow
• Deployable artifact (everything ready except the publish PAT)

P1

• Side-by-side compare
• Permalinks + deep links from `VisAsset.repr_html` to the hosted page
• /tst parallel preview live
• Direct HF download links per tier
• "Use in build123d" code snippet generator
• Accessibility (keyboard nav, ARIA, screen reader)

P2

• Multi-language (en/de at least)
• OG image per material for social embeds
• PWA / offline-first via service worker (since data is static, this is nearly free)
• Telemetry-free analytics (Plausible / GoatCounter / none)

Pitfalls

• Substrate has ~5200 materials; eager-load grid would be slow. Need virtual scrolling or pagination.
• License-badge accuracy: `license_spdx` field is upstream-truth; verify across CC0 / CC-BY / CC-BY-NC / non-CC. Display attribution per upstream's terms.
• Per-material thumbs: ~5200 × 50KB ≈ 260MB total. Don't bundle into the GH Pages artifact; lazy-load from HF.
• DuckDB-WASM is ~2MB gzipped — heavy. FlexSearch is ~30KB. Pagefind is build-time-indexed (smallest runtime, but less query flexibility).
• GH Pages has a 1GB repo size limit + 10GB/month bandwidth soft cap. Since thumbs proxy to HF, this is fine.
• The "PAT to host it" — GH_PAGES_PAT repo secret needs publish-to-gh-pages permission. Must be supplied before first deploy.

Acceptance criteria

P0 (working prototype):

• `cd docs/site && npm run build` produces a static site under `docs/site/dist/`
• `docs/site/dist/index.html` renders the grid with at least ambientcg (the only source with thumbs today)
• Search box: type "metal" → only metal-category materials show
• Click a material → detail page with PBR scalars + attribution + license
• Source/license badge rendering correct
• `pages.yml` workflow exists, dry-run produces the artifact, only the publish step lacks the PAT secret
• /tst preview mechanism chosen + documented + ready to wire in (PAT pending)

References

• feat(bake): dedicated "thumb" tier — sphere-rendered material previews #361 / feat(bake): thumb-tier renderer pipeline (closes #361) #395 (thumb bake pipeline)
• feat(client): VisAsset.thumb discovery surface (#362) #363 (VisAsset.thumb + repr_html)
• feat(ci): derive matrix — kind: thumb (wire #361 thumb-bake into derive.yml) #402 / feat(ci): derive matrix — kind: thumb (#402) #403 (derive matrix `kind: thumb`)
• investigate: VisAsset.thumb returns 434KB but HF file is 47KB for same material #421 (size-mismatch followup — should be resolved before gallery publishes)
• HF substrate at `huggingface.co/datasets/gerchowl/mat-vis` (prod)
• Spike subagents to run: data/search arch, preview-deploy mechanism, framework choice