@pascal-app/editor 1.0.3 → 1.0.4

package/src/lib/keyboard-pan.test.ts

@@ -1,13 +1,18 @@
 import { afterAll, beforeAll, expect, test } from 'bun:test'
 import {
   acceptsKeyboardPan,
+  advanceKeyboardPanMotion,
   clearKeyboardPanKeys,
+  createKeyboardPanMotion,
   hasKeyboardPanInput,
   isKeyboardPanKey,
+  KEYBOARD_PAN_RAMP_SECONDS,
+  KEYBOARD_PAN_START_FRACTION,
+  KEYBOARD_PAN_STOP_SECONDS,
   type KeyboardPanState,
-  keyboardPanDirection,
   keyboardPanSpeed,
   setKeyboardPanKey,
+  syncKeyboardPanMotion,
 } from './keyboard-pan'
 
 const idle = (): KeyboardPanState => ({
@@ -16,6 +21,51 @@ const idle = (): KeyboardPanState => ({
   left: false,
   right: false,
 })
+
+/**
+ * Frames every `1000 / hz` ms from `phaseMs`; `codes` go down at `pressMs` and
+ * up `holdMs` later, synced at the edges like the views do. Returns the total
+ * travel in cruise-seconds and how long the glide lasted.
+ */
+function simulate({
+  codes = ['KeyD'],
+  holdMs,
+  hz = 60,
+  phaseMs = 0,
+  pressMs = 1000,
+}: {
+  codes?: string[]
+  holdMs: number
+  hz?: number
+  phaseMs?: number
+  pressMs?: number
+}) {
+  const motion = createKeyboardPanMotion()
+  const keys = idle()
+  const releaseMs = pressMs + holdMs
+  let x = 0
+  let y = 0
+  let pressed = false
+  let released = false
+  let restMs = releaseMs
+  for (let now = phaseMs; now < releaseMs + 2000; now += 1000 / hz) {
+    if (!pressed && now >= pressMs) {
+      syncKeyboardPanMotion(motion, keys, pressMs)
+      for (const code of codes) setKeyboardPanKey(keys, code, true)
+      pressed = true
+    }
+    if (!released && now >= releaseMs) {
+      syncKeyboardPanMotion(motion, keys, releaseMs)
+      clearKeyboardPanKeys(keys)
+      released = true
+    }
+    if (advanceKeyboardPanMotion(motion, keys, now)) restMs = now
+    x += motion.stepX
+    y += motion.stepY
+  }
+  return { x, y, glideMs: restMs - releaseMs, motion }
+}
+
 const key = (init: Partial<KeyboardEvent>) => ({ target: null, ...init }) as KeyboardEvent
 
 // No DOM in this runner: stand in for the element classes the editable check reads.
@@ -39,9 +89,15 @@ test('physical WASD keys drive a screen-space direction; letters on other layout
   expect(setKeyboardPanKey(state, 'KeyW', true)).toBe(true)
   expect(setKeyboardPanKey(state, 'KeyW', true)).toBe(false)
   setKeyboardPanKey(state, 'KeyD', true)
-  expect(keyboardPanDirection(state)).toEqual({ horizontal: 1, vertical: 1 })
+  const motion = createKeyboardPanMotion()
+  syncKeyboardPanMotion(motion, state, 0)
+  advanceKeyboardPanMotion(motion, state, 100)
+  expect(motion.stepX).toBeGreaterThan(0)
+  expect(motion.stepY).toBeCloseTo(motion.stepX)
   setKeyboardPanKey(state, 'KeyA', true)
-  expect(keyboardPanDirection(state)).toEqual({ horizontal: 0, vertical: 1 })
+  advanceKeyboardPanMotion(motion, state, 200)
+  expect(motion.stepX).toBe(0)
+  expect(motion.stepY).toBeGreaterThan(0)
   clearKeyboardPanKeys(state)
   expect(hasKeyboardPanInput(state)).toBe(false)
 })
@@ -55,8 +111,74 @@ test('modifier chords stay shortcuts, and typing in a field never pans', () => {
   expect(acceptsKeyboardPan(key({ target: new Input() }))).toBe(false)
 })
 
-test('speed scales with the visible width within fixed bounds', () => {
-  expect(keyboardPanSpeed(0)).toBe(2)
-  expect(keyboardPanSpeed(20)).toBeCloseTo(13)
-  expect(keyboardPanSpeed(1000)).toBe(55)
+test('cruise speed scales with the visible width within fixed bounds', () => {
+  expect(keyboardPanSpeed(0)).toBe(0.5)
+  expect(keyboardPanSpeed(20)).toBeCloseTo(6)
+  expect(keyboardPanSpeed(1000)).toBe(30)
+})
+
+test('a press starts just under cruise and reaches it within the ramp', () => {
+  const at = (holdSeconds: number) => {
+    const motion = createKeyboardPanMotion()
+    syncKeyboardPanMotion(motion, idle(), 0)
+    advanceKeyboardPanMotion(motion, { ...idle(), right: true }, holdSeconds * 1000)
+    return motion.velocityX
+  }
+  expect(at(0.001)).toBeCloseTo(KEYBOARD_PAN_START_FRACTION, 2)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS / 2)).toBeGreaterThan(KEYBOARD_PAN_START_FRACTION)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS / 2)).toBeLessThan(1)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS)).toBe(1)
+})
+
+test('a tap moves a small, predictable amount and a hold travels at cruise', () => {
+  // 100 ms ramping up from the start fraction, plus a short glide.
+  const tap = simulate({ holdMs: 100 }).x
+  expect(tap).toBeGreaterThan(0.1 * KEYBOARD_PAN_START_FRACTION)
+  expect(tap).toBeLessThan(0.1)
+  const hold = simulate({ holdMs: 2000 }).x
+  expect(hold).toBeGreaterThan(1.98)
+  expect(hold).toBeLessThan(2.02)
+})
+
+test('a tap counts from the key events, not from the frames around them', () => {
+  const taps = [0, 5, 11, 16].map((phaseMs) => simulate({ holdMs: 100, phaseMs }).x)
+  const slowFrames = [0, 40, 80].map((phaseMs) => simulate({ holdMs: 100, hz: 10, phaseMs }).x)
+  for (const tap of [...taps, ...slowFrames]) expect(tap).toBeCloseTo(taps[0] ?? 0, 2)
+  // Shorter than a frame still moves, by its own length.
+  expect(simulate({ holdMs: 8, phaseMs: 1 }).x).toBeGreaterThan(0.006)
+})
+
+test('release comes to rest within the stop time, with a barely visible glide', () => {
+  const hold = simulate({ codes: ['KeyW'], holdMs: 1000 })
+  expect(hold.glideMs).toBeLessThanOrEqual(KEYBOARD_PAN_STOP_SECONDS * 1000 + 1000 / 60)
+  // Glide under 3% of a cruise-second: about 1% of the view width.
+  const held1s = 1 - ((1 - KEYBOARD_PAN_START_FRACTION) * KEYBOARD_PAN_RAMP_SECONDS) / 3
+  expect(hold.y - held1s).toBeGreaterThan(0)
+  expect(hold.y - held1s).toBeLessThan(0.03)
+  expect(hold.motion.velocityY).toBe(0)
+})
+
+test('travel does not depend on the frame rate', () => {
+  const at60 = simulate({ holdMs: 1000 }).x
+  expect(simulate({ holdMs: 1000, hz: 144 }).x).toBeCloseTo(at60, 3)
+  expect(simulate({ holdMs: 1000, hz: 20 }).x).toBeCloseTo(at60, 2)
+})
+
+test('diagonals move no faster than a straight press', () => {
+  const straight = simulate({ holdMs: 1000 })
+  const diagonal = simulate({ codes: ['KeyD', 'KeyW'], holdMs: 1000 })
+  expect(Math.hypot(diagonal.x, diagonal.y)).toBeCloseTo(straight.x)
+  expect(diagonal.x).toBeCloseTo(diagonal.y)
+})
+
+test('a press during the glide resumes from the current speed', () => {
+  const motion = createKeyboardPanMotion()
+  const right = { ...idle(), right: true }
+  syncKeyboardPanMotion(motion, idle(), 0)
+  syncKeyboardPanMotion(motion, right, 1000)
+  syncKeyboardPanMotion(motion, idle(), 1002)
+  const glidingSpeed = motion.velocityX
+  expect(glidingSpeed).toBeGreaterThan(KEYBOARD_PAN_START_FRACTION)
+  advanceKeyboardPanMotion(motion, right, 1003)
+  expect(motion.velocityX).toBeGreaterThanOrEqual(glidingSpeed)
 })

