|
| 1 | +# A row must not be able to take the Queue header's place - design |
| 2 | + |
| 3 | +## 1. Goal and baseline |
| 4 | + |
| 5 | +During a sidebar drag, a list row can be painted across the Queue header. A release aimed at what the |
| 6 | +user sees - the row - enqueues into the Queue instead. |
| 7 | + |
| 8 | +Baseline on `personal` at `fadeb04f5` (viewport 1400x900, both shelves open, 3 queued, 4 Active): |
| 9 | +pick up an Active row, drag upward past an earlier row, and the row below it carries |
| 10 | +`translate(0,133)` across the header at `428..460`. **810 of 810 sampled header pixels covered** and the Queue |
| 11 | +toggle **100%** covered (an earlier draft said 73%; it does not reproduce at any inset, step or |
| 12 | +viewport - it is 100% at every one). `check.sh` occluded-drop-zone. |
| 13 | + |
| 14 | +The gesture matters and the older probes could not produce it: parking just below the picked-up row |
| 15 | +gave 0 covered samples over 5 gestures x 3 reps. You must park over an EARLIER row. It is also a |
| 16 | +race, not a steady state - once the pointer enters the header `over` flips to the Queue and the rows |
| 17 | +slide back within ~100ms, so a sample taken after a 100ms dwell reads clean while the user's flick |
| 18 | +does not. |
| 19 | + |
| 20 | +## 2. Two defects, not one |
| 21 | + |
| 22 | +The independent RCA established these as separate mechanisms. |
| 23 | + |
| 24 | +| | Defect | Where | |
| 25 | +| ----- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | |
| 26 | +| **A** | A transform-moved row paints over the header | `collapseQueue` in `Sidebar.tsx` | |
| 27 | +| **B** | The drop is decided by rect containment, with no occlusion test | `pointerOverVisibleRect`, and the release override in `handleThreadDragEnd` | |
| 28 | + |
| 29 | +**A**: the main list is positioned by CSS `transform`, which has no layout effect, while the Queue |
| 30 | +header is a plain `li` in normal flow - so the projection's downward shift lands on it. The only |
| 31 | +thing separating them was the drag-time collapse, `collapseQueue = queueDropShown && !listScrolls`, |
| 32 | +and `listScrolls` is sampled once at drag start, so **when the list already scrolls the collapse |
| 33 | +never runs**. One variable, nothing else changed: VH 900 overlaps, VH 1000 does not. The collapse is |
| 34 | +not sufficient even when it runs - it frees a finite `mt-auto` slack that one row dragged in from a |
| 35 | +shelf consumes (143 of 254 scan samples covered). |
| 36 | + |
| 37 | +**B** is real as a mechanism - the RCA's 2x2 flips the drop by moving the rect and not by moving the |
| 38 | +paint - but **only A can produce it today**: every element whose rect intersects the header during a |
| 39 | +drag is that one translated row and its own descendants. Nothing else in the document. |
| 40 | + |
| 41 | +## 3. Approach: fix A. B is deliberately not fixed. |
| 42 | + |
| 43 | +**A - the header outranks the sorting preview, and is opaque.** The Queue header takes `relative |
| 44 | +z-20 bg-sidebar` while a drag runs. Both classes are load-bearing, and the first draft of this design |
| 45 | +had only the first: |
| 46 | + |
| 47 | +| state | row ink inside the header | |
| 48 | +| ---------------------------------- | ------------------------- | |
| 49 | +| `z-20` + `bg-sidebar` | **0 / 6480 px** | |
| 50 | +| `z-20` alone | 5953 / 6480 px | |
| 51 | +| neither | 6088 / 6480 px | |
| 52 | +| `bg-sidebar/50` (half-transparent) | 5953 / 6480 px | |
| 53 | + |
| 54 | +`z-20` wins the hit test - against the transformed `li`, which is its own stacking context, NOT |
| 55 | +against the row card's `z-10` which that context already caps. But both elements are transparent, so |
| 56 | +ordering alone left the row's title rendering across the drop zone and moved the user-visible result |
| 57 | +from 6088 to 5953 of 6480 leaked pixels, a difference inside the arm's own run-to-run spread. |
| 58 | +`bg-sidebar` is what actually hides it, and it must stay a WHOLE token: `bg-sidebar/50` is plainly |
| 59 | +see-through and defeated both gates written for this. This aligns paint with behaviour instead |
| 60 | +of fighting it: the header IS the drop target, so drawing it above a preview of where rows _would_ |
| 61 | +land is what the user needs to see. |
| 62 | + |
| 63 | +`relative` is belt-and-braces: measured, `z-20` applies without it because the parent `ul` is a flex |
| 64 | +container, and `relative` has no layout effect here (the header's box and all 11 descendant boxes are |
| 65 | +byte-identical with and without it). It is kept so the z-index does not silently stop applying if |
| 66 | +that parent ever stops being flex. |
| 67 | + |
| 68 | +Rejected - making the collapse unconditional: it has no space to collapse into when the list |
| 69 | +scrolls, which is exactly the failing case, and it would unmount the queue rows on every drag. |
| 70 | + |
| 71 | +Rejected - excluding the header's band from the projection: the projection is dnd-kit's, shared by |
| 72 | +every sortable row. Bending it for one non-sortable sibling is a far larger blast radius than a |
| 73 | +stacking change. |
| 74 | + |
| 75 | +### Why B is not fixed |
| 76 | + |
| 77 | +A prototype of B - accept a point only if `document.elementsFromPoint` reaches the zone - was built |
| 78 | +and driven against the live sidebar. It loses on four measurements: |
| 79 | + |
| 80 | +1. **It cannot refuse at the release.** The override in `handleThreadDragEnd` is additive: if the |
| 81 | + detector already left `over` holding the Queue, a release-time refusal is inert. Instrumented, the |
| 82 | + guard reported _not painted_ and the thread enqueued anyway, 2/2. Only the collision detector can |
| 83 | + enforce it, which is the path A already protects. |
| 84 | +2. **It regresses a shipped fix.** `rounded-md` is 8px, so the header does not paint its own corners. |
| 85 | + A release 1px above the bottom border and 3px from the left went from 3/3 enqueue to 0/3 - inside |
| 86 | + the visibly dashed box, and inside the 2px band `e96e79b37` shipped to protect. |
| 87 | +3. **The repo cannot test it.** happy-dom has no `elementsFromPoint` and its `elementFromPoint` |
| 88 | + returns `null` unconditionally, so the guard crashed all six pointer-drop-zone DOM tests. Testing |
| 89 | + it in-repo means stubbing the hit test, which pins a hand-written stack rather than real paint. |
| 90 | +4. **Its failure mode is silent and total.** The drag overlay sits at index 0 of the hit stack at the |
| 91 | + pointer on every release, so the overlay exclusion IS the guard. Mutating only the exclusion - skip |
| 92 | + the overlay's `ul` but not dnd-kit's wrapper `div`, a one-element slip - refused the Queue drop |
| 93 | + 100% of the time with no error. A guard whose only in-repo coverage is impossible and whose |
| 94 | + failure disables the feature is worse than the hypothetical it protects against. |
| 95 | + |
| 96 | +So the invariant is enforced by the LAYOUT, not by the hit test. If a future change reintroduces an |
| 97 | +overlap, occluded-drop-zone reports it. |
| 98 | + |
| 99 | +The arm has now been wrong twice, in the same direction, and both versions passed a build a human |
| 100 | +could see was broken. Version 1 asked `elementsFromPoint` who was on top, which is ordering and not |
| 101 | +paint. Version 2 counted fully-saturated sentinel glyph pixels, and scored 0 on a `bg-sidebar/50` |
| 102 | +header - the leaked glyphs composite to about G=126, so the saturation gate discarded every one. |
| 103 | +Version 3 paints a sentinel BACKGROUND on each row and accepts a composited tint, so a leak is a |
| 104 | +large solid area rather than a few antialiased edges, and it also reports the served class so a stale |
| 105 | +dev-server transform cannot read as a pass. |
| 106 | + |
| 107 | +## 4. Withdrawn premise |
| 108 | + |
| 109 | +An earlier draft carried **P1: "the drag overlay does not hit-test at the pointer"**, from one |
| 110 | +measurement reading `overlayInStack:false`. It is FALSE. That measurement used a single-teleport |
| 111 | +gesture, and the overlay had not repositioned yet; on any multi-step gesture the overlay is at index |
| 112 | +0 of the stack on every release. The lesson is the same one the clipped-drop work learned twice: a |
| 113 | +single synthesized pointer move is not evidence about a gesture. |
| 114 | + |
| 115 | +## 5. Invariants |
| 116 | + |
| 117 | +| # | Invariant | Proof | |
| 118 | +| --- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 119 | +| K1 | No sidebar list row's INK is visible inside the Queue header during a drag | `check.sh` occluded-drop-zone, which screenshots the band and counts composited sentinel tint: 0/6480 with the fix, 5953/6480 with only the ordering half, and 5953/6480 at `bg-sidebar/50` | |
| 120 | +| K2 | The Queue toggle and pause button stay uncovered throughout a drag | measured 100% -> 0% covered by hand; NOT pinned by an arm, see section 6 | |
| 121 | +| K3 | A release where the header is painted still enqueues, on both edges and at the corners | existing header-edges and clipped-drop-zone arms stay green | |
| 122 | + |
| 123 | +## 6. Known gaps, recorded on purpose |
| 124 | + |
| 125 | +K2 is measured but not pinned: `occl.mjs` screenshots the header band only, so a future change that |
| 126 | +re-covers the Queue toggle without touching the header would not fail an arm. |
| 127 | + |
| 128 | +For ~30-60ms after mouseup the row paints back over the header while it animates home, because |
| 129 | +`dragging` drops at the release. Cosmetic: no drop decision happens after the release. |
| 130 | + |
| 131 | +A drop zone is still accepted on rect containment plus the clip test, not on paint. Today nothing but |
| 132 | +a translated row can cover the Queue header, and A removes that - so the gap is unreachable rather |
| 133 | +than tolerated. Anyone reopening it should read section 3 first: the obvious fix was built, measured, |
| 134 | +and rejected on evidence, not skipped. |
0 commit comments