Renderive/render_3D/datoviz/spec/docs/GALLERY_SITE.md

Gallery Site Notes

This document owns public-doc-site implementation notes for the v0.4 gallery. Scene example style rules live in ../scene/examples/STYLE.md.

MkDocs Material Direction

For v0.4, keep the public website and documentation in one MkDocs Material site. The goal is not a separate marketing stack; it is a visual documentation front door backed by reproducible gallery assets. A custom web application becomes useful later only if Datoviz needs live WebGPU embeds, benchmark dashboards, richer release/news pages, or product-level storytelling that MkDocs cannot carry cleanly.

Use this order of complexity:

1. Markdown plus Material cards for most index pages.
2. Custom CSS in docs/stylesheets/extra.css for Datoviz-specific card grids, image overlays, dark gallery bands, responsive media, badges, and lead cards.
3. Generated Markdown for gallery pages from example metadata.
4. A page-local template override only for the homepage or top gallery index if Markdown becomes too constrained.
5. Additional JavaScript only for progressive enhancement such as lightweight filters, media lazy-loading, or WebGPU demo mounting.

Do not fork the Material theme for normal gallery work. Prefer small CSS and template overrides that can survive theme upgrades.

Page Shapes

Page	Shape
Home	compact hero, four-card visual-proof grid, six start links, current status
Gallery index	lane overview with large cards for showcases and smaller cards for visual/features
Showcase page	one large screenshot or looped video, short thesis, source link, run/capture command, feature tags
Visual-family page	controlled baseline image, supported attributes, minimal C example, deferred variants
Technique page	before/after or side-by-side image pair, limits, backend requirements
Runtime/WebGPU page	explicit experimental labels, supported subset, unsupported-feature diagnostics

Example cards should use real <img> or <video> elements, not CSS background images, so alt text, loading behavior, social previews, and future asset checks stay straightforward.

Live WebGPU/WASM Examples

Treat live WebGPU/WASM gallery examples as progressive enhancement over stable PNG or video artifacts. The default gallery artifact remains static media; live execution is an optional browser path for examples where interactivity, animation, or backend proof materially improves the page.

The source of truth remains the normal C example tree plus example metadata. WASM modules, JavaScript bundles, packed assets, generated manifests, and deployment-specific paths are generated artifacts. Do not commit them unless a release-artifact policy explicitly approves the exact files.

Each gallery example may advertise independent capabilities:

Capability	Meaning
static-media	Has PNG and/or video fallback used as the default gallery artifact.
wasm-supported	Builds and runs through the portable WASM/WebGPU scene path.
gallery-live	Is selected for public live embedding with browser fallback UX.

Live embeds must:

1. load only after user intent or viewport visibility;
2. fall back to PNG or video when WebGPU, WASM, assets, or diagnostics fail;
3. use the shared scene -> DRP2 -> WebGPU path, not a duplicate gallery renderer;
4. be generated by CI/deployment from source examples and metadata;
5. report unsupported features honestly.

Data-backed live embeds must use fetched, versioned web bundles instead of growing the base WASM module with build-time preloaded example data. The bundle contract and migration plan live in ../data/WEBGPU_DATA_BUNDLES.md.

Prefer broad WASM build coverage but curated public embedding. A release can compile many examples to WASM for validation while showing only a small gallery-live subset on the public gallery.

Front-page card set

Use four visual-proof cards so the homepage reaches onboarding links quickly. Keep the six-card capacity for the separate text-first Start here grid. The current visual set is:

1. point cloud;
2. brain volume plus transparent mesh;
3. wind field;
4. choropleth.