playwriter 0.0.63 → 0.0.89

package/src/screen-recording.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Unit tests for fitToAspectRatio — verifies viewport shrink-to-fit
+ * for common screen sizes and aspect ratios.
+ */
+import { describe, test, expect } from 'vitest'
+import { fitToAspectRatio } from './screen-recording.js'
+
+describe('fitToAspectRatio', () => {
+  test('common sizes → 16:9', () => {
+    const ratio = { width: 16, height: 9 }
+
+    // Already 16:9 — no change
+    expect(fitToAspectRatio({ width: 1920, height: 1080 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 1080,
+        "width": 1920,
+      }
+    `)
+    expect(fitToAspectRatio({ width: 1280, height: 720 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 720,
+        "width": 1280,
+      }
+    `)
+
+    // 16:10 (MacBook default) — too tall, shrink height
+    expect(fitToAspectRatio({ width: 1440, height: 900 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 810,
+        "width": 1440,
+      }
+    `)
+    expect(fitToAspectRatio({ width: 1680, height: 1050 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 945,
+        "width": 1680,
+      }
+    `)
+
+    // 4:3 — too tall, shrink height
+    expect(fitToAspectRatio({ width: 1024, height: 768 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 576,
+        "width": 1024,
+      }
+    `)
+
+    // Ultra-wide 21:9 — too wide, shrink width
+    expect(fitToAspectRatio({ width: 2560, height: 1080 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 1080,
+        "width": 1920,
+      }
+    `)
+    expect(fitToAspectRatio({ width: 3440, height: 1440 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 1440,
+        "width": 2560,
+      }
+    `)
+
+    // Square — too tall, shrink height
+    expect(fitToAspectRatio({ width: 1000, height: 1000 }, ratio)).toMatchInlineSnapshot(`
+      {
+        "height": 563,
+        "width": 1000,
+      }
+    `)
+  })
+
+  test('custom aspect ratios', () => {
+    // 4:3
+    expect(fitToAspectRatio({ width: 1920, height: 1080 }, { width: 4, height: 3 })).toMatchInlineSnapshot(`
+      {
+        "height": 1080,
+        "width": 1440,
+      }
+    `)
+
+    // 1:1
+    expect(fitToAspectRatio({ width: 1920, height: 1080 }, { width: 1, height: 1 })).toMatchInlineSnapshot(`
+      {
+        "height": 1080,
+        "width": 1080,
+      }
+    `)
+
+    // 9:16 vertical
+    expect(fitToAspectRatio({ width: 1920, height: 1080 }, { width: 9, height: 16 })).toMatchInlineSnapshot(`
+      {
+        "height": 1080,
+        "width": 608,
+      }
+    `)
+  })
+
+  test('never increases dimensions', () => {
+    const ratio = { width: 16, height: 9 }
+    const sizes = [
+      { width: 800, height: 600 },
+      { width: 1440, height: 900 },
+      { width: 2560, height: 1080 },
+      { width: 1000, height: 1000 },
+    ]
+    for (const size of sizes) {
+      const result = fitToAspectRatio(size, ratio)
+      expect(result.width).toBeLessThanOrEqual(size.width)
+      expect(result.height).toBeLessThanOrEqual(size.height)
+    }
+  })
+})

package/src/screen-recording.ts

@@ -1,14 +1,14 @@
 /**
  * Screen recording utility for playwriter using chrome.tabCapture.
  * Recording happens in the extension context, so it survives page navigation.
- * 
+ *
  * This module communicates with the relay server which forwards commands to the extension.
- * SessionId (pw-tab-X format) is used to identify which tab to record.
+ * sessionId (pw-tab-* format) is used to identify which tab to record.
  */
 
 import os from 'node:os'
 import path from 'node:path'
-import type { Page } from '@xmorse/playwright-core'
+import type { BrowserContext, Page } from '@xmorse/playwright-core'
 import type {
   StartRecordingResult,
   StopRecordingResult,
@@ -16,19 +16,22 @@ import type {
   CancelRecordingResult,
 } from './protocol.js'
 import { EXTENSION_IDS } from './utils.js'
+import { RecordingGhostCursorController } from './recording-ghost-cursor.js'
 
 /**
  * Generate a shell command to quit and restart Chrome with flags that allow automatic tab capture.
  * This enables screen recording without user interaction (clicking extension icon).
- * 
+ *
  * Required flags:
  * - --allowlisted-extension-id=<id> - grants the extension special privileges (one per extension)
  * - --auto-accept-this-tab-capture - auto-accepts tab capture permission requests
  */
 export function getChromeRestartCommand(): string {
   const platform = os.platform()
-  const flags = EXTENSION_IDS.map(id => `--allowlisted-extension-id=${id}`).join(' ') + ' --auto-accept-this-tab-capture'
-  
+  const extensionFlags = EXTENSION_IDS.map((id) => `--allowlisted-extension-id=${id}`).join(' ')
+  // --profile-directory=Default skips the profile picker on startup, preventing Chrome from hanging
+  const flags = `${extensionFlags} --auto-accept-this-tab-capture --profile-directory=Default`
+
   if (platform === 'darwin') {
     return `osascript -e 'quit app "Google Chrome"' && sleep 1 && open -a "Google Chrome" --args ${flags}`
   }
@@ -39,19 +42,45 @@ export function getChromeRestartCommand(): string {
   return `pkill chrome; sleep 1; google-chrome ${flags}`
 }
 
+const DEFAULT_ASPECT_RATIO = { width: 16, height: 9 }
+
+/** Default max recording duration: 15 minutes in milliseconds */
+const DEFAULT_MAX_DURATION_MS = 15 * 60 * 1000
+
+/**
+ * Compute the largest viewport that fits inside `current` at the target aspect ratio.
+ * Never increases width or height beyond current values — only shrinks the
+ * dimension that's "too large" relative to the target ratio.
+ */
+export function fitToAspectRatio(
+  current: { width: number; height: number },
+  ratio: { width: number; height: number } = DEFAULT_ASPECT_RATIO,
+): { width: number; height: number } {
+  const targetRatio = ratio.width / ratio.height
+  const currentRatio = current.width / current.height
+  if (currentRatio > targetRatio) {
+    // Too wide — keep height, shrink width
+    return { width: Math.round(current.height * targetRatio), height: current.height }
+  }
+  // Too tall (or already exact) — keep width, shrink height
+  return { width: current.width, height: Math.round(current.width / targetRatio) }
+}
+
 /**
  * Check if an error is related to missing activeTab permission for recording.
  */
 function isActiveTabPermissionError(error: string): boolean {
-  return error.includes('Extension has not been invoked') || 
-         error.includes('activeTab') ||
-         error.includes('enable recording')
+  return (
+    error.includes('Extension has not been invoked') ||
+    error.includes('activeTab') ||
+    error.includes('enable recording')
+  )
 }
 
 export interface StartRecordingOptions {
   /** Target page to record */
   page: Page
-  /** Session ID (pw-tab-X format) to identify which tab to record */
+  /** CDP tab session ID (pw-tab-* format) to identify which tab to record */
   sessionId?: string
   /** Frame rate (default: 30) */
   frameRate?: number
@@ -65,12 +94,18 @@ export interface StartRecordingOptions {
   outputPath: string
   /** Relay server port (default: 19988) */
   relayPort?: number
+  /** Aspect ratio to fit viewport to before recording (default: { width: 16, height: 9 }).
+   *  Set to null to skip viewport resizing. */
+  aspectRatio?: { width: number; height: number } | null
+  /** Max recording duration in ms (default: 15 min = 900000). Auto-stops recording
+   *  when exceeded to prevent accidentally filling disk. Set to 0 or Infinity to disable. */
+  maxDurationMs?: number
 }
 
 export interface StopRecordingOptions {
   /** Target page that is being recorded */
   page: Page
-  /** Session ID (pw-tab-X format) to identify which tab to stop recording */
+  /** CDP tab session ID (pw-tab-* format) to identify which tab to stop recording */
   sessionId?: string
   /** Relay server port (default: 19988) */
   relayPort?: number
@@ -82,6 +117,178 @@ export interface RecordingState {
   tabId?: number
 }
 
+export interface ExecutionTimestamp {
+  start: number
+  end: number
+}
+
+interface RecordingTargetOptions {
+  page?: Page
+  sessionId?: string
+}
+
+interface CreateRecordingApiOptions {
+  context: BrowserContext
+  defaultPage: Page
+  relayPort: number
+  ghostCursorController: RecordingGhostCursorController
+  onStart: () => void
+  onFinish: () => void
+  getExecutionTimestamps: () => ExecutionTimestamp[]
+}
+
+interface StartRecordingWithDefaultsOptions extends Omit<StartRecordingOptions, 'relayPort'> {}
+interface StopRecordingWithDefaultsOptions extends Omit<StopRecordingOptions, 'relayPort'> {}
+interface IsRecordingWithDefaultsOptions {
+  page?: Page
+  sessionId?: string
+}
+interface CancelRecordingWithDefaultsOptions {
+  page?: Page
+  sessionId?: string
+}
+
+function resolveRecordingTargetPage(options: {
+  context: BrowserContext
+  defaultPage: Page
+  ghostCursorController: RecordingGhostCursorController
+  target?: RecordingTargetOptions
+}): Page {
+  return options.ghostCursorController.resolveRecordingTargetPage({
+    context: options.context,
+    defaultPage: options.defaultPage,
+    target: options.target,
+  })
+}
+
+function withRecordingDefaults<T extends { page?: Page; sessionId?: string }, R>(options: {
+  relayPort: number
+  defaultPage: Page
+  fn: (opts: T & { relayPort: number; sessionId?: string }) => Promise<R>
+}): (input?: T) => Promise<R> {
+  const { relayPort, defaultPage, fn } = options
+  return async (input: T = {} as T) => {
+    const targetPage = input.page || defaultPage
+    const sessionId = input.sessionId || targetPage.sessionId() || undefined
+    return fn({ page: targetPage, sessionId, relayPort, ...input })
+  }
+}
+
+export function createRecordingApi(options: CreateRecordingApiOptions): {
+  start: (opts?: StartRecordingWithDefaultsOptions) => Promise<RecordingState>
+  stop: (opts?: StopRecordingWithDefaultsOptions) => Promise<{ path: string; duration: number; size: number; executionTimestamps: ExecutionTimestamp[] }>
+  isRecording: (opts?: IsRecordingWithDefaultsOptions) => Promise<RecordingState>
+  cancel: (opts?: CancelRecordingWithDefaultsOptions) => Promise<void>
+} {
+  const { context, defaultPage, relayPort, ghostCursorController, onStart, onFinish, getExecutionTimestamps } = options
+
+  // Stores the original viewport before aspect-ratio resize so we can restore on stop/cancel
+  let preRecordingViewport: { width: number; height: number } | null = null
+  // Auto-stop timer to prevent unbounded recordings
+  let maxDurationTimer: ReturnType<typeof setTimeout> | null = null
+
+  const startWithDefaults = withRecordingDefaults<StartRecordingWithDefaultsOptions, RecordingState>({
+    relayPort,
+    defaultPage,
+    fn: startRecording,
+  })
+  const stopWithDefaults = withRecordingDefaults<StopRecordingWithDefaultsOptions, { path: string; duration: number; size: number }>({
+    relayPort,
+    defaultPage,
+    fn: stopRecording,
+  })
+  const isRecordingWithDefaults = async (opts: IsRecordingWithDefaultsOptions = {}): Promise<RecordingState> => {
+    const targetPage = opts.page || defaultPage
+    const sessionId = opts.sessionId || targetPage.sessionId() || undefined
+    return isRecording({ page: targetPage, sessionId, relayPort })
+  }
+
+  const cancelWithDefaults = async (opts: CancelRecordingWithDefaultsOptions = {}): Promise<void> => {
+    const targetPage = opts.page || defaultPage
+    const sessionId = opts.sessionId || targetPage.sessionId() || undefined
+    await cancelRecording({ page: targetPage, sessionId, relayPort })
+  }
+
+  const start = async (opts?: StartRecordingWithDefaultsOptions): Promise<RecordingState> => {
+    const targetPage = resolveRecordingTargetPage({ context, defaultPage, ghostCursorController, target: opts })
+
+    // Resize viewport to target aspect ratio (default 16:9) before recording.
+    // Only shrinks — never increases width or height beyond current values.
+    const aspectRatio = opts?.aspectRatio === undefined ? DEFAULT_ASPECT_RATIO : opts.aspectRatio
+    if (aspectRatio) {
+      const current = targetPage.viewportSize()
+      if (current) {
+        const fitted = fitToAspectRatio(current, aspectRatio)
+        if (fitted.width !== current.width || fitted.height !== current.height) {
+          preRecordingViewport = current
+          await targetPage.setViewportSize(fitted)
+        }
+      }
+    }
+
+    const result = await startWithDefaults(opts)
+    onStart()
+    await ghostCursorController.enableForRecording({ page: targetPage })
+
+    // Schedule auto-stop to prevent unbounded recordings filling disk.
+    // Default 15 min. Set maxDurationMs to 0 or Infinity to disable.
+    const maxMs = opts?.maxDurationMs ?? DEFAULT_MAX_DURATION_MS
+    if (maxMs > 0 && maxMs < Infinity) {
+      maxDurationTimer = setTimeout(() => {
+        maxDurationTimer = null
+        stop(opts ? { page: opts.page, sessionId: opts.sessionId } : undefined).catch(() => {})
+      }, maxMs)
+    }
+
+    return result
+  }
+
+  const clearMaxDurationTimer = (): void => {
+    if (maxDurationTimer) {
+      clearTimeout(maxDurationTimer)
+      maxDurationTimer = null
+    }
+  }
+
+  const restoreViewport = async (targetPage: Page): Promise<void> => {
+    if (!preRecordingViewport) {
+      return
+    }
+    const saved = preRecordingViewport
+    preRecordingViewport = null
+    await targetPage.setViewportSize(saved)
+  }
+
+  const stop = async (
+    opts?: StopRecordingWithDefaultsOptions,
+  ): Promise<{ path: string; duration: number; size: number; executionTimestamps: ExecutionTimestamp[] }> => {
+    clearMaxDurationTimer()
+    const targetPage = resolveRecordingTargetPage({ context, defaultPage, ghostCursorController, target: opts })
+    const result = await stopWithDefaults(opts)
+    const executionTimestamps = [...getExecutionTimestamps()]
+    onFinish()
+    await ghostCursorController.disableForRecording({ page: targetPage })
+    await restoreViewport(targetPage)
+    return { ...result, executionTimestamps }
+  }
+
+  const cancel = async (opts?: CancelRecordingWithDefaultsOptions): Promise<void> => {
+    clearMaxDurationTimer()
+    const targetPage = resolveRecordingTargetPage({ context, defaultPage, ghostCursorController, target: opts })
+    await cancelWithDefaults(opts)
+    onFinish()
+    await ghostCursorController.disableForRecording({ page: targetPage })
+    await restoreViewport(targetPage)
+  }
+
+  return {
+    start,
+    stop,
+    isRecording: isRecordingWithDefaults,
+    cancel,
+  }
+}
+
 /**
  * Start recording the page.
  * The recording is handled by the extension, so it survives page navigation.
@@ -96,34 +303,41 @@ export async function startRecording(options: StartRecordingOptions): Promise<Re
     outputPath,
     relayPort = 19988,
   } = options
-  
+
   // Resolve relative paths to absolute using the caller's cwd.
   // The relay server may have a different cwd, so we must resolve here.
   const absoluteOutputPath = path.resolve(outputPath)
-  
+
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/start`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ sessionId, frameRate, videoBitsPerSecond, audioBitsPerSecond, audio, outputPath: absoluteOutputPath }),
+    body: JSON.stringify({
+      sessionId,
+      frameRate,
+      videoBitsPerSecond,
+      audioBitsPerSecond,
+      audio,
+      outputPath: absoluteOutputPath,
+    }),
   })
 
-  const result = await response.json() as StartRecordingResult
+  const result = (await response.json()) as StartRecordingResult
 
   if (!result.success) {
     const errorMsg = result.error || 'Unknown error'
-    
+
     // If the error is about missing activeTab permission, provide helpful guidance
     if (isActiveTabPermissionError(errorMsg)) {
       const restartCmd = getChromeRestartCommand()
       throw new Error(
         `Failed to start recording: ${errorMsg}\n\n` +
-        `For automated recording, Chrome must be restarted with special flags.\n` +
-        `WARNING: This will close all Chrome windows. Save your work first!\n\n` +
-        `  ${restartCmd}\n\n` +
-        `Or click the Playwriter extension icon on the tab once to grant permission.`
+          `For automated recording, Chrome must be restarted with special flags.\n` +
+          `WARNING: This will close all Chrome windows. Save your work first!\n\n` +
+          `  ${restartCmd}\n\n` +
+          `Or click the Playwriter extension icon on the tab once to grant permission.`,
       )
     }
-    
+
     throw new Error(`Failed to start recording: ${errorMsg}`)
   }
 
@@ -138,7 +352,9 @@ export async function startRecording(options: StartRecordingOptions): Promise<Re
  * Stop recording and save to file.
  * Returns the path to the saved video file.
  */
-export async function stopRecording(options: StopRecordingOptions): Promise<{ path: string; duration: number; size: number }> {
+export async function stopRecording(
+  options: StopRecordingOptions,
+): Promise<{ path: string; duration: number; size: number }> {
   const { sessionId, relayPort = 19988 } = options
 
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/stop`, {
@@ -147,7 +363,7 @@ export async function stopRecording(options: StopRecordingOptions): Promise<{ pa
     body: JSON.stringify({ sessionId }),
   })
 
-  const result = await response.json() as StopRecordingResult
+  const result = (await response.json()) as StopRecordingResult
 
   if (!result.success) {
     throw new Error(`Failed to stop recording: ${result.error}`)
@@ -159,14 +375,19 @@ export async function stopRecording(options: StopRecordingOptions): Promise<{ pa
 /**
  * Check if recording is currently active.
  */
-export async function isRecording(options: { page: Page; sessionId?: string; relayPort?: number }): Promise<RecordingState> {
+export async function isRecording(options: {
+  page: Page
+  sessionId?: string
+  relayPort?: number
+}): Promise<RecordingState> {
   const { sessionId, relayPort = 19988 } = options
 
-  const url = sessionId 
-    ? `http://127.0.0.1:${relayPort}/recording/status?sessionId=${encodeURIComponent(sessionId)}`
-    : `http://127.0.0.1:${relayPort}/recording/status`
-  const response = await fetch(url)
-  const result = await response.json() as IsRecordingResult
+  const url = new URL(`http://127.0.0.1:${relayPort}/recording/status`)
+  if (sessionId) {
+    url.searchParams.set('sessionId', sessionId)
+  }
+  const response = await fetch(url.toString())
+  const result = (await response.json()) as IsRecordingResult
 
   return { isRecording: result.isRecording, startedAt: result.startedAt, tabId: result.tabId }
 }
@@ -174,7 +395,11 @@ export async function isRecording(options: { page: Page; sessionId?: string; rel
 /**
  * Cancel recording without saving.
  */
-export async function cancelRecording(options: { page: Page; sessionId?: string; relayPort?: number }): Promise<void> {
+export async function cancelRecording(options: {
+  page: Page
+  sessionId?: string
+  relayPort?: number
+}): Promise<void> {
   const { sessionId, relayPort = 19988 } = options
 
   const response = await fetch(`http://127.0.0.1:${relayPort}/recording/cancel`, {
@@ -183,7 +408,7 @@ export async function cancelRecording(options: { page: Page; sessionId?: string;
     body: JSON.stringify({ sessionId }),
   })
 
-  const result = await response.json() as CancelRecordingResult
+  const result = (await response.json()) as CancelRecordingResult
 
   if (!result.success) {
     throw new Error(`Failed to cancel recording: ${result.error}`)