@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/chrome-devtools/scripts/performance.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Measure performance metrics and record trace
+ * Usage: node performance.js --url https://example.com [--trace trace.json] [--metrics]
+ */
+import fs from 'node:fs/promises';
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+async function measurePerformance() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    outputError(new Error('--url is required'));
+
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Start tracing if requested
+    if (args.trace) {
+      await page.tracing.start({
+        path: args.trace,
+        categories: [
+          'devtools.timeline',
+          'disabled-by-default-devtools.timeline',
+          'disabled-by-default-devtools.timeline.frame',
+        ],
+      });
+    }
+
+    // Navigate
+    await page.goto(args.url, {
+      waitUntil: 'networkidle2',
+    });
+
+    // Stop tracing
+    if (args.trace) {
+      await page.tracing.stop();
+    }
+
+    // Get performance metrics
+    const metrics = await page.metrics();
+
+    // Get Core Web Vitals
+    const vitals = await page.evaluate(() => {
+      return new Promise((resolve) => {
+        const vitals = {
+          LCP: null,
+          FID: null,
+          CLS: 0,
+          FCP: null,
+          TTFB: null,
+        };
+
+        // LCP
+        try {
+          new PerformanceObserver((list) => {
+            const entries = list.getEntries();
+
+            if (entries.length > 0) {
+              const lastEntry = entries.at(-1);
+
+              vitals.LCP = lastEntry.renderTime || lastEntry.loadTime;
+            }
+          }).observe({ entryTypes: ['largest-contentful-paint'], buffered: true });
+        } catch {}
+
+        // CLS
+        try {
+          new PerformanceObserver((list) => {
+            list.getEntries().forEach((entry) => {
+              if (!entry.hadRecentInput) {
+                vitals.CLS += entry.value;
+              }
+            });
+          }).observe({ entryTypes: ['layout-shift'], buffered: true });
+        } catch {}
+
+        // FCP
+        try {
+          const paintEntries = performance.getEntriesByType('paint');
+          const fcpEntry = paintEntries.find((e) => e.name === 'first-contentful-paint');
+
+          if (fcpEntry) {
+            vitals.FCP = fcpEntry.startTime;
+          }
+        } catch {}
+
+        // TTFB
+        try {
+          const [navigationEntry] = performance.getEntriesByType('navigation');
+
+          if (navigationEntry) {
+            vitals.TTFB = navigationEntry.responseStart - navigationEntry.requestStart;
+          }
+        } catch {}
+
+        // Wait a bit for metrics to stabilize
+        setTimeout(() => resolve(vitals), 1000);
+      });
+    });
+
+    // Get resource timing
+    const resources = await page.evaluate(() => {
+      return performance.getEntriesByType('resource').map((r) => ({
+        name: r.name,
+        type: r.initiatorType,
+        duration: r.duration,
+        size: r.transferSize,
+        startTime: r.startTime,
+      }));
+    });
+
+    const result = {
+      success: true,
+      url: page.url(),
+      metrics: {
+        ...metrics,
+        JSHeapUsedSizeMB: (metrics.JSHeapUsedSize / 1024 / 1024).toFixed(2),
+        JSHeapTotalSizeMB: (metrics.JSHeapTotalSize / 1024 / 1024).toFixed(2),
+      },
+      vitals,
+      resources: {
+        count: resources.length,
+        totalDuration: resources.reduce((sum, r) => sum + r.duration, 0),
+        items: args.resources === 'true' ? resources : undefined,
+      },
+    };
+
+    if (args.trace) {
+      result.trace = args.trace;
+    }
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+measurePerformance();

