# AGENTS.md — Esiah's Universe ## Core Rules - Never commit or push without explicit user request. - Always respond in English. - No automatic git operations (commit/push/amend/force). - Keep changes minimal and scoped to request. - Do not modify unrelated files. - Ask for clarification if ambiguous. ## Project Context Esiah's Universe is an interactive React/Vite portfolio (WebGL/GSAP). Static site for showcase; projects data in `src/components/data/ProjectDetails.tsx`. Navigation via CardNav/InfiniteMenu. Build with `npm run build`. ## Git Workflow - Check `git status`/`git diff` before any git action. - Only act on git when explicitly asked. - Never push to remote unless explicitly requested. - Use clear commit messages if asked to commit. ## Code Conventions - TypeScript strict, React 18+, Vite - Tailwind CSS - GSAP for animations - gl-matrix for WebGL/math - Follow existing patterns, minimal diffs - No secrets in code ## Scroll System - A **region** is an element or a group of elements, not a page wrapper. - Declare them in the markup, three levels of priority: 1. `data-region` on the element: that element is exactly one region. 2. `data-region-children` on a container: each **direct child** is one region. 3. `.page-snap-section` is only a **fallback**: it counts as a region when it contains no `data-region` / `data-region-children` marker. - `data-no-region` excludes an element (and its subtree) from the regions: page titles/heroes are not landing points, the first region is the one **below** the title. Keep the hero excluded, otherwise the first scroll only moves a few percent of the viewport. - Every section must be covered: a section taller than its content creates an empty zone where the scroll feels like a plain scroll. Sections hug their content, and galleries expose one region per project (`data-region-children` on the list holding the project cards). - **The page never rests between two regions.** A gesture (wheel, swipe, arrow key, Space) moves to the next/previous region: native scrolling is neutralised (`wheel` / `touchmove` are `preventDefault`ed). - Regions taller than the viewport are subdivided into screens, so their content stays readable. Landing spots = region tops + screen offsets. - The wheel threshold is proportional to the region being crossed (50–300px): the pace follows the size of the content. - Keyboard: Arrow/PageUp/PageDown/Space step one region, Home/End jump to the first/last region. - Region targets are measured on the **layout** (`offsetTop` chain, not `getBoundingClientRect`) so entrance transforms (translate/scale) cannot offset the landing position. Offset = `--nav-offset` (100px) + 2rem. - Animation is a **time based rAF** loop (power3.out, 420–900ms), never a GSAP tween: `ScrollTrigger.refresh()` (triggered by `AnimatedContent` resizing the body) restores the scroll position and kills `ScrollToPlugin` tweens mid-flight. An animation is interrupted only by a scroll that does not match the position it just applied (compared to the last applied value, not to the interpolation). - The hook publishes `--region-tail` on ``: the extra bottom padding needed (capped to 15vh) to align the last region without a large empty void so the last region can still be aligned under the nav. - Do NOT re-enable native `scroll-snap-type`: Chrome's proximity snap pulls the page backwards and traps the user on the first region. - Never put `overflow-x: hidden/clip` on `html`/`body`: it breaks the sticky nav. - Immersive routes (`html.no-snap`) must stay scroll-free. ## Before Finishing - Run `npm run build` if changes affect build - Verify paths/imports - Keep assets organized