[#562] Rebuild the KHIX homepage rendering pipeline

.forge/features/homepage-memory/spec.md

@@ -0,0 +1,73 @@
+# KHIX Homepage Memory Optimization Spec
+
+Status: Approved
+
+## User-facing purpose
+
+The public Knight Hacks IX homepage should retain its illustrated, animated
+experience while loading quickly and remaining responsive throughout a visit.
+Scrolling through the full page or leaving it open must not cause browser memory
+to climb toward gigabyte-scale usage.
+
+## Users / actors
+
+- Prospective hackers, sponsors, speakers, and community members visiting the
+  public homepage on desktop or mobile.
+- Visitors who prefer reduced motion or use a lower-powered device.
+
+## User-visible interface
+
+- The full `/` homepage: hero, About, Tracks, Speakers, Sponsors, Team, FAQ, and
+  footer.
+- The existing parallax, gallery, speaker carousel, waterfall, ambient creature,
+  cave-note, and Lenny interactions remain recognizable.
+- Reduced-motion visitors receive complete static artwork without decorative
+  autoplay motion.
+
+## Scope
+
+### In scope
+
+- Replace memory-intensive decorative animation delivery with bounded,
+  viewport-aware media while preserving transparent artwork and motion.
+- Serve static raster artwork at dimensions appropriate to its rendered size.
+- Defer below-the-fold media and data until it is near the viewport.
+- Pause timers, media, and CSS animation when their section or browser tab is not
+  active.
+- Reuse browser audio resources across cave-note interactions.
+- Improve initial hero discovery and paint without changing the visual hierarchy.
+
+### Out of scope
+
+- Portal, dashboard, application, credits, and other non-homepage routes.
+- Changes to event copy, sponsor data, team membership, or authentication.
+- A visual redesign or removal of the KHIX illustrated theme.
+- CDN deployment or changes to external asset storage.
+
+## Vocabulary
+
+- `ambient media`: decorative looping motion that is not required to understand
+  or operate the page.
+- `viewport-aware`: active only while the relevant section is visible or close to
+  visible.
+- `static fallback`: the existing non-animated art shown when motion is disabled
+  or video playback is unavailable.
+
+## Acceptance criteria
+
+- The homepage keeps its layered hero, moving water, atmospheric motion, gallery,
+  speaker carousel, interactive tracks, cave notes, and blinking Lenny.
+- Animated assets no longer retain every full-resolution WebP frame in browser
+  image memory.
+- Images with small rendered dimensions do not download/decode their original
+  multi-megapixel sources.
+- Below-the-fold autoplay work is idle before the visitor approaches it and
+  pauses after it leaves the viewport or the document becomes hidden.
+- Repeated cave-note interactions share one audio context.
+- Desktop and mobile layouts remain visually coherent at current breakpoints.
+- The page remains fully usable with `prefers-reduced-motion: reduce`.
+
+## Open questions
+
+- None. The user explicitly requested a broad homepage pass that preserves or
+  improves visual quality while dramatically improving performance.

.forge/features/homepage-memory/srd.md

@@ -0,0 +1,88 @@
+# KHIX Homepage Memory Optimization SRD
+
+Status: Approved
+
+## Technical purpose
+
+Bound the KHIX homepage's decoded media, compositor, DOM-animation, timer, and
+audio costs without reducing the site's art direction. Issue #562 supplies the
+initial suspects; profiling the full homepage determines the implementation.
+
+## Relevant principles
+
+- `docs/agentic-development/forge-engineering-principles.md#react-and-nextjs-principles`
+- `docs/agentic-development/forge-engineering-principles.md#readability-and-colocation`
+- `docs/agentic-development/forge-engineering-principles.md#testing-principles`
+- `docs/agentic-development/frontend-design-skill.md`
+
+## Access policy
+
+The homepage remains public and unauthenticated. This work adds no logged-in or
+permission-based behavior.
+
+## Architecture / data flow
+
+- Changes stay in `apps/2026` and its public assets.
+- Decorative animated WebPs are transcoded to transparent VP9 WebM. Existing
+  static scene layers remain underneath as fallbacks.
+- A small app-local ambient-video component owns intersection, document
+  visibility, and reduced-motion playback lifecycle.
+- Homepage components independently pause section-specific timers or CSS
+  animation when inactive.
+- No shared package or new dependency is required.
+
+## tRPC/API behavior
+
+No API contract changes. The existing public team-roster request keeps its
+contract but begins only when the Team section approaches the viewport.
+
+## Validation
+
+No new data validation. Media elements retain accessible fallbacks, and all
+decorative video remains hidden from assistive technology.
+
+## Data / migration / compatibility
+
+- No database or migration changes.
+- Transparent WebM is an enhancement over existing static scene art. Browsers
+  that cannot play it still render the static fallback.
+- Rollback consists of restoring the prior WebP references and component
+  lifecycles.
+
+## Discord integration
+
+None.
+
+## Configurability review
+
+Would this require a developer change next year?
+
+- Answer: Only when yearly artwork itself changes, as it already does.
+- The media lifecycle component is generic within the 2026 app; event and roster
+  content remain untouched.
+
+## React / frontend constraints
+
+- Keep `page.tsx` server-side and isolate browser lifecycle behavior in focused
+  client components/hooks.
+- Preserve server-rendered initial hero art so LCP discovery does not depend on
+  hydration.
+- Set explicit responsive `sizes` and use Next image optimization for raster
+  images that do not need original-file delivery.
+- Do not keep permanent `will-change` hints on large inactive surfaces.
+- Honor reduced motion and document visibility in every autoplay lifecycle.
+- Maintain existing semantic controls, labels, focus behavior, and static art.
+
+## Testing / verification strategy
+
+- Static regression tests cover viewport-activity rules where practical.
+- Run `pnpm --filter=@forge/2026 test`, `lint`, `typecheck`, and `build`.
+- Run `pnpm analyze:react:changed` for the meaningful React changes.
+- Compare production-mode Lighthouse desktop/mobile reports before and after.
+- Inspect the live and local page at desktop and mobile breakpoints, including
+  reduced motion and interactive controls.
+- Verify generated media metadata, transparency, dimensions, and file sizes.
+
+## Open questions
+
+- None.

.forge/features/homepage-memory/status.md

@@ -0,0 +1,72 @@
+# KHIX Homepage Memory Optimization Status
+
+Current phase: Complete
+
+## Decision log
+
+- 2026-09-11: User requested a broad homepage optimization rather than a literal
+  checklist implementation of issue #562. Visual quality and interactions must
+  be preserved or improved while performance improves dramatically.
+- 2026-09-11: Scope is limited to `apps/2026` homepage behavior and assets; no
+  shared packages, dependencies, data, auth, or portal behavior will change.
+- 2026-09-11: Use transparent VP9 video plus existing static fallbacks for large
+  decorative animation. Make all autoplay work viewport-, visibility-, and
+  reduced-motion-aware.
+
+## Open questions
+
+- None.
+
+## Task list
+
+- [x] Complete reverse-prompting for `spec.md` from issue #562 and user scope.
+- [x] Complete reverse-prompting for `srd.md`.
+- [x] Complete reverse-prompting for `test-cases.md`.
+- [x] Record user approval of the broad performance/quality direction.
+- [x] Finish desktop and mobile baseline profiling.
+- [x] Generate and verify optimized transparent video assets.
+- [x] Implement responsive image and media lifecycle changes.
+- [x] Implement viewport-aware animation, timer, data, and audio lifecycles.
+- [x] Run scoped validation and the 2026 app formatting gate.
+- [x] Complete desktop/mobile/browser lifecycle verification.
+
+## Validation / commands
+
+- `pnpm install --frozen-lockfile`: passed.
+- `pnpm forge:feature homepage-memory "KHIX Homepage Memory Optimization"`:
+  first attempt failed because dependencies were absent; passed after install.
+- Live desktop Lighthouse baseline: performance 62, LCP 11.7 s, 87 requests,
+  19,334 KiB transferred, with about 7,116 KiB estimated image-delivery savings.
+- Observed Chrome memory on the same full-page test fell from approximately
+  1.3 GB to 450 MB after the rendering and media lifecycle changes.
+- Media inspection: the nine largest static/animated suspects represent roughly
+  1.34 GiB of worst-case RGBA frame data; `extended-front.webp` alone is
+  3840x12000 (175.8 MiB decoded), and the animated WebPs contain 5-20 frames.
+- Final desktop Lighthouse: performance 87, LCP 2.3 s, 57 requests, and 2.30
+  MiB transferred. Compared with production, transfer fell 87.8%, LCP fell
+  80.2%, and the performance score rose 25 points.
+- Final mobile Lighthouse: performance 63, LCP 7.5 s, 53 requests, and 1.30
+  MiB transferred. Compared with production, transfer fell 88.1%, LCP fell
+  64.6%, total blocking time fell 64.6%, and the score rose 21 points.
+- `pnpm --filter=@forge/2026 test`: passed (14 tests).
+- `pnpm --filter=@forge/2026 typecheck`: passed with a 4 GiB Node heap after
+  the default 2 GiB process exhausted its heap.
+- `pnpm analyze:react:changed`: passed (0 failures).
+- Production `@forge/2026` build: passed with local non-secret environment
+  placeholders.
+- In-app browser checks: desktop and mobile composition preserved, no
+  horizontal overflow, no runtime console errors, responsive video sources
+  selected correctly, and only near-viewport video/ambient work became active.
+- Final architecture follow-up: replaced the desktop hero's nine decoded image
+  layers with one AVIF composition and one merged transparent ambient video;
+  replaced 154 animated waterfall DOM nodes with one viewport-bound canvas;
+  and limited the waterfall to one active, centered video stream at a time.
+- Final in-app browser hero sample: 567 DOM nodes, one active 1280x720 ambient
+  video, no active canvas, and approximately 12.1 MiB of decoded in-DOM imagery.
+- `pnpm --filter @forge/2026 format`: passed.
+
+## Links
+
+- PRs:
+- Issues: https://github.com/KnightHacks/forge/issues/562
+- Discord/thread context:

.forge/features/homepage-memory/test-cases.md

@@ -0,0 +1,153 @@
+# KHIX Homepage Memory Optimization Test Cases
+
+Status: Approved
+
+## Scope
+
+Homepage media loading, autoplay lifecycle, responsive image delivery, cave-note
+audio reuse, and visual/interactive regressions. Portal and non-homepage routes
+are excluded.
+
+## Test placement plan
+
+- App-level lifecycle tests in `apps/2026` where behavior can be isolated.
+- Browser and Lighthouse verification against the production build.
+- Commands: `pnpm --filter=@forge/2026 test`, `lint`, `typecheck`, `build`, plus
+  `pnpm analyze:react:changed`.
+
+## Test cases
+
+### TC-001: Initial hero is discoverable before hydration
+
+Setup:
+
+- Load `/` on a fresh desktop or mobile navigation.
+
+Action:
+
+- Inspect the initial document and first visual paint.
+
+Expected observations:
+
+- A viewport-appropriate base hero image is present immediately.
+- Only that critical base image receives high fetch priority.
+- The remaining layers appear without a layout shift.
+
+### TC-002: Ambient animation uses bounded video decoding
+
+Setup:
+
+- Load `/` with normal motion preferences.
+
+Action:
+
+- Visit the hero, waterfall, and footer regions.
+
+Expected observations:
+
+- Water and Lenny motion remain visible through transparent looping video.
+- The previous animated WebP resources are not requested.
+- Existing static layers remain visible if video is unavailable.
+
+### TC-003: Ambient work follows viewport and tab activity
+
+Setup:
+
+- Load `/` with normal motion preferences.
+
+Action:
+
+- Scroll each animated section in and out of range, then hide and restore the
+  document.
+
+Expected observations:
+
+- Video, decorative CSS animation, gallery rotation, and speaker rotation run
+  only when relevant and pause while offscreen or hidden.
+- User controls still work immediately when a section is visible.
+
+### TC-004: Static raster images are responsive
+
+Setup:
+
+- Load `/` at desktop and mobile widths.
+
+Action:
+
+- Inspect requested image URLs and intrinsic dimensions after scrolling through
+  the page.
+
+Expected observations:
+
+- Hero layers, track characters/leaves, speaker art, and other small rendered
+  rasters use responsive image variants instead of full original dimensions.
+- Artwork remains crisp at its rendered size.
+
+### TC-005: Cave-note audio resources are reused
+
+Setup:
+
+- Load the FAQ and activate multiple gemstone/hotspot notes.
+
+Action:
+
+- Trigger notes repeatedly, including overlapping notes.
+
+Expected observations:
+
+- Notes remain audible and responsive.
+- A single reusable audio context is used, and completed node graphs disconnect.
+
+### TC-006: Interactive homepage behavior is preserved
+
+Setup:
+
+- Load `/` and scroll through the full page.
+
+Action:
+
+- Use hero/apply navigation, gallery controls, tracks reveal, speaker controls,
+  sponsor/team links, FAQ categories/questions, and footer links.
+
+Expected observations:
+
+- Controls remain keyboard accessible and visually coherent.
+- No horizontal overflow or material layout shift is introduced.
+
+## Negative / regression cases
+
+### TC-NEG-001: Reduced-motion preference
+
+Setup:
+
+- Enable `prefers-reduced-motion: reduce` before loading `/`.
+
+Action:
+
+- Scroll through the full page and use all controls.
+
+Expected observations:
+
+- Decorative video and CSS autoplay motion remain paused/hidden.
+- Static hero, waterfall, speaker, and Lenny artwork remains complete.
+- User-triggered controls continue to work without animated transitions where
+  applicable.
+
+### TC-NEG-002: Video playback is unavailable
+
+Setup:
+
+- Simulate an unsupported or failed WebM source.
+
+Action:
+
+- Visit each video-enhanced section.
+
+Expected observations:
+
+- The underlying static art prevents blank or broken scene regions.
+- No unhandled promise rejection is logged.
+
+## Open questions
+
+- None.