brep_app/viewport/

interaction.rs

use super::*;

/// The RAW (unsmoothed) vertical wheel delta this frame, in UI points — summed
/// straight from the `MouseWheel` events instead of egui's `smooth_scroll_delta`.
/// egui smooths a wheel notch across ~6-10 frames (an ease-in/ease-out ramp that
/// reads as "dampening" at the start/end of a zoom); the raw events give one clean
/// discrete step per notch. Line/Page units are normalized to points the SAME way
/// egui's smoothing would (default `line_scroll_speed` = 40, private on
/// `InputState`, so mirrored here), so the calibrated `controls::wheel` step is
/// unchanged — only the ramp is gone.
fn raw_wheel_delta_y(ctx: &egui::Context) -> f32 {
    const LINE_POINTS: f32 = 40.0;
    ctx.input(|i| {
        i.events
            .iter()
            .filter_map(|event| match event {
                egui::Event::MouseWheel { unit, delta, .. } => Some(match unit {
                    egui::MouseWheelUnit::Point => delta.y,
                    egui::MouseWheelUnit::Line => delta.y * LINE_POINTS,
                    egui::MouseWheelUnit::Page => delta.y * LINE_POINTS * 20.0,
                }),
                _ => None,
            })
            .sum()
    })
}

impl Viewport {
    /// The rect (egui points) the viewport last drew into. Now that the viewport
    /// is a dock PANE (its rect moves as the user re-frames it), the shell anchors
    /// the floating context / Finish-Cancel overlays to THIS rect's right edge so
    /// they stay glued to the 3D view — see the top-right overlay in `app.rs`.
    /// `None` before the first draw (shell falls back to window-right until then).
    pub fn last_rect(&self) -> Option<egui::Rect> {
        self.last_rect
    }

    /// The last viewport rect as `{x, y, w, h}` in egui points (verification: the
    /// origin lets the verifier map engine viewport-local pick coords → page px).
    #[cfg(target_arch = "wasm32")]
    pub fn viewport_rect_json(&self) -> String {
        match self.last_rect {
            Some(r) => {
                serde_json::json!({ "x": r.min.x, "y": r.min.y, "w": r.width(), "h": r.height() })
                    .to_string()
            }
            None => "null".to_string(),
        }
    }

    /// The clean entry the shell calls: fill the central panel with the 3D
    /// viewport — size tracking, input routing, on-demand render, and the blit
    /// composite. Borrows the engine brain to draw + drive.
    pub fn show(&mut self, ui: &mut egui::Ui, state: &mut EngineState) {
        let ppp = ui.ctx().pixels_per_point();
        // Empty frame → NO inner margin/padding: the 3D view fills the central
        // area edge-to-edge (the viewport paints the whole rect anyway).
        egui::containers::panel::CentralPanel::default()
            .frame(egui::Frame::NONE)
            .show(ui, |ui| {
                let rect = ui.available_rect_before_wrap();
            self.last_rect = Some(rect);
            let response = ui.allocate_rect(rect, egui::Sense::click_and_drag());

            // Track viewport size in the engine (logical px) + offscreen (physical).
            let phys_w = (rect.width() * ppp).round().max(1.0) as u32;
            let phys_h = (rect.height() * ppp).round().max(1.0) as u32;
            self.ensure_offscreen(phys_w, phys_h);
            state.resize(rect.width() as f64, rect.height() as f64);

            // Feed input BEFORE rendering so a change is reflected this frame.
            self.handle_viewport_input(ui, rect, &response, state);

            // Per-frame overlay upkeep, AFTER the input + resize above so a zoom
            // is reflected in the SAME frame it happened. Re-bakes the
            // screen-constant sizing of every draggable gizmo that rides the
            // pre-expanded `set_overlay` channel — assembly-constraint handles
            // (§8.4), the ◎ feature-dimension gizmo, the live sketch overlay —
            // on a material world-per-pixel change, and hides/restores the
            // constraint graphics with their toggle + sketch mode.
            state.ensure_overlays_current();

            if state.dirty {
                self.render_viewport(phys_w, phys_h, ppp, state);
                // Keep animating while a drag is live / more input pending.
                ui.ctx().request_repaint();
            }

            // Composite the offscreen 3D texture into egui's frame via the
            // wgpu paint callback.
            ui.painter().add(egui_wgpu::Callback::new_paint_callback(
                rect,
                ViewportCallback,
            ));
        });

        // The "candidates under the cursor" disambiguation popup (Alt+click)
        // floats over the viewport at ctx level, like the file dialog / palette.
        let ctx = ui.ctx().clone();
        self.show_candidate_popup(&ctx, state);

        // Editable dimension labels (S5): value text drawn at each dimension's
        // screen-projected anchor, click-to-edit + drag-to-reposition. Drawn at ctx
        // level (foreground of the viewport) so it floats over the 3D like the popup.
        if let Some(rect) = self.last_rect {
            self.draw_dimension_labels(&ctx, rect, state);
            // Feature-dimension labels (FD-1): the ◎ dimension-gizmo mode draws the
            // primitive's param dims here, click-to-edit + drag-to-resize.
            self.draw_feature_dimension_labels(&ctx, rect, state);
            // Transform-gizmo axis labels (XC/YC/ZC): the colored cone-tip labels.
            self.draw_transform_axis_labels(&ctx, rect, state);
            // Assembly-constraint labels (§8.4): status-colored chips at each
            // constraint's anchor — hover highlights the referenced geometry,
            // click expands the row in the Assembly Constraints panel.
            self.draw_constraint_labels(&ctx, rect, state);
            // DEBUG: 1px RED outline of the EXACT gizmo-arrow hit regions (axis
            // capsules + grab circles of the transform widget — feature transform
            // mode AND the component Move gizmo — or the dimension arrowheads).
            // Drawn LAST so the outlines overlay everything.
            self.draw_gizmo_hit_areas(&ctx, rect, state);
        }
        if self.candidate_popup.is_some() || state.dirty {
            // Keep animating while the popup is open (its entry hover / a fresh
            // highlight is applied AFTER this frame's render).
            ctx.request_repaint();
        }

        // Verification hooks (wasm only): the selection-UX globals the headed
        // verifier reads. Published from HERE because viewport.rs owns hover + the
        // candidate popup (keeps app.rs untouched). Purely additive.
        #[cfg(target_arch = "wasm32")]
        {
            publish_to_js("__brepHover", &state.hovered_json());
            publish_to_js("__brepCandidates", &self.candidates_json(state));
            publish_to_js("__brepCandidateHit", &self.candidate_hits_json());
            // Re-publish the selection with the POST-input value: the app shell
            // publishes `__brepSelection` before this viewport draws (so its copy
            // lags a viewport click by a frame); overwrite it here with the value
            // that reflects this frame's click so the verifier reads it live.
            publish_to_js("__brepSelection", &state.selection_json());
            // The ◎ dimension-gizmo state (mode + annotations) for the verifier.
            publish_to_js("__brepFeatureDim", &state.feature_dimension_state_json());
            // The assembly-constraint overlay labels (id/text/status/color/world/
            // draggable) so the verifier can locate + drag a constraint handle.
            publish_to_js("__brepConstraints", &state.constraint_labels_json());
            // The ViewCube corner rect (viewport-local `{x,y,w,h}`) so the verifier
            // can click a cube face/edge/corner by hit-rect (offset by `__brepView`).
            publish_to_js("__brepViewCube", &state.viewcube_rect_json());
        }
    }

