Skip to content

Edge-Drop is a clipboard shelf on the edge of your screen. Hover to open it. Drag files and images into any app, click to copy text and links. Free and open-source for Windows.

feat(edge): rest-as-intent seam policy - reliable open on interior display boundaries

Deepender250059a41aaf5c
diff --git a/electron/main/stickProbe.ts b/electron/main/stickProbe.ts
index b048584..ccebc69 100644
--- a/electron/main/stickProbe.ts
+++ b/electron/main/stickProbe.ts
@@ -60,3 +60,152 @@ export function probeStickEdge(input: StickProbeInput): StickProbeResult {
export function isNearProximity(distFromEdge: number): boolean {
return distFromEdge <= FAST_POLL_PROXIMITY_PX
}
+
+/* ------------------------------------------------------------------ */
+/* Seam-aware arming (industry three-pillar model) */
+/* */
+/* When the shelf is mounted on a boundary shared with another */
+/* display, position alone cannot distinguish "hover my edge" from */
+/* "traveling between screens". Three pillars make it deterministic: */
+/* */
+/* 1. OWN-PIXEL ARMING - the trigger arms only at dist >= 0 (the */
+/* stick display's own side). The legacy -30px overshoot remains */
+/* ONLY as keep-open forgiveness downstream, never for arming. */
+/* 2. INTENT SPEED - a frame arms only when travel speed is */
+/* below MAX_INTENT_SPEED_PX_PER_MS (or unknowable due to a long */
+/* sampling gap). Fast flicks through the band never arm. */
+/* 3. CROSSING LOCKOUT - a boundary crossing suppresses arming for */
+/* SEAM_LOCKOUT_MS, killing the "popped open right after landing */
+/* on the other screen" residual. */
+/* */
+/* At a normal outer edge all three are invisible: the cursor clamps */
+/* at the physical boundary so dist is always >= 0, crossings never */
+/* occur, and arrival-then-stop yields speed ~0 immediately. */
+/* ------------------------------------------------------------------ */
+
+/** Suppression after a boundary crossing lasts until the cursor COMES TO REST… */
+export const REST_FRAMES_REQUIRED = 3
+/** …and "rest" means slow movement parked inside the own-side band. */
+export const MAX_INTENT_SPEED_PX_PER_MS = 1.5
+
+/** Caller-held memory between ticks (no module-level globals => fully simulatable). */
+export interface SeamTickState {
+ lastPoint?: { x: number; y: number }
+ lastDist?: number
+ lastTime?: number
+ /** True between a boundary crossing and the moment rest forgives it. */
+ crossPending?: boolean
+ /** Consecutive qualifying rest frames accumulated while crossPending. */
+ restStreak?: number
+}
+
+export interface SeamAwareProbe {
+ probe: StickProbeResult
+ /** True on the exact tick the cursor crossed the stuck boundary. */
+ crossedNow: boolean
+ /** px/ms between this and the previous sample; null when unmeasurable. */
+ speedPxPerMs: number | null
+ slowEnough: boolean
+ /** True while a crossing awaits rest-forgiveness (arming suppressed). */
+ lockedOut: boolean
+ /**
+ * The seam-policy verdict that production must report as `inEdge`.
+ * Requires ALL of: own pixels, inside band, slow enough, not pending rest.
+ */
+ armedInEdge: boolean
+ nextState: SeamTickState
+}
+
+export function probeSeamAware(
+ input: {
+ cursor: { x: number; y: number }
+ workArea: WorkAreaRect
+ stickPosition: 'left' | 'right'
+ hotZoneWidth: number
+ /** Monotonic-ish wall time for THIS sample (Date.now() in production). */
+ now: number
+ },
+ state: SeamTickState
+): SeamAwareProbe {
+ const probe = probeStickEdge({
+ cursor: input.cursor,
+ workArea: input.workArea,
+ stickPosition: input.stickPosition,
+ hotZoneWidth: input.hotZoneWidth
+ })
+
+ // Garbage samples must never poison the tracker.
+ if (probe.garbage) {
+ return {
+ probe,
+ crossedNow: false,
+ speedPxPerMs: null,
+ slowEnough: false,
+ lockedOut: false,
+ armedInEdge: false,
+ nextState: state
+ }
+ }
+
+ // ── Speed (pillar 2) ────────────────────────────────────────────────────
+ let speedPxPerMs: number | null = null
+ if (state.lastPoint && state.lastTime !== undefined) {
+ const dt = Math.min(250, Math.max(1, input.now - state.lastTime))
+ const dx = input.cursor.x - state.lastPoint.x
+ const dy = input.cursor.y - state.lastPoint.y
+ speedPxPerMs = Math.sqrt(dx * dx + dy * dy) / dt
+ }
+ const slowEnough = speedPxPerMs === null || speedPxPerMs <= MAX_INTENT_SPEED_PX_PER_MS
+
+ // ── Crossing detection ──────────────────────────────────────────────────
+ const crossedNow =
+ state.lastDist !== undefined &&
+ ((state.lastDist < 0 && probe.distFromEdge >= 0) ||
+ (state.lastDist >= 0 && probe.distFromEdge < 0))
+
+ // ── REST-AS-INTENT (pillar 3, refined) ──────────────────────────────────
+ // A crossing suppresses arming until the cursor comes to REST: moving
+ // slowly while parked INSIDE the own-side band for REST_FRAMES_REQUIRED
+ // consecutive frames. Motion resets the streak; rest forgives the crossing
+ // entirely. Behavior beats clocks: flicks never rest, so they stay
+ // suppressed forever; a deliberate stop is forgiven almost immediately.
+ let crossPending = state.crossPending ?? false
+ let restStreak = state.restStreak ?? 0
+
+ if (crossedNow) {
+ crossPending = true
+ restStreak = 0
+ } else if (crossPending) {
+ const inOwnBand =
+ probe.distFromEdge >= 0 && probe.distFromEdge <= input.hotZoneWidth
+ if (inOwnBand && slowEnough) restStreak++
+ else restStreak = 0
+ if (restStreak >= REST_FRAMES_REQUIRED) crossPending = false
+ }
+
+ const lockedOut = crossPending
+
+ // ── Combined verdict ────────────────────────────────────────────────────
+ // Pillar 1 lives in the distFromEdge >= 0 term (own pixels only).
+ const armedInEdge =
+ !lockedOut &&
+ probe.distFromEdge >= 0 &&
+ probe.distFromEdge <= input.hotZoneWidth &&
+ slowEnough
+
+ return {
+ probe,
+ crossedNow,
+ speedPxPerMs,
+ slowEnough,
+ lockedOut,
+ armedInEdge,
+ nextState: {
+ lastPoint: { x: input.cursor.x, y: input.cursor.y },
+ lastDist: probe.distFromEdge,
+ lastTime: input.now,
+ crossPending,
+ restStreak
+ }
+ }
+}
diff --git a/electron/main/window.ts b/electron/main/window.ts
index 995aee2..5f785f3 100644
--- a/electron/main/window.ts
+++ b/electron/main/window.ts
@@ -21,7 +21,7 @@ import { PATHS } from '../store/paths'
import { TRANSLATIONS, en } from '../../src/i18n/translations'
import { computeStickBounds } from './geometry'
import { WorkAreaCache } from './workAreaCache'
-import { probeStickEdge, isNearProximity } from './stickProbe'
+import { probeSeamAware, isNearProximity, type SeamTickState } from './stickProbe'
import { loadSettings, saveSettings } from '../store/settings'
import { isFullscreenAppActive, registerFullscreenActiveListener } from './fullscreen'
@@ -234,6 +234,8 @@ let _lastProximityExitMs = 0
/** Last sent cursor position — used to suppress duplicate IPC messages. */
let _lastSentX = -9999
let _lastSentY = -9999
+/** Seam-policy tracker threaded between ticks (see stickProbe.ts pillars). */
+let _seamState: SeamTickState = {}
/**
* Temporarily suspend the always-on-top heartbeat.
@@ -286,19 +288,26 @@ function _pollTick(): void {
const wa = workAreaCache.get(currentStickDisplayId)
if (!wa) return // no successful enumeration yet; retry next tick
- // Pure edge-probe math (unit-tested against simulated multi-display
- // topologies in tests/stickProbeScenarios.test.ts).
- const probe = probeStickEdge({
- cursor: pt,
- workArea: wa,
- stickPosition: settings.stickPosition,
- hotZoneWidth: currentHotZoneWidth
- })
- if (probe.garbage) return
-
- const clientX = probe.clientX
- const clientY = probe.clientY
- const distFromEdge = probe.distFromEdge
+ // Seam-aware probe (unit-tested against simulated multi-display
+ // topologies in tests/stickProbeScenarios.test.ts). The returned
+ // armedInEdge is what the renderer's dwell consumes: own pixels only,
+ // slow enough to be intent, and outside any post-crossing lockout.
+ const seam = probeSeamAware(
+ {
+ cursor: pt,
+ workArea: wa,
+ stickPosition: settings.stickPosition,
+ hotZoneWidth: currentHotZoneWidth,
+ now: Date.now()
+ },
+ _seamState
+ )
+ _seamState = seam.nextState
+ if (seam.probe.garbage) return
+
+ const clientX = seam.probe.clientX
+ const clientY = seam.probe.clientY
+ const distFromEdge = seam.probe.distFromEdge
// ── Adaptive speed: switch to fast poll when cursor approaches the edge ──
const nearProximity = isNearProximity(distFromEdge)
@@ -326,7 +335,10 @@ function _pollTick(): void {
}
}
- const inEdge = probe.inEdge
+ // Seam-aware verdict replaces the raw band test: fast traversal through a
+ // display boundary never arms the opener, while outer-edge behavior is
+ // preserved (cursor clamps at hardware edges => speed ~0, no crossings).
+ const inEdge = seam.armedInEdge
const newState = inEdge
diff --git a/tests/stickProbeScenarios.test.ts b/tests/stickProbeScenarios.test.ts
index 6f99ced..f5ad3ac 100644
--- a/tests/stickProbeScenarios.test.ts
+++ b/tests/stickProbeScenarios.test.ts
@@ -18,7 +18,7 @@
import { describe, expect, it, vi } from 'vitest'
import { WorkAreaCache } from '../electron/main/workAreaCache'
import { computeStickBounds } from '../electron/main/geometry'
-import { probeStickEdge, isNearProximity, FAST_POLL_PROXIMITY_PX } from '../electron/main/stickProbe'
+import { probeStickEdge, probeSeamAware, isNearProximity, FAST_POLL_PROXIMITY_PX, REST_FRAMES_REQUIRED, MAX_INTENT_SPEED_PX_PER_MS, type SeamTickState } from '../electron/main/stickProbe'
/* ------------------------------------------------------------------ */
/* Virtual desktop simulator */
@@ -326,3 +326,157 @@ describe('SIMULATION — adaptive proximity thresholds (unchanged feel)', () =>
expect(isNearProximity(ctl.tick({ x: 1921 + FAST_POLL_PROXIMITY_PX + 5, y: 0 })!.distFromEdge)).toBe(false)
})
})
+
+/* ------------------------------------------------------------------ */
+/* THREE-PILLAR SEAM POLICY (probeSeamAware) */
+/* Simulated at 16ms production fast-poll cadence */
+/* ------------------------------------------------------------------ */
+
+const SEC_X = 1920
+function seamController(stickPosition: 'left' | 'right' = 'left') {
+ const ctl = new StickController(sideBySideDesktop())
+ ctl.stickPosition = stickPosition
+ ctl.applyStickDisplay(2)
+ let state: SeamTickState = {}
+ let t = 1000
+ const wa = ctl.cache.get(ctl.currentStickDisplayId)!
+ return {
+ tick(x: number, y = 500) {
+ t += 16
+ const r = probeSeamAware({ cursor: { x, y }, workArea: wa, stickPosition, hotZoneWidth: 3, now: t }, state)
+ state = r.nextState
+ return r
+ },
+ get time() { return t }
+ }
+}
+
+describe('SEAM POLICY - pillar 1: own-pixel arming', () => {
+ it('neighbor-side hover (even fully stopped) never arms', () => {
+ const c = seamController()
+ let r = c.tick(SEC_X - 5)
+ for (let i = 0; i < 10; i++) r = c.tick(SEC_X - 5) // dwell ~160ms
+ expect(r.armedInEdge).toBe(false)
+ expect(r.probe.inEdge).toBe(true) // legacy band would have armed - policy must not
+ })
+
+ it('own-side pixel inside the band arms once slow', () => {
+ const c = seamController()
+ let r = c.tick(SEC_X + 2) // arrival may be fast
+ for (let i = 0; i < 5; i++) r = c.tick(SEC_X + 2) // settle
+ expect(r.armedInEdge).toBe(true)
+ })
+})
+
+describe('SEAM POLICY - pillar 2: velocity intent', () => {
+ it('fast flick THROUGH the band never arms on any frame', () => {
+ const c = seamController()
+ let anyArmed = false
+ for (let x = 1500; x <= 2400; x += 96) { // ~6 px/ms sweep
+ const r = c.tick(x)
+ if (r.armedInEdge) anyArmed = true
+ }
+ expect(anyArmed).toBe(false)
+ })
+
+ it("arrival then settle arms within a beat, like today's feel", () => {
+ const c = seamController()
+ c.tick(SEC_X + 60)
+ let r = c.tick(SEC_X + 2)
+ r = c.tick(SEC_X + 2)
+ expect(r.slowEnough).toBe(true)
+ r = c.tick(SEC_X + 2)
+ expect(r.armedInEdge).toBe(true)
+ })
+})
+
+describe('SEAM POLICY - pillar 3: rest-as-intent forgiveness', () => {
+ it('slow crossing suppresses until the cursor RESTS on own pixels (~3 frames), then forgives', () => {
+ const c = seamController()
+ // Cross slowly to the neighbor side.
+ c.tick(SEC_X + 1); c.tick(SEC_X - 40); c.tick(SEC_X - 80)
+ // Come back and park on own pixels: arrival frame is pending-rest.
+ let r = c.tick(SEC_X + 1)
+ expect(r.lockedOut).toBe(true)
+ r = c.tick(SEC_X + 1) // rest frame 1
+ r = c.tick(SEC_X + 1) // rest frame 2
+ expect(r.lockedOut).toBe(true)
+ r = c.tick(SEC_X + 1) // rest frame 3 => forgiven, armed same frame
+ expect(r.lockedOut).toBe(false)
+ expect(r.armedInEdge).toBe(true)
+ })
+
+ it('fast movement during the settle window RESETS rest progress', () => {
+ const c = seamController()
+ c.tick(SEC_X + 1); c.tick(SEC_X - 40)
+ c.tick(SEC_X + 1) // arrive (crossing) -> streak 0
+ c.tick(SEC_X + 2) // rest 1
+ let r = c.tick(SEC_X - 30) // quick jiggle across the seam: reset + re-cross
+ expect(r.crossedNow).toBe(true)
+ r = c.tick(SEC_X + 2) // arrival again, streak restarts at 0
+ expect(r.armedInEdge).toBe(false)
+ r = c.tick(SEC_X + 2) // rest 1
+ r = c.tick(SEC_X + 2) // rest 2
+ r = c.tick(SEC_X + 2) // rest 3 -> forgiven
+ expect(r.lockedOut).toBe(false)
+ expect(r.armedInEdge).toBe(true)
+ })
+
+ it('rest policy constants match the documented design', () => {
+ expect(REST_FRAMES_REQUIRED).toBe(3)
+ expect(MAX_INTENT_SPEED_PX_PER_MS).toBeGreaterThan(0)
+ })
+})
+
+describe('SEAM POLICY - outer-edge parity (single display, no neighbor)', () => {
+ it('hardware edge clamps cursor: prompt arming, zero crossings, zero lockouts', () => {
+ const desktop = new VirtualDesktop([display(1, 0, 0, 1920, 1080, true)])
+ const cache = new WorkAreaCache((id) => {
+ const all = desktop.getAllDisplays()
+ const s = all.find(d => d.id === id) ?? desktop.getPrimaryDisplay()
+ return { displayId: s.id, workArea: s.workArea }
+ })
+ const wa = cache.get(1)!
+ let state: SeamTickState = {}
+ let t = 1000
+ let sawCrossing = false
+ let sawLockout = false
+
+ const seq = [400, 120, 30, 4, 0, 0, 0, 0, 0, 0]
+ let armedAtFrame = -1
+ seq.forEach((x, i) => {
+ t += 16
+ const r = probeSeamAware({ cursor: { x, y: 300 }, workArea: wa, stickPosition: 'left', hotZoneWidth: 3, now: t }, state)
+ state = r.nextState
+ if (r.crossedNow) sawCrossing = true
+ if (r.lockedOut) sawLockout = true
+ if (r.armedInEdge && armedAtFrame === -1) armedAtFrame = i
+ })
+ expect(sawCrossing).toBe(false)
+ expect(sawLockout).toBe(false)
+ expect(armedAtFrame).toBeGreaterThanOrEqual(0)
+ expect(armedAtFrame).toBeLessThanOrEqual(5)
+ })
+})
+
+describe('SEAM POLICY - primary interior regression guard while stuck to secondary', () => {
+ it('primary interior never arms; own-side seam strip arms after arriving + settling', () => {
+ const c = seamController()
+ expect(c.tick(960, 540)!.armedInEdge).toBe(false)
+ expect(c.tick(500, 200)!.armedInEdge).toBe(false)
+
+ // Teleporting from primary-center into the seam IS a boundary crossing:
+ // arming stays suppressed until rest forgives it (~3 settled frames).
+ const arrive = c.tick(SEC_X + 1)!
+ expect(arrive.crossedNow).toBe(true)
+ expect(arrive.armedInEdge).toBe(false)
+
+ // Park on own pixels; rest streak builds and forgives without any timer.
+ let r = c.tick(SEC_X + 2)! // rest 1
+ r = c.tick(SEC_X + 2)! // rest 2
+ r = c.tick(SEC_X + 2)! // rest 3 -> forgiven
+ expect(r.lockedOut).toBe(false)
+ expect(r.slowEnough).toBe(true)
+ expect(r.armedInEdge).toBe(true)
+ })
+})