heroshot 0.11.4 → 0.12.1

package/README.md

@@ -28,22 +28,7 @@ npx heroshot
 
 First run opens a browser with a visual picker. Click what you want, name it, done. Screenshots land in `heroshots/`, config saves to `.heroshot/config.json`. Next run regenerates everything headlessly.
 
-<table align="center">
-  <tr>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-desktop-light.png?raw=true" alt="Desktop Light"></td>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-desktop-dark.png?raw=true" alt="Desktop Dark"></td>
-  </tr>
-  <tr>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-tablet-light.png?raw=true" alt="Tablet Light"></td>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-tablet-dark.png?raw=true" alt="Tablet Dark"></td>
-  </tr>
-  <tr>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-mobile-light.png?raw=true" alt="Mobile Light"></td>
-    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-mobile-dark.png?raw=true" alt="Mobile Dark"></td>
-  </tr>
-</table>
-
-<p align="center"><em>6 screenshots from one config entry - always in sync with the live site.</em></p>
+https://github.com/user-attachments/assets/f35600a6-9220-4bd2-a8c6-a6b4ee8a33d9
 
 ## Use in Your Docs
 
@@ -90,6 +75,25 @@ plugins:
 
 One component/macro, all variants - light/dark mode switches automatically, responsive sizes via srcset.
 
+## One Screenshot - All Variants
+
+<table align="center">
+  <tr>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-desktop-light.png?raw=true" alt="Desktop Light"></td>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-desktop-dark.png?raw=true" alt="Desktop Dark"></td>
+  </tr>
+  <tr>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-tablet-light.png?raw=true" alt="Tablet Light"></td>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-tablet-dark.png?raw=true" alt="Tablet Dark"></td>
+  </tr>
+  <tr>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-mobile-light.png?raw=true" alt="Mobile Light"></td>
+    <td><img src="https://github.com/omachala/heroshot/blob/main/docs/public/screenshots/hero-mobile-dark.png?raw=true" alt="Mobile Dark"></td>
+  </tr>
+</table>
+
+<p align="center"><em>6 screenshots from one config entry - always in sync with the live site.</em></p>
+
 ## Learn More
 
 |                     |                                                                       |

package/dist/cli/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as intro, D as setVerbose, E as outro, O as spinner, S as error, T as note, _ as loadConfig, a as launchBrowser, c as generateSessionKey, d as loadSession, f as saveLocalKey, g as getConfigPath, h as ensureHeroshotDirectory, k as verbose, l as getSessionPath, m as sessionExists, n as snippetAction, o as DEFAULT_VIEWPORT, p as saveSession, r as sync, s as EDITOR_DIR, u as loadLocalKey, v as saveConfig, w as log, x as generateUid, y as VIEWPORT_PRESETS } from "../snippet-B1n5AWKH.js";
+import { C as intro, D as setVerbose, E as outro, O as spinner, S as error, T as note, _ as loadConfig, a as launchBrowser, c as generateSessionKey, d as loadSession, f as saveLocalKey, g as getConfigPath, h as ensureHeroshotDirectory, k as verbose, l as getSessionPath, m as sessionExists, n as snippetAction, o as DEFAULT_VIEWPORT, p as saveSession, r as sync, s as EDITOR_DIR, u as loadLocalKey, v as saveConfig, w as log, x as generateUid, y as VIEWPORT_PRESETS } from "../snippet-3pBmpUTB.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
@@ -518,7 +518,9 @@ function buildShotConfig(url, options, existingConfig) {
 		browser: {
 			viewport: getViewport(options, existingConfig),
 			colorScheme: getColorScheme(options, false),
-			deviceScaleFactor: getDeviceScaleFactor(options, existingConfig)
+			deviceScaleFactor: getDeviceScaleFactor(options, existingConfig),
+			reducedMotion: options?.reducedMotion ? "reduce" : existingConfig?.browser?.reducedMotion,
+			userAgent: options?.userAgent ?? existingConfig?.browser?.userAgent
 		},
 		screenshots: [screenshot]
 	};
