# Gasser GSAP Route Transition + Aligned Hero Assets

Session-derived pattern for Gasser-style local-business websites using Astro ClientRouter, GSAP logo intros, and client-supplied layered hero artwork.

## When to use

Use when the homepage has:

- a direct first-visit logo intro;
- a separate, subtler page-transition animation for internal navigation;
- layered hero artwork where a base architectural/plan image must align exactly with a hover/reveal overlay.

## Direct homepage intro vs route transition

Keep two distinct animation policies:

1. **Direct first homepage load**
   - Run the larger architectural logo intro.
   - Respect `sessionStorage.gasserIntroSeen`.
   - Hide header and hero copy only during the intro.
   - After completion, set the overlay to `display: none`, not merely `opacity: 0`.

2. **Internal navigation, including return to `/`**
   - Do **not** replay the full homepage intro.
   - Run only the compact route transition.
   - Suppress `.site-intro` on Astro swaps so old homepage intro markup cannot flash.

## Astro ClientRouter pitfall

If the transition overlay is appended to `document.body`, Astro body swaps can remove it during navigation. This makes the transition appear missing or inconsistent.

Preferred pattern:

- create the route overlay once;
- append it to `document.documentElement`, not `body`;
- start the route transition immediately in the captured click handler after confirming the link is internal/navigable;
- keep `astro:before-preparation` only for cleanup/state reset, not as the sole trigger;
- ensure route overlay styles exist before every run;
- after the GSAP timeline completes, remove the running class and set `display: none`.

## Timing guidance

For a subtle but visible internal route transition, around `1.1–1.3s` reads better than a sub-second flash.

Example GSAP timing shape:

- depth/raster fade in: `0.30–0.35s`;
- logo focus: `0.50–0.55s`;
- logo exit/blur: `0.60–0.65s`, starting around `0.50–0.55s`;
- overlay fade out: last `0.30–0.35s`, ending around `1.2s`.

Keep this smaller than the first-visit homepage intro so it does not feel like a loader on every click.

## Layered hero assets

When the user supplies a base drawing and hover/reality overlay, do not substitute similar previous versions. File names matter when the visual alignment has been corrected by the user.

For the Gasser hero correction, the correct pair was:

- base: `Bleistiftzeichnung_beton_neu.png`;
- hover overlay: `überlagerung_realer.png`.

Avoid stale variants such as:

- `bleistiftzeichnung_beton.png` when a newer `_neu` asset exists;
- `bleistiftzeichnung_ueberlagerung.png` if the user explicitly requested `überlagerung_realer.png`;
- white/BW/original sketch startup layers after the homepage intro has moved to the logo intro.

## Pixel alignment checks

Before claiming layered artwork is correct, verify:

- both images have the same natural pixel dimensions;
- both are rendered in identical DOM rectangles;
- both share the same `object-fit`, `object-position`, `transform`, and `transform-origin`;
- both use the same mask geometry unless intentionally different;
- hover overlay only changes opacity/mask radius, not position/scale.

Browser-side checks can inspect:

```js
[...document.querySelectorAll('.hero-sketch-bg img')].map(img => {
  const cs = getComputedStyle(img);
  const r = img.getBoundingClientRect();
  return {
    src: img.getAttribute('src'),
    natural: [img.naturalWidth, img.naturalHeight],
    rect: [Math.round(r.x), Math.round(r.y), Math.round(r.width), Math.round(r.height)],
    objectFit: cs.objectFit,
    objectPosition: cs.objectPosition,
    transform: cs.transform,
    transformOrigin: cs.transformOrigin,
  };
});
```

Also inspect loaded resources and DOM sources for stale assets:

```js
performance.getEntriesByType('resource')
  .map(r => r.name)
  .filter(n => /Bleistiftzeichnung|überlagerung|bleistiftzeichnung|ueberlagerung/.test(n));
```

## Cleanup rule

If old visual assets are no longer meant to be used and are tracked in `public/images`, remove them from the repo after replacing references. Otherwise browser caches, OG metadata, or stale CSS references can keep them appearing during internal navigation or social previews.

Search both `src/` and built `dist/` after build for old names before final reporting.