Smooth Scrolling (WebApp) — מדריך תמציתי לסוכני AI

מדריך זה מסביר את יכולות הגלילה החלקה שהוטמעו ב‑WebApp, כיצד להשתמש בהן באופן בטוח, ומה הדגשים לסוכני AI כדי לשמור על נגישות וביצועים.

מה פעיל כבר

  • טעינה גלובלית של רכיבי הגלילה: - webapp/static/js/smooth-scroll.js (מנגנון JS) - webapp/static/css/smooth-scroll.css (סגנונות בסיס + נגישות) - משולב אוטומטית דרך webapp/templates/base.html

  • תמיכה בכניסות קלט: - Wheel/Trackpad (גלגלת) עם אנימציה חלקה - מקלדת: PageUp/Down, Home/End, חיצים - קישורי עוגן (Anchor Links) עם גלילה חלקה

  • נגישות: - כיבוד prefers-reduced-motion: reduce — אנימציות מקוצרות/מכובות - Fallback של scroll-behavior: smooth כאשר JS לא זמין

  • אנדרואיד (מורחב): - מאזיני touch ב‑{passive: true} + דגימת מהירות בזמן אמת - Momentum משופר + בוסטר אינרציה כאשר אין אינרציה נייטיבית - הזרקת מחלקות android-optimized / android-no-bounce לאיפוס overscroll - התאמות Samsung Internet (מניעת scroll-behavior כפול) - ניטור FPS שמקצר משך אנימציה בעת עומס - כרטיס ”גלילה חלקה“ במסך ההגדרות מאפשר לכוון משך, easing ורגישות (וקיים בכל פלטפורמה)

API לשימוש קליינט

  • הפעלה/כיבוי:

window.smoothScroll.enable();
window.smoothScroll.disable();

  • עדכון הגדרות בזמן ריצה:

window.smoothScroll.updateConfig({
  duration: 300,              // ms
  easing: 'ease-out',         // 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'
  offset: 80,                 // px, למשל Sticky Header
  wheelSensitivity: 1.0,      // 0.1–3
  keyboardSensitivity: 1.5    // 0.5–3
});

  • גלילה לאלמנט/סלקטור:

window.smoothScroll.smoothScrollTo('#section-2', {
  offset: 80,
  duration: 400,
  easing: 'ease-in-out'
});

שמירת העדפות

  • השמירה מתבצעת ל‑localStorage תחת smoothScrollPrefs.

  • ניסוי שליחה עדינה לשרת (אם קיים API): POST /api/ui_prefs עם { smooth_scroll: {...} }.

  • כישלון שרת אינו חוסם — אין תלות בבקשת ה‑POST.

ממשק הגדרות מובנה

  • במסך /settings קיים כרטיס גלילה חלקה עם הטפסים הבאים: - Toggle הפעלה/כיבוי - סליידר משך (150‑1200ms) + בחירת easing - רגישות גלגלת/מקלדת (0.5‑3x) - סליידר אינרציה לאנדרואיד (10‑60x) - כפתורי בדיקה/איפוס/שמירה

  • ניתן עדיין לפתוח חלונית debug באמצעות הוספת smooth_debug=1 ל‑URL לצורך ניטור מהיר.

  • שליטה תכנותית קיימת דרך הקונסול באמצעות updateConfig:

window.smoothScroll.updateConfig({
    duration: 350,
    wheelSensitivity: 1.2
});

הנחיות לסוכני AI

  • זיהוי מהיר של זמינות:

const supported = Boolean(window.smoothScroll?.config?.enabled);

  • הימנעו מאזיני wheel/touch כפולים: המערכת מאזינה גלובלית כברירת מחדל.

  • כבדו נגישות: אם prefers-reduced-motion פעיל — אל תוסיפו אנימציות ידניות.

  • לכוונון — השתמשו ב‑updateConfig ולא בכתיבה ישירה ל‑localStorage.

  • שמרו על ביצועים: אל תוסיפו לולאות polling/setInterval כבדות; העדיפו requestAnimationFrame.

אנדרואיד — מה יש ומה לא

הוטמעו: - Passive touch listeners + דגימת מהירות - Momentum יזום עם בוסטר אינרציה וכיול friction/threshold - התאמות Samsung Internet ו‑overscroll (android-optimized) - ניטור FPS שמכוונן משך/עקומת אנימציה - UI מובנה לקביעת עוצמת אינרציה ומשך

לא הוטמעו (ייעשה בשלבים הבאים): - אופטימיזציות WebView מתקדמות (lazy, IntersectionObserver מותאם) - A/B test לניהול פרופילי ביצועים ספציפיים לדפדפנים

נגישות וביצועים

  • נגישות: - prefers-reduced-motion: reduce מבטל/מקצר אנימציה. - גלילה לעוגנים מכבדת offset לכותרות sticky.

  • ביצועים: - Throttle ל‑wheel סביב 16ms - שימוש ב‑requestAnimationFrame לכל האנימציות - ב‑Android, קיצור משך אנימציה אם FPS ירוד

פתרון תקלות

  • “גלילה עדיין קופצת ב‑Samsung”: - נבדק UA לזיהוי Samsung; מוודאים ש‑document.documentElement.style.scrollBehavior = 'auto' הופעל.

  • “אין השפעה לשינוי הגדרות”: - ודאו שהקריאה היא דרך updateConfig / כרטיס ההגדרות ב‑/settings ושקיים window.smoothScroll.

  • “משתמש עם Reduced Motion עדיין רואה אנימציות”: - בדקו את העדפת המערכת (DevTools > Rendering > Emulate CSS prefers-reduced-motion).

  • “אני לא בטוח אם הפיצ’ר פועל”: - הוסיפו ל‑URL את הפרמטר smooth_debug=1 (למשל /?smooth_debug=1 או &smooth_debug=1) כדי לפתוח חלונית בדיקה. - החלונית מציגה אם הדפדפן מסמן prefers-reduced-motion, אם המנגנון פעיל, ומאפשרת להפעיל/לכבות או למחוק את ההעדפה שנשמרה ב‑localStorage.

תוכנית המשך (Roadmap מקוצר)

  • CodeMirror: גלילה חלקה בתוך העורך ו‑Jump to line

  • TOC חכם: שימוש ב‑offset, Smart Scrolling, Active item

  • ניטור מתקדם (PerformanceObserver + Analytics)

  • אופטימיזציות WebView ו‑Virtual Scrolling לרשימות ארוכות

קישורים פנימיים

  • קוד: webapp/static/js/smooth-scroll.js | webapp/static/css/smooth-scroll.css | webapp/templates/base.html

  • API: POST /api/ui_prefs (עדכון העדפות UI, Best‑effort בלבד)