playwriter 0.0.105 → 0.2.0

package/src/ghost-cursor-client.ts

@@ -1,10 +1,23 @@
 /**
- * Browser-side ghost cursor renderer.
- * Injected into the page to visualize automated mouse actions with smooth easing.
+ * Browser-side ghost cursor renderer, injected into every Playwriter-attached tab.
+ * Auto-enables on load (top frame only). Idles out after 5s of no activity.
+ *
+ * Two-element DOM structure so move and press have independent CSS transitions:
+ *   outer (#__playwriter_ghost_cursor__) → translate3d, move easing/duration
+ *   inner (first child)                  → scale + opacity, press easing/duration
  */
 
 import { SCREENSTUDIO_POINTER_MACOS_TAHOE_DATA_URL } from './assets/cursors/screen-studio/pointer-macos-tahoe-data-url.js'
 
+// Top-frame only — skip iframes. try/catch for sandboxed iframes that throw.
+const isTopFrame = (() => {
+  try {
+    return window === window.top
+  } catch {
+    return false
+  }
+})()
+
 type GhostCursorActionType = 'move' | 'down' | 'up' | 'wheel'
 type GhostCursorButton = 'left' | 'right' | 'middle' | 'none'
 type GhostCursorStyle = 'minimal' | 'dot' | 'screenstudio'
