tabwright 1.0.0

package/src/package-paths.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export function getInstalledTabwrightPackageDir(): string {
+  const localPackageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+  const localPackageJsonPath = path.join(localPackageDir, 'package.json')
+  if (fs.existsSync(localPackageJsonPath)) {
+    return localPackageDir
+  }
+
+  const packageJsonPath = require.resolve('tabwright/package.json')
+  return path.dirname(packageJsonPath)
+}
+
+export function getBundledExtensionPath(): string {
+  const packageDir = getInstalledTabwrightPackageDir()
+  const candidates = [
+    path.join(packageDir, 'dist', 'extension'),
+    path.join(packageDir, '..', 'extension', 'dist'),
+  ]
+
+  for (const extensionPath of candidates) {
+    const manifestPath = path.join(extensionPath, 'manifest.json')
+    if (fs.existsSync(manifestPath)) {
+      return extensionPath
+    }
+  }
+
+  throw new Error(
+    `Bundled Tabwright extension not found under ${packageDir}. Rebuild or reinstall the tabwright package.`,
+  )
+}
+
+export const getInstalledPlaywriterPackageDir = getInstalledTabwrightPackageDir

package/src/page-markdown.ts

@@ -0,0 +1,240 @@
+/**
+ * Extract page content as markdown using Mozilla Readability.
+ *
+ * This utility injects the Readability library into the page and extracts
+ * the main content, similar to Firefox Reader View.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Page } from '@xmorse/playwright-core'
+import { createSmartDiff } from './diff-utils.js'
+
+export interface PageMarkdownResult {
+  /** Extracted content as plain text (HTML tags stripped) */
+  content: string
+  /** Article title */
+  title: string | null
+  /** Article author/byline */
+  author: string | null
+  /** Article excerpt/description */
+  excerpt: string | null
+  /** Site name */
+  siteName: string | null
+  /** Content language */
+  lang: string | null
+  /** Published time */
+  publishedTime: string | null
+  /** Word count */
+  wordCount: number
+}
+
+export interface GetPageMarkdownOptions {
+  page: Page
+  /** String or regex to filter content (returns matching lines with context) */
+  search?: string | RegExp
+  /** Return diff since last call for this page */
+  showDiffSinceLastCall?: boolean
+}
+
+// Cache for the bundled readability code
+let readabilityCode: string | null = null
+
+function getReadabilityCode(): string {
+  if (readabilityCode) {
+    return readabilityCode
+  }
+  const currentDir = path.dirname(fileURLToPath(import.meta.url))
+  const readabilityPath = path.join(currentDir, '..', 'dist', 'readability.js')
+  readabilityCode = fs.readFileSync(readabilityPath, 'utf-8')
+  return readabilityCode
+}
+
+// Store last snapshots per page for diffing
+const lastMarkdownSnapshots: WeakMap<Page, string> = new WeakMap()
+
+function isRegExp(value: unknown): value is RegExp {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as RegExp).test === 'function' &&
+    typeof (value as RegExp).exec === 'function'
+  )
+}
+
+/**
+ * Extract page content as markdown using Mozilla Readability.
+ *
+ * Injects Readability into the page if not already present, then extracts
+ * the main content. Returns plain text content (no HTML).
+ */
+export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<string> {
+  const { page, search, showDiffSinceLastCall = !search } = options
+
+  // Check if readability is already injected
+  const hasReadability = await page.evaluate(() => !!(globalThis as any).__readability)
+
+  if (!hasReadability) {
+    const code = getReadabilityCode()
+    await page.evaluate(code)
+  }
+
+  // Extract content using Readability
+  const result = (await page.evaluate(() => {
+    const readability = (globalThis as any).__readability
+    if (!readability) {
+      throw new Error('Readability not loaded')
+    }
+
+    // Clone document to avoid modifying the original
+    const documentClone = document.cloneNode(true)
+
+    // Check if page is probably readable
+    if (!readability.isProbablyReaderable(documentClone)) {
+      return {
+        content: document.body?.innerText || '',
+        title: document.title || null,
+        author: null,
+        excerpt: null,
+        siteName: null,
+        lang: document.documentElement?.lang || null,
+        publishedTime: null,
+        wordCount: (document.body?.innerText || '').split(/\s+/).filter(Boolean).length,
+        _notReadable: true,
+      }
+    }
+
+    const article = new readability.Readability(documentClone).parse()
+
+    if (!article) {
+      return {
+        content: document.body?.innerText || '',
+        title: document.title || null,
+        author: null,
+        excerpt: null,
+        siteName: null,
+        lang: document.documentElement?.lang || null,
+        publishedTime: null,
+        wordCount: (document.body?.innerText || '').split(/\s+/).filter(Boolean).length,
+        _notReadable: true,
+      }
+    }
+
+    return {
+      content: article.textContent || '',
+      title: article.title || null,
+      author: article.byline || null,
+      excerpt: article.excerpt || null,
+      siteName: article.siteName || null,
+      lang: article.lang || null,
+      publishedTime: article.publishedTime || null,
+      wordCount: (article.textContent || '').split(/\s+/).filter(Boolean).length,
+    }
+  })) as PageMarkdownResult & { _notReadable?: boolean }
+
+  // Format output
+  const lines: string[] = []
+
+  if (result.title) {
+    lines.push(`# ${result.title}`)
+    lines.push('')
+  }
+
+  const metadata: string[] = []
+  if (result.author) {
+    metadata.push(`Author: ${result.author}`)
+  }
+  if (result.siteName) {
+    metadata.push(`Site: ${result.siteName}`)
+  }
+  if (result.publishedTime) {
+    metadata.push(`Published: ${result.publishedTime}`)
+  }
+  if (metadata.length > 0) {
+    lines.push(metadata.join(' | '))
+    lines.push('')
+  }
+
+  if (result.excerpt && result.excerpt !== result.content.slice(0, result.excerpt.length)) {
+    lines.push(`> ${result.excerpt}`)
+    lines.push('')
+  }
+
+  lines.push(result.content)
+
+  let markdown = lines.join('\n').trim()
+
+  // Sanitize to remove unpaired surrogates that break JSON encoding
+  markdown = markdown.toWellFormed?.() ?? markdown
+
+  // Store snapshot and handle diffing
+  const previousSnapshot = lastMarkdownSnapshots.get(page)
+  lastMarkdownSnapshots.set(page, markdown)
+
+  // Diff defaults off when search is provided, but agent can explicitly enable both
+  if (showDiffSinceLastCall && previousSnapshot) {
+    const diffResult = createSmartDiff({
+      oldContent: previousSnapshot,
+      newContent: markdown,
+      label: 'content',
+    })
+    if (diffResult.type === 'no-change') {
+      return 'No changes since last call. Use showDiffSinceLastCall: false to see full content.'
+    }
+    return diffResult.content
+  }
+
+  // Handle search
+  if (search) {
+    const contentLines = markdown.split('\n')
+    const matchIndices: number[] = []
+
+    for (let i = 0; i < contentLines.length; i++) {
+      const line = contentLines[i]
+      let isMatch = false
+      if (isRegExp(search)) {
+        isMatch = search.test(line)
+      } else {
+        isMatch = line.toLowerCase().includes(search.toLowerCase())
+      }
+
+      if (isMatch) {
+        matchIndices.push(i)
+        if (matchIndices.length >= 10) {
+          break
+        }
+      }
+    }
+
+    if (matchIndices.length === 0) {
+      return 'No matches found'
+    }
+
+    // Collect lines with 5 lines of context above and below each match
+    const CONTEXT_LINES = 5
+    const includedLines = new Set<number>()
+    for (const idx of matchIndices) {
+      const start = Math.max(0, idx - CONTEXT_LINES)
+      const end = Math.min(contentLines.length - 1, idx + CONTEXT_LINES)
+      for (let i = start; i <= end; i++) {
+        includedLines.add(i)
+      }
+    }
+
+    // Build result with separators between non-contiguous sections
+    const sortedIndices = [...includedLines].sort((a, b) => a - b)
+    const resultLines: string[] = []
+    for (let i = 0; i < sortedIndices.length; i++) {
+      const lineIdx = sortedIndices[i]
+      if (i > 0 && sortedIndices[i - 1] !== lineIdx - 1) {
+        resultLines.push('---')
+      }
+      resultLines.push(contentLines[lineIdx])
+    }
+
+    return resultLines.join('\n')
+  }
+
+  return markdown
+}

