Instruction file imported from sprzedawcaMily/mikolaj-portfolio (.cursor/rules/scroll-morph-stability.mdc). Copyright stays with the author.

Scroll morph — stabilność i wydajność

Architektura

• Warstwa: FlyingMeshDots (#mesh-flying-layer, canvas #flying-mesh-canvas)
• Silnik: flyingDotEngine.ts — lot kropek, paint canvas, morph między strefami
• Scroll / strefy: meshScrollEngine.ts — dyskretne strefy z histerezą
• Pętla: meshAnimationLoop.ts — jeden RAF; FlyingMeshDots subskrybuje tick
• CSS scroll: setMeshScrolling → html.mesh-scrolling (klasa z meshZoneStore.ts)

Zasada główna

Scroll wybiera strefę docelową. Kropki lecą wspólnym tempem morphu — nie mapuj progressu 1:1 na scroll position (wyjątek: pin layout palety od anchorów DOM).

Łańcuch stref

hero → palette → bus → fork → spray → loupe → ring → careerEye → skillsEye → contactArrow

scrollLite — stabilność (nie psuj)

scrollLite — wydajność (zatwierdzona konfiguracja)

Ta kombinacja daje akceptowalny FPS (np. ~120+ przy 144 Hz) przy minimalnym scrollu w dół od hero.

FlyingMeshDots.tsx

• scrollLite: scrolling, wireStride przy scrollu: 4 (normal), 5–6 (lite/slow/reduced)
• Pomiń tick co 2. klatkę RAF gdy scrolling && !isMeshMorphBusy(pool) — animacja twarzy ~72 Hz wystarczy
• ?full=1 (isMeshFullFps) — stride 1 tylko poza scrollem

flyingDotEngine.ts

meshScrollEngine.ts

• computeAllZonePins(frameId, scrollHold) — przy scrollHold=true (scrollLite) cache pinów na 2 klatki (mniej getBoundingClientRect)

perf.css

/* Tylko sekcje poniżej hero — header i #top zachowują glass */
html.mesh-scrolling #studio-palety, #projekty, … { backdrop-filter: none !important; }

Nie używaj html.mesh-scrolling * — zabija blur headera i hero.

Antywzorce (powodują regresje)

// ❌ Kreski znikają
skipWires = scrollLite && zone === 'hero';

// ❌ Skok kropek przy scrollu
syncRigidLayoutFollow(...) // gdy freezeHeroScroll
heroFaceActive = ... && !scrollLite;
paintHeroCanvasDots(..., scrollFrozen: scrollLite);

// ❌ Podwojenie / „milion kropek”
hideDotElement(dot); // bez detach gdy canvas przejął strefę
fullClear = scrollLite; // czyści canvas wysokości całej strony
clearWireCanvasRegion(fullClear) na klatkach bez paintu

// ❌ Zamrożenie twarzy
faceMotionReady = !scrollLite && ...; // + brak lerp w scrollLite

// ❌ FPS 144→80 przy minimalnym scrollu
for (const dot of pool.dots.values()) { stepHairMix(...) } // w scrollLite
settleHeroMeshDots(...) // co klatkę w scrollZoneIdle
// brak scrollDormant / scrollZoneIdle / tick co 2. klatkę
// brak wyłączenia backdrop-filter w mesh-scrolling

Inne invarianty

• Histereza stref (committedZone, ZONE_HYSTERESIS_PX)
• setMorphZoneLock — blokada flipu strefy w trakcie morphu
• Reflektory — snapReflectorForMorph + reflectorIgnite
• Spray footprint — rozszerzony clip (sprayPaintMargin)
• Ring shimmer — tylko kropki, nie kreski
• Mobile ≤959px — brak FlyingMeshDots; scroll perf hero nie dotyczy telefonu

Pliki