@@ -39,13 +52,15 @@ interface GhostCursorRuntimeOptions {
 }
 
 interface GhostCursorRuntimeState {
-  cursorElement: ReturnType<typeof createCursorElement> | null
+  outerElement: HTMLDivElement | null
+  innerElement: HTMLDivElement | null
   options: GhostCursorRuntimeOptions
   x: number
   y: number
   scale: number
   hasPosition: boolean
   enabled: boolean
+  idleHidden: boolean
 }
 
 interface GhostCursorApi {
@@ -66,27 +81,42 @@ const SCREENSTUDIO_HOTSPOT_Y_RATIO = 0.06
 const MINIMAL_TRIANGLE_HOTSPOT_X_RATIO = 0.07
 const MINIMAL_TRIANGLE_HOTSPOT_Y_RATIO = 0.06
 
+// Animation curves from Emil Kowalski's guidelines (https://animations.dev):
+// moves use ease-in-out (accel/decel), presses use strong ease-out (100-160ms).
+const MOVE_EASING = 'cubic-bezier(0.65, 0, 0.35, 1)' // easeInOutCubic
+const PRESS_EASING = 'cubic-bezier(0.23, 1, 0.32, 1)' // strong ease-out
+const PRESS_DURATION_MS = 140
+
+// Cursor fades out after 5s of no activity, wakes on next action.
+const IDLE_HIDE_DELAY_MS = 5000
+const IDLE_FADE_OUT_MS = 600
+
 const DEFAULT_OPTIONS: GhostCursorRuntimeOptions = {
   style: 'minimal',
   color: '#111827',
   size: 22,
   zIndex: 2147483647,
-  easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-  minDurationMs: 24,
-  maxDurationMs: 320,
-  speedPxPerMs: 4,
+  easing: MOVE_EASING,
+  // Slow enough to track with the eye. Override per-call via ghostCursor.show().
+  minDurationMs: 220,
+  maxDurationMs: 1500,
+  speedPxPerMs: 1.2,
 }
 
 const runtime: GhostCursorRuntimeState = {
-  cursorElement: null,
+  outerElement: null,
+  innerElement: null,
   options: DEFAULT_OPTIONS,
   x: 0,
   y: 0,
   scale: 1,
   hasPosition: false,
   enabled: false,
+  idleHidden: false,
 }
 
+let idleHideTimer: ReturnType<typeof setTimeout> | null = null
+
 function clamp(options: { value: number; min: number; max: number }): number {
   const { value, min, max } = options
   return Math.min(max, Math.max(min, value))
@@ -159,13 +189,23 @@ function getBaseOpacity(): string {
   return '0.72'
 }
 
-function applyTransform(): void {
-  if (!runtime.cursorElement) {
+// Outer element: translate only (move timing).
+function applyTranslate(): void {
+  if (!runtime.outerElement) {
     return
   }
 
   const hotspot = getHotspotOffsetPx()
-  runtime.cursorElement.style.transform = `translate3d(${runtime.x - hotspot.x}px, ${runtime.y - hotspot.y}px, 0) scale(${runtime.scale})`
+  runtime.outerElement.style.transform = `translate3d(${runtime.x - hotspot.x}px, ${runtime.y - hotspot.y}px, 0)`
+}
+
+// Inner element: scale only (press timing).
+function applyScale(): void {
+  if (!runtime.innerElement) {
+    return
+  }
+
+  runtime.innerElement.style.transform = `scale(${runtime.scale})`
 }
 
 function computeDurationMs(options: { targetX: number; targetY: number }): number {
@@ -185,93 +225,139 @@ function computeDurationMs(options: { targetX: number; targetY: number }): numbe
   })
 }
 
-function createCursorElement() {
-  const element = document.createElement('div')
-  element.id = CURSOR_ID
-  element.setAttribute('aria-hidden', 'true')
-  element.style.position = 'fixed'
-  element.style.left = '0'
-  element.style.top = '0'
-  element.style.pointerEvents = 'none'
-  element.style.zIndex = `${runtime.options.zIndex}`
-  element.style.opacity = getBaseOpacity()
-  element.style.transitionProperty = 'transform, opacity'
-  element.style.transitionTimingFunction = runtime.options.easing
-  element.style.transitionDuration = '0ms'
-  element.style.willChange = 'transform'
-
-  runtime.cursorElement = element
+function createCursorElement(): HTMLDivElement {
+  const outer = document.createElement('div')
+  outer.id = CURSOR_ID
+  outer.setAttribute('aria-hidden', 'true')
+  outer.style.position = 'fixed'
+  outer.style.left = '0'
+  outer.style.top = '0'
+  outer.style.pointerEvents = 'none'
+  outer.style.zIndex = `${runtime.options.zIndex}`
+  outer.style.transitionProperty = 'transform'
+  outer.style.transitionTimingFunction = runtime.options.easing
+  outer.style.transitionDuration = '0ms'
+  outer.style.willChange = 'transform'
+
+  const inner = document.createElement('div')
+  inner.style.transitionProperty = 'transform, opacity'
+  inner.style.transitionTimingFunction = PRESS_EASING
+  inner.style.transitionDuration = `${PRESS_DURATION_MS}ms`
+  inner.style.opacity = getBaseOpacity()
+  outer.appendChild(inner)
+
+  runtime.outerElement = outer
+  runtime.innerElement = inner
   applyRuntimeVisualOptions()
 
-  return element
+  return outer
 }
 
-function ensureCursorElement() {
-  const existing = document.getElementById(CURSOR_ID)
+function ensureCursorElement(): HTMLDivElement {
+  const existing = document.getElementById(CURSOR_ID) as HTMLDivElement | null
   if (existing) {
-    runtime.cursorElement = existing
+    runtime.outerElement = existing
+    runtime.innerElement = (existing.firstElementChild as HTMLDivElement) || null
     return existing
   }
 
-  const element = createCursorElement()
-  runtime.cursorElement = element
+  const outer = createCursorElement()
   const root = document.documentElement || document.body
-  root.appendChild(element)
-  return element
+  root.appendChild(outer)
+  return outer
 }
 
 function applyRuntimeVisualOptions(): void {
-  if (!runtime.cursorElement) {
+  if (!runtime.innerElement) {
     return
   }
 
   const dimensions = getCursorDimensions()
-  runtime.cursorElement.style.width = `${dimensions.width}px`
-  runtime.cursorElement.style.height = `${dimensions.height}px`
-  runtime.cursorElement.style.zIndex = `${runtime.options.zIndex}`
-  runtime.cursorElement.style.transitionTimingFunction = runtime.options.easing
+  runtime.innerElement.style.width = `${dimensions.width}px`
+  runtime.innerElement.style.height = `${dimensions.height}px`
+
+  if (runtime.outerElement) {
+    runtime.outerElement.style.zIndex = `${runtime.options.zIndex}`
+    runtime.outerElement.style.transitionTimingFunction = runtime.options.easing
+  }
+
+  // Scale around the hotspot so press doesn't shift the arrow tip.
+  const hotspot = getHotspotOffsetPx()
+  runtime.innerElement.style.transformOrigin = `${hotspot.x}px ${hotspot.y}px`
 
   if (runtime.options.style === 'screenstudio') {
-    runtime.cursorElement.style.borderRadius = '0'
-    runtime.cursorElement.style.border = 'none'
-    runtime.cursorElement.style.backgroundColor = 'transparent'
-    runtime.cursorElement.style.backgroundImage = `url("${SCREENSTUDIO_POINTER_MACOS_TAHOE_DATA_URL}")`
-    runtime.cursorElement.style.backgroundRepeat = 'no-repeat'
-    runtime.cursorElement.style.backgroundPosition = 'left top'
-    runtime.cursorElement.style.backgroundSize = 'contain'
-    runtime.cursorElement.style.backdropFilter = 'none'
-    runtime.cursorElement.style.filter = 'none'
-    runtime.cursorElement.style.boxShadow = 'none'
-    runtime.cursorElement.style.opacity = getBaseOpacity()
+    runtime.innerElement.style.borderRadius = '0'
+    runtime.innerElement.style.border = 'none'
+    runtime.innerElement.style.backgroundColor = 'transparent'
+    runtime.innerElement.style.backgroundImage = `url("${SCREENSTUDIO_POINTER_MACOS_TAHOE_DATA_URL}")`
+    runtime.innerElement.style.backgroundRepeat = 'no-repeat'
+    runtime.innerElement.style.backgroundPosition = 'left top'
+    runtime.innerElement.style.backgroundSize = 'contain'
+    runtime.innerElement.style.backdropFilter = 'none'
+    runtime.innerElement.style.filter = 'none'
+    runtime.innerElement.style.boxShadow = 'none'
+    runtime.innerElement.style.opacity = getBaseOpacity()
     return
   }
 
   if (runtime.options.style === 'minimal') {
-    // White fill with dark border stroke, like a standard macOS cursor
     const triangleSvg = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="-1 -1 26 26"><path fill="white" stroke="${runtime.options.color}" stroke-width="1.5" stroke-linejoin="round" d="m23.284 19.124l-6.866-6.895a.4.4 0 0 1-.118-.296a.43.43 0 0 1 .163-.282l4.439-3.077a1.48 1.48 0 0 0 .621-1.48a1.48 1.48 0 0 0-1.036-1.198L1.623.302a1.14 1.14 0 0 0-1.11.282A1.13 1.13 0 0 0 .29 1.649L5.928 20.44a1.48 1.48 0 0 0 1.183 1.035a1.48 1.48 0 0 0 1.48-.621l3.078-4.44a.37.37 0 0 1 .31-.118a.43.43 0 0 1 .296.104l6.91 6.91a1.48 1.48 0 0 0 2.087 0l2.086-2.086a1.48 1.48 0 0 0-.074-2.101"/></svg>`
     const triangleDataUrl = `url("data:image/svg+xml,${encodeURIComponent(triangleSvg)}")`
-    runtime.cursorElement.style.borderRadius = '0'
-    runtime.cursorElement.style.border = 'none'
-    runtime.cursorElement.style.backgroundColor = 'transparent'
-    runtime.cursorElement.style.backgroundImage = triangleDataUrl
-    runtime.cursorElement.style.backgroundRepeat = 'no-repeat'
-    runtime.cursorElement.style.backgroundSize = 'contain'
-    runtime.cursorElement.style.backgroundPosition = 'left top'
-    runtime.cursorElement.style.backdropFilter = 'none'
-    runtime.cursorElement.style.boxShadow = 'none'
-    runtime.cursorElement.style.filter = 'drop-shadow(0 1px 2px rgba(0, 0, 0, 0.4))'
-    runtime.cursorElement.style.opacity = getBaseOpacity()
+    runtime.innerElement.style.borderRadius = '0'
+    runtime.innerElement.style.border = 'none'
+    runtime.innerElement.style.backgroundColor = 'transparent'
+    runtime.innerElement.style.backgroundImage = triangleDataUrl
+    runtime.innerElement.style.backgroundRepeat = 'no-repeat'
+    runtime.innerElement.style.backgroundSize = 'contain'
+    runtime.innerElement.style.backgroundPosition = 'left top'
+    runtime.innerElement.style.backdropFilter = 'none'
+    runtime.innerElement.style.boxShadow = 'none'
+    runtime.innerElement.style.filter = 'drop-shadow(0 1px 2px rgba(0, 0, 0, 0.4))'
+    runtime.innerElement.style.opacity = getBaseOpacity()
     return
   }
 
-  runtime.cursorElement.style.borderRadius = '999px'
-  runtime.cursorElement.style.border = 'none'
-  runtime.cursorElement.style.backgroundColor = runtime.options.color
-  runtime.cursorElement.style.backgroundImage = 'none'
-  runtime.cursorElement.style.backdropFilter = 'none'
-  runtime.cursorElement.style.filter = 'none'
-  runtime.cursorElement.style.boxShadow = '0 2px 10px rgba(0, 0, 0, 0.18), inset 0 0 0 2px rgba(255, 255, 255, 0.55)'
-  runtime.cursorElement.style.opacity = getBaseOpacity()
+  runtime.innerElement.style.borderRadius = '999px'
+  runtime.innerElement.style.border = 'none'
+  runtime.innerElement.style.backgroundColor = runtime.options.color
+  runtime.innerElement.style.backgroundImage = 'none'
+  runtime.innerElement.style.backdropFilter = 'none'
+  runtime.innerElement.style.filter = 'none'
+  runtime.innerElement.style.boxShadow = '0 2px 10px rgba(0, 0, 0, 0.18), inset 0 0 0 2px rgba(255, 255, 255, 0.55)'
+  runtime.innerElement.style.opacity = getBaseOpacity()
+}
+
+function clearIdleHideTimer(): void {
+  if (idleHideTimer !== null) {
+    clearTimeout(idleHideTimer)
+    idleHideTimer = null
+  }
+}
+
+function scheduleIdleHide(): void {
+  clearIdleHideTimer()
+  idleHideTimer = setTimeout(() => {
+    idleHideTimer = null
+    if (!runtime.enabled || !runtime.innerElement) {
+      return
+    }
+    runtime.idleHidden = true
+    runtime.innerElement.style.transitionDuration = `${IDLE_FADE_OUT_MS}ms`
+    runtime.innerElement.style.transitionTimingFunction = PRESS_EASING
+    runtime.innerElement.style.opacity = '0'
+  }, IDLE_HIDE_DELAY_MS)
+}
+
+function wakeFromIdle(options: { x: number; y: number }): void {
+  // Teleport so moveCursor sees zero distance.
+  runtime.x = options.x
+  runtime.y = options.y
+  runtime.hasPosition = true
+  if (runtime.innerElement) {
+    runtime.innerElement.style.transitionDuration = `${PRESS_DURATION_MS}ms`
+    runtime.innerElement.style.transitionTimingFunction = PRESS_EASING
+    runtime.innerElement.style.opacity = getBaseOpacity()
+  }
 }
 
 function moveCursor(options: { x: number; y: number }): void {
@@ -279,31 +365,34 @@ function moveCursor(options: { x: number; y: number }): void {
     return
   }
 
-  const element = ensureCursorElement()
+  ensureCursorElement()
   const durationMs = computeDurationMs({ targetX: options.x, targetY: options.y })
-  element.style.transitionDuration = `${Math.round(durationMs)}ms`
+  if (runtime.outerElement) {
+    runtime.outerElement.style.transitionDuration = `${Math.round(durationMs)}ms`
+    runtime.outerElement.style.transitionTimingFunction = runtime.options.easing
+  }
 
   runtime.x = options.x
   runtime.y = options.y
   runtime.hasPosition = true
-  applyTransform()
+  applyTranslate()
 }
 
 function setPressed(options: { pressed: boolean }): void {
-  if (!runtime.enabled) {
+  if (!runtime.enabled || !runtime.innerElement) {
     return
   }
 
-  const element = ensureCursorElement()
+  // Subtle press feedback (0.95). Dot style uses 0.92 — needs a bigger pulse.
   runtime.scale = options.pressed
-    ? runtime.options.style === 'screenstudio'
-      ? 0.94
-      : runtime.options.style === 'minimal'
-        ? 0.93
-      : 0.82
+    ? runtime.options.style === 'dot'
+      ? 0.92
+      : 0.95
     : 1
-  element.style.opacity = options.pressed ? '1' : getBaseOpacity()
-  applyTransform()
+  runtime.innerElement.style.transitionDuration = `${PRESS_DURATION_MS}ms`
+  runtime.innerElement.style.transitionTimingFunction = PRESS_EASING
+  runtime.innerElement.style.opacity = options.pressed ? '1' : getBaseOpacity()
+  applyScale()
 }
 
 function enable(options?: GhostCursorClientOptions): void {
@@ -319,17 +408,27 @@ function enable(options?: GhostCursorClientOptions): void {
     runtime.hasPosition = true
   }
 
-  applyTransform()
+  runtime.idleHidden = false
+  if (runtime.innerElement) {
+    runtime.innerElement.style.opacity = getBaseOpacity()
+  }
+
+  applyTranslate()
+  applyScale()
+  scheduleIdleHide()
 }
 
 function disable(): void {
   runtime.enabled = false
   runtime.scale = 1
   runtime.hasPosition = false
+  runtime.idleHidden = false
+  clearIdleHideTimer()
 
-  if (runtime.cursorElement) {
-    runtime.cursorElement.remove()
-    runtime.cursorElement = null
+  if (runtime.outerElement) {
+    runtime.outerElement.remove()
+    runtime.outerElement = null
+    runtime.innerElement = null
   }
 }
 
@@ -338,21 +437,22 @@ function applyMouseAction(action: GhostCursorAction): void {
     return
   }
 
-  if (action.type === 'move' || action.type === 'wheel') {
-    moveCursor({ x: action.x, y: action.y })
-    return
+  if (runtime.idleHidden) {
+    runtime.idleHidden = false
+    wakeFromIdle({ x: action.x, y: action.y })
   }
 
-  if (action.type === 'down') {
+  if (action.type === 'move' || action.type === 'wheel') {
+    moveCursor({ x: action.x, y: action.y })
+  } else if (action.type === 'down') {
     moveCursor({ x: action.x, y: action.y })
     setPressed({ pressed: true })
-    return
-  }
-
-  if (action.type === 'up') {
+  } else if (action.type === 'up') {
     moveCursor({ x: action.x, y: action.y })
     setPressed({ pressed: false })
   }
+
+  scheduleIdleHide()
 }
 
 const api: GhostCursorApi = {
@@ -364,6 +464,31 @@ const api: GhostCursorApi = {
   },
 }
 
-globalThis.__playwriterGhostCursor = api
+if (isTopFrame) {
+  globalThis.__playwriterGhostCursor = api
+
+  // Auto-enable. Defer for early injection (addScriptToEvaluateOnNewDocument)
+  // when DOM isn't ready yet. After hard navigations the cursor re-centers
+  // until the next mouse action arrives.
+  try {
+    if (document.readyState === 'loading') {
+      document.addEventListener(
+        'DOMContentLoaded',
+        () => {
+          try {
+            api.enable()
+          } catch {
+            // Non-fatal — DOM may be in an unexpected state.
+          }
+        },
+        { once: true },
+      )
+    } else {
+      api.enable()
+    }
+  } catch {
+    // Restricted contexts (chrome://, devtools://) — silently skip.
+  }
+}
 
 export {}

package/src/{recording-ghost-cursor.ts → ghost-cursor-controller.ts}

@@ -1,6 +1,9 @@
 /**
- * Encapsulates ghost cursor lifecycle for recording sessions.
- * Keeps onMouseAction chaining/restoration isolated from executor logic.
+ * Always-on ghost cursor controller (Node side).
+ *
+ * Wires page.onMouseAction → applyGhostCursorMouseAction for every page.
+ * Chains with any pre-existing onMouseAction callback. Cursor-apply is
+ * fire-and-forget via a per-page queue so it does not block action completion.
  */
 
 import type { BrowserContext, Page } from '@xmorse/playwright-core'
@@ -11,7 +14,7 @@ import {
   type GhostCursorClientOptions,
 } from './ghost-cursor.js'
 
-interface RecordingGhostCursorLogger {
+interface GhostCursorLogger {
   error: (...args: unknown[]) => void
 }
 
@@ -20,12 +23,13 @@ interface RecordingTargetOptions {
   sessionId?: string
 }
 
-export class RecordingGhostCursorController {
+export class GhostCursorController {
   private readonly previousMouseActionByPage = new WeakMap<Page, Page['onMouseAction']>()
   private readonly cursorApplyQueueByPage = new WeakMap<Page, Promise<void>>()
-  private readonly logger: RecordingGhostCursorLogger
+  private readonly attachedPages = new WeakSet<Page>()
+  private readonly logger: GhostCursorLogger
 
-  constructor(options: { logger: RecordingGhostCursorLogger }) {
+  constructor(options: { logger: GhostCursorLogger }) {
     this.logger = options.logger
   }
 
@@ -53,61 +57,73 @@ export class RecordingGhostCursorController {
     return defaultPage
   }
 
-  async enableForRecording(options: { page: Page }): Promise<void> {
+  /** Wire onMouseAction. Idempotent. */
+  attachToPage(options: { page: Page }): void {
     const { page } = options
 
-    try {
-      await enableGhostCursor({ page })
+    if (this.attachedPages.has(page)) {
+      return
+    }
+    this.attachedPages.add(page)
 
-      if (!this.previousMouseActionByPage.has(page)) {
-        this.previousMouseActionByPage.set(page, page.onMouseAction)
-      }
+    if (!this.previousMouseActionByPage.has(page)) {
+      this.previousMouseActionByPage.set(page, page.onMouseAction)
+    }
+    const previousMouseAction = this.previousMouseActionByPage.get(page)
 
-      const previousMouseAction = this.previousMouseActionByPage.get(page)
-      page.onMouseAction = async (event) => {
+    page.onMouseAction = async (event) => {
+      // Ghost cursor must never crash the main Playwright action (click, move, etc).
+      // Wrap the entire cursor logic in try/catch so errors stay cosmetic.
+      try {
         const pendingCursorApply = this.cursorApplyQueueByPage.get(page) || Promise.resolve()
         const nextCursorApply = pendingCursorApply
           .then(async () => {
             await applyGhostCursorMouseAction({ page, event })
           })
           .catch((error) => {
+            if (page.isClosed()) {
+              return
+            }
             this.logger.error('[playwriter] Failed to apply ghost cursor action', error)
           })
         this.cursorApplyQueueByPage.set(page, nextCursorApply)
+      } catch (error) {
+        this.logger.error('[playwriter] Ghost cursor onMouseAction error (non-fatal)', error)
+      }
 
-        if (!previousMouseAction) {
-          return
-        }
-
-        await previousMouseAction(event)
+      if (!previousMouseAction) {
+        return
       }
-    } catch (error) {
-      page.onMouseAction = this.previousMouseActionByPage.get(page) ?? null
-      this.previousMouseActionByPage.delete(page)
-      this.logger.error('[playwriter] Failed to enable ghost cursor', error)
+      await previousMouseAction(event)
     }
   }
 
-  async disableForRecording(options: { page: Page }): Promise<void> {
+  detachFromPage(options: { page: Page }): void {
     const { page } = options
+    if (!this.attachedPages.has(page)) {
+      return
+    }
+    this.attachedPages.delete(page)
     page.onMouseAction = this.previousMouseActionByPage.get(page) ?? null
     this.previousMouseActionByPage.delete(page)
     this.cursorApplyQueueByPage.delete(page)
-
-    try {
-      await disableGhostCursor({ page })
-    } catch (error) {
-      this.logger.error('[playwriter] Failed to disable ghost cursor', error)
-    }
   }
 
   async show(options: { page: Page; cursorOptions?: GhostCursorClientOptions }): Promise<void> {
-    const { page, cursorOptions } = options
-    await enableGhostCursor({ page, cursorOptions })
+    try {
+      const { page, cursorOptions } = options
+      await enableGhostCursor({ page, cursorOptions })
+    } catch {
+      // Non-fatal — page may be closing or navigating.
+    }
   }
 
   async hide(options: { page: Page }): Promise<void> {
-    const { page } = options
-    await disableGhostCursor({ page })
+    try {
+      const { page } = options
+      await disableGhostCursor({ page })
+    } catch {
+      // Non-fatal — page may be closing or navigating.
+    }
   }
 }