package/src/performance-examples.ts

@@ -0,0 +1,186 @@
+// Example snippets for profiling website performance with Tabwright and CDP.
+
+import { console, getCDPSession, page } from './debugger-examples-types.js'
+
+type PerfMetrics = {
+  paints: Record<string, number>
+  lcp: number
+  cls: number
+}
+
+type ObservedPerfEntry = {
+  name: string
+  startTime: number
+  duration: number
+  hadRecentInput?: boolean
+  value?: number
+  interactionId?: number
+}
+
+type NavigationTimingEntry = {
+  responseStart: number
+  domContentLoadedEventEnd: number
+  loadEventEnd: number
+}
+
+type LongTaskEntry = {
+  startTime: number
+  duration: number
+}
+
+type EventTimingEntry = {
+  name: string
+  duration: number
+  interactionId: number
+}
+
+// Example: Collect navigation timing and basic web vitals from the current page
+async function collectWebVitals() {
+  await page.evaluate(() => {
+    const metrics: PerfMetrics = {
+      paints: {},
+      lcp: 0,
+      cls: 0,
+    }
+
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwPerfMetrics?: PerfMetrics
+    }
+
+    perfGlobal.__pwPerfMetrics = metrics
+
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as ObservedPerfEntry[]) {
+        metrics.paints[entry.name] = entry.startTime
+      }
+    }).observe({ type: 'paint', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries() as ObservedPerfEntry[]
+      const lastEntry = entries[entries.length - 1]
+      if (!lastEntry) {
+        return
+      }
+      metrics.lcp = lastEntry.startTime
+    }).observe({ type: 'largest-contentful-paint', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as ObservedPerfEntry[]) {
+        if (entry.hadRecentInput) {
+          continue
+        }
+        metrics.cls += entry.value || 0
+      }
+    }).observe({ type: 'layout-shift', buffered: true } as never)
+  })
+
+  await page.reload({ waitUntil: 'domcontentloaded' })
+
+  const report = await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwPerfMetrics?: PerfMetrics
+    }
+    const nav = performance.getEntriesByType('navigation' as never)[0] as unknown as
+      | NavigationTimingEntry
+      | undefined
+    const metrics = perfGlobal.__pwPerfMetrics
+
+    return {
+      ttfb: nav?.responseStart || 0,
+      domContentLoaded: nav?.domContentLoadedEventEnd || 0,
+      load: nav?.loadEventEnd || 0,
+      fcp: metrics?.paints['first-contentful-paint'] || 0,
+      lcp: metrics?.lcp || 0,
+      cls: metrics?.cls || 0,
+    }
+  })
+
+  console.log(report)
+}
+
+// Example: Measure the biggest transferred requests with raw CDP network events
+async function collectHeaviestRequests() {
+  const cdp = await getCDPSession({ page })
+  await cdp.send('Network.enable')
+  await cdp.send('Network.setCacheDisabled', { cacheDisabled: true })
+
+  const responses = new Map<string, { url: string; mimeType: string }>()
+  const finished = new Map<string, number>()
+
+  cdp.on('Network.responseReceived', (event) => {
+    responses.set(event.requestId, {
+      url: event.response.url,
+      mimeType: event.response.mimeType,
+    })
+  })
+
+  cdp.on('Network.loadingFinished', (event) => {
+    finished.set(event.requestId, event.encodedDataLength)
+  })
+
+  await page.reload({ waitUntil: 'domcontentloaded' })
+
+  const largest = [...responses.entries()]
+    .map(([requestId, response]) => {
+      return {
+        url: response.url,
+        mimeType: response.mimeType,
+        bytes: finished.get(requestId) || 0,
+      }
+    })
+    .sort((a, b) => b.bytes - a.bytes)
+    .slice(0, 10)
+
+  console.log(largest)
+}
+
+// Example: Check whether interactivity is blocked by long tasks or slow events
+async function measureInteractivity() {
+  await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwLongTasks?: LongTaskEntry[]
+      __pwEventTimings?: EventTimingEntry[]
+    }
+
+    perfGlobal.__pwLongTasks = []
+    perfGlobal.__pwEventTimings = []
+
+    new PerformanceObserver((list) => {
+      perfGlobal.__pwLongTasks?.push(
+        ...(list.getEntries() as ObservedPerfEntry[]).map((entry) => ({
+          startTime: entry.startTime,
+          duration: entry.duration,
+        })),
+      )
+    }).observe({ type: 'longtask', buffered: true } as never)
+
+    new PerformanceObserver((list) => {
+      perfGlobal.__pwEventTimings?.push(
+        ...(list.getEntries() as ObservedPerfEntry[]).map((entry) => ({
+          name: entry.name,
+          duration: entry.duration,
+          interactionId: entry.interactionId || 0,
+        })),
+      )
+    }).observe({ type: 'event', buffered: true, durationThreshold: 16 } as never)
+  })
+
+  const button = page.getByRole('button').first()
+  await button.click()
+
+  const report = await page.evaluate(() => {
+    const perfGlobal = globalThis as typeof globalThis & {
+      __pwLongTasks?: LongTaskEntry[]
+      __pwEventTimings?: EventTimingEntry[]
+    }
+
+    return {
+      longTasks: (perfGlobal.__pwLongTasks || []).filter((entry) => entry.duration >= 50),
+      events: (perfGlobal.__pwEventTimings || []).filter((entry) => entry.interactionId !== 0),
+    }
+  })
+
+  console.log(report)
+}
+
+export { collectWebVitals, collectHeaviestRequests, measureInteractivity }

