heroshot 0.12.0 → 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-BYzU_uSZ.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-BYzU_uSZ.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-BYzU_uSZ.js → snippet-3pBmpUTB.js}

@@ -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")
@@ -303,7 +307,7 @@ const screenshotSchema = z.object({
 	url: z.url().describe("Full URL of the page to capture"),
 	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({
@@ -1039,32 +1045,6 @@ 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);
-}
-/**
-* Scroll the window to a specific position.
-*/
-function scrollTo({ x, y }) {
-	window.scrollTo(x, y);
-}
-
 //#endregion
 //#region src/sync/elementFinder.ts
 /**
@@ -1077,13 +1057,18 @@ function normalizeSelector(selector) {
 /**
 * 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++) {
 		try {
-			const element = await page.locator(normalizedSelector).elementHandle({ timeout: intervalMs });
-			if (element) return element;
+			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);
 	}
@@ -1156,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).
 *
-* 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;
-}
-`;
+* 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);
+}
+
+//#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.
@@ -1481,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, {
@@ -1497,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 };
 }
 /**
@@ -1530,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,
@@ -1540,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