    /// The ViewCube corner rect (logical px, viewport-local), if enabled.
    fn viewcube_local(&self, state: &EngineState, x: f64, y: f64) -> Option<(f64, f64)> {
        viewcube_local(state, x, y)
    }

    /// Route pointer/wheel over the viewport into the engine's SKETCH interaction
    /// (S2), while [`EngineState::sketch_mode`]. Point drags move sketch points;
    /// empty-space drags still orbit/pan the camera; clicks select (Ctrl/Cmd adds);
    /// hover lights the entity under the cursor. The ViewCube corner + wheel zoom
    /// keep working. NONE of the modeling select/candidate/transform/ref-select
    /// branches run here.
    fn handle_sketch_input(
        &mut self,
        ui: &egui::Ui,
        rect: egui::Rect,
        response: &egui::Response,
        state: &mut EngineState,
    ) {
        let local = |p: egui::Pos2| ((p.x - rect.min.x) as f64, (p.y - rect.min.y) as f64);

        // A DRAW tool (point/line/rect/circle/arc) is active vs S2 selection mode.
        // In draw mode clicks PLACE geometry and points are NOT grabbed for dragging
        // (so an empty drag still orbits the camera); hover still runs for snap + the
        // rubber-band preview.
        let draw_mode = state.sketch_active_tool().is_some();

        // Right-click aborts the in-progress draw geometry. (Escape → drop back to
        // the Select/drag tool is handled globally in `BrepApp::handle_shortcuts`,
        // the only reliable capture point: it `consume_key`s Escape before the
        // viewport runs, and it fires for EVERY armed tool, not just draw mode.)
        if draw_mode && response.secondary_clicked() {
            state.sketch_tool_cancel();
        }

        // Delete / Backspace removes the current sketch selection (S3b) — geometries +
        // points + constraints + orphan cleanup, driven by the engine. Gated on sketch
        // mode AND on no egui TEXT edit being focused, so a Backspace typed into an open
        // dimension value editor edits the number rather than deleting the selection
        // (same guard `handle_shortcuts` uses for the global keys).
        let delete = !ui.ctx().text_edit_focused()
            && ui
                .ctx()
                .input(|i| i.key_pressed(egui::Key::Delete) || i.key_pressed(egui::Key::Backspace));
        if delete {
            state.sketch_delete_selection();
        }

        if response.drag_started() {
            if let Some(pos) = response.interact_pointer_pos() {
                let (lx, ly) = local(pos);
                // ViewCube first (a view snap); then the freehand handdraw stroke
                // capture (S6b-3 — a drag IS the stroke, never a camera orbit); then a
                // sketch point grab (SELECT mode only — other draw modes never grab, so
                // an empty drag orbits); else an empty-space camera orbit/pan so
                // navigation still works.
                if let Some((cx, cy)) = self.viewcube_local(state, lx, ly) {
                    state.viewcube_click(cx, cy);
                } else if state.sketch_active_tool() == Some("handdraw") {
                    state.sketch_handdraw_begin(lx, ly);
                    self.sketch_handdrawing = true;
                } else if !draw_mode && state.sketch_drag_begin(lx, ly) {
                    self.sketch_dragging = true;
                } else {
                    let btn = if response.dragged_by(egui::PointerButton::Secondary) {
                        BUTTON_RIGHT
                    } else if response.dragged_by(egui::PointerButton::Middle) {
                        BUTTON_MIDDLE
                    } else {
                        BUTTON_LEFT
                    };
                    state.pointer_down(lx, ly, btn);
                    self.dragging = true;
                }
            }
        }
        if response.dragged() {
            if let Some(pos) = response.interact_pointer_pos() {
                let (lx, ly) = local(pos);
                if self.sketch_handdrawing {
                    state.sketch_handdraw_move(lx, ly);
                } else if self.sketch_dragging {
                    state.sketch_drag_to(lx, ly);
                } else if self.dragging {
                    state.pointer_move(lx, ly);
                }
            }
        }
        if response.drag_stopped() {
            if self.sketch_handdrawing {
                state.sketch_handdraw_end();
                self.sketch_handdrawing = false;
            }
            if self.sketch_dragging {
                state.sketch_drag_end();
                self.sketch_dragging = false;
            }
            if self.dragging {
                state.pointer_up();
                self.dragging = false;
            }
        }

        // A plain click either PLACES draw-tool geometry (draw mode) or selects the
        // entity under the cursor (SELECT mode: Ctrl/Cmd adds/toggles, empty clears).
        // A click over the ViewCube corner snaps the camera, never a sketch pick/place.
        if response.clicked() {
            if let Some(pos) = response.interact_pointer_pos() {
                let (lx, ly) = local(pos);
                if let Some((cx, cy)) = self.viewcube_local(state, lx, ly) {
                    // A plain click on the ViewCube corner snaps the camera. A plain
                    // click never fires drag_started (see the modeling path), so the
                    // snap must run here, not only on the drag-start branch above.
                    state.viewcube_click(cx, cy);
                } else if state.sketch_active_tool() == Some("handdraw") {
                    // handdraw (S6b-3) captures a DRAG as a stroke; a plain click (no
                    // drag) is a deliberate no-op.
                } else if state.sketch_active_tool() == Some("pickEdges") {
                    // pickEdges (S6b-2) acts on the 3D SCENE EDGE under the cursor
                    // (pixel coords), never a plane place/select.
                    state.sketch_pick_edge_at(lx, ly);
                } else if draw_mode {
                    state.sketch_tool_click_at(lx, ly);
                } else {
                    let mods = ui.ctx().input(|i| i.modifiers);
                    state.sketch_click_at(lx, ly, mods.command || mods.ctrl);
                }
            }
        }

        // Hover: the entity under the pointer (skip while dragging / over the cube).
        // Also FREEZE the entity hover while the primary button is held in SELECT
        // mode: between the press and egui's drag-start (~6px of movement later) the
        // pointer keeps moving, and re-hovering there would slide the highlight off
        // the point the user pressed — so the grab (which takes the hovered entity)
        // would miss. Draw mode keeps updating (its rubber-band preview rides the
        // live hover).
        let primary_held = ui.input(|i| i.pointer.primary_down());
        if !self.sketch_dragging
            && !self.dragging
            && !self.sketch_handdrawing
            && !(primary_held && !draw_mode)
        {
            match response.hover_pos() {
                Some(pos) => {
                    let (lx, ly) = local(pos);
                    match self.viewcube_local(state, lx, ly) {
                        Some((cx, cy)) => {
                            state.viewcube_hover(cx, cy);
                            state.sketch_clear_hover(); // over the cube, not the sketch
                        }
                        None => {
                            state.viewcube_clear_hover();
                            state.sketch_hover_at(lx, ly);
                            // pickEdges (S6b-2) targets a 3D scene edge, so also
                            // hover-highlight the edge under the cursor (modeling
                            // emphasis) as a link affordance.
                            if state.sketch_active_tool() == Some("pickEdges") {
                                state.hover_at(lx, ly);
                            }
                        }
                    }
                }
                None => {
                    state.viewcube_clear_hover();
                    // Pointer is off the viewport entirely. Don't clobber a hover the
                    // entity-LIST panel set THIS frame (it drew before us) — that is
                    // the list→canvas highlight. When the panel didn't set one, clear
                    // as usual so a stale highlight doesn't linger.
                    if !state.take_sketch_list_hover() {
                        state.sketch_clear_hover();
                    }
                }
            }
        }

        // Wheel zoom toward the cursor (same as modeling).
        if response.hovered() {
            // Raw (unsmoothed) wheel delta so each notch is a discrete step with NO
            // ease-in/out ramp (egui's smooth_scroll_delta dampens the start/end of a
            // scroll). See [`raw_wheel_delta_y`].
            let scroll_y = raw_wheel_delta_y(ui.ctx());
            if scroll_y != 0.0 {
                let cursor = response.hover_pos().map(|p| {
                    let (lx, ly) = local(p);
                    [lx, ly]
                });
                state.wheel(-(scroll_y as f64), cursor);
            }
        }
    }