package/src/playwright-import.ts

@@ -0,0 +1,59 @@
+/**
+ * Conditional playwright-core import. When patchright mode is enabled via
+ * TABWRIGHT_PATCHRIGHT=1 env var, imports from @playwriter/patchright-core
+ * instead of @xmorse/playwright-core. Both packages expose identical APIs.
+ *
+ * Type imports continue to use @xmorse/playwright-core directly (types are
+ * the same in both packages) so TypeScript resolution works without the
+ * optional patchright dep being installed.
+ */
+
+export type {
+  Page,
+  Frame,
+  Browser,
+  BrowserContext,
+  Locator,
+  FrameLocator,
+  ElementHandle,
+  CDPSession,
+  MouseActionEvent,
+} from '@xmorse/playwright-core'
+
+export type { BrowserType } from '@xmorse/playwright-core'
+
+type Chromium = typeof import('@xmorse/playwright-core').chromium
+
+let _chromium: Chromium | undefined
+
+/**
+ * Returns the chromium BrowserType, loading from patchright-core if enabled.
+ * Caches after first call.
+ */
+export async function getChromium(): Promise<Chromium> {
+  if (_chromium) {
+    return _chromium
+  }
+  if (isPatchrightEnabled()) {
+    try {
+      // Dynamic import — @playwriter/patchright-core is an optional dependency.
+      // Types come from @xmorse/playwright-core (identical API surface).
+      const mod: { chromium: Chromium } = await import('@playwriter/patchright-core' as string)
+      _chromium = mod.chromium
+    } catch (e: unknown) {
+      throw new Error(
+        '@playwriter/patchright-core is not installed. Install it with: pnpm add @playwriter/patchright-core',
+        { cause: e },
+      )
+    }
+  } else {
+    const mod = await import('@xmorse/playwright-core')
+    _chromium = mod.chromium
+  }
+  return _chromium!
+}
+
+export function isPatchrightEnabled(): boolean {
+  const value = process.env.TABWRIGHT_PATCHRIGHT || process.env.PLAYWRITER_PATCHRIGHT
+  return value === '1' || value === 'true'
+}

