diff --git a/docs/explorations/0196_[x]_IMAGE_RICH_INTERACTIVE_CHANGELOG_PAGE.md b/docs/explorations/0196_[x]_IMAGE_RICH_INTERACTIVE_CHANGELOG_PAGE.md new file mode 100644 index 000000000..0500741c2 --- /dev/null +++ b/docs/explorations/0196_[x]_IMAGE_RICH_INTERACTIVE_CHANGELOG_PAGE.md @@ -0,0 +1,1049 @@ +# Image-Rich & Interactive Changelog Page + +## Problem Statement + +The xNet public changelog page (`site/src/pages/changelog/index.astro`) is a +clean vertical timeline of text entries with optional hero images. That +foundation is solid — RSS, JSON feed, dark mode, PR links, tag badges — but it +treats media as an afterthought. Entries carry a single optional `hero` image +and the `ChangelogEntry` type has no fields for image galleries, before/after +comparisons, or video clips. Meanwhile the CI visual-capture pipeline +(exploration 0185) already produces per-PR screenshot sets including baseline, +current, and diff frames — exactly the raw material a great changelog page +wants. + +The gaps this exploration addresses: + +- **No image gallery**: multi-screenshot entries show at most one image. +- **No before/after comparison**: the CI pipeline produces baseline + current + pairs but there is no UI to compare them. +- **No search or tag filtering**: the `tagColor` map in `index.astro` renders + badges but clicking them does nothing. +- **No video support**: `ChangelogEntry` has no video field; features that are + better shown than described get a screenshot if they're lucky. +- **No contributor attribution**: entries link to a PR number but don't surface + the author avatar or name from the GitHub API. +- **No copy-link affordance**: the `

` links to `#entry-id` but there's no + visible "copy anchor link" button. + +This is a static Astro site (no server, no framework JS). Any solution must +work as vanilla JS islands or pure CSS. + +## Executive Summary + +The headline answer to "show most/all of the images from the diff, +automatically": each changelog entry already carries a `pr` number, and every +post-0189 PR has a **durable `diff-manifest.json`** enumerating every captured +screenshot (with before/after/diff frames, captions, and SSIM). So the gallery +should be **auto-derived from that manifest at build time** — fetch it in the +Astro page's frontmatter, drop the `unchanged` rows, and render the rest. No +manual image curation; the gallery grows itself as CI captures more surfaces. +A curated `images[]`/`hero` override stays available for backfilled entries (no +manifest) and for hand-picking a hero. + +Around that core, the right approach for a minimal-JS static changelog is a +**layered upgrade**: + +0. **Auto-gallery from the visual-capture manifest** — at SSG time, for each + entry with a `pr`, fetch `https://xnet.fyi/visuals/pr//diff-manifest.json`, + keep `status !== "unchanged"`, and feed the results into the gallery + + before/after sliders + video below. This is the centerpiece. +1. **Multi-image support in the data model** — extend `ChangelogEntry` with an + `images` array (each with `src`, `alt`, optionally `caption`, and an + optional `before`/`after` pair marker) as the manual override / fallback. +2. **PhotoSwipe v5 as the lightbox** — 26 KB gzipped, zero runtime deps, + framework-free, best-in-class keyboard nav and ARIA. Load it only when the + page has gallery entries (a single ` +``` + +### Before/after comparison slider + +```html + + + + {`Before: + {`After: + +``` + +### Video with prefers-reduced-motion + +```html +
+ +
{entry.video.alt}
+
+ + +``` + +### Vanilla JS tag filter + +```html + +
+ + {Object.keys(tagColor).map(tag => ( + + ))} +
+ + +``` + +### Copy-link button + +```html +

+ {entry.title} + +

+ + +``` + +## Risks And Open Questions + +1. **PhotoSwipe CDN vs bundled**: Using a CDN `