    /// Route pointer/wheel over the viewport into `EngineState` (mirrors
    /// `desktop.rs`). `rect` is the viewport in egui points; coords fed to the
    /// engine are viewport-local logical px, the space `state.camera` lives in.
    fn handle_viewport_input(
        &mut self,
        ui: &egui::Ui,
        rect: egui::Rect,
        response: &egui::Response,
        state: &mut EngineState,
    ) {
        let local = |p: egui::Pos2| ((p.x - rect.min.x) as f64, (p.y - rect.min.y) as f64);

        // Sketch mode (S2) owns the pointer: hover/select/point-drag in plane space,
        // never the modeling select/candidate/transform/ref-select branches. Routed
        // BEFORE the modeling path, which stays byte-for-byte for `!sketch_mode()`.
        if state.sketch_mode() {
            self.handle_sketch_input(ui, rect, response, state);
            return;
        }

        if response.drag_started() {
            if let Some(pos) = response.interact_pointer_pos() {
                let (lx, ly) = local(pos);
                // Every drag-start ends the hover: the pointer is now steering
                // the camera / the cube / a gizmo handle / a dimension arrow,
                // not hovering the model — a frozen highlight riding a camera
                // snap, an orbit, or geometry that a gizmo/dim drag is reshaping
                // live reads as a stale pick. Hover re-resolves at the new pose
                // as soon as the interaction ends (the per-frame hover branch).
                state.clear_hover();
                // WHERE the press landed — the point every handle hit test below is
                // taken at ([`drag_start_local`]), which is NOT `pos`: egui only calls
                // a press a drag once the pointer has left the click radius, so by
                // this frame `pos` has already drifted off whatever the user
                // pressed on.
                let (gx, gy) = drag_start_local(response, rect).unwrap_or((lx, ly));
                // A drag that STARTS over the ViewCube corner snaps/orbits via the
                // cube (a plain click — which never fires drag_started — is snapped
                // in the `clicked()` branch below); a press on an armed
                // transform-gizmo HANDLE drives the gizmo; anywhere else starts a
                // camera drag through the controls.
                match route_drag_start(state, gx, gy) {
                    // The cube already snapped the camera inside the router.
                    DragStart::ViewCube => {}
                    // Grabbed a gizmo handle → route the drag to the transform.
                    DragStart::Gizmo => self.gizmo_dragging = true,
                    // Grabbed the armed COMPONENT Move gizmo → free-move the gizmo
                    // during the drag, commit the pose (+ re-solve) on release.
                    DragStart::Component => self.component_gizmo_dragging = true,
                    // Grabbed a ◎ dimension ARROWHEAD (Fix 4) → route the drag to
                    // that param's live edit instead of orbiting the camera.
                    DragStart::Dimension(field) => self.dim_dragging = Some(field),
                    // Grabbed an ASSEMBLY-CONSTRAINT handle (a distance leader /
                    // angle-arc handle, §8.4 grabbable arrows) → the drag previews
                    // that constraint's value; release commits + auto-solves.
                    DragStart::Constraint => self.constraint_dragging = true,
                    DragStart::Camera => {
                        let btn = if response.dragged_by(egui::PointerButton::Secondary) {
                            BUTTON_RIGHT
                        } else if response.dragged_by(egui::PointerButton::Middle) {
                            BUTTON_MIDDLE
                        } else {
                            BUTTON_LEFT
                        };
                        // The camera anchors at the CURRENT pointer position, not
                        // the press origin: `pointer_move` deltas run from whatever
                        // `pointer_down` recorded, so anchoring at the (older) press
                        // origin would make the first orbit frame jump by the whole
                        // click-radius drift.
                        state.pointer_down(lx, ly, btn);
                        self.dragging = true;
                    }
                }
            }
        }
        if response.dragged() {
            if let Some(pos) = response.interact_pointer_pos() {
                let (lx, ly) = local(pos);
                if self.gizmo_dragging {
                    // Drive the transform gizmo: updates the feature's transform +
                    // re-runs the history (the model moves live).
                    state.transform_drag_to(lx, ly);
                } else if self.component_gizmo_dragging {
                    // Drive the component Move gizmo: the GIZMO follows the pointer
                    // (free move); the pose commits on release.
                    state.component_drag_to(lx, ly);
                } else if let Some(field) = self.dim_dragging.clone() {
                    // Drive the dimension arrow (Fix 4): edit the param + re-run the
                    // history live, so the geometry AND its arrow follow the pointer.
                    let feature = state.dimension_armed_feature();
                    if !feature.is_empty() {
                        state.feature_dimension_drag(&feature, &field, lx, ly);
                    }
                } else if self.constraint_dragging {
                    // Drive the constraint handle: the value PREVIEWS live (arrow +
                    // label track the pointer); nothing commits until release.
                    state.constraint_drag_to(lx, ly);
                } else if self.dragging {
                    state.pointer_move(lx, ly);
                }
            }
        }
        if response.drag_stopped() {
            if self.gizmo_dragging {
                state.transform_release();
                self.gizmo_dragging = false;
            }
            if self.component_gizmo_dragging {
                // COMMIT: compose the drag delta onto the ACOMP transform, one
                // param write + rerun (the constraint tail re-solves — by design).
                state.component_release();
                self.component_gizmo_dragging = false;
            }
            if self.dim_dragging.take().is_some() {
                // The overlay is already glued to the final value from the last drag
                // frame; just drop the flag so hover/select resume.
            }
            if self.constraint_dragging {
                // COMMIT the previewed constraint value: updates the constraint
                // (auto-solves), re-tessellates the re-posed components, folds the
                // solved poses into the history document, refreshes the overlay.
                state.constraint_drag_release();
                self.constraint_dragging = false;
            }
            if self.dragging {
                state.pointer_up();
                self.dragging = false;
            }
        }

        // A plain click (press+release, no drag) over the viewport: in
        // reference-selection mode it type-constrained-picks a reference under the
        // cursor (engine drives the highlight); otherwise the modeling selection
        // UX — a PLAIN click on ONE filter-admitted item selects it (replace, or
        // toggle in the Click-toggles multi-select mode), a plain click on SEVERAL
        // overlapping items opens the PICK LIST popup at the cursor (front/back
        // faces, obstructed geometry), Ctrl/Cmd+click ADDS/TOGGLES the top pick
        // directly, and Alt+click opens the pick list explicitly. ViewCube clicks
        // are snapped in this branch (checked right after the popup), never a
        // selection/pick.
        if response.clicked() {
            if let Some(pos) = response.interact_pointer_pos() {
                let on_popup = self.candidate_popup.is_some()
                    && self
                        .candidate_popup_rect
                        .map(|r| r.contains(pos))
                        .unwrap_or(false);
                let (lx, ly) = local(pos);
                let mods = ui.ctx().input(|i| i.modifiers);
                if on_popup {
                    // A click inside the OPEN popup belongs to the popup — its
                    // entry buttons handle it in `show_candidate_popup`. Don't let
                    // the viewport close it or pick the geometry behind it.
                } else if self.candidate_popup.is_some() {
                    // A click OUTSIDE the open pick list DISMISSES it and is
                    // SWALLOWED — it must not fall through to the selection
                    // branches below, or dismissing the list would re-pick (or, on
                    // empty space, CLEAR a multi-selection built through the
                    // list). The NEXT click acts normally.
                    self.candidate_popup = None;
                    self.candidate_popup_rect = None;
                } else if let Some((cx, cy)) = self.viewcube_local(state, lx, ly) {
                    // A click over the ViewCube corner snaps the camera to that
                    // region's standard view. Checked FIRST (after the popup) so a
                    // corner click is always a view snap, never a scene / ref-select
                    // / gizmo pick. A PLAIN click never fires `drag_started` (egui
                    // postpones the click/drag decision for a click_and_drag widget
                    // and only fires drag_started once the pointer is decidedly
                    // dragging), so the snap MUST run here — the drag-start path only
                    // catches a press that egui classifies as a drag.
                    state.viewcube_click(cx, cy);
                } else if state.ref_select_active() {
                    state.ref_select_click(lx, ly);
                } else if state.transform_center_pick(lx, ly) {
                    // The orange CENTER sphere in transform mode toggles to the
                    // DIMENSION arrows (the old app's center-handle ◎ toggle).
                    // Must precede the generic handle-swallow below so a center
                    // click flips modes instead of being swallowed; a center
                    // DRAG still free-moves (handled on drag-start, not here).
                    state.toggle_to_dimension();
                } else if state.dimension_origin_pick(lx, ly) {
                    // The orange ORIGIN sphere in dimension mode toggles back to
                    // the TRANSFORM controls (the reverse ◎ toggle).
                    state.toggle_to_transform();
                } else if state.dimension_arrow_pick(lx, ly).is_some() {
                    // A bare click on a dimension ARROWHEAD is a no-op — only a DRAG
                    // on it edits the value (Fix 4). Swallow it so the solid behind
                    // the arrow isn't selected.
                } else if state.constraint_arrow_pick(lx, ly).is_some() {
                    // Same rule for an assembly-constraint handle: only a DRAG edits
                    // the value; swallow the bare click so the geometry behind the
                    // leader/arc isn't selected.
                } else if (state.transform_armed() || state.component_move_armed())
                    && state.transform_pick(lx, ly) != 0
                {
                    // A bare click on an armed (non-center) gizmo handle — feature
                    // OR component Move gizmo — swallow it so the solid behind the
                    // gizmo is not selected.
                } else if mods.alt {
                    // Alt+click → open the pick list explicitly, even for a
                    // single candidate (the power-user inspection trigger).
                    let cands = state.candidates_filtered_at(lx, ly);
                    self.candidate_popup = (!cands.is_empty())
                        .then(|| CandidatePopup { anchor: pos, candidates: cands });
                    self.candidate_popup_fresh = self.candidate_popup.is_some();
                } else if mods.command || mods.ctrl {
                    // Ctrl/Cmd+click ADDS/TOGGLES the top pick directly, no list
                    // (the classic additive shortcut, both multi-select modes).
                    state.select_toggle_at(lx, ly);
                } else {
                    // A plain click: ONE admitted item under the cursor selects it
                    // directly — REPLACE in Ctrl+Click mode, TOGGLE in the
                    // Click-toggles mode (a second click on the same item
                    // unselects it). SEVERAL overlapping items open the PICK LIST
                    // popup so front/back faces, obstructed geometry AND the
                    // construction planes over them are all reachable. A miss
                    // clears.
                    //
                    // Construction planes are ORDINARY candidates in this list
                    // (`PickKind::Plane`, ranked right after faces), so there is
                    // no geometry-miss `datum_pick` fallback any more: a plane
                    // under other geometry used to be unreachable because the
                    // fallback only ran when the list came back EMPTY, and an
                    // unchecked Plane filter could not have excluded it.
                    let cands = state.candidates_filtered_at(lx, ly);
                    let toggles =
                        state.settings.multi_select == MultiSelectMode::ClickToggles;
                    match cands.len() {
                        0 => {
                            state.clear_selection();
                        }
                        1 => {
                            if toggles {
                                state.toggle_candidate(&cands[0]);
                            } else {
                                state.select_candidate(&cands[0]);
                            }
                        }
                        _ => {
                            self.candidate_popup =
                                Some(CandidatePopup { anchor: pos, candidates: cands });
                            self.candidate_popup_fresh = true;
                        }
                    }
                }
            }
        }

        // Hover: the ViewCube corner, an armed transform-gizmo handle, OR the
        // top filter-admitted scene entity under the pointer (the modeling
        // hover-highlight). Suppressed while dragging / over a gizmo handle / mid
        // dimension-arrow or constraint-handle drag (feature, component-move, or
        // constraint gizmo), while the candidate popup owns the highlight, and
        // for the ONE frame a constraint LABEL applied its element highlight
        // (the label pass draws after us and re-arms the flag while hovered —
        // mirrors the sketch entity-list hover yield).
        let label_hover = state.take_constraint_label_hover();
        if !self.dragging
            && !self.gizmo_dragging
            && !self.component_gizmo_dragging
            && self.dim_dragging.is_none()
            && !self.constraint_dragging
            && !label_hover
        {
            match response.hover_pos() {
                Some(pos) => {
                    let (lx, ly) = local(pos);
                    match self.viewcube_local(state, lx, ly) {
                        Some((cx, cy)) => {
                            state.viewcube_hover(cx, cy);
                            state.clear_hover(); // over the cube, not the scene
                        }
                        None => {
                            state.viewcube_clear_hover();
                            // Over an armed gizmo handle → highlight the handle, not
                            // the solid behind it (the previous app's "skip scene hover over
                            // the gizmo" rule). Else hover-highlight the top pick.
                            let over_handle = (state.transform_armed()
                                || state.component_move_armed())
                                && state.transform_hover(lx, ly) != 0;
                            if over_handle {
                                state.clear_hover();
                            } else if self.candidate_popup.is_none() {
                                state.hover_at(lx, ly);
                            }
                        }
                    }
                }
                None => {
                    state.viewcube_clear_hover();
                    // Pointer left the viewport (or moved onto the popup, which
                    // drives its own entry-hover) → drop the scene hover.
                    if self.candidate_popup.is_none() {
                        state.clear_hover();
                    }
                }
            }
        }

        // Wheel zoom toward the cursor when hovering the viewport.
        if response.hovered() {
            // Raw (unsmoothed) wheel delta so each notch is a discrete step with NO
            // ease-in/out ramp (egui's smooth_scroll_delta dampens the start/end of a
            // scroll). See [`raw_wheel_delta_y`].
            let scroll_y = raw_wheel_delta_y(ui.ctx());
            if scroll_y != 0.0 {
                let cursor = response.hover_pos().map(|p| {
                    let (lx, ly) = local(p);
                    [lx, ly]
                });
                // egui scroll: +y = wheel up = zoom in; the controls treat
                // negative delta_y as zoom-in (see desktop.rs), so negate.
                state.wheel(-(scroll_y as f64), cursor);
            }
        }
    }