package/src/popup-relocation.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Tests for auto-relocation of popup windows to tabs.
+ * - Connected source tab → popup gets relocated + auto-attached.
+ * - No source tab connected → popup is left alone.
+ */
+
+import { createMCPClient } from './mcp-client.js'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import {
+  setupTestContext,
+  cleanupTestContext,
+  getExtensionServiceWorker,
+  createSimpleServer,
+  type TestContext,
+  type SimpleServer,
+  js,
+} from './test-utils.js'
+import './test-declarations.js'
+
+const TEST_PORT = 19995
+
+describe('Popup window relocation', () => {
+  let client: Awaited<ReturnType<typeof createMCPClient>>['client']
+  let cleanup: (() => Promise<void>) | null = null
+  let testCtx: TestContext | null = null
+  let htmlServer: SimpleServer | null = null
+
+  beforeAll(async () => {
+    testCtx = await setupTestContext({
+      port: TEST_PORT,
+      tempDirPrefix: 'pw-popup-test-',
+      toggleExtension: true,
+    })
+
+    const result = await createMCPClient({ port: TEST_PORT })
+    client = result.client
+    cleanup = result.cleanup
+
+    htmlServer = await createSimpleServer({
+      routes: {
+        '/opener': `<!doctype html>
+<html>
+  <body>
+    <button id="open-popup" onclick="window.open('/target', '', 'width=400,height=300,popup=1')">Open popup</button>
+  </body>
+</html>`,
+        '/target': `<!doctype html>
+<html>
+  <body>
+    <h1 id="target-heading">Popup target page</h1>
+  </body>
+</html>`,
+      },
+    })
+  }, 600000)
+
+  afterAll(async () => {
+    if (htmlServer) {
+      await htmlServer.close()
+    }
+    await cleanupTestContext(testCtx, cleanup)
+    cleanup = null
+    testCtx = null
+  })
+
+  it('relocates popup window into main browser context as a tab', async () => {
+    if (!htmlServer) throw new Error('html server not initialized')
+    const browserContext = testCtx!.browserContext
+    const serviceWorker = await getExtensionServiceWorker(browserContext)
+
+    await client.callTool({
+      name: 'execute',
+      arguments: {
+        code: js`
+          state.popupTestPage = context.pages().find((p) => p.url() === 'about:blank') ?? (await context.newPage());
+          await state.popupTestPage.goto('${htmlServer.baseUrl}/opener', { waitUntil: 'domcontentloaded' });
+          return { url: state.popupTestPage.url(), pagesBefore: context.pages().length };
+        `,
+      },
+    })
+
+    const clickResult = await client.callTool({
+      name: 'execute',
+      arguments: {
+        code: js`
+          await state.popupTestPage.click('#open-popup');
+          await state.popupTestPage.waitForTimeout(1500);
+          return { pagesAfter: context.pages().length, allUrls: context.pages().map((p) => p.url()) };
+        `,
+      },
+    })
+
+    const clickOutput = (clickResult as any).content[0].text as string
+
+    expect(clickOutput).toContain('/target')
+    expect((clickResult as any).isError).not.toBe(true)
+    expect(clickOutput).toContain('[WARNING] New page opened from current page')
+    expect(clickOutput).not.toContain('Popup window detected')
+    expect(clickOutput).not.toContain('cannot be controlled by playwriter')
+
+    const windowTypes = await serviceWorker.evaluate(async () => {
+      const windows = await chrome.windows.getAll({ populate: false })
+      return windows.map((w) => w.type)
+    })
+    expect(windowTypes).not.toContain('popup')
+    expect(windowTypes).toContain('normal')
+
+    await client.callTool({
+      name: 'execute',
+      arguments: {
+        code: js`
+          const targetPage = context.pages().find((p) => p.url().endsWith('/target'));
+          if (targetPage) { await targetPage.close(); }
+          await state.popupTestPage.close();
+          delete state.popupTestPage;
+        `,
+      },
+    })
+  }, 60000)
+
+  it('leaves popup windows alone when no Tabwright tab is connected', async () => {
+    if (!htmlServer) throw new Error('html server not initialized')
+    const browserContext = testCtx!.browserContext
+    const serviceWorker = await getExtensionServiceWorker(browserContext)
+
+    await serviceWorker.evaluate(async () => {
+      await globalThis.disconnectEverything()
+    })
+    await new Promise((r) => {
+      setTimeout(r, 200)
+    })
+
+    // Drive the browser directly via browserContext (not MCP/extension) so
+    // the opener tab stays unconnected.
+    const unconnectedPage = await browserContext.newPage()
+    await unconnectedPage.goto(`${htmlServer.baseUrl}/opener`, { waitUntil: 'domcontentloaded' })
+    await unconnectedPage.bringToFront()
+    await unconnectedPage.click('#open-popup')
+    // If relocation DID happen, the popup window would be gone by now.
+    await new Promise((r) => {
+      setTimeout(r, 1500)
+    })
+
+    const windowTypes = await serviceWorker.evaluate(async () => {
+      const windows = await chrome.windows.getAll({ populate: false })
+      return windows.map((w) => w.type)
+    })
+    expect(windowTypes).toContain('popup')
+
+    const windowIdsToClose = await serviceWorker.evaluate(async () => {
+      const windows = await chrome.windows.getAll({ populate: false })
+      return windows.filter((w) => w.type === 'popup').map((w) => w.id)
+    })
+    for (const windowId of windowIdsToClose) {
+      if (windowId !== undefined) {
+        await serviceWorker.evaluate(async (id: number) => {
+          await chrome.windows.remove(id)
+        }, windowId)
+      }
+    }
+    await unconnectedPage.close()
+  }, 60000)
+})