playwriter 0.0.29 → 0.0.32

package/dist/styles-api.md

@@ -0,0 +1,117 @@
+# Styles API Reference
+
+The getStylesForLocator function inspects CSS styles applied to an element, similar to browser DevTools "Styles" panel.
+
+## Types
+
+```ts
+import type { CDPSession } from './cdp-session.js';
+import type { Locator } from 'playwright-core';
+export interface StyleSource {
+    url: string;
+    line: number;
+    column: number;
+}
+export type StyleDeclarations = Record<string, string>;
+export interface StyleRule {
+    selector: string;
+    source: StyleSource | null;
+    origin: 'regular' | 'user-agent' | 'injected' | 'inspector';
+    declarations: StyleDeclarations;
+    inheritedFrom: string | null;
+}
+export interface StylesResult {
+    element: string;
+    inlineStyle: StyleDeclarations | null;
+    rules: StyleRule[];
+}
+export declare function getStylesForLocator({ locator, cdp, includeUserAgentStyles, }: {
+    locator: Locator;
+    cdp: CDPSession;
+    includeUserAgentStyles?: boolean;
+}): Promise<StylesResult>;
+export declare function formatStylesAsText(styles: StylesResult): string;
+```
+
+## Examples
+
+```ts
+import { page, getStylesForLocator, formatStylesAsText, console } from './debugger-examples-types.js'
+
+// Example: Get styles for an element and display them
+async function getElementStyles() {
+  const loc = page.locator('.my-button')
+  const styles = await getStylesForLocator({ locator: loc })
+  console.log(formatStylesAsText(styles))
+}
+
+// Example: Inspect computed styles for a specific element
+async function inspectButtonStyles() {
+  const button = page.getByRole('button', { name: 'Submit' })
+  const styles = await getStylesForLocator({ locator: button })
+
+  console.log('Element:', styles.element)
+
+  if (styles.inlineStyle) {
+    console.log('Inline styles:', styles.inlineStyle)
+  }
+
+  for (const rule of styles.rules) {
+    console.log(`${rule.selector}: ${JSON.stringify(rule.declarations)}`)
+    if (rule.source) {
+      console.log(`  Source: ${rule.source.url}:${rule.source.line}`)
+    }
+  }
+}
+
+// Example: Include browser default (user-agent) styles
+async function getStylesWithUserAgent() {
+  const loc = page.locator('input[type="text"]')
+  const styles = await getStylesForLocator({
+    locator: loc,
+    includeUserAgentStyles: true,
+  })
+  console.log(formatStylesAsText(styles))
+}
+
+// Example: Find where a CSS property is defined
+async function findPropertySource() {
+  const loc = page.locator('.card')
+  const styles = await getStylesForLocator({ locator: loc })
+
+  const backgroundRule = styles.rules.find((r) => 'background-color' in r.declarations)
+  if (backgroundRule) {
+    console.log('background-color defined by:', backgroundRule.selector)
+    if (backgroundRule.source) {
+      console.log(`  at ${backgroundRule.source.url}:${backgroundRule.source.line}`)
+    }
+  }
+}
+
+// Example: Check inherited styles
+async function checkInheritedStyles() {
+  const loc = page.locator('.nested-text')
+  const styles = await getStylesForLocator({ locator: loc })
+
+  const inheritedRules = styles.rules.filter((r) => r.inheritedFrom)
+  for (const rule of inheritedRules) {
+    console.log(`Inherited from ${rule.inheritedFrom}: ${rule.selector}`)
+    console.log('  Properties:', rule.declarations)
+  }
+}
+
+// Example: Compare styles between two elements
+async function compareStyles() {
+  const primary = await getStylesForLocator({ locator: page.locator('.btn-primary') })
+  const secondary = await getStylesForLocator({ locator: page.locator('.btn-secondary') })
+
+  console.log('Primary button:')
+  console.log(formatStylesAsText(primary))
+
+  console.log('Secondary button:')
+  console.log(formatStylesAsText(secondary))
+}
+
+export { getElementStyles, inspectButtonStyles, getStylesWithUserAgent, findPropertySource, checkInheritedStyles, compareStyles }
+
+```