    /// Draw the PICK LIST popup — a semi-transparent, scrollable list of the
    /// ranked, filter-admitted candidates at the cursor, in the category order
    /// points > edges > faces > solids > components (nearest first within each).
    /// Opens on a plain click with MULTIPLE items under the pointer (so front +
    /// back faces and obstructed geometry are reachable) and on Alt+click
    /// explicitly. HOVERING an entry pre-highlights that entity in the scene
    /// (and hover-out clears it); a row draws SELECTED while its entity is in
    /// the selection, so toggling reads back visually. CLICKING an entry picks
    /// it and ALWAYS closes the list: in the Click-toggles multi-select mode
    /// (and on Ctrl/Cmd+click in either mode) the entry TOGGLES into the
    /// selection — front AND back faces join one selection across two
    /// click→entry rounds — while in Ctrl+Click mode a plain entry click
    /// REPLACES the selection with exactly it. The header's "Clear Selection"
    /// clears + closes. Also closes on Escape (routed via the app shell so it
    /// never also clears the selection) and on a click outside (swallowed by
    /// the viewport click router). Rebuilds `candidate_hits` (per-entry screen
    /// rects) each frame for the headed verifier. Engine mutations are applied
    /// AFTER the draw closure (the codebase's "no engine mutation inside the
    /// draw" rule).
    fn show_candidate_popup(&mut self, ctx: &egui::Context, state: &mut EngineState) {
        self.candidate_hits.clear();
        // A modal mode (reference-selection / sketch edit) supersedes the pick
        // list: drop a popup left open by modeling clicks so it neither draws
        // over the modal nor swallows the modal's first viewport click.
        if state.ref_select_active() || state.sketch_mode() {
            self.candidate_popup = None;
        }
        let Some(popup) = self.candidate_popup.as_ref() else {
            self.candidate_popup_rect = None;
            return;
        };
        let candidates = popup.candidates.clone();
        let anchor = popup.anchor;
        let mods = ctx.input(|i| i.modifiers);
        // Row selected-state, read BEFORE the draw (no engine borrow inside it).
        let selected_rows: Vec<bool> = candidates
            .iter()
            .map(|c| state.candidate_is_selected(c))
            .collect();

        let mut hits: Vec<egui::Rect> = Vec::with_capacity(candidates.len());
        let mut hovered_index: Option<usize> = None;
        let mut clicked_index: Option<usize> = None;
        let mut clear_clicked = false;

        let area = egui::Area::new(egui::Id::new("brep-candidate-popup"))
            .order(egui::Order::Foreground)
            .fixed_pos(anchor)
            // Keep the whole list on screen when the click lands near an edge.
            .constrain(true)
            .show(ctx, |ui| {
                // The standard popup frame at reduced opacity: the model stays
                // visible through the list while scrolling it.
                let mut frame = egui::Frame::popup(ui.style());
                frame.fill = frame.fill.gamma_multiply(0.85);
                frame.show(ui, |ui| {
                    ui.set_max_width(280.0);
                    // Header row: title + a "Clear Selection" action.
                    ui.horizontal(|ui| {
                        ui.label(egui::RichText::new("Select an object").weak().small());
                        ui.with_layout(
                            egui::Layout::right_to_left(egui::Align::Center),
                            |ui| {
                                if ui.small_button("Clear Selection").clicked() {
                                    clear_clicked = true;
                                }
                            },
                        );
                    });
                    // A long candidate list scrolls instead of growing past the
                    // viewport; hover keeps re-resolving as rows slide under the
                    // pointer, so scrolling through the list highlights each
                    // entity in turn.
                    egui::ScrollArea::vertical()
                        .max_height(240.0)
                        .show(ui, |ui| {
                            ui.set_min_width(220.0);
                            for (i, candidate) in candidates.iter().enumerate() {
                                let label = format!(
                                    "{}  {}",
                                    state.candidate_kind_label(candidate),
                                    candidate_label(candidate)
                                );
                                let resp = ui.selectable_label(selected_rows[i], label);
                                hits.push(resp.rect);
                                if resp.hovered() {
                                    hovered_index = Some(i);
                                }
                                if resp.clicked() {
                                    clicked_index = Some(i);
                                }
                            }
                        });
                });
            });

        self.candidate_hits = hits;
        self.candidate_popup_rect = Some(area.response.rect);

        // Apply engine mutations outside the draw closure.
        if let Some(i) = hovered_index {
            state.hover_candidate(&candidates[i]);
        } else {
            // No entry under the pointer → drop the pre-highlight, so the
            // last-hovered row's entity doesn't stay lit while the pointer
            // roams elsewhere.
            state.clear_hover();
        }
        let mut close = false;
        if clear_clicked {
            state.clear_selection();
            close = true;
        }
        if let Some(i) = clicked_index {
            // Picking an entry ALWAYS dismisses the list — the pick is the
            // list's job and it is done. In Click-toggles mode (or with
            // Ctrl/Cmd held) the entry TOGGLES into the selection, so a
            // front+back multi-selection is click → front, click → back (the
            // list reopens on the next click); in Ctrl+Click mode a plain
            // entry click REPLACES the selection with exactly that entity.
            let toggles = state.settings.multi_select == MultiSelectMode::ClickToggles;
            if toggles || mods.command || mods.ctrl {
                state.toggle_candidate(&candidates[i]);
            } else {
                state.select_candidate(&candidates[i]);
            }
            close = true;
        }
        // Fallback only: the app shell's global Escape router consumes the key
        // first and closes via `close_candidate_popup` (so Escape never ALSO
        // clears the selection); this fires only when that router is skipped
        // (e.g. a text edit had focus).
        if ctx.input(|i| i.key_pressed(egui::Key::Escape)) {
            close = true;
        }
        // Ignore the OPENING Alt+click on the frame it opened; honor click-outside
        // from the next frame on.
        if self.candidate_popup_fresh {
            self.candidate_popup_fresh = false;
        } else if area.response.clicked_elsewhere() {
            close = true;
        }
        if close {
            state.clear_hover();
            self.candidate_popup = None;
            self.candidate_popup_rect = None;
        }
    }

