סימניות (Bookmarks)
====================

מהן סימניות?
------------

תכונת הסימניות מאפשרת לשמור "קיצורי דרך" לנקודות ספציפיות בקבצים, עם
הדגשה ויזואלית בצבעים והוספת הערות (Annotations). סימנייה יכולה להיות
מבוססת על מספר שורה בקובץ קוד או על "עוגן" יציב כמו כותרת ב‑Markdown או
מזהה ``id`` ב‑HTML.

איך להוסיף סימנייה
-------------------

ההתנהגות משתנה לפי סוג הקובץ. הטבלה הבאה מסכמת:

.. list-table::
   :header-rows: 1
   :widths: 18 22 30 30

   * - סוג קובץ
     - מיקום הסימנייה
     - פעולה להוספה/הפעלה
     - הערות ותיקון
   * - קוד (``.py``, ``.js`` וכו')
     - מספר שורה
     - לחיצה על מספר השורה
     - קליק ימני לפתיחת תפריט צבע. שינוי צבע/מחיקה דרך פאנל הסימניות.
   * - Markdown (``.md``)
     - כותרת עם מזהה (Anchor)
     - לחיצה על הכותרת בתצוגה
     - ``Shift + Click`` להוספת הערה (Annotation). אין הרצת JS בתוך Markdown.
   * - HTML
     - אלמנט עם ``id`` קבוע
     - לחיצה על האלמנט בתצוגה
     - שינוי צבע/מחיקה אפשרי דרך פאנל הסימניות. מוצג ב‑``sandbox`` לבידוד.

פאנל הסימניות
--------------

פאנל צד ייעודי מאפשר ניהול מלא של הסימניות בקובץ ובחשבון:

- ניווט מהיר: לחיצה על סימנייה מקפיצה ישר לשורה/עוגן.
- עריכה ומחיקה: עדכון ההערה (Annotation) או מחיקה של סימנייה.
- ניהול צבעים: בחירת צבע לכל סימנייה (למשל ירוק ל"בוצע", אדום ל"באג").
- ייצוא (עתידי): תתוסף אפשרות לייצוא רשימת סימניות.

Anchor יציב
-----------

כאשר ניתן, מומלץ להשתמש בעוגן יציב במקום מספר שורה כדי לשמור על תקפות
הסימנייה גם לאחר עריכות בקובץ. השדה ``anchor`` משמש לשמירה לפי מזהה יציב:
כותרת ב‑Markdown או ``id`` ב‑HTML.

מגבלות, אבטחה ופרטיות
----------------------

- מגבלות שימוש: עד 50 סימניות לקובץ ועד 500 סימניות לכל משתמש.
- ולידציות: בדיקות לצבעים ולפורמטים של הערות.
- פרטיות: הסימניות נשמרות לחשבון המשתמש בלבד.
- אבטחה:
  - אין הפעלת JavaScript בתוך קבצי Markdown.
  - תצוגת HTML נעשית בתוך ``sandbox`` לצורך בידוד.

API קצר (למפתחים)
------------------

.. list-table::
   :header-rows: 1
   :widths: 28 44 28

   * - פעולה
     - תיאור
     - שדות מרכזיים
   * - ``POST /api/bookmarks/toggle``
     - הוספה או מחיקה של סימנייה (Toggle)
     - ``file_id``, ``line_number`` או ``anchor_id``
   * - ``GET /api/bookmarks/get``
     - שליפת כל הסימניות לקובץ
     - ``file_id``
   * - ``PUT /api/bookmarks/update``
     - עדכון הערה/צבע
     - ``bookmark_id``, ``color``, ``annotation``
   * - ``DELETE /api/bookmarks/delete``
     - מחיקת סימנייה
     - ``bookmark_id``

הערות שימושיות
--------------

- בחירה בצבעים אחידים מקלה על סיווג וניווט (למשל ירוק=בוצע, אדום=דחוף).
- שימוש בעוגנים יציבים מפחית "שבירה" של סימניות לאחר שינויים בקובץ.