Text Book Reader

קורא ספרי הטקסט

lib/text_book/ הוא הפיצ'ר הגדול ביותר באפליקציה — קורא הספרים הטקסטואליים. דף זה מתאר את ה־BLoC, טעינת התוכן ומצבי התצוגה. למפרשים וקישורים ראו מפרשים וקישורים.

תמונת־על

• BLoC יחיד לכל טאב — TextBookBloc מחזיק את כל מצב הספר הפתוח.
• שכבת תצוגה לפי אסטרטגיה (Strategy Pattern) — שלושה מצבים: מפרשים בצד (split), מפרשים מתחת (combined), וצורת הדף (page shape).
• טעינה עצלה ברקע — טקסט, קישורים, TOC ומפרשים נטענים בהדרגה דרך TextBookRepository.
• עיקרון אינדקסים: כל האינדקסים ב־state הם שורות־מקור — ‏0-based בקוד, ‏1-based ב־DB ובקישורים. "מצב קריאה רציף" מוסיף שכבת ReadingSegment שהיא פריט תצוגה בלבד.

ה־BLoC — ‏bloc/

TextBookLoaded — המצב המרכזי

מכיל בין השאר: content (רשימת שורות־מקור, כולל placeholders ריקים לשורות שטרם נטענו), contentVersion (מונה שמכריח rebuild), קישורים (links, ‏linksByLine במפתח 1-based, ‏visibleLinks), מפרשים (זמינים/פעילים/קבוצות/נדירים), ‏TOC, סגמנטים של קריאה רציפה, אינדקסים גלויים ונבחרים (כולל ריבוי בחירה), דגלי תצוגה, ניקוד/פיסוק, מצב חיפוש, הדגשות, ובקרי גלילה של scrollable_positioned_list.

זרימת פתיחת ספר — _onLoadContent

1. חלון תוכן התחלתי — getBookContentRange סביב המיקום הראשוני (כ־80 שורות לפני / 180 אחרי).
2. אם אין תמיכה בטווחים — ‏fallback ל־preview מהיר (getBookQuickPreview) והשלמת הספר המלא ברקע.
3. ‏fallback אחרון — טעינת תוכן מלא + פיצול שורות ב־isolate.
4. טעינת TOC, חישוב כותרת נוכחית (refFromIndex), קביעת ברירות מחדל של ניקוד/פיסוק/קריאה רציפה.
5. רישום listener על מיקומי הגלילה — ממיר גלילה לאירועי UpdateVisibleIndecies עם debounce של 160ms.
6. פליטת TextBookLoaded והרצת משימות רקע: השלמת טווחי תוכן, חימום מטמון, טעינת קישורים ומפרשים, העשרת קטגוריות.

ניהול זיכרון וטעינה עצלה

• חימום מטמון — chunks של 640 שורות סביב ה־viewport, מוחלים באצוות של 8 כדי לא לגרור rebuilds; מושהה בזמן גלילה ומדולג בטאב רקע.
• שחרור בטאב רקע — SetTabVisibility(false) מחליף שורות מחוץ לחלון ב־placeholders (רק בספרים מעל 2000 שורות שתומכים בטווחים).
• מעקב טעינה דרך _loadedContentFlags — אסור להניח ששורה טעונה רק כי היא קיימת ברשימה.
• contentVersion מקודם בכל החלת טווח — כך עוקפים את השוואת ה־Equatable מבוססת האורך.

TextBookRepository

• getBookContent / getBookContentRange — שרשרת: ‏LibraryProviderManager ← ‏DatabaseLibraryProvider (ב־isolate) ← ‏SqliteDataProvider ← קובץ (docx דרך מטמון המרה). תומך ב־versionTitle (מהדורה חלופית).
• getBookLinksInRange — קישורי בסיס + קישורי משתמש (forward ו־inverse).
• getCommentatorsWithRarity — מפרשים עם סימון "נדירים" (מוסתרים כברירת מחדל).
• getTableOfContents — עם fallback לפרסור תוכן ב־isolate‏ (TocParser).

מצבי התצוגה

TextBookScreen (ה־scaffold: ‏AppBar, כפתורים, קיצורים) ← ‏TextBookScaffold בוחר אסטרטגיה:

מצב	אסטרטגיה	מסך
צורת הדף	PageShapeStrategyImpl	PageShapeScreen
מפרשים בצד	SplitViewStrategyImpl	SplitedViewScreen(showSplitView: true)
מפרשים מתחת (ברירת מחדל)	CombinedViewStrategyImpl	SplitedViewScreen(showSplitView: false)

שימו לב: SplitedViewScreen משרת גם split וגם combined לפי דגל — אין קובץ נפרד ל־combined.

CombinedView — ‏view/combined_view/combined_book_screen.dart