    /// The OPEN popup's candidate list as JSON `[{index,kind,name,solid,depth}]`
    /// (empty when closed) — the headed verifier asserts the sorted list.
    #[cfg(target_arch = "wasm32")]
    fn candidates_json(&self, state: &EngineState) -> String {
        match self.candidate_popup.as_ref() {
            Some(popup) => {
                let out: Vec<serde_json::Value> = popup
                    .candidates
                    .iter()
                    .enumerate()
                    .map(|(i, c)| {
                        serde_json::json!({
                            "index": i,
                            "kind": state.candidate_kind_label(c),
                            "name": c.name,
                            "solid": c.solid,
                            "depth": c.depth,
                        })
                    })
                    .collect();
                serde_json::Value::Array(out).to_string()
            }
            None => "[]".to_string(),
        }
    }

    /// The OPEN popup's per-entry screen rects as JSON `[{index,x,y,w,h}]` (egui
    /// points) so the verifier can click a specific candidate entry.
    #[cfg(target_arch = "wasm32")]
    fn candidate_hits_json(&self) -> String {
        let out: Vec<serde_json::Value> = self
            .candidate_hits
            .iter()
            .enumerate()
            .map(|(i, r)| {
                serde_json::json!({
                    "index": i,
                    "x": r.min.x,
                    "y": r.min.y,
                    "w": r.width(),
                    "h": r.height(),
                })
            })
            .collect();
        serde_json::Value::Array(out).to_string()
    }
}