package/src/lib/keyboard-pan.ts

@@ -9,9 +9,23 @@ export type KeyboardPanState = {
   right: boolean
 }
 
-const KEYBOARD_PAN_VIEW_WIDTH_PER_SECOND = 0.65
-const KEYBOARD_PAN_MIN_SPEED = 2
-const KEYBOARD_PAN_MAX_SPEED = 55
+// Tuning. Speeds are in visible view widths per second, so a pan feels the
+// same at any zoom; the world-unit clamps only bite on tiny or huge views.
+/** Cruise speed once a key is held, in view widths per second. */
+export const KEYBOARD_PAN_CRUISE_VIEW_WIDTHS_PER_SECOND = 0.3
+/** Share of cruise speed a fresh press starts at. */
+export const KEYBOARD_PAN_START_FRACTION = 0.55
+/** Seconds of holding to reach cruise speed. */
+export const KEYBOARD_PAN_RAMP_SECONDS = 0.22
+/** Seconds to come to rest after the last key is released. */
+export const KEYBOARD_PAN_STOP_SECONDS = 0.09
+const KEYBOARD_PAN_MIN_SPEED = 0.5
+const KEYBOARD_PAN_MAX_SPEED = 30
+// A stalled frame (tab switch, long task) must not turn into one big jump.
+const KEYBOARD_PAN_MAX_STEP_SECONDS = 0.25
+// Release decays exponentially; three time constants leave 5%, then it snaps to rest.
+const KEYBOARD_PAN_STOP_TIME_CONSTANT = KEYBOARD_PAN_STOP_SECONDS / 3
+const KEYBOARD_PAN_REST_FRACTION = 0.05
 
 export function isEditableKeyboardTarget(target: EventTarget | null) {
   return (
@@ -72,18 +86,153 @@ export function acceptsKeyboardPan(event: KeyboardEvent) {
   )
 }
 
-/** Screen-space direction: `horizontal` +1 is right, `vertical` +1 is forward (up). */
-export function keyboardPanDirection(state: KeyboardPanState) {
+/** Cruise speed, in world units per second, for a view `viewWidth` wide. */
+export function keyboardPanSpeed(viewWidth: number) {
+  return Math.min(
+    Math.max(viewWidth * KEYBOARD_PAN_CRUISE_VIEW_WIDTHS_PER_SECOND, KEYBOARD_PAN_MIN_SPEED),
+    KEYBOARD_PAN_MAX_SPEED,
+  )
+}
+
+/**
+ * Per-view motion carried between frames. Velocity and step are screen space
+ * (+x right, +y forward) in shares of cruise speed; multiply the step by
+ * `keyboardPanSpeed` for world units.
+ */
+export type KeyboardPanMotion = {
+  holding: boolean
+  /** Time on the ramp's clock, so a press during the glide resumes its speed. */
+  heldSeconds: number
+  velocityX: number
+  velocityY: number
+  /** This frame's travel, in cruise-seconds. */
+  stepX: number
+  stepY: number
+  // Travel integrated at key edges since the last frame.
+  pendingX: number
+  pendingY: number
+  /** `performance.now()` the motion was last advanced to; null before the first press. */
+  time: number | null
+}
+
+export function createKeyboardPanMotion(): KeyboardPanMotion {
   return {
-    horizontal: (state.right ? 1 : 0) - (state.left ? 1 : 0),
-    vertical: (state.forward ? 1 : 0) - (state.backward ? 1 : 0),
+    holding: false,
+    heldSeconds: 0,
+    velocityX: 0,
+    velocityY: 0,
+    stepX: 0,
+    stepY: 0,
+    pendingX: 0,
+    pendingY: 0,
+    time: null,
   }
 }
 
-/** World units per second for a view `viewWidth` wide. */
-export function keyboardPanSpeed(viewWidth: number) {
-  return Math.min(
-    Math.max(viewWidth * KEYBOARD_PAN_VIEW_WIDTH_PER_SECOND, KEYBOARD_PAN_MIN_SPEED),
-    KEYBOARD_PAN_MAX_SPEED,
+export function resetKeyboardPanMotion(motion: KeyboardPanMotion) {
+  motion.holding = false
+  motion.heldSeconds = 0
+  motion.velocityX = 0
+  motion.velocityY = 0
+  motion.stepX = 0
+  motion.stepY = 0
+  motion.pendingX = 0
+  motion.pendingY = 0
+  motion.time = null
+}
+
+// Speed eases out of the start fraction into cruise: s(u) = S + (1 - S)(2u - u²), u = t / ramp.
+const rampSpeed = (seconds: number) => {
+  const u = Math.min(seconds / KEYBOARD_PAN_RAMP_SECONDS, 1)
+  return KEYBOARD_PAN_START_FRACTION + (1 - KEYBOARD_PAN_START_FRACTION) * (2 * u - u * u)
+}
+
+// ∫₀ᵗ s, exact, so the distance does not depend on the frame rate.
+const rampDistance = (seconds: number) => {
+  const u = seconds / KEYBOARD_PAN_RAMP_SECONDS
+  const eased = u < 1 ? u * u - (u * u * u) / 3 : u - 1 / 3
+  return (
+    KEYBOARD_PAN_START_FRACTION * seconds +
+    (1 - KEYBOARD_PAN_START_FRACTION) * KEYBOARD_PAN_RAMP_SECONDS * eased
+  )
+}
+
+const rampSecondsForSpeed = (speed: number) => {
+  const eased = (speed - KEYBOARD_PAN_START_FRACTION) / (1 - KEYBOARD_PAN_START_FRACTION)
+  if (eased <= 0) return 0
+  if (eased >= 1) return KEYBOARD_PAN_RAMP_SECONDS
+  return KEYBOARD_PAN_RAMP_SECONDS * (1 - Math.sqrt(1 - eased))
+}
+
+/**
+ * Integrates `motion` up to `now` (`performance.now()`) under `keys`. Call it
+ * with the keys as they were just before one changes, so a press or release
+ * counts from the moment it happened rather than from the next frame.
+ */
+export function syncKeyboardPanMotion(
+  motion: KeyboardPanMotion,
+  keys: KeyboardPanState,
+  now: number,
+) {
+  const elapsed = motion.time === null ? 0 : (now - motion.time) / 1000
+  motion.time = motion.time === null ? now : Math.max(motion.time, now)
+  const dt = Math.min(Math.max(elapsed, 0), KEYBOARD_PAN_MAX_STEP_SECONDS)
+  const horizontal = (keys.right ? 1 : 0) - (keys.left ? 1 : 0)
+  const vertical = (keys.forward ? 1 : 0) - (keys.backward ? 1 : 0)
+
+  if (horizontal !== 0 || vertical !== 0) {
+    if (!motion.holding) {
+      motion.holding = true
+      motion.heldSeconds = rampSecondsForSpeed(Math.hypot(motion.velocityX, motion.velocityY))
+    }
+    const from = motion.heldSeconds
+    motion.heldSeconds = from + dt
+    // Diagonals travel at the same speed as straight moves.
+    const length = Math.hypot(horizontal, vertical)
+    const distance = rampDistance(motion.heldSeconds) - rampDistance(from)
+    const speed = rampSpeed(motion.heldSeconds)
+    motion.pendingX += (horizontal / length) * distance
+    motion.pendingY += (vertical / length) * distance
+    motion.velocityX = (horizontal / length) * speed
+    motion.velocityY = (vertical / length) * speed
+    return
+  }
+
+  motion.holding = false
+  motion.heldSeconds = 0
+  if (motion.velocityX === 0 && motion.velocityY === 0) return
+  const decay = Math.exp(-dt / KEYBOARD_PAN_STOP_TIME_CONSTANT)
+  const glide = KEYBOARD_PAN_STOP_TIME_CONSTANT * (1 - decay)
+  motion.pendingX += motion.velocityX * glide
+  motion.pendingY += motion.velocityY * glide
+  motion.velocityX *= decay
+  motion.velocityY *= decay
+  if (Math.hypot(motion.velocityX, motion.velocityY) < KEYBOARD_PAN_REST_FRACTION) {
+    motion.velocityX = 0
+    motion.velocityY = 0
+  }
+}
+
+/**
+ * Once per frame: syncs `motion` to `now` and leaves the travel since the
+ * last frame in `stepX`/`stepY`. Returns false once the
+ * view is at rest with nothing left to apply.
+ */
+export function advanceKeyboardPanMotion(
+  motion: KeyboardPanMotion,
+  keys: KeyboardPanState,
+  now: number,
+): boolean {
+  syncKeyboardPanMotion(motion, keys, now)
+  motion.stepX = motion.pendingX
+  motion.stepY = motion.pendingY
+  motion.pendingX = 0
+  motion.pendingY = 0
+  return (
+    motion.holding ||
+    motion.velocityX !== 0 ||
+    motion.velocityY !== 0 ||
+    motion.stepX !== 0 ||
+    motion.stepY !== 0
   )
 }