tabwright 1.0.0

package/src/ghost-cursor-controller.ts

@@ -0,0 +1,129 @@
+/**
+ * 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'
+import {
+  applyGhostCursorMouseAction,
+  disableGhostCursor,
+  enableGhostCursor,
+  type GhostCursorClientOptions,
+} from './ghost-cursor.js'
+
+interface GhostCursorLogger {
+  error: (...args: unknown[]) => void
+}
+
+interface RecordingTargetOptions {
+  page?: Page
+  sessionId?: string
+}
+
+export class GhostCursorController {
+  private readonly previousMouseActionByPage = new WeakMap<Page, Page['onMouseAction']>()
+  private readonly cursorApplyQueueByPage = new WeakMap<Page, Promise<void>>()
+  private readonly attachedPages = new WeakSet<Page>()
+  private readonly logger: GhostCursorLogger
+
+  constructor(options: { logger: GhostCursorLogger }) {
+    this.logger = options.logger
+  }
+
+  resolveRecordingTargetPage(options: {
+    context: BrowserContext
+    defaultPage: Page
+    target?: RecordingTargetOptions
+  }): Page {
+    const { context, defaultPage, target } = options
+
+    if (target?.page) {
+      return target.page
+    }
+
+    if (target?.sessionId) {
+      const pageForSession = context.pages().find((candidatePage) => {
+        return candidatePage.sessionId() === target.sessionId
+      })
+
+      if (pageForSession) {
+        return pageForSession
+      }
+    }
+
+    return defaultPage
+  }
+
+  /** Wire onMouseAction. Idempotent. */
+  attachToPage(options: { page: Page }): void {
+    const { page } = options
+
+    if (this.attachedPages.has(page)) {
+      return
+    }
+    this.attachedPages.add(page)
+
+    if (!this.previousMouseActionByPage.has(page)) {
+      this.previousMouseActionByPage.set(page, page.onMouseAction)
+    }
+    const previousMouseAction = this.previousMouseActionByPage.get(page)
+
+    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('[tabwright] Failed to apply ghost cursor action', error)
+          })
+        this.cursorApplyQueueByPage.set(page, nextCursorApply)
+      } catch (error) {
+        this.logger.error('[tabwright] Ghost cursor onMouseAction error (non-fatal)', error)
+      }
+
+      if (!previousMouseAction) {
+        return
+      }
+      await previousMouseAction(event)
+    }
+  }
+
+  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)
+  }
+
+  async show(options: { page: Page; cursorOptions?: GhostCursorClientOptions }): Promise<void> {
+    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> {
+    try {
+      const { page } = options
+      await disableGhostCursor({ page })
+    } catch {
+      // Non-fatal — page may be closing or navigating.
+    }
+  }
+}

package/src/ghost-cursor.ts

@@ -0,0 +1,123 @@
+/**
+ * Node-side ghost cursor helpers.
+ * Injects the browser bundle and forwards mouse action events to the page overlay.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Page, MouseActionEvent } from '@xmorse/playwright-core'
+
+export interface GhostCursorClientOptions {
+  style?: 'minimal' | 'dot' | 'screenstudio'
+  color?: string
+  size?: number
+  zIndex?: number
+  easing?: string
+  minDurationMs?: number
+  maxDurationMs?: number
+  speedPxPerMs?: number
+}
+
+interface GhostCursorBrowserApi {
+  enable: (options?: GhostCursorClientOptions) => void
+  disable: () => void
+  applyMouseAction: (event: MouseActionEvent) => void
+}
+
+let ghostCursorCode: string | null = null
+
+function getGhostCursorCode(): string {
+  if (ghostCursorCode) {
+    return ghostCursorCode
+  }
+
+  const currentDir = path.dirname(fileURLToPath(import.meta.url))
+  const bundlePath = path.join(currentDir, '..', 'dist', 'ghost-cursor-client.js')
+  ghostCursorCode = fs.readFileSync(bundlePath, 'utf-8')
+  return ghostCursorCode
+}
+
+async function ensureGhostCursorInjected(options: { page: Page }): Promise<void> {
+  const { page } = options
+  const hasGhostCursor = await page.evaluate(() => {
+    return Boolean((globalThis as { __playwriterGhostCursor?: unknown }).__playwriterGhostCursor)
+  })
+
+  if (hasGhostCursor) {
+    return
+  }
+
+  const code = getGhostCursorCode()
+  await page.evaluate(code)
+}
+
+export async function enableGhostCursor(options: {
+  page: Page
+  cursorOptions?: GhostCursorClientOptions
+}): Promise<void> {
+  try {
+    const { page, cursorOptions } = options
+    await ensureGhostCursorInjected({ page })
+
+    await page.evaluate(
+      ({ optionsFromNode }) => {
+        const api = (globalThis as { __playwriterGhostCursor?: GhostCursorBrowserApi }).__playwriterGhostCursor
+        api?.enable(optionsFromNode)
+      },
+      { optionsFromNode: cursorOptions },
+    )
+  } catch {
+    // Non-fatal — page may be closed or navigating.
+  }
+}
+
+export async function disableGhostCursor(options: { page: Page }): Promise<void> {
+  try {
+    const { page } = options
+    await page.evaluate(() => {
+      const api = (globalThis as { __playwriterGhostCursor?: GhostCursorBrowserApi }).__playwriterGhostCursor
+      api?.disable()
+    })
+  } catch {
+    // Non-fatal — page may be closed or navigating.
+  }
+}
+
+export async function applyGhostCursorMouseAction(options: {
+  page: Page
+  event: MouseActionEvent
+}): Promise<void> {
+  // Never throw — the cursor is cosmetic and must not break the caller's action.
+  try {
+    const { page, event } = options
+
+    const applied = await page.evaluate(
+      ({ serializedEvent }) => {
+        const api = (globalThis as { __playwriterGhostCursor?: GhostCursorBrowserApi }).__playwriterGhostCursor
+        if (!api) {
+          return false
+        }
+
+        api.applyMouseAction(serializedEvent)
+        return true
+      },
+      { serializedEvent: event },
+    )
+
+    if (applied) {
+      return
+    }
+
+    await ensureGhostCursorInjected({ page })
+    await page.evaluate(
+      ({ serializedEvent }) => {
+        const api = (globalThis as { __playwriterGhostCursor?: GhostCursorBrowserApi }).__playwriterGhostCursor
+        api?.applyMouseAction(serializedEvent)
+      },
+      { serializedEvent: event },
+    )
+  } catch {
+    // Swallow — page may be closed, navigating, or debugger detached.
+  }
+}