/// Which branch CLAIMED a viewport drag-start — the one dispatch that decides
/// whether a press drives a gizmo handle or the camera. Returned by
/// [`route_drag_start`], which performs the claim; the caller only records which
/// drag is now live.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) enum DragStart {
    /// The ViewCube corner: the router already snapped the camera.
    ViewCube,
    /// A transform-gizmo handle (arrow / ring ball / center sphere).
    Gizmo,
    /// A handle of the armed assembly-component Move gizmo.
    Component,
    /// A ◎ dimension arrowhead; carries the param field key it edits.
    Dimension(String),
    /// An assembly-constraint distance/angle handle.
    Constraint,
    /// Nothing claimed it → the camera orbit/pan fallthrough.
    Camera,
}

/// The VIEWPORT-LOCAL point a drag-start hit test must be taken at. The ONE
/// place that choice is made — the dispatch and its tests both call THIS, so a
/// test can never pass against a call site that resolved the point differently.
///
/// NOT `response.interact_pointer_pos()`, which is the pointer's position on the
/// frame egui DECIDED the press was a drag — by then it has travelled at least
/// `max_click_dist` (6 pt) from the press, and a slow frame (the 3D viewport
/// waking from egui's on-demand repaint) coalesces the whole flick into one
/// step, so the reported point can be tens of px away. A gizmo handle carries
/// 7-9 px of grab radius (axis arrow / rotation ball / centre sphere), a
/// dimension leader 18, so hit-testing there misses the handle the user
/// actually pressed and the press falls through to the camera orbit.
///
/// `press_origin` is exactly where the button went down, so the test asks "what
/// did you press on", not "where has the cursor got to". It is `None` only when
/// no button is down — a press and release inside ONE frame — where the reported
/// interact position is all there is.
fn drag_start_local(response: &egui::Response, rect: egui::Rect) -> Option<(f64, f64)> {
    let p = response
        .ctx
        .input(|i| i.pointer.press_origin())
        .or_else(|| response.interact_pointer_pos())?;
    Some(((p.x - rect.min.x) as f64, (p.y - rect.min.y) as f64))
}

/// Dispatch ONE viewport drag-start at viewport-local px `(x, y)`: the first
/// branch whose handle is under the press CLAIMS it (and arms its drag inside
/// the engine), else the camera takes it.
///
/// Precedence is load-bearing and unchanged: ViewCube corner → transform gizmo →
/// component Move gizmo → ◎ dimension arrowhead → assembly-constraint handle →
/// camera. Split out of `handle_viewport_input` so the claim can be driven from
/// a test without a GPU-backed [`Viewport`].
pub(super) fn route_drag_start(state: &mut EngineState, x: f64, y: f64) -> DragStart {
    if let Some((cx, cy)) = viewcube_local(state, x, y) {
        state.viewcube_click(cx, cy);
        DragStart::ViewCube
    } else if state.transform_press(x, y) {
        DragStart::Gizmo
    } else if state.component_press(x, y) {
        DragStart::Component
    } else if let Some(field) = state.dimension_arrow_pick(x, y) {
        DragStart::Dimension(field)
    } else if state.constraint_drag_begin(x, y) {
        DragStart::Constraint
    } else {
        DragStart::Camera
    }
}

/// The ViewCube corner rect hit test (viewport-local logical px) — `Some` with
/// the CUBE-local coords when `(x, y)` is inside the drawn cube, else `None`.
fn viewcube_local(state: &EngineState, x: f64, y: f64) -> Option<(f64, f64)> {
    let v: serde_json::Value = serde_json::from_str(&state.viewcube_rect_json()).ok()?;
    let (rx, ry, rw, rh) = (
        v["x"].as_f64()?,
        v["y"].as_f64()?,
        v["w"].as_f64()?,
        v["h"].as_f64()?,
    );
    if rw > 0.0 && rh > 0.0 && x >= rx && x <= rx + rw && y >= ry && y <= ry + rh {
        Some((x - rx, y - ry))
    } else {
        None
    }
}

/// A human label for a pick candidate: its kernel name, or a positional tag for
/// unnamed vertices.
fn candidate_label(candidate: &PickCandidate) -> String {
    if candidate.name.trim().is_empty() {
        let p = candidate.position;
        format!("({:.2}, {:.2}, {:.2})", p[0], p[1], p[2])
    } else {
        candidate.name.clone()
    }
}

/// Mirror an engine JSON string to `window.<name>` (wasm/verification only) — the
/// viewport's own copy so it can publish its hover/candidate globals without
/// reaching into the app shell.
#[cfg(target_arch = "wasm32")]
fn publish_to_js(name: &str, json: &str) {
    if let Some(win) = web_sys::window() {
        let _ = js_sys::Reflect::set(
            &win,
            &wasm_bindgen::JsValue::from_str(name),
            &wasm_bindgen::JsValue::from_str(json),
        );
    }
}

#[cfg(test)]
mod drag_start_tests {
    use super::*;
    use brep_render::engine_state::EngineState;

    /// The viewport rect the harness allocates: the WHOLE 800x600 screen, so
    /// viewport-local px and egui screen points are the same numbers.
    const VIEW: egui::Rect =
        egui::Rect::from_min_max(egui::pos2(0.0, 0.0), egui::pos2(800.0, 600.0));

    /// A one-feature history whose cube carries a `transform` group, so the
    /// transform gizmo can arm on it.
    fn cube_history(name: &str) -> String {
        serde_json::json!({
            "expressions": "",
            "configurator": {},
            "features": [{
                "type": "P.CU",
                "inputParams": {
                    "id": name,
                    "sizeX": 10.0, "sizeY": 10.0, "sizeZ": 10.0,
                    "transform": {
                        "position": [0.0, 0.0, 0.0],
                        "rotationEuler": [0.0, 0.0, 0.0],
                        "scale": [1.0, 1.0, 1.0]
                    },
                    "boolean": { "targets": [], "operation": "NONE" }
                },
                "persistentData": {}
            }]
        })
        .to_string()
    }