@@ -703,7 +705,7 @@ program.name("heroshot").description("Define your screenshots once, update them
 	setVerbose(program.opts().verbose ?? false);
 	intro(version);
 });
-program.command("oneshot [url]", { isDefault: true }).description("Capture URL directly, or sync all screenshots from config").option("--selector <selector...>", "CSS selector(s) to capture").option("-o, --output <file>", "Output filename").option("-p, --padding <pixels>", "Padding around element", Number.parseInt).option("-w, --width <pixels>", "Viewport width", Number.parseInt).option("--height <pixels>", "Viewport height", Number.parseInt).option("--mobile", "Use mobile viewport (430x932)").option("--tablet", "Use tablet viewport (768x1024)").option("--desktop", "Use desktop viewport (1280x800)").option("--dark", "Force dark color scheme").option("--light", "Force light color scheme").option("--scale <factor>", "Device scale factor (1, 2, 3)", Number.parseInt).option("--retina", "Use retina scale (2x)").option("-q, --quality <percent>", "JPEG quality (1-100), outputs JPEG", Number.parseInt).option("--viewport-only", "Capture only viewport (not full page)").option("--save", "Save screenshot definition to config").option("--clean", "Delete stale files in output directory").option("--workers <count>", "Number of parallel capture workers", Number.parseInt).option("--headed", "Run browser in headed mode (visible window) for debugging").action(async (url, options) => {
+program.command("oneshot [url]", { isDefault: true }).description("Capture URL directly, or sync all screenshots from config").option("--selector <selector...>", "CSS selector(s) to capture").option("-o, --output <file>", "Output filename").option("-p, --padding <pixels>", "Padding around element", Number.parseInt).option("-w, --width <pixels>", "Viewport width", Number.parseInt).option("--height <pixels>", "Viewport height", Number.parseInt).option("--mobile", "Use mobile viewport (430x932)").option("--tablet", "Use tablet viewport (768x1024)").option("--desktop", "Use desktop viewport (1280x800)").option("--dark", "Force dark color scheme").option("--light", "Force light color scheme").option("--scale <factor>", "Device scale factor (1, 2, 3)", Number.parseInt).option("--retina", "Use retina scale (2x)").option("-q, --quality <percent>", "JPEG quality (1-100), outputs JPEG", Number.parseInt).option("--viewport-only", "Capture only viewport (not full page)").option("--reduced-motion", "Emulate prefers-reduced-motion: reduce (disables animations)").option("--user-agent <string>", "Custom user agent string").option("--save", "Save screenshot definition to config").option("--clean", "Delete stale files in output directory").option("--workers <count>", "Number of parallel capture workers", Number.parseInt).option("--headed", "Run browser in headed mode (visible window) for debugging").action(async (url, options) => {
 	if (!await shotAction(url, options, program.opts())) process.exitCode = 1;
 });
 program.command("config").description("Open browser to add/edit screenshot definitions").option("--reset", "Clear existing session and start fresh").option("--only", "Only run config, skip sync afterwards").option("--light", "Force light mode (prefers-color-scheme: light)").option("--dark", "Force dark mode (prefers-color-scheme: dark)").action(async (options) => {

package/dist/mcp/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { _ as loadConfig, b as screenshotSchema, g as getConfigPath, i as filterScreenshots, r as sync, t as generateSnippets, v as saveConfig, x as generateUid } from "../snippet-B1n5AWKH.js";
+import { _ as loadConfig, b as screenshotSchema, g as getConfigPath, i as filterScreenshots, r as sync, t as generateSnippets, v as saveConfig, x as generateUid } from "../snippet-3pBmpUTB.js";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/{snippet-B1n5AWKH.js → snippet-3pBmpUTB.js}

@@ -87,7 +87,7 @@ function log$1(text) {
 //#region src/actionSchema.ts
 /**
 * Action Schemas — Pre-screenshot actions that run before capturing.
-* Vocabulary aligned with Playwright MCP but uses CSS selectors instead of ephemeral accessibility refs.
+* Uses Playwright locator API, supporting all selector formats: CSS, XPath, text, role, shadow DOM.
 * Reference: https://github.com/microsoft/playwright-mcp
 *
 * ROADMAP extensions (not in Playwright MCP):
@@ -96,7 +96,7 @@ function log$1(text) {
 */
 const clickActionSchema = z.object({
 	type: z.literal("click"),
-	selector: z.string().describe("CSS selector of the element to click"),
+	selector: z.string().describe("Element selector (CSS, XPath, text, role, or shadow DOM)"),
 	doubleClick: z.boolean().optional().describe("Whether to perform a double click"),
 	button: z.enum([
 		"left",
@@ -114,7 +114,7 @@ const clickActionSchema = z.object({
 }).describe("Click an element. Use to dismiss cookie banners, open menus, expand dropdowns.");
 const typeActionSchema = z.object({
 	type: z.literal("type"),
-	selector: z.string().describe("CSS selector of the input element"),
+	selector: z.string().describe("Input element selector (CSS, XPath, text, role, or shadow DOM)"),
 	text: z.string().describe("Text to type into the element"),
 	submit: z.boolean().optional().describe("Whether to press Enter after typing (submit form)"),
 	slowly: z.boolean().optional().describe("Type one character at a time for key handlers"),
@@ -122,12 +122,12 @@ const typeActionSchema = z.object({
 }).describe("Type text into an input, textarea, or contenteditable element.");
 const hoverActionSchema = z.object({
 	type: z.literal("hover"),
-	selector: z.string().describe("CSS selector of the element to hover over"),
+	selector: z.string().describe("Element selector (CSS, XPath, text, role, or shadow DOM)"),
 	timeout: z.number().int().positive().optional().describe("Timeout in milliseconds")
 }).describe("Hover over an element to trigger :hover states, show tooltips, or reveal menus.");
 const selectOptionActionSchema = z.object({
 	type: z.literal("select_option"),
-	selector: z.string().describe("CSS selector of the <select> element"),
+	selector: z.string().describe("Select element selector (CSS, XPath, text, role, or shadow DOM)"),
 	values: z.array(z.string()).describe("Option values to select. Supports multiple."),
 	timeout: z.number().int().positive().optional().describe("Timeout in milliseconds")
 }).describe("Select one or more options in a native <select> dropdown.");
@@ -137,8 +137,8 @@ const pressKeyActionSchema = z.object({
 }).describe("Press a keyboard key or combination. Use to close modals, submit forms, etc.");
 const dragActionSchema = z.object({
 	type: z.literal("drag"),
-	from: z.string().describe("CSS selector of the element to drag"),
-	to: z.string().describe("CSS selector of the drop target"),
+	from: z.string().describe("Selector of the element to drag"),
+	to: z.string().describe("Selector of the drop target"),
 	timeout: z.number().int().positive().optional().describe("Timeout in milliseconds")
 }).describe("Drag an element and drop it onto another.");
 const waitActionSchema = z.object({
@@ -155,12 +155,12 @@ const navigateActionSchema = z.object({
 const evaluateActionSchema = z.object({
 	type: z.literal("evaluate"),
 	function: z.string().describe("JavaScript function: () => { ... } or (el) => { ... }"),
-	selector: z.string().optional().describe("CSS selector of element to pass to function")
+	selector: z.string().optional().describe("Element selector to pass to function")
 }).describe("Run arbitrary JavaScript in the browser context. Escape hatch for DOM manipulation.");
 const fillFormActionSchema = z.object({
 	type: z.literal("fill_form"),
 	fields: z.array(z.object({
-		selector: z.string().describe("CSS selector of the form field"),
+		selector: z.string().describe("Form field selector"),
 		value: z.string().describe("Value to fill. Checkboxes: \"true\"/\"false\""),
 		fieldType: z.enum([
 			"textbox",
@@ -179,7 +179,7 @@ const handleDialogActionSchema = z.object({
 }).describe("Set up handler for browser dialog. Place BEFORE action that triggers dialog.");
 const fileUploadActionSchema = z.object({
 	type: z.literal("file_upload"),
-	selector: z.string().describe("CSS selector of the file input element"),
+	selector: z.string().describe("File input element selector"),
 	paths: z.array(z.string()).describe("File paths to upload (absolute or relative to config)")
 }).describe("Upload one or more files through a file input element.");
 const resizeActionSchema = z.object({
@@ -189,7 +189,7 @@ const resizeActionSchema = z.object({
 }).describe("Resize the browser viewport mid-flow.");
 const hideActionSchema = z.object({
 	type: z.literal("hide"),
-	selectors: z.array(z.string()).describe("CSS selectors of elements to hide (display: none)")
+	selectors: z.array(z.string()).describe("Element selectors to hide (display: none)")
 }).describe("Hide elements from screenshot. Use to remove cookie banners, chat widgets, ads.");
 /** Union of all supported action types. Actions execute sequentially before screenshot. */
 const actionSchema = z.discriminatedUnion("type", [
@@ -260,7 +260,11 @@ const paddingSchema = z.object({
 	bottom: z.number().int().min(0).default(0).describe("Bottom padding in pixels"),
 	left: z.number().int().min(0).default(0).describe("Left padding in pixels")
 });
-/** Scroll position to restore when capturing */
+/**
+* Scroll position saved from editor.
+* NOTE: Currently not used during capture - we use scrollIntoView instead.
+* Kept for potential future use (e.g., precise scroll offset from element).
+*/
 const scrollPositionSchema = z.object({
 	x: z.number().int().min(0).default(0).describe("Horizontal scroll offset in pixels"),
 	y: z.number().int().min(0).default(0).describe("Vertical scroll offset in pixels")
@@ -301,9 +305,9 @@ const screenshotSchema = z.object({
 	id: z.string().min(1).default(generateUid).describe("Unique identifier (auto-generated if omitted)"),
 	name: z.string().min(1).describe("Display name, also used to derive the output filename"),
 	url: z.url().describe("Full URL of the page to capture"),
-	selector: z.string().optional().describe("CSS selector for element capture (omit for full-page)"),
+	selector: z.string().optional().describe("Element selector for capture (omit for full-page). Supports Playwright selector formats: CSS (.class, #id), shadow DOM (host >> child), XPath (xpath=...), text (text=...), role (role=button[name=\"OK\"]), and chained selectors."),
 	padding: paddingSchema.optional().describe("Expand capture area beyond element bounds"),
-	scroll: scrollPositionSchema.optional().describe("Scroll position to restore before capturing"),
+	scroll: scrollPositionSchema.optional().describe("Saved scroll position (not used during capture - scrollIntoView is used instead)"),
 	paddingFill: paddingFillSchema.optional().describe("Background fill for padding area: \"inherit\" (default) shows page content, \"solid\" fills with detected background color"),
 	elementFill: elementFillSchema.optional().describe("Background fill for element area: \"original\" (default) keeps actual background, \"solid\" replaces with detected color"),
 	viewports: z.array(viewportVariantSchema).optional().describe("Viewport variants to generate — preset names (\"desktop\", \"tablet\", \"mobile\") or custom \"WIDTHxHEIGHT\""),
@@ -334,7 +338,9 @@ const shotCliOptionsSchema = z.object({
 	scale: z.number().min(1).max(3).optional(),
 	retina: z.boolean().optional(),
 	quality: z.number().int().min(1).max(100).optional(),
-	viewportOnly: z.boolean().optional()
+	viewportOnly: z.boolean().optional(),
+	reducedMotion: z.boolean().optional(),
+	userAgent: z.string().optional()
 });
 /** CLI command options for URL capture (includes --save and --clean flags) */
 const shotCommandOptionsSchema = shotCliOptionsSchema.extend({
@@ -1040,64 +1046,30 @@ async function executeActions(page, actions) {
 }
 
 //#endregion
-//#region src/sync/browserFunctions.ts
-/**
-* Browser context functions for DOM manipulation.
-* These functions execute in the browser via page.evaluate(fn, ...args).
-*
-* IMPORTANT: These functions run in browser context, not Node.js.
-* They cannot access Node modules or closures - all data must be passed as arguments.
-*
-* NOTE: Most functions that need nested helpers or module-level constants have been
-* moved to use string-based evaluation in their respective wrapper files to avoid
-* tsx __name wrapper issues. Only simple functions are exported here.
-*/
-/**
-* Apply or remove dark mode class on document element.
-*/
-function applyColorScheme(isDark) {
-	document.documentElement.classList.toggle("dark", isDark);
-}
+//#region src/sync/elementFinder.ts
 /**
-* Scroll the window to a specific position.
+* Normalize selector for Playwright compatibility.
+* Converts legacy `>>>` shadow-piercing syntax to Playwright's `>>`.
 */
-function scrollTo({ x, y }) {
-	window.scrollTo(x, y);
+function normalizeSelector(selector) {
+	return selector.replaceAll(">>>", ">>").replaceAll("  ", " ").trim();
 }
-
-//#endregion
-//#region src/sync/elementFinder.ts
 /**
-* Find element using shadow-piercing selector with retries.
-* The >>> syntax pierces shadow DOM boundaries.
+* Find element using Playwright's locator API with retries.
+* Supports all Playwright selector formats including shadow DOM piercing.
+* Automatically scrolls the element into view once found.
 */
 async function findElement(page, selector, maxAttempts = 10, intervalMs = 500) {
+	const normalizedSelector = normalizeSelector(selector);
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		const handle = await page.evaluateHandle(`
-      (() => {
-        const selector = ${JSON.stringify(selector)};
-        const parts = selector.split('>>>').map((part) => part.trim());
-        let current = document;
-
-        for (const part of parts) {
-          if (!part) continue;
-
-          const root = current instanceof Element
-            ? (current.shadowRoot ?? current)
-            : current;
-
-          const found = root.querySelector(part);
-          if (!found) return null;
-
-          current = found;
-        }
-
-        return current instanceof Element ? current : null;
-      })()
-    `);
-		const element = handle.asElement();
-		if (element) return element;
-		await handle.dispose();
+		try {
+			const locator = page.locator(normalizedSelector);
+			const element = await locator.elementHandle({ timeout: intervalMs });
+			if (element) {
+				await locator.scrollIntoViewIfNeeded({ timeout: 5e3 });
+				return element;
+			}
+		} catch {}
 		if (attempt < maxAttempts) await page.waitForTimeout(intervalMs);
 	}
 	return null;
@@ -1169,126 +1141,116 @@ async function removePaddingMask(page) {
 }
 
 //#endregion
-//#region src/sync/pageScripts.ts
+//#region src/sync/browserFunctions.ts
 /**
-* Shared helper function for shadow DOM piercing selectors.
-* Defined as a string to be inlined into page.evaluate() calls.
+* Browser context functions for DOM manipulation.
+* These functions execute in the browser via page.evaluate(fn, ...args).
+*
+* IMPORTANT: These functions run in browser context, not Node.js.
+* They cannot access Node modules or closures - all data must be passed as arguments.
 *
-* WHY STRING-BASED: If this were a regular function inlined into an exported
-* function, esbuild/tsx would wrap it with __name() which doesn't exist in
-* the browser, causing "ReferenceError: __name is not defined".
-*/
-const QUERY_SELECTOR_DEEP = `
-function querySelectorDeep(selector) {
-  var parts = selector.split('>>>').map(function(p) { return p.trim(); });
-  var current = document;
-  for (var i = 0; i < parts.length; i++) {
-    var part = parts[i];
-    if (!part) continue;
-    var root = (current instanceof Element && current.shadowRoot) ? current.shadowRoot : current;
-    var found = root.querySelector(part);
-    if (!found) return null;
-    current = found;
-  }
-  return current instanceof Element ? current : null;
-}
-`;
+* NOTE: Most functions that need nested helpers or module-level constants have been
+* moved to use string-based evaluation in their respective wrapper files to avoid
+* tsx __name wrapper issues. Only simple functions are exported here.
+*/
+/**
+* Apply or remove dark mode class on document element.
+*/
+function applyColorScheme(isDark) {
+	document.documentElement.classList.toggle("dark", isDark);
+}
+
+//#endregion
+//#region src/sync/pageScripts.ts
 /**
 * Store original background and apply new background color to element.
+* Uses Playwright's locator API to support all selector formats.
 */
 async function applyElementBackground(page, selector, bgColor) {
-	await page.evaluate(`(function(selector, bgColor) {
-      ${QUERY_SELECTOR_DEEP}
-      var element = querySelectorDeep(selector);
-      if (!element || !(element instanceof HTMLElement)) return;
-      element.dataset.heroshotOriginalBg = element.style.backgroundColor;
-      element.style.backgroundColor = bgColor;
-    })(${JSON.stringify(selector)}, ${JSON.stringify(bgColor)})`);
+	const locator = page.locator(normalizeSelector(selector));
+	try {
+		await locator.evaluate((element, color) => {
+			if (element instanceof HTMLElement) {
+				element.dataset["heroshotOriginalBg"] = element.style.backgroundColor;
+				element.style.backgroundColor = color;
+			}
+		}, bgColor, { timeout: 5e3 });
+	} catch {}
 }
 /**
 * Restore original background on element.
+* Uses Playwright's locator API to support all selector formats.
 */
 async function restoreElementBackground(page, selector) {
-	await page.evaluate(`(function(selector) {
-      ${QUERY_SELECTOR_DEEP}
-      var element = querySelectorDeep(selector);
-      if (!element || !(element instanceof HTMLElement)) return;
-      var originalBg = element.dataset.heroshotOriginalBg;
-      if (originalBg !== undefined) {
-        element.style.backgroundColor = originalBg;
-        delete element.dataset.heroshotOriginalBg;
-      }
-    })(${JSON.stringify(selector)})`);
+	const locator = page.locator(normalizeSelector(selector));
+	try {
+		await locator.evaluate((element) => {
+			if (element instanceof HTMLElement) {
+				const originalBg = element.dataset["heroshotOriginalBg"];
+				if (originalBg !== void 0) {
+					element.style.backgroundColor = originalBg;
+					delete element.dataset["heroshotOriginalBg"];
+				}
+			}
+		}, { timeout: 5e3 });
+	} catch {}
 }
 /**
 * Apply text overrides to elements on the page.
+* Uses Playwright's locator API for the container, then CSS selectors for relative paths.
 */
 async function applyTextOverrides(page, selector, textOverrides) {
-	await page.evaluate(`(function(containerSelector, overrides) {
-      ${QUERY_SELECTOR_DEEP}
-      var container = querySelectorDeep(containerSelector);
-      if (!container) return;
-      var keys = Object.keys(overrides);
-      for (var i = 0; i < keys.length; i++) {
-        var relativeSelector = keys[i];
-        var newText = overrides[relativeSelector];
-        var textElement = container.querySelector(relativeSelector);
-        if (textElement) {
-          textElement.textContent = newText;
-        }
-      }
-    })(${JSON.stringify(selector)}, ${JSON.stringify(textOverrides)})`);
+	const locator = page.locator(normalizeSelector(selector));
+	try {
+		await locator.evaluate((container, overrides) => {
+			for (const [relativeSelector, newText] of Object.entries(overrides)) {
+				const textElement = container.querySelector(relativeSelector);
+				if (textElement) textElement.textContent = newText;
+			}
+		}, textOverrides, { timeout: 5e3 });
+	} catch {}
 	await page.waitForTimeout(50);
 }
 /**
-* Get background color for an element via page.evaluate.
+* Get background color for an element.
+* Uses Playwright's locator API to support all selector formats.
 */
 async function getElementBackgroundColor(page, selector) {
-	const script = `(function(selector) {
-      ${QUERY_SELECTOR_DEEP}
-
-      function rgbToHex(bgColor) {
-        var rgbMatch = ${"/rgba?" + String.raw`\((\d+),\s*(\d+),\s*(\d+)/`}.exec(bgColor);
-        if (rgbMatch && rgbMatch[1] && rgbMatch[2] && rgbMatch[3]) {
-          var red = parseInt(rgbMatch[1], 10);
-          var green = parseInt(rgbMatch[2], 10);
-          var blue = parseInt(rgbMatch[3], 10);
-          return '#' +
-            red.toString(16).padStart(2, '0') +
-            green.toString(16).padStart(2, '0') +
-            blue.toString(16).padStart(2, '0');
-        }
-        return bgColor;
-      }
-
-      function isOpaqueColor(bgColor) {
-        return Boolean(bgColor && bgColor !== 'transparent' && !bgColor.startsWith('rgba(0, 0, 0, 0)'));
-      }
-
-      var element = querySelectorDeep(selector);
-      if (!element) return '#ffffff';
-
-      var current = element;
-      while (current) {
-        var backgroundColor = getComputedStyle(current).backgroundColor;
-        if (isOpaqueColor(backgroundColor)) {
-          return rgbToHex(backgroundColor);
-        }
-        var root = current.getRootNode();
-        current = (root instanceof ShadowRoot) ? root.host : current.parentElement;
-      }
-
-      var bodyBg = getComputedStyle(document.body).backgroundColor;
-      if (isOpaqueColor(bodyBg)) return rgbToHex(bodyBg);
-
-      var htmlBg = getComputedStyle(document.documentElement).backgroundColor;
-      if (isOpaqueColor(htmlBg)) return rgbToHex(htmlBg);
-
-      return '#ffffff';
-    })(${JSON.stringify(selector)})`;
-	const bgColor = await page.evaluate(script);
-	verbose(`Detected background color: ${bgColor}`);
-	return bgColor;
+	const locator = page.locator(normalizeSelector(selector));
+	try {
+		const bgColor = await locator.evaluate((element) => {
+			function rgbToHex(color) {
+				const rgbMatch = /rgba?\((\d+),\s*(\d+),\s*(\d+)/.exec(color);
+				if (rgbMatch?.[1] && rgbMatch[2] && rgbMatch[3]) {
+					const red = Number.parseInt(rgbMatch[1], 10);
+					const green = Number.parseInt(rgbMatch[2], 10);
+					const blue = Number.parseInt(rgbMatch[3], 10);
+					return "#" + red.toString(16).padStart(2, "0") + green.toString(16).padStart(2, "0") + blue.toString(16).padStart(2, "0");
+				}
+				return color;
+			}
+			function isOpaqueColor(color) {
+				return Boolean(color && color !== "transparent" && !color.startsWith("rgba(0, 0, 0, 0)"));
+			}
+			let current = element;
+			while (current) {
+				const { backgroundColor } = getComputedStyle(current);
+				if (isOpaqueColor(backgroundColor)) return rgbToHex(backgroundColor);
+				const root = current.getRootNode();
+				current = root instanceof ShadowRoot ? root.host : current.parentElement;
+			}
+			const { backgroundColor: bodyBg } = getComputedStyle(document.body);
+			if (isOpaqueColor(bodyBg)) return rgbToHex(bodyBg);
+			const { backgroundColor: htmlBg } = getComputedStyle(document.documentElement);
+			if (isOpaqueColor(htmlBg)) return rgbToHex(htmlBg);
+			return "#ffffff";
+		}, { timeout: 5e3 });
+		verbose(`Detected background color: ${bgColor}`);
+		return bgColor;
+	} catch {
+		verbose("Could not detect background color, using default #ffffff");
+		return "#ffffff";
+	}
 }
 /**
 * Apply dark mode class to document based on color scheme.
@@ -1494,8 +1456,9 @@ const RETRY_DELAYS = [
 ];
 /**
 * Navigate to URL and prepare page for screenshot.
+* Note: Scroll position is handled by findElement which scrolls the element into view.
 */
-async function navigateAndPrepare(page, url, colorScheme, scroll) {
+async function navigateAndPrepare(page, url, colorScheme) {
 	if (colorScheme) await page.emulateMedia({ colorScheme });
 	try {
 		await page.goto(url, {
@@ -1510,13 +1473,6 @@ async function navigateAndPrepare(page, url, colorScheme, scroll) {
 	}
 	if (colorScheme) await applyColorSchemeClass(page, colorScheme);
 	await page.waitForTimeout(2e3);
-	if (scroll) {
-		await page.evaluate(scrollTo, {
-			x: scroll.x,
-			y: scroll.y
-		});
-		await page.waitForTimeout(100);
-	}
 	return { success: true };
 }
 /**
@@ -1543,7 +1499,7 @@ async function capturePageScreenshot(page, outputPath, format, quality, fullPage
 * Capture a single screenshot.
 */
 async function captureScreenshot(page, screenshot, outputDirectory, captureOptions, variant = {}) {
-	const { name, url, selector, padding, scroll, paddingFill, elementFill, textOverrides } = screenshot;
+	const { name, url, selector, padding, paddingFill, elementFill, textOverrides } = screenshot;
 	const { format, quality, fullPage } = captureOptions;
 	const filename = generateScreenshotFilename({
 		name,
@@ -1553,7 +1509,7 @@ async function captureScreenshot(page, screenshot, outputDirectory, captureOptio
 	});
 	const suffix = buildVariantSuffix(variant.viewportName, variant.colorScheme);
 	verbose(`Capturing: ${name}${suffix ? ` (${suffix})` : ""}`);
-	const navResult = await navigateAndPrepare(page, url, variant.colorScheme, scroll);
+	const navResult = await navigateAndPrepare(page, url, variant.colorScheme);
 	if (!navResult.success) return {
 		...navResult,
 		filename
@@ -1740,8 +1696,8 @@ async function captureParallel(options) {
 		captureSpinner.message(`Capturing ${progress.captured}/${progress.total}: ${result.name}`);
 	};
 	const batchPromises = batches.map(async (batch) => limit(async () => executeBatch(batch, outputDirectory, captureOptions, browserOptions, onProgress)));
-	const batchResults = await Promise.all(batchPromises);
-	for (const results of batchResults) allResults.push(...results);
+	const settledResults = await Promise.allSettled(batchPromises);
+	for (const settled of settledResults) if (settled.status === "fulfilled") allResults.push(...settled.value);
 	return allResults;
 }
 
@@ -1918,6 +1874,7 @@ async function executeCapture(context) {
 */
 async function sync(options = {}) {
 	const configPath = options.configPath ?? getConfigPath();
+	if (options.configPath && !existsSync(options.configPath)) throw new Error(`Config file not found: ${options.configPath}`);
 	const config = options.config ?? loadConfig(configPath);
 	if (config.screenshots.length === 0) {
 		warn("No screenshots defined.");