Phase 14 - Organized directories.

2026-10-03 19:13:39 -04:00
parent 6666173c4f
commit d950fd9d9a
307 changed files with 1452 additions and 1110 deletions
@@ -0,0 +1,49 @@
+# Speech Bubble Badge Stability
+
+## Diagram
+
+Separate bubbles keep their own badge positions when selection changes:
+
+```text
+① [Bubble 1]                         ② [Bubble 2]
+```
+
+After selecting bubble 2, only its selection appearance changes:
+
+```text
+① [Bubble 1]                         🟡② [Bubble 2]
+```
+
+When preferred badge positions are crowded, badges form a sorted group:
+
+```text
+      ① ② ③
+   [overlapping bubbles]
+```
+
+## Behavior
+
+- Give each bubble a preferred badge center at its frame's upper-left corner.
+- Recalculate badge positions from bubble geometry, viewport bounds, and other badge positions. Selection state and floating dialog rectangles do not affect the badge layout.
+- Keep distant, non-overlapping bubbles independent. Arrange badges as a sorted row or column when preferred badge centers are closer than the minimum badge spacing, or when their bubble frames intersect.
+- When intersecting bubble frames form a badge cluster, place the sorted row above the largest bubble frame so smaller bubbles' badges cannot show through the larger bubble's text area. If the top row is within the viewport, allow it to use space above the ordinary toolbar-safe margin.
+- Move badge clusters deterministically when they reach viewport edges or collide with another badge.
+- Preserve selected-state feedback through the existing selected badge colors and bubble outline. Selection changes do not change badge centers.
+- Keep badges visible and clickable above floating editor panels by passing their viewport rectangles to the Show Speech and Speech Style toolbars. Place those panels in the nearest available location that avoids badges. The Show Speech panel keeps its pinned top edge while expanded; in that state, badge avoidance may adjust its horizontal position only.
+- Badge positions may change when bubble geometry, camera transform, viewport size, or a true badge-to-badge collision changes.
+
+## Implementation notes
+
+- `SpeechBubble.order_badge_viewport_rects()` exposes the current badge bounds for UI collision avoidance.
+- The badge solver remains independent of selection and dialog positions.
+- The stage shares badge bounds with the speech toolbars; toolbars reposition themselves rather than feeding their positions back into badge placement.
+- The existing badge hit testing and pointing-hand hover behavior use the same resolved centers as badge drawing.
+
+## Acceptance checks
+
+- Selecting a different bubble without moving bubbles or changing the viewport leaves every badge center unchanged.
+- Two distant bubbles retain individual badges without being grouped.
+- Crowded badge anchors produce a stable, reading-order row or column.
+- When one bubble obscures another, their badges form a stable, sorted horizontal row above the larger bubble.
+- A toolbar avoids badge bounds when a clear placement exists.
+- Camera/viewport changes keep badges inside the stage's safe bounds where possible.