package/dist/styles-examples.d.ts

@@ -0,0 +1,8 @@
+declare function getElementStyles(): Promise<void>;
+declare function inspectButtonStyles(): Promise<void>;
+declare function getStylesWithUserAgent(): Promise<void>;
+declare function findPropertySource(): Promise<void>;
+declare function checkInheritedStyles(): Promise<void>;
+declare function compareStyles(): Promise<void>;
+export { getElementStyles, inspectButtonStyles, getStylesWithUserAgent, findPropertySource, checkInheritedStyles, compareStyles };
+//# sourceMappingURL=styles-examples.d.ts.map

package/dist/styles-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles-examples.d.ts","sourceRoot":"","sources":["../src/styles-examples.ts"],"names":[],"mappings":"AAGA,iBAAe,gBAAgB,kBAI9B;AAGD,iBAAe,mBAAmB,kBAgBjC;AAGD,iBAAe,sBAAsB,kBAOpC;AAGD,iBAAe,kBAAkB,kBAWhC;AAGD,iBAAe,oBAAoB,kBASlC;AAGD,iBAAe,aAAa,kBAS3B;AAED,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,CAAA"}

package/dist/styles-examples.js

@@ -0,0 +1,64 @@
+import { page, getStylesForLocator, formatStylesAsText, console } from './debugger-examples-types.js';
+// Example: Get styles for an element and display them
+async function getElementStyles() {
+    const loc = page.locator('.my-button');
+    const styles = await getStylesForLocator({ locator: loc });
+    console.log(formatStylesAsText(styles));
+}
+// Example: Inspect computed styles for a specific element
+async function inspectButtonStyles() {
+    const button = page.getByRole('button', { name: 'Submit' });
+    const styles = await getStylesForLocator({ locator: button });
+    console.log('Element:', styles.element);
+    if (styles.inlineStyle) {
+        console.log('Inline styles:', styles.inlineStyle);
+    }
+    for (const rule of styles.rules) {
+        console.log(`${rule.selector}: ${JSON.stringify(rule.declarations)}`);
+        if (rule.source) {
+            console.log(`  Source: ${rule.source.url}:${rule.source.line}`);
+        }
+    }
+}
+// Example: Include browser default (user-agent) styles
+async function getStylesWithUserAgent() {
+    const loc = page.locator('input[type="text"]');
+    const styles = await getStylesForLocator({
+        locator: loc,
+        includeUserAgentStyles: true,
+    });
+    console.log(formatStylesAsText(styles));
+}
+// Example: Find where a CSS property is defined
+async function findPropertySource() {
+    const loc = page.locator('.card');
+    const styles = await getStylesForLocator({ locator: loc });
+    const backgroundRule = styles.rules.find((r) => 'background-color' in r.declarations);
+    if (backgroundRule) {
+        console.log('background-color defined by:', backgroundRule.selector);
+        if (backgroundRule.source) {
+            console.log(`  at ${backgroundRule.source.url}:${backgroundRule.source.line}`);
+        }
+    }
+}
+// Example: Check inherited styles
+async function checkInheritedStyles() {
+    const loc = page.locator('.nested-text');
+    const styles = await getStylesForLocator({ locator: loc });
+    const inheritedRules = styles.rules.filter((r) => r.inheritedFrom);
+    for (const rule of inheritedRules) {
+        console.log(`Inherited from ${rule.inheritedFrom}: ${rule.selector}`);
+        console.log('  Properties:', rule.declarations);
+    }
+}
+// Example: Compare styles between two elements
+async function compareStyles() {
+    const primary = await getStylesForLocator({ locator: page.locator('.btn-primary') });
+    const secondary = await getStylesForLocator({ locator: page.locator('.btn-secondary') });
+    console.log('Primary button:');
+    console.log(formatStylesAsText(primary));
+    console.log('Secondary button:');
+    console.log(formatStylesAsText(secondary));
+}
+export { getElementStyles, inspectButtonStyles, getStylesWithUserAgent, findPropertySource, checkInheritedStyles, compareStyles };
+//# sourceMappingURL=styles-examples.js.map

