Skip to content

Commit 485f7fa

Browse files
longtngoclaude
andcommitted
fix(web): stop a sidebar row taking the Queue header's place mid-drag
The sorting preview moves rows by transform, which has no layout effect, and the Queue header is a plain li rather than a sortable item - so when the list already scrolls at drag start the drag-time collapse is skipped and a shifted row lands on top of it, covering the whole header and the Queue toggle. A release aimed at the row enqueued into the Queue. The header now draws above the preview and opaque. Both parts are needed: z-20 alone won the hit test while the row's title still rendered through, which is also how the first version of the live arm scored it green. The occlusion hit test this seemed to call for was built, measured and rejected - it cannot refuse at the release, it breaks a release at the header's rounded corners, happy-dom cannot run it, and its failure mode is a silent total loss of the Queue drop. The design doc records all four so it is not re-proposed blind. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent fadeb04 commit 485f7fa

3 files changed

Lines changed: 169 additions & 1 deletion

File tree

‎apps/web/src/components/SidebarQueueBlock.dom.test.tsx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,13 @@ function render(dragging: boolean, collapse: boolean) {
3636
);
3737
}
3838

39+
/** The class attribute of the element carrying the queue-header testid, and nothing else's. */
40+
function headerClass(markup: string) {
41+
const tag = markup.match(/<[^>]*data-testid="sidebar-queue-header"[^>]*>/)?.[0];
42+
if (tag === undefined) throw new Error("no queue header in the markup");
43+
return tag.match(/class="([^"]*)"/)?.[1] ?? "";
44+
}
45+
3946
describe("SidebarQueueBlock", () => {
4047
it("lists the queued rows at rest", () => {
4148
const markup = render(false, false);
@@ -61,5 +68,19 @@ describe("SidebarQueueBlock", () => {
6168
expect(markup).not.toContain("mt-auto");
6269
expect(markup).toContain("border-dashed");
6370
expect(markup).not.toContain("Queue (2)");
71+
// This is the state the header gets covered in - no slack to collapse into, so the sorting
72+
// preview shifts a row onto it. BOTH classes are load-bearing and neither is cosmetic: z-20
73+
// wins the hit test against the transformed row, and the background is what stops the row's
74+
// title rendering through. Measured live with a sentinel background on the rows: with both,
75+
// 0 of 6480 band pixels show row ink; with z-20 alone, 5953; with neither, 6088.
76+
//
77+
// Two traps, both of which a real mutation walked through:
78+
// - read the HEADER's own class attribute, not the whole markup - a plain
79+
// `toContain("bg-sidebar")` matches other elements in this tree and stayed green with the
80+
// background deleted;
81+
// - match `bg-sidebar` as a WHOLE token - as a substring it also accepts `bg-sidebar/50`, a
82+
// half-transparent header you can read the row's title straight through.
83+
expect(headerClass(markup).split(/\s+/)).toContain("z-20");
84+
expect(headerClass(markup).split(/\s+/)).toContain("bg-sidebar");
6485
});
6586
});

‎apps/web/src/components/SidebarQueueBlock.tsx‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,20 @@ export function SidebarQueueBlock(props: {
8484
// Pushed into the empty space below the rows while a main-list drag runs: the preview
8585
// opens space where the Queue sits, and a zone that moves with it is a target the
8686
// pointer chases. It shares the free space with the shelves' own auto margin.
87-
props.dragging && "border border-dashed border-sidebar-foreground/25",
87+
// Above the sorting preview AND opaque. The preview moves rows by TRANSFORM, which cannot
88+
// push this header aside: it is not a sortable item, just a plain li in normal flow. So
89+
// whenever the list already scrolls at drag start the collapse below is skipped, the header
90+
// stays inline under the last Active row, and a shifted row lands on top of it - covering
91+
// 810 of 810 sampled header pixels and 100% of the Queue toggle.
92+
//
93+
// `z-20` beats the transformed li, which is its own stacking context (NOT the row card's
94+
// `z-10`, which that context already caps). But z alone only wins the HIT TEST: both
95+
// elements are transparent, so the row's title still rendered across the drop zone and the
96+
// leaked ink barely moved. `bg-sidebar` is what actually hides it - and it must stay a
97+
// whole token, since `bg-sidebar/50` is see-through and defeated both gates written for
98+
// this.
99+
props.dragging &&
100+
"relative z-20 border border-dashed border-sidebar-foreground/25 bg-sidebar",
88101
props.collapse && "mt-auto",
89102
isOver && "border-primary/40 bg-primary/5",
90103
)}
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
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

Comments
 (0)