    /// An engine with the cube armed for transform, framed dead-on down -Z in
    /// orthographic so the gizmo origin projects to the viewport centre.
    fn armed_engine() -> EngineState {
        let mut state = EngineState::new();
        state.set_history_json(&cube_history("Pin")).unwrap();
        state.resize(800.0, 600.0);
        state.camera.eye = [0.0, 0.0, 40.0];
        state.camera.target = [0.0, 0.0, 0.0];
        state.camera.up = [0.0, 1.0, 0.0];
        state.camera.projection =
            brep_render::view::Projection::Orthographic { half_height: 20.0 };
        state.arm_transform("Pin");
        state
    }

    /// The published hit regions of the armed gizmo, exactly as the debug
    /// outline (and the hit test) see them, in viewport-local px.
    fn hit_areas(state: &EngineState) -> Vec<serde_json::Value> {
        serde_json::from_str(&state.transform_hit_areas_json()).unwrap()
    }

    /// The FIRST axis-arrow capsule, as `(a, b, r)` screen px.
    fn axis_capsule(state: &EngineState) -> (egui::Pos2, egui::Pos2, f32) {
        let areas = hit_areas(state);
        let cap = areas
            .iter()
            .find(|a| a["kind"] == "capsule")
            .expect("an axis-arrow capsule");
        let at = |v: &serde_json::Value| {
            egui::pos2(v[0].as_f64().unwrap() as f32, v[1].as_f64().unwrap() as f32)
        };
        (at(&cap["a"]), at(&cap["b"]), cap["r"].as_f64().unwrap() as f32)
    }

    /// The LAST circle region — a rotation grab BALL (the centre sphere is
    /// emitted first, the three ring balls after it).
    fn ring_ball(state: &EngineState) -> (egui::Pos2, f32) {
        let areas = hit_areas(state);
        let ball = areas
            .iter()
            .filter(|a| a["kind"] == "circle")
            .next_back()
            .expect("a rotation grab ball");
        let c = &ball["c"];
        (
            egui::pos2(c[0].as_f64().unwrap() as f32, c[1].as_f64().unwrap() as f32),
            ball["r"].as_f64().unwrap() as f32,
        )
    }

    /// Run ONE egui frame over the viewport rect with `events`, dispatching a
    /// drag-start exactly the way `handle_viewport_input` does. Returns the
    /// claimed branch on the frame egui decides the press is a drag.
    fn frame(
        ctx: &egui::Context,
        state: &mut EngineState,
        events: Vec<egui::Event>,
    ) -> Option<DragStart> {
        let raw = egui::RawInput {
            screen_rect: Some(VIEW),
            events,
            ..Default::default()
        };
        let mut claimed = None;
        let _ = ctx.run_ui(raw, |ui| {
            let response = ui.allocate_rect(VIEW, egui::Sense::click_and_drag());
            if response.drag_started() {
                if let Some(pos) = response.interact_pointer_pos() {
                    let (gx, gy) = drag_start_local(&response, VIEW).unwrap_or((
                        (pos.x - VIEW.min.x) as f64,
                        (pos.y - VIEW.min.y) as f64,
                    ));
                    claimed = Some(route_drag_start(state, gx, gy));
                }
            }
        });
        claimed
    }

    fn moved(pos: egui::Pos2) -> egui::Event {
        egui::Event::PointerMoved(pos)
    }

    fn button(pos: egui::Pos2, pressed: bool) -> egui::Event {
        egui::Event::PointerButton {
            pos,
            button: egui::PointerButton::Primary,
            pressed,
            modifiers: egui::Modifiers::default(),
        }
    }

    /// Hover, press at `press`, then take ONE coalesced move to `press + delta`
    /// — the frame egui promotes the press to a drag. Returns the claiming
    /// branch and the pointer position the drag is now at (still held down).
    fn press_and_drag(
        ctx: &egui::Context,
        state: &mut EngineState,
        press: egui::Pos2,
        delta: egui::Vec2,
    ) -> (DragStart, egui::Pos2) {
        frame(ctx, state, vec![moved(press)]);
        frame(ctx, state, vec![button(press, true)]);
        let to = press + delta;
        let claimed = frame(ctx, state, vec![moved(to)])
            .expect("egui promotes the press to a drag on the move frame");
        (claimed, to)
    }

    /// The same, released at the end. Returns the claiming branch.
    fn press_drag_release(
        ctx: &egui::Context,
        state: &mut EngineState,
        press: egui::Pos2,
        delta: egui::Vec2,
    ) -> DragStart {
        let (claimed, to) = press_and_drag(ctx, state, press, delta);
        frame(ctx, state, vec![button(to, false)]);
        claimed
    }

    /// The reported bug: the FIRST click-drag on a gizmo BALL orbits the camera
    /// instead of grabbing the handle (only the second drag moves the gizmo).
    ///
    /// The press lands dead-centre on a rotation grab ball's published hit
    /// region, then the pointer takes ONE coalesced ~20 px step — what a real
    /// flick looks like when the 3D viewport wakes from egui's on-demand
    /// repaint. The grab must resolve at the PRESS, not at where the cursor got
    /// to, so BOTH cycles claim the gizmo.
    #[test]
    fn the_first_drag_on_a_gizmo_ball_grabs_it_instead_of_orbiting() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        let (ball, r) = ring_ball(&state);
        assert!(r < 12.0, "grab ball radius {r}px is smaller than the click radius");