package/dist/styles-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles-examples.js","sourceRoot":"","sources":["../src/styles-examples.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "playwriter",
   "description": "",
-  "version": "0.0.29",
+  "version": "0.0.32",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": "https://github.com/remorses/playwriter",
   "scripts": {
-    "build": "rm -rf dist *.tsbuildinfo && mkdir dist && cp src/resource.md src/prompt.md src/debugger-examples.ts dist/ && bun scripts/build-selector-generator.ts && bun scripts/build-bippy.ts && tsc",
+    "build": "rm -rf dist *.tsbuildinfo && mkdir dist && bun scripts/build-selector-generator.ts && bun scripts/build-bippy.ts && tsc && bun scripts/build-resources.ts",
     "prepublishOnly": "pnpm build",
     "watch": "tsc -w",
     "typecheck": "tsc --noEmit",

package/src/cdp-relay.ts

@@ -271,14 +271,17 @@ export async function startPlayWriterCDPRelayServer({ port = 19988, host = '127.
         const contextCreatedPromise = new Promise<void>((resolve) => {
           const handler = ({ event }: { event: CDPEventBase }) => {
             if (event.method === 'Runtime.executionContextCreated' && event.sessionId === sessionId) {
-              clearTimeout(timeout)
-              emitter.off('cdp:event', handler)
-              resolve()
+              const params = event.params as Protocol.Runtime.ExecutionContextCreatedEvent | undefined
+              if (params?.context?.auxData?.isDefault === true) {
+                clearTimeout(timeout)
+                emitter.off('cdp:event', handler)
+                resolve()
+              }
             }
           }
           const timeout = setTimeout(() => {
             emitter.off('cdp:event', handler)
-            logger?.log(chalk.yellow(`IMPORTANT: Runtime.enable timed out waiting for executionContextCreated (sessionId: ${sessionId}). This may cause pages to not be visible immediately.`))
+            logger?.log(chalk.yellow(`IMPORTANT: Runtime.enable timed out waiting for main frame executionContextCreated (sessionId: ${sessionId}). This may cause pages to not be visible immediately.`))
             resolve()
           }, 3000)
           emitter.on('cdp:event', handler)

package/src/debugger-examples-types.ts

@@ -1,10 +1,13 @@
-import type { Page } from 'playwright-core'
+import type { Page, Locator } from 'playwright-core'
 import type { CDPSession } from './cdp-session.js'
 import type { Debugger } from './debugger.js'
 import type { Editor } from './editor.js'
+import type { StylesResult } from './styles.js'
 
 export declare const page: Page
 export declare const getCDPSession: (options: { page: Page }) => Promise<CDPSession>
 export declare const createDebugger: (options: { cdp: CDPSession }) => Debugger
 export declare const createEditor: (options: { cdp: CDPSession }) => Editor
+export declare const getStylesForLocator: (options: { locator: Locator; includeUserAgentStyles?: boolean }) => Promise<StylesResult>
+export declare const formatStylesAsText: (styles: StylesResult) => string
 export declare const console: { log: (...args: unknown[]) => void }

package/src/mcp.ts

@@ -431,72 +431,48 @@ const promptContent =
   fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'prompt.md'), 'utf-8') +
   `\n\nfor debugging internal playwriter errors, check playwriter relay server logs at: ${LOG_FILE_PATH}`
 
-server.resource('debugger-api', 'playwriter://debugger-api', { mimeType: 'text/plain' }, async () => {
+server.resource('debugger-api', 'https://playwriter.dev/resources/debugger-api.md', { mimeType: 'text/plain' }, async () => {
   const packageJsonPath = require.resolve('playwriter/package.json')
-  const distDir = path.join(path.dirname(packageJsonPath), 'dist')
-
-  const debuggerTypes = fs
-    .readFileSync(path.join(distDir, 'debugger.d.ts'), 'utf-8')
-    .replace(/\/\/# sourceMappingURL=.*$/gm, '')
-    .trim()
-  const debuggerExamples = fs.readFileSync(path.join(distDir, 'debugger-examples.ts'), 'utf-8')
+  const packageDir = path.dirname(packageJsonPath)
+  const content = fs.readFileSync(path.join(packageDir, 'dist', 'debugger-api.md'), 'utf-8')
 
   return {
     contents: [
       {
-        uri: 'playwriter://debugger-api',
-        text: dedent`
-          # Debugger API Reference
-
-          ## Types
-
-          \`\`\`ts
-          ${debuggerTypes}
-          \`\`\`
-
-          ## Examples
-
-          \`\`\`ts
-          ${debuggerExamples}
-          \`\`\`
-        `,
+        uri: 'https://playwriter.dev/resources/debugger-api.md',
+        text: content,
         mimeType: 'text/plain',
       },
     ],
   }
 })
 
-server.resource('editor-api', 'playwriter://editor-api', { mimeType: 'text/plain' }, async () => {
+server.resource('editor-api', 'https://playwriter.dev/resources/editor-api.md', { mimeType: 'text/plain' }, async () => {
   const packageJsonPath = require.resolve('playwriter/package.json')
-  const distDir = path.join(path.dirname(packageJsonPath), 'dist')
-
-  const editorTypes = fs
-    .readFileSync(path.join(distDir, 'editor.d.ts'), 'utf-8')
-    .replace(/\/\/# sourceMappingURL=.*$/gm, '')
-    .trim()
-  const editorExamples = fs.readFileSync(path.join(distDir, 'editor-examples.ts'), 'utf-8')
+  const packageDir = path.dirname(packageJsonPath)
+  const content = fs.readFileSync(path.join(packageDir, 'dist', 'editor-api.md'), 'utf-8')
 
   return {
     contents: [
       {
-        uri: 'playwriter://editor-api',
-        text: dedent`
-          # Editor API Reference
-
-          The Editor class provides a Claude Code-like interface for viewing and editing web page scripts at runtime.
-
-          ## Types
-
-          \`\`\`ts
-          ${editorTypes}
-          \`\`\`
+        uri: 'https://playwriter.dev/resources/editor-api.md',
+        text: content,
+        mimeType: 'text/plain',
+      },
+    ],
+  }
+})
 
-          ## Examples
+server.resource('styles-api', 'https://playwriter.dev/resources/styles-api.md', { mimeType: 'text/plain' }, async () => {
+  const packageJsonPath = require.resolve('playwriter/package.json')
+  const packageDir = path.dirname(packageJsonPath)
+  const content = fs.readFileSync(path.join(packageDir, 'dist', 'styles-api.md'), 'utf-8')
 
-          \`\`\`ts
-          ${editorExamples}
-          \`\`\`
-        `,
+  return {
+    contents: [
+      {
+        uri: 'https://playwriter.dev/resources/styles-api.md',
+        text: content,
         mimeType: 'text/plain',
       },
     ],
@@ -839,13 +815,13 @@ server.tool(
 server.tool(
   'reset',
   dedent`
-    Recreates the CDP connection and resets the browser/page/context. Use this when the MCP stops responding, you get connection errors, assertion failures, page closed, or timeout issues.
+    Recreates the CDP connection and resets the browser/page/context. Use this when the MCP stops responding, you get connection errors, if there are no pages in context, assertion failures, page closed, or other issues.
 
     After calling this tool, the page and context variables are automatically updated in the execution environment.
 
-    IMPORTANT: this completely resets the execution context, removing any custom properties you may have added to the global scope AND clearing all keys from the \`state\` object. Only \`page\`, \`context\`, \`state\` (empty), \`console\`, and utility functions will remain.
+    This tools also removes any custom properties you may have added to the global scope AND clearing all keys from the \`state\` object. Only \`page\`, \`context\`, \`state\` (empty), \`console\`, and utility functions will remain.
 
-    if playwright always returns all pages as about:blank urls and evaluate does not work you should aks the user to restart Chrome. This is a known Chrome bug.
+    if playwright always returns all pages as about:blank urls and evaluate does not work you should ask the user to restart Chrome. This is a known Chrome bug.
   `,
   {},
   async () => {

package/src/prompt.md

@@ -95,82 +95,13 @@ you have access to some functions in addition to playwright methods:
     - `page`: the page object to create the session for
     - Returns: `{ send(method, params?), on(event, callback), off(event, callback) }`
     - Example: `const cdp = await getCDPSession({ page }); const metrics = await cdp.send('Page.getLayoutMetrics');`
-- `createDebugger({ cdp })`: creates a Debugger instance for setting breakpoints, stepping, and inspecting variables. Works with browser JS or Node.js (--inspect).
-    - `cdp`: a CDPSession from `getCDPSession`
-    - Methods: `enable()`, `setBreakpoint({ file, line, condition? })`, `deleteBreakpoint({ breakpointId })`, `listBreakpoints()`, `listScripts({ search? })`, `evaluate({ expression })`, `inspectLocalVariables()`, `getLocation()`, `stepOver()`, `stepInto()`, `stepOut()`, `resume()`, `isPaused()`, `setXHRBreakpoint({ url })`, `removeXHRBreakpoint({ url })`, `listXHRBreakpoints()`, `setBlackboxPatterns({ patterns })`, `addBlackboxPattern({ pattern })`, `removeBlackboxPattern({ pattern })`, `listBlackboxPatterns()`
-    - Example:
-      ```js
-      const cdp = await getCDPSession({ page }); const dbg = createDebugger({ cdp }); await dbg.enable();
-      console.log(dbg.listScripts({ search: 'app' }));
-      await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 });
-      // conditional breakpoint - only pause when userId is 123
-      await dbg.setBreakpoint({ file: 'app.js', line: 50, condition: 'userId === 123' });
-      // XHR breakpoint - pause when fetch/XHR URL contains '/api'
-      await dbg.setXHRBreakpoint({ url: '/api' });
-      // blackbox framework code when stepping
-      await dbg.setBlackboxPatterns({ patterns: ['node_modules/'] });
-      // user triggers the code, then:
-      if (dbg.isPaused()) { console.log(await dbg.getLocation()); console.log(await dbg.inspectLocalVariables()); await dbg.resume(); }
-      ```
-- `createEditor({ cdp })`: creates an Editor instance for viewing and live-editing page scripts and CSS stylesheets. Provides a Claude Code-like interface.
-    - `cdp`: a CDPSession from `getCDPSession`
-    - Methods: `enable()`, `list({ pattern? })`, `read({ url, offset?, limit? })`, `edit({ url, oldString, newString, dryRun? })`, `grep({ regex, pattern? })`, `write({ url, content, dryRun? })`
-    - `pattern` parameter: regex to filter URLs (e.g. `/\.js/` for JS files, `/\.css/` for CSS files)
-    - Inline scripts get `inline://` URLs, inline styles get `inline-css://` URLs - use grep() to find them by content
-    - Example:
-      ```js
-      const cdp = await getCDPSession({ page }); const editor = createEditor({ cdp }); await editor.enable();
-      // list all scripts and stylesheets
-      console.log(editor.list());
-      // list only JS files
-      console.log(editor.list({ pattern: /\.js/ }));
-      // list only CSS files
-      console.log(editor.list({ pattern: /\.css/ }));
-      // read a script with line numbers (like Claude Code Read tool)
-      const { content, totalLines } = await editor.read({ url: 'https://example.com/app.js', offset: 0, limit: 50 });
-      console.log(content);
-      // edit a script (like Claude Code Edit tool) - exact string replacement
-      await editor.edit({ url: 'https://example.com/app.js', oldString: 'DEBUG = false', newString: 'DEBUG = true' });
-      // edit CSS
-      await editor.edit({ url: 'https://example.com/styles.css', oldString: 'color: red', newString: 'color: blue' });
-      // search across all scripts (like Grep) - useful for finding inline scripts
-      const matches = await editor.grep({ regex: /myFunction/ });
-      if (matches.length > 0) { await editor.edit({ url: matches[0].url, oldString: 'return false', newString: 'return true' }); }
-      // search only in CSS files
-      const cssMatches = await editor.grep({ regex: /background-color/, pattern: /\.css/ });
-      ```
-- `getStylesForLocator({ locator, includeUserAgentStyles? })`: gets the CSS styles applied to an element, similar to browser DevTools "Styles" panel.
-    - `locator`: a Playwright Locator for the element to inspect
-    - `includeUserAgentStyles`: (optional, default: false) include browser default styles
-    - Returns: `StylesResult` object with:
-      - `element`: string description of the element (e.g. `div#main.container`)
-      - `inlineStyle`: object of `{ property: value }` inline styles, or null
-      - `rules`: array of CSS rules that apply to this element, each with:
-        - `selector`: the CSS selector that matched
-        - `source`: `{ url, line, column }` location in the stylesheet, or null
-        - `origin`: `"regular"` | `"user-agent"` | `"injected"` | `"inspector"`
-        - `declarations`: object of `{ property: value }` (values include `!important` if applicable)
-        - `inheritedFrom`: element description if inherited (e.g. `body`), or null for direct matches
-    - Example:
-      ```js
-      const loc = page.locator('.my-button');
-      const styles = await getStylesForLocator({ locator: loc });
-      console.log(formatStylesAsText(styles));
-      ```
-- `formatStylesAsText(styles)`: formats a `StylesResult` object as human-readable text. Use this to display styles in a readable format.
+- `createDebugger({ cdp })`: creates a Debugger instance for setting breakpoints, stepping, and inspecting variables. Read the `https://playwriter.dev/resources/debugger-api.md` resource for full API docs and examples.
+- `createEditor({ cdp })`: creates an Editor instance for viewing and live-editing page scripts and CSS stylesheets. Read the `https://playwriter.dev/resources/editor-api.md` resource for full API docs and examples.
+- `getStylesForLocator({ locator })`: gets the CSS styles applied to an element, similar to browser DevTools "Styles" panel. Read the `https://playwriter.dev/resources/styles-api.md` resource for full API docs and examples.
 - `getReactSource({ locator })`: gets the React component source location (file, line, column) for an element.
     - `locator`: a Playwright Locator or ElementHandle for the element to inspect
     - Returns: `{ fileName, lineNumber, columnNumber, componentName }` or `null` if not found
-    - **Important**: Only works on **local dev servers** (localhost with Vite, Next.js, CRA in dev mode). Production builds strip source info. The JSX transform must have `development: true` to include `_debugSource`.
-    - Example:
-      ```js
-      const loc = page.locator('.my-component');
-      const source = await getReactSource({ locator: loc });
-      if (source) {
-        console.log(`Component: ${source.componentName}`);
-        console.log(`File: ${source.fileName}:${source.lineNumber}:${source.columnNumber}`);
-      }
-      ```
+    - **Important**: Only works on **local dev servers** (localhost with Vite, Next.js, CRA in dev mode). Production builds strip source info.
 
 example:
 

package/src/styles-examples.ts

@@ -0,0 +1,77 @@
+import { page, getStylesForLocator, formatStylesAsText, console } from './debugger-examples-types.js'
+
+// Example: Get styles for an element and display them
+async function getElementStyles() {
+  const loc = page.locator('.my-button')
+  const styles = await getStylesForLocator({ locator: loc })
+  console.log(formatStylesAsText(styles))
+}
+
+// Example: Inspect computed styles for a specific element
+async function inspectButtonStyles() {
+  const button = page.getByRole('button', { name: 'Submit' })
+  const styles = await getStylesForLocator({ locator: button })
+
+  console.log('Element:', styles.element)
+
+  if (styles.inlineStyle) {
+    console.log('Inline styles:', styles.inlineStyle)
+  }
+
+  for (const rule of styles.rules) {
+    console.log(`${rule.selector}: ${JSON.stringify(rule.declarations)}`)
+    if (rule.source) {
+      console.log(`  Source: ${rule.source.url}:${rule.source.line}`)
+    }
+  }
+}
+
+// Example: Include browser default (user-agent) styles
+async function getStylesWithUserAgent() {
+  const loc = page.locator('input[type="text"]')
+  const styles = await getStylesForLocator({
+    locator: loc,
+    includeUserAgentStyles: true,
+  })
+  console.log(formatStylesAsText(styles))
+}
+
+// Example: Find where a CSS property is defined
+async function findPropertySource() {
+  const loc = page.locator('.card')
+  const styles = await getStylesForLocator({ locator: loc })
+
+  const backgroundRule = styles.rules.find((r) => 'background-color' in r.declarations)
+  if (backgroundRule) {
+    console.log('background-color defined by:', backgroundRule.selector)
+    if (backgroundRule.source) {
+      console.log(`  at ${backgroundRule.source.url}:${backgroundRule.source.line}`)
+    }
+  }
+}
+
+// Example: Check inherited styles
+async function checkInheritedStyles() {
+  const loc = page.locator('.nested-text')
+  const styles = await getStylesForLocator({ locator: loc })
+
+  const inheritedRules = styles.rules.filter((r) => r.inheritedFrom)
+  for (const rule of inheritedRules) {
+    console.log(`Inherited from ${rule.inheritedFrom}: ${rule.selector}`)
+    console.log('  Properties:', rule.declarations)
+  }
+}
+
+// Example: Compare styles between two elements
+async function compareStyles() {
+  const primary = await getStylesForLocator({ locator: page.locator('.btn-primary') })
+  const secondary = await getStylesForLocator({ locator: page.locator('.btn-secondary') })
+
+  console.log('Primary button:')
+  console.log(formatStylesAsText(primary))
+
+  console.log('Secondary button:')
+  console.log(formatStylesAsText(secondary))
+}
+
+export { getElementStyles, inspectButtonStyles, getStylesWithUserAgent, findPropertySource, checkInheritedStyles, compareStyles }

package/dist/debugger-examples.ts

@@ -1,66 +0,0 @@
-import { page, getCDPSession, createDebugger, console } from './debugger-examples-types.js'
-
-// Example: List available scripts and set a breakpoint
-async function listScriptsAndSetBreakpoint() {
-  const cdp = await getCDPSession({ page })
-  const dbg = createDebugger({ cdp })
-  await dbg.enable()
-
-  const scripts = await dbg.listScripts({ search: 'app' })
-  console.log(scripts)
-
-  if (scripts.length > 0) {
-    const bpId = await dbg.setBreakpoint({ file: scripts[0].url, line: 100 })
-    console.log('Breakpoint set:', bpId)
-  }
-}
-
-// Example: Inspect state when paused at a breakpoint
-async function inspectWhenPaused() {
-  const cdp = await getCDPSession({ page })
-  const dbg = createDebugger({ cdp })
-  await dbg.enable()
-
-  if (dbg.isPaused()) {
-    const loc = await dbg.getLocation()
-    console.log('Paused at:', loc.url, 'line', loc.lineNumber)
-    console.log('Source:', loc.sourceContext)
-
-    const vars = await dbg.inspectLocalVariables()
-    console.log('Variables:', vars)
-
-    const result = await dbg.evaluate({ expression: 'myVar.length' })
-    console.log('myVar.length =', result.value)
-
-    await dbg.stepOver()
-  }
-}
-
-// Example: Step through code
-async function stepThroughCode() {
-  const cdp = await getCDPSession({ page })
-  const dbg = createDebugger({ cdp })
-  await dbg.enable()
-
-  await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
-
-  if (dbg.isPaused()) {
-    await dbg.stepOver()
-    await dbg.stepInto()
-    await dbg.stepOut()
-    await dbg.resume()
-  }
-}
-
-// Example: Cleanup all breakpoints
-async function cleanupBreakpoints() {
-  const cdp = await getCDPSession({ page })
-  const dbg = createDebugger({ cdp })
-
-  const breakpoints = dbg.listBreakpoints()
-  for (const bp of breakpoints) {
-    await dbg.deleteBreakpoint({ breakpointId: bp.id })
-  }
-}
-
-export { listScriptsAndSetBreakpoint, inspectWhenPaused, stepThroughCode, cleanupBreakpoints }