Commentaries and Links

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

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

סוגי קישורים

lib/models/link_types.dart — ‏LinkTypes.isDependentTextLink מבחין בין:

• קישור תלוי־טקסט (מפרש, תרגום) — מוצג בפאנל המפרשים.
• הפניה/מקור (reference) — מוצג בכרטיסיית הקישורים (visibleLinks).

בנוסף קיימים:

• קישורים הפוכים (inverse) — מפרש־משתמש שמצביע אל הספר הנוכחי; נטענים דרך loadUserLinksForBook וממוזגים עם קישורי הבסיס.
• קישורי inline — קישורים עם start/end המוזרקים לתוך הטקסט עצמו (note_inline_render.dart, ‏link_anchor_markers.dart), עם סכמות פנימיות otzaria://note ו־otzaria://inline-link.

טעינת קישורים ברקע

_loadLinksInBackground ב־TextBookBloc:

• חלון קישורים = 60 שורות לפני / 140 אחרי ה־viewport.
• סינון לפי ספרי היעד: בצורת הדף — לפי קונפיגורציית החלוניות; בשאר המצבים — לפי המפרשים הפעילים.
• העיבוד (processLinksForState ב־utils/link_processing.dart): מיזוג לפי זהות ← בניית linksByLine (מפתח 1-based) ← חישוב computeVisibleLinks. מעל 250 קישורים — רץ ב־isolate.
• _preloadLinkEras טוען מראש את דורות הספרים לצורך מיון.

קיבוץ מפרשים — buildCommentatorGroups

lib/text_book/utils/commentator_group_builder.dart — מקור האמת היחיד לקיבוץ מפרשים (משמש גם את page shape וגם את מסכי ה־PDF; אסור לשכפל את הלוגיקה inline):

• קיבוץ לפי דורות: תורה שבכתב ← חז"ל ← ראשונים ← אחרונים ← מחברי זמננו ← שאר מפרשים (הדור מגיע משדה book_generation ב־DB בלבד — אין היוריסטיקה לפי נתיב).
• _promoteBase — מפרשי ברירת מחדל (לפי position ב־DB) מוקדמים לראש כל קבוצה.
• _anchorNotesAfterBase — ספר "הערות על X" ממוקם מיד אחרי X.
• computeRareCommentators — מפרש עם פחות מ־10 קישורים על ספר גדול (מעל 100 שורות) מוסתר מהרשימה הכללית ומוצג רק כשהוא רלוונטי לשורה הנוכחית.

פאנל המפרשים — TabbedCommentaryPanel

שלוש כרטיסיות:

1. מפרשים — במצב split: ‏CommentaryListBase (הרשימה עצמה עם חיפוש); במצב combined: ‏CommentatorsListView (בחירת מפרשים בלבד, התוכן מוצג מתחת לטקסט).
2. קישורים — SelectedLineLinksView (הפניות ומקורות לשורה הנבחרת).
3. הערות אישיות — PersonalNotesSidebar.

אפשרויות נוספות:

• פתיחת כרטיסיית מפרשים עצמאית (CommentatorsTab) — טאב נפרד שמציג רק מפרשים.
• מפרשים על אותו קטע (sibling_commentaries_menu.dart) — בספר מפרש, תפריט ההקשר מציע את שאר המפרשים על אותו עמוד (getSiblingCommentaries, ממוין לפי דורות).
• פתיחה אוטומטית של כרטיסיית ההערות כשתוצאת חיפוש נמצאת בהערת שוליים.

תוכן מפרש — CommentaryContent

מציג קישור בודד: טוען את link.content (אסינכרוני), מרנדר עם SmartTextWidget לפי הגדרות התצוגה של הטאב (ניקוד/פיסוק/גופן מפרשים — WYSIWYG מלא). לחיצה כפולה פותחת את המפרש בטאב חדש. תומך בהדגשת חיפוש ובהדגשת הטווח המצוטט (wrapVisibleRange).

מפרש "הערות" וירטואלי

ספרים רבים (~322) מקודדים הערות שוליים כ־HTML בתוך השורה (<sup class="footnote-marker"> + ‏<i class="footnote">). ה־bloc מזהה אותם ומוסיף מפרש וירטואלי בשם "הערות" (kNotesCommentatorTitle) לרשימת המפרשים — הוא מתנהג כמפרש רגיל בכל ה־UI אבל תוכנו נבנה מהשורה עצמה.

שירותים קשורים

• lib/services/commentary_service.dart — ‏CommentaryService.sortLinksByEra — מיון קישורים לפי דורות.
• קבצי בדיקה רלוונטיים: test/text_book/commentary_grouping_test.dart, ‏test/commentary_reverse_links_test.dart, ‏test/inline_links_test.dart.

דפים קשורים

• קורא הטקסט
• קורא ה-PDF (פאנל מפרשים ל־PDF)
• שכבת הנתונים (מבנה טבלאות הקישורים)