הקורא המרכזי: ‏ScrollablePositionedList שבו itemCount = מספר סגמנטים. כל פריט עטוף ב־EnhancedGestureDetector: לחיצה = בחירה, ‏Shift+לחיצה = טווח, ‏Ctrl+לחיצה = הוספה, לחיצה כפולה, ולחיצה ימנית = תפריט הקשר. במצב combined המפרשים מוצגים כ־ExpansionTiles מתחת לכל שורה. לחיצה על קטע עם מפרשים גוללת כך שהטקסט בראש (15%) והמפרשים עד 75% מהמסך.

צורת הדף — view/page_shape/

• page_shape_screen.dart — פריסת דף תלמודי: טקסט ראשי במרכז ו־4 חלוניות מפרשים (ימין/שמאל/תחתון/תחתון־ימני; מפתחות המיקום הפוכים לצד הפיזי בגלל RTL). מנהל גדלי חלוניות, סנכרון גלילה בין הטקסט למפרשים, ורענון קישורים.
• simple_text_viewer.dart — קורא הטקסט הראשי של צורת הדף: פוקוס וניווט מקלדת, שחזור גלילה במעבר מצב תצוגה.
• links_notes_sidebar.dart — חלונית צד (קישורים + הערות אישיות).
• הגדרות חלוניות עם 3 רמות עדיפות: ספר ← קטגוריה ← ברירת מחדל (page_shape_settings_manager.dart). מפרשי ברירת מחדל מגיעים משדות default_commentator/default_targum ב־DB וממופים למיקומים לפי position (‏utils/default_commentators.dart).

מצב קריאה רציפה

utils/reading_segments.dart — ‏ReadingSegment (טקסט + אינדקסי שורות מקור). המרות חובה: segmentIndexForLine (שורה←סגמנט) ו־sourceLineIndicesForSegmentViewports (‏viewport←שורות). ברירת מחדל גלובלית (תנ"ך + תלמוד) עם עקיפה פר־ספר.

ניקוד, פיסוק והגדרות פר־ספר

• הסרת ניקוד/פיסוק אינה משנה את התוכן — היא מיושמת ברינדור בלבד (RenderSettings/TextRendererService, סדר: טעמים←ניקוד←פיסוק), ולכן העתקה משקפת בדיוק את המסך (WYSIWYG). ההגדרה חלה גם על כל המפרשים והפופאפים.
• ברירות מחדל: ‏shouldRemoveNikudForBook משקלל הגדרה גלובלית + הגדרת תנ"ך + סוג הספר; הסרת פיסוק לא חלה על תנ"ך.
• הגדרות פר־ספר — savePerBookDisplaySettings שומר גופן/ניקוד/פיסוק/מצב תצוגה רק כשהאפשרות דלוקה, ומוחק ערך השווה לברירת המחדל (כדי לרשת שינויים עתידיים). בחירת מפרשים נשמרת תמיד פר־ספר.

חיפוש בתוך הספר

• utils/section_search_utils.dart — המנגנון המרכזי: ניקוי שורה (הסרת הערות inline‏, HTML, ניקוד), חיפוש ב־chunks של 128 ב־isolate, עד 1000 תוצאות. queryMatchesInlineNoteOnly מזהה התאמה שנמצאת רק בהערת שוליים — ואז נפתחת חלונית ההערות.
• models/text_book_searcher.dart — ‏TextBookSearcher לחיפוש פשוט עם snippets וכתובות היררכיות.

בחירת טקסט והעתקה — view/selection/

• SelectionSyncController — מסנכרן בחירה בין כמה SelectionArea באותו מסך (ל־Flutter אין API לניקוי בחירה מרחוק).
• EnhancedGestureDetector — זיהוי כל סוגי הלחיצות וגרירת בחירה.
• selected_text_copy.dart — העתקה מעוצבת (HTML+טקסט) עם כותרות אופציונליות.
• selected_text_restore.dart — שחזור מעברי שורה בטקסט השטוח ש־SelectionArea מחזיר.

עריכת טקסט מקומית — editing/ (מנוטרלת)

הקוד קיים אך מנוטרל בייצור (מסומן [EDITING DISABLED]): מודל TextOverride עם hash של המקור, ‏repository עם כתיבה אטומית, ‏MarkdownProcessor עם sanitize, ושירות rebase למיזוג עם מקור שהתעדכן. אירועי העריכה מוגדרים אך לא רשומים ב־bloc.

הערות חשובות למפתח

1. ‏content ו־visibleIndices — ‏0-based; ‏linksByLine/Link.index1 — ‏1-based; אינדקס הרשימה הנגללת — ‏segmentIndex.
2. מפרש "הערות" (kNotesCommentatorTitle) הוא וירטואלי — הערות שוליים המקודדות ב־HTML בתוך השורה מוצגות כמפרש לכל דבר, אבל אין ספר כזה.
3. דיאלוגים נלווים: מקור הספר (book_source_dialog), דיווח טעות (error_report_dialog), תצוגה מקדימה של קישור (link_preview_overlay).

דפים קשורים

• מפרשים וקישורים
• איתור מקורות
• שכבת הנתונים
• טאבים ושולחנות עבודה