Files
Esiah-s-Universe/docs/AGENTS.md
T
Esiah 8727eac300 Refactor scroll system, regions, layout and download flow
- Completely reworked `useRegionScroll` controller: paginated region-by-region scroll (wheel/swipe/arrows/Home/End/Space), native scroll neutralized, regions taller than viewport split into screens, time-based rAF animation, interruption only on effective deviation.
- Region resolution in 3 levels: `data-region` (single element), `data-region-children` (each direct child), `.page-snap-section` as fallback. Added `data-no-region` to exclude hero/title.
- Homepage: entire MagicBento as a single region. Projects page: one stop per project (`HorizontalMotion` with `data-region-children`), category title preserved, hero excluded.
- Project detail pages (ProjectPage): hero excluded from regions, media in `data-region-children`, download button as separate region.
- Contact/PageShell: updated markers, removed empty zones (no forced `min-height` on `.page-snap-section`).
- Removed unbounded `--region-tail` in favor of capped reserve (15vh) + merged landing spots too close to each other.
- Navigation: more reliable scroll-to-top, footer "Co Hai Se" bold with target cursor.
- ZIP download: stopped propagation + global click handler ignores download.
- Various fixes (cursor, 404, layouts), docs updated, typecheck/ignoreDeprecations adjusted.
2026-10-22 15:20:20 +02:00

76 lines
3.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 `<html>`: 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
## Docs
Update `ROADMAP.md` regularly when tasks progress/completed/planned.