        for cycle in 1..=2 {
            let claimed = press_drag_release(&ctx, &mut state, ball, egui::vec2(14.0, 14.0));
            assert_eq!(
                claimed,
                DragStart::Gizmo,
                "cycle {cycle}: pressing the rotation ball must drive the gizmo, not the camera"
            );
            assert!(state.transform_dragging(), "cycle {cycle}: the gizmo drag is armed");
            state.transform_release();
        }
    }

    /// Same class on an axis ARROW, at the MINIMUM drift egui can report: the
    /// press sits 3 px off the shaft spine (inside the 7 px capsule) and the
    /// pointer moves just past the 6 px click radius perpendicular to it, so the
    /// reported drag position is ~9.5 px off the spine — outside the arrow.
    #[test]
    fn the_first_drag_on_a_gizmo_arrow_grabs_it_at_the_minimum_drift() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        let (a, b, r) = axis_capsule(&state);
        assert!(r > 3.0 && r < 10.0, "axis hit radius {r}px");
        let dir = (b - a).normalized();
        let normal = egui::vec2(-dir.y, dir.x);
        // 60% along the shaft (clear of the centre ball), 3 px off the spine.
        let press = a + dir * ((b - a).length() * 0.6) + normal * 3.0;

        for cycle in 1..=2 {
            let claimed = press_drag_release(&ctx, &mut state, press, normal * 6.5);
            assert_eq!(
                claimed,
                DragStart::Gizmo,
                "cycle {cycle}: pressing the axis arrow must drive the gizmo, not the camera"
            );
            state.transform_release();
        }
    }



    /// Why the SECOND drag used to work: how far egui's reported drag position
    /// has drifted depends entirely on how fast the pointer was moving.
    ///
    /// Same press, same handle, two speeds — a brisk flick that egui coalesces
    /// into ONE 20 px step, and a deliberate crawl in 2 px steps that trips the
    /// 6 px click radius barely past it. Hit-testing at the reported position
    /// claimed the gizmo only for the crawl, which is exactly the shape of the
    /// report: the natural first attempt orbited, the careful second one (made
    /// while watching for the glitch) grabbed. Anchored at the press, BOTH
    /// speeds claim the handle.
    #[test]
    fn a_flick_and_a_crawl_on_the_same_handle_both_grab_it() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        let (ball, _) = ring_ball(&state);

        // The flick: one coalesced 20 px step.
        let flicked = press_drag_release(&ctx, &mut state, ball, egui::vec2(14.0, 14.0));
        assert_eq!(flicked, DragStart::Gizmo, "a brisk flick must grab the ball");
        state.transform_release();

        // The crawl: 2 px a frame until egui calls it a drag.
        frame(&ctx, &mut state, vec![moved(ball)]);
        frame(&ctx, &mut state, vec![button(ball, true)]);
        let mut at = ball;
        let mut crawled = None;
        for _ in 0..8 {
            at += egui::vec2(2.0, 0.0);
            if let Some(claim) = frame(&ctx, &mut state, vec![moved(at)]) {
                crawled = Some(claim);
                break;
            }
        }
        frame(&ctx, &mut state, vec![button(at, false)]);
        assert_eq!(
            crawled,
            Some(DragStart::Gizmo),
            "a deliberate crawl must grab the ball too"
        );
        state.transform_release();
    }

    /// The OUTCOME the user asked for: the first drag MOVES the feature. The
    /// CLAIM is what keeps the camera out of it (a `Camera` route is the bug);
    /// the eye check below is belt-and-braces, since `pointer_down` alone
    /// records rather than orbits. The press is dead-centre on the +X arrow and the
    /// pointer takes one coalesced (25, 10) px step — 10 px off the shaft spine,
    /// outside the 7 px capsule, so hit-testing at the reported drag position
    /// would orbit instead.
    ///
    /// The translation is the WHOLE press → cursor delta (25 px of axial travel
    /// = 25 × `world_per_pixel`), not that minus the click radius: the grab is
    /// anchored at the press, so the feature ends up under the cursor rather
    /// than lagging it by the drift for the rest of the drag.
    #[test]
    fn the_first_drag_moves_the_feature_and_leaves_the_camera_alone() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        let eye_before = state.camera.eye;
        let wpp = state.camera.world_per_pixel();
        let (a, b, _) = axis_capsule(&state);
        // Dead-centre on the shaft, 60% out from the origin ball.
        let dir = (b - a).normalized();
        let press = a + dir * ((b - a).length() * 0.6);

        let (claimed, to) = press_and_drag(&ctx, &mut state, press, egui::vec2(25.0, 10.0));
        assert_eq!(claimed, DragStart::Gizmo, "the press must claim the arrow");
        state.transform_drag_to(to.x as f64, to.y as f64);
        frame(&ctx, &mut state, vec![button(to, false)]);
        state.transform_release();

        let index = state.history.index_of("Pin").unwrap();
        let params = state.history.feature_params(index).unwrap();
        let moved_x = params["transform"]["position"][0].as_f64().unwrap();
        let want = 25.0 * wpp;
        assert!(
            (moved_x - want).abs() < want * 0.02,
            "the feature must track the whole press→cursor travel: {moved_x} vs {want}"
        );
        assert_eq!(state.camera.eye, eye_before, "the camera must not have orbited");
    }

    /// The ◎ DIMENSION arrowheads share the drag-start chain, so they shared the
    /// bug and the same fix covers them: a press on a dimension leader followed
    /// by a coalesced step off its capsule must still grab the param, not orbit.
    /// The leader's grab radius is 18 px (`ARROW_HANDLE_HIT_RAD_PX`), so the
    /// step here clears it perpendicular to the shaft.
    #[test]
    fn the_first_drag_on_a_dimension_arrow_grabs_the_param() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        state.arm_dimension("Pin");
        assert_eq!(state.gizmo_mode(), "dimension");

        // The sizeX leader runs origin → (sizeX, 0, 0); press on its shaft.
        let annotations: Vec<serde_json::Value> =
            serde_json::from_str(&state.feature_dimension_annotations_json("Pin")).unwrap();
        let ann = annotations
            .iter()
            .find(|a| a["fieldKey"] == "sizeX")
            .expect("a sizeX dim");
        let world = |v: &serde_json::Value| {
            [
                v[0].as_f64().unwrap(),
                v[1].as_f64().unwrap(),
                v[2].as_f64().unwrap(),
            ]
        };
        let (ax, ay, _) = state.camera.project(world(&ann["pointA"]));
        let (bx, by, _) = state.camera.project(world(&ann["pointB"]));
        let a = egui::pos2(ax as f32, ay as f32);
        let b = egui::pos2(bx as f32, by as f32);
        let dir = (b - a).normalized();
        let normal = egui::vec2(-dir.y, dir.x);
        let press = a + dir * ((b - a).length() * 0.7);

        for cycle in 1..=2 {
            let claimed = press_drag_release(&ctx, &mut state, press, normal * 25.0);
            assert_eq!(
                claimed,
                DragStart::Dimension("sizeX".to_string()),
                "cycle {cycle}: pressing the dimension leader must edit sizeX, not orbit"
            );
        }
    }

    /// The FALLTHROUGH stays intact: a press on empty space still starts a
    /// camera orbit and arms no gizmo drag.
    #[test]
    fn an_empty_space_drag_still_orbits_the_camera() {
        let ctx = egui::Context::default();
        let mut state = armed_engine();
        // Far from the gizmo (which sits at the viewport centre) and from the
        // ViewCube corner.
        let empty = egui::pos2(120.0, 480.0);
        let claimed = press_drag_release(&ctx, &mut state, empty, egui::vec2(20.0, 8.0));
        assert_eq!(claimed, DragStart::Camera, "empty space must still orbit");
        assert!(!state.transform_dragging(), "no gizmo drag was armed");
    }

    /// The ViewCube corner keeps its precedence over everything else in the
    /// chain: a drag that starts inside the cube rect snaps the view, never a
    /// gizmo grab or an orbit.
    #[test]
    fn a_drag_started_over_the_viewcube_still_snaps_the_view() {
        let mut state = armed_engine();
        let cube: serde_json::Value =
            serde_json::from_str(&state.viewcube_rect_json()).unwrap();
        let (x, y, w, h) = (
            cube["x"].as_f64().unwrap(),
            cube["y"].as_f64().unwrap(),
            cube["w"].as_f64().unwrap(),
            cube["h"].as_f64().unwrap(),
        );
        assert!(w > 0.0 && h > 0.0, "the ViewCube is drawn");
        assert_eq!(
            route_drag_start(&mut state, x + w * 0.5, y + h * 0.5),
            DragStart::ViewCube
        );
        assert!(!state.transform_dragging(), "the cube beat the gizmo");
    }
}