package/templates/claude/skills/chrome-devtools/scripts/screenshot.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * Take a screenshot
+ * Usage: node screenshot.js --output screenshot.png [--url https://example.com] [--full-page true] [--selector .element] [--max-size 5] [--no-compress]
+ * Supports both CSS and XPath selectors:
+ *   - CSS: node screenshot.js --selector ".main-content" --output page.png
+ *   - XPath: node screenshot.js --selector "//div[@class='main-content']" --output page.png
+ *
+ * Session behavior:
+ *   By default, browser stays running for session persistence
+ *   Use --close true to fully close browser
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+import { parseSelector, getElement, enhanceError } from './lib/selector.js';
+
+/**
+ * Check if Sharp is available
+ */
+let sharp = null;
+
+try {
+  sharp = (await import('sharp')).default;
+} catch {
+  // Sharp not installed, compression disabled
+}
+
+/**
+ * Compress image using Sharp if it exceeds max size
+ * Sharp is 4-5x faster than ImageMagick with lower memory usage
+ * Falls back to no compression if Sharp is not installed
+ * @param {string} filePath - Path to the image file
+ * @param {number} maxSizeMB - Maximum file size in MB (default: 5)
+ * @returns {Promise<{compressed: boolean, originalSize: number, finalSize: number}>}
+ */
+async function compressImageIfNeeded(filePath, maxSizeMB = 5) {
+  const stats = await fs.stat(filePath);
+  const originalSize = stats.size;
+  const maxSizeBytes = maxSizeMB * 1024 * 1024;
+
+  if (originalSize <= maxSizeBytes) {
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+
+  if (!sharp) {
+    console.error('Warning: Sharp not installed. Run npm install to enable automatic compression.');
+
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+
+  try {
+    const ext = path.extname(filePath).toLowerCase();
+    const imageBuffer = await fs.readFile(filePath);
+    const metadata = await sharp(imageBuffer).metadata();
+
+    // First pass: moderate compression
+    let outputBuffer;
+
+    switch (ext) {
+      case '.png': {
+        // PNG: resize to 90% and compress
+        const newWidth = Math.round(metadata.width * 0.9);
+
+        outputBuffer = await sharp(imageBuffer).resize(newWidth).png({ quality: 85, compressionLevel: 9 }).toBuffer();
+
+        break;
+      }
+      case '.jpg':
+      case '.jpeg': {
+        // JPEG: quality 80 with progressive encoding
+        outputBuffer = await sharp(imageBuffer).jpeg({ quality: 80, progressive: true, mozjpeg: true }).toBuffer();
+
+        break;
+      }
+      case '.webp': {
+        // WebP: quality 80
+        outputBuffer = await sharp(imageBuffer).webp({ quality: 80 }).toBuffer();
+
+        break;
+      }
+      default: {
+        // Other formats: convert to JPEG
+        outputBuffer = await sharp(imageBuffer).jpeg({ quality: 80, progressive: true, mozjpeg: true }).toBuffer();
+      }
+    }
+
+    // Second pass: aggressive compression if still too large
+    if (outputBuffer.length > maxSizeBytes) {
+      if (ext === '.png') {
+        const newWidth = Math.round(metadata.width * 0.75);
+
+        outputBuffer = await sharp(outputBuffer).resize(newWidth).png({ quality: 70, compressionLevel: 9 }).toBuffer();
+      } else {
+        outputBuffer = await sharp(outputBuffer).jpeg({ quality: 60, progressive: true, mozjpeg: true }).toBuffer();
+      }
+    }
+
+    // Write compressed image back to file
+    await fs.writeFile(filePath, outputBuffer);
+
+    return { compressed: true, originalSize, finalSize: outputBuffer.length };
+  } catch (error) {
+    console.error('Compression error:', error.message);
+
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+}
+
+async function screenshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.output) {
+    outputError(new Error('--output is required'));
+
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2',
+      });
+    }
+
+    // Ensure output directory exists
+    const outputDir = path.dirname(path.resolve(args.output));
+
+    await fs.mkdir(outputDir, { recursive: true });
+
+    const screenshotOptions = {
+      path: args.output,
+      type: args.format || 'png',
+      fullPage: args['full-page'] === 'true',
+    };
+
+    if (args.quality) {
+      screenshotOptions.quality = Number.parseInt(args.quality);
+    }
+
+    let buffer;
+
+    if (args.selector) {
+      // Parse and validate selector
+      const parsed = parseSelector(args.selector);
+
+      // Get element based on selector type
+      const element = await getElement(page, parsed);
+
+      if (!element) {
+        throw new Error(`Element not found: ${args.selector}`);
+      }
+      buffer = await element.screenshot(screenshotOptions);
+    } else {
+      buffer = await page.screenshot(screenshotOptions);
+    }
+
+    const result = {
+      success: true,
+      output: path.resolve(args.output),
+      size: buffer.length,
+      url: page.url(),
+    };
+
+    // Compress image if needed (unless --no-compress flag is set)
+    if (args['no-compress'] !== 'true') {
+      const maxSize = args['max-size'] ? Number.parseFloat(args['max-size']) : 5;
+      const compressionResult = await compressImageIfNeeded(args.output, maxSize);
+
+      if (compressionResult.compressed) {
+        result.compressed = true;
+        result.originalSize = compressionResult.originalSize;
+        result.size = compressionResult.finalSize;
+        result.compressionRatio = `${((1 - compressionResult.finalSize / compressionResult.originalSize) * 100).toFixed(2)}%`;
+      }
+    }
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    // Enhance error message if selector-related
+    if (args.selector) {
+      const enhanced = enhanceError(error, args.selector);
+
+      outputError(enhanced);
+    } else {
+      outputError(error);
+    }
+    process.exit(1);
+  }
+}
+
+screenshot();

package/templates/claude/skills/chrome-devtools/scripts/select-ref.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Select and interact with elements by ref from ARIA snapshot
+ * Usage: node select-ref.js --ref e5 --action click
+ *        node select-ref.js --ref e10 --action fill --value "text"
+ *        node select-ref.js --ref e3 --action screenshot --output element.png
+ *
+ * Actions:
+ *   click       - Click the element
+ *   fill        - Fill input with --value
+ *   screenshot  - Take screenshot of element
+ *   text        - Get text content
+ *   focus       - Focus the element
+ *   hover       - Hover over element
+ *
+ * Refs are obtained from aria-snapshot.js output (e.g., [ref=e5])
+ *
+ * Session behavior:
+ *   By default, browser stays running for session persistence
+ *   Use --close true to fully close browser
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+async function selectRef() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.ref) {
+    outputError(new Error('--ref is required (e.g., --ref e5)'));
+
+    return;
+  }
+
+  if (!args.action) {
+    outputError(new Error('--action is required (click, fill, screenshot, text, focus, hover)'));
+
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Get element by ref from window.__chromeDevToolsRefs
+    const element = await page.evaluateHandle((ref) => {
+      const refs = window.__chromeDevToolsRefs;
+
+      if (!refs) {
+        throw new Error('No refs available. Run aria-snapshot.js first to generate refs.');
+      }
+      const el = refs.get(ref);
+
+      if (!el) {
+        throw new Error(`Ref "${ref}" not found. Available refs: ${[...refs.keys()].join(', ')}`);
+      }
+
+      return el;
+    }, args.ref);
+
+    const elementHandle = element.asElement();
+
+    if (!elementHandle) {
+      throw new Error(`Could not get element handle for ref "${args.ref}"`);
+    }
+
+    const result = {
+      success: true,
+      ref: args.ref,
+      action: args.action,
+    };
+
+    // Perform action
+    switch (args.action) {
+      case 'click': {
+        await elementHandle.click();
+        result.message = 'Element clicked';
+        break;
+      }
+
+      case 'fill': {
+        if (!args.value && args.value !== '') {
+          throw new Error('--value is required for fill action');
+        }
+        await elementHandle.click({ clickCount: 3 }); // Select all
+        await elementHandle.type(args.value);
+        result.message = 'Element filled';
+        result.value = args.value;
+        break;
+      }
+
+      case 'screenshot': {
+        if (!args.output) {
+          throw new Error('--output is required for screenshot action');
+        }
+        const outputDir = path.dirname(args.output);
+
+        await fs.mkdir(outputDir, { recursive: true });
+        await elementHandle.screenshot({ path: args.output });
+        result.output = path.resolve(args.output);
+        result.message = 'Screenshot saved';
+        break;
+      }
+
+      case 'text': {
+        const text = await page.evaluate((el) => el.textContent?.trim(), elementHandle);
+
+        result.text = text;
+        break;
+      }
+
+      case 'focus': {
+        await elementHandle.focus();
+        result.message = 'Element focused';
+        break;
+      }
+
+      case 'hover': {
+        await elementHandle.hover();
+        result.message = 'Hovering over element';
+        break;
+      }
+
+      default: {
+        throw new Error(`Unknown action: ${args.action}. Valid actions: click, fill, screenshot, text, focus, hover`);
+      }
+    }
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+selectRef();

package/templates/claude/skills/chrome-devtools/scripts/snapshot.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Get DOM snapshot with selectors
+ * Usage: node snapshot.js [--url https://example.com] [--output snapshot.json]
+ */
+import fs from 'node:fs/promises';
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+async function snapshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2',
+      });
+    }
+
+    // Get interactive elements with metadata
+    const elements = await page.evaluate(() => {
+      const interactiveSelectors = [
+        'a[href]',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        '[onclick]',
+        '[role="button"]',
+        '[role="link"]',
+        '[contenteditable]',
+      ];
+
+      const elements = [];
+      const selector = interactiveSelectors.join(', ');
+      const nodes = document.querySelectorAll(selector);
+
+      nodes.forEach((el, index) => {
+        const rect = el.getBoundingClientRect();
+
+        // Generate unique selector
+        let uniqueSelector = '';
+
+        if (el.id) {
+          uniqueSelector = `#${el.id}`;
+        } else if (el.className) {
+          const classes = [...el.classList].join('.');
+
+          uniqueSelector = `${el.tagName.toLowerCase()}.${classes}`;
+        } else {
+          uniqueSelector = el.tagName.toLowerCase();
+        }
+
+        elements.push({
+          index,
+          tagName: el.tagName.toLowerCase(),
+          type: el.type || null,
+          id: el.id || null,
+          className: el.className || null,
+          name: el.name || null,
+          value: el.value || null,
+          text: el.textContent?.trim().slice(0, 100) || null,
+          href: el.href || null,
+          selector: uniqueSelector,
+          xpath: getXPath(el),
+          visible: rect.width > 0 && rect.height > 0,
+          position: {
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height,
+          },
+        });
+      });
+
+      function getXPath(element) {
+        if (element.id) {
+          return `//*[@id="${element.id}"]`;
+        }
+        if (element === document.body) {
+          return '/html/body';
+        }
+        let ix = 0;
+        const siblings = element.parentNode?.childNodes || [];
+
+        for (const sibling of siblings) {
+          if (sibling === element) {
+            return `${getXPath(element.parentNode)}/${element.tagName.toLowerCase()}[${ix + 1}]`;
+          }
+          if (sibling.nodeType === 1 && sibling.tagName === element.tagName) {
+            ix++;
+          }
+        }
+
+        return '';
+      }
+
+      return elements;
+    });
+
+    const result = {
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+      elementCount: elements.length,
+      elements,
+    };
+
+    if (args.output) {
+      await fs.writeFile(args.output, JSON.stringify(result, null, 2));
+      outputJSON({
+        success: true,
+        output: args.output,
+        elementCount: elements.length,
+      });
+    } else {
+      outputJSON(result);
+    }
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+snapshot();

package/templates/claude/skills/chrome-devtools/scripts/ws-debug.js

@@ -0,0 +1,47 @@
+import { getBrowser, getPage, disconnectBrowser, outputJSON } from './lib/browser.js';
+
+async function debugWs() {
+  const browser = await getBrowser();
+  const page = await getPage(browser);
+
+  const logs = [];
+  const wsEvents = [];
+
+  // Capture console
+  page.on('console', (msg) => {
+    logs.push({ type: msg.type(), text: msg.text() });
+  });
+
+  // Monitor WebSocket via CDP
+  const client = await page.createCDPSession();
+
+  await client.send('Network.enable');
+
+  client.on('Network.webSocketCreated', (e) => wsEvents.push({ event: 'created', ...e }));
+  client.on('Network.webSocketWillSendHandshakeRequest', (e) => wsEvents.push({ event: 'handshake', ...e }));
+  client.on('Network.webSocketHandshakeResponseReceived', (e) => wsEvents.push({ event: 'response', ...e }));
+  client.on('Network.webSocketClosed', (e) => wsEvents.push({ event: 'closed', ...e }));
+  client.on('Network.webSocketFrameError', (e) => wsEvents.push({ event: 'error', ...e }));
+
+  await page.goto('http://localhost:5173', { waitUntil: 'networkidle0', timeout: 15_000 });
+
+  // Wait for WS connections
+  await new Promise((r) => setTimeout(r, 5000));
+
+  outputJSON({
+    success: true,
+    url: page.url(),
+    logs: logs.filter(
+      (l) => l.text.toLowerCase().includes('websocket') || l.text.toLowerCase().includes('ws') || l.type === 'error',
+    ),
+    wsEvents,
+  });
+
+  await disconnectBrowser();
+  process.exit(0);
+}
+
+debugWs().catch((error) => {
+  console.error(JSON.stringify({ success: false, error: error.message }));
+  process.exit(1);
+});