heroshot 0.14.2 → 0.15.0

package/README.md

@@ -30,7 +30,9 @@ npx heroshot
 
 First run opens a browser with a visual editor. Pick elements, adjust padding, style borders, edit text, and add annotations (arrows, rectangles, callouts). Screenshots land in `heroshots/`, config saves to `.heroshot/config.json`. Next run regenerates everything headlessly.
 
-https://github.com/user-attachments/assets/1636d404-1e5f-4151-9aba-d5676ed3ff2a
+<p align="center">
+  <img src="https://github.com/omachala/heroshot/blob/main/assets/video/demo-v0.14.gif?raw=true" alt="Heroshot demo" width="720">
+</p>
 
 ## Use in Your Docs
 

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-B6Lg_Ant.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-Fc-PkcTD.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -65,6 +65,151 @@ function dispatchHighlightJob(options) {
 	} }));
 }
 
+//#endregion
+//#region src/browser/toConfigScreenshot.ts
+/**
+* Convert ScreenshotData to Screenshot for config.
+* Filename is derived from name at sync time - not stored in config.
+*/
+function toConfigScreenshot(data) {
+	return {
+		id: data.id,
+		name: data.name,
+		url: data.url,
+		selector: data.selector,
+		...data.padding && { padding: {
+			top: Math.round(data.padding.top),
+			right: Math.round(data.padding.right),
+			bottom: Math.round(data.padding.bottom),
+			left: Math.round(data.padding.left)
+		} },
+		...data.scroll && { scroll: data.scroll },
+		...data.paddingFill && { paddingFill: data.paddingFill },
+		...data.paddingColor && { paddingColor: data.paddingColor },
+		...data.elementFill && { elementFill: data.elementFill },
+		...data.elementColor && { elementColor: data.elementColor },
+		...data.textOverrides && Object.keys(data.textOverrides).length > 0 && { textOverrides: data.textOverrides },
+		...data.annotations && data.annotations.length > 0 && { annotations: data.annotations },
+		...data.borderWidth && { borderWidth: data.borderWidth },
+		...data.borderColor && { borderColor: data.borderColor },
+		...data.borderRadius && { borderRadius: data.borderRadius }
+	};
+}
+
+//#endregion
+//#region src/browser/saveCurrentConfig.ts
+/**
+* Save current screenshot and browser settings state to config file.
+*/
+function saveCurrentConfig(configPath, allScreenshots, browserSettings, hiddenElements) {
+	const config = loadConfig(configPath);
+	config.screenshots = allScreenshots.map(toConfigScreenshot);
+	if (browserSettings) {
+		config.browser = {
+			...config.browser,
+			viewport: browserSettings.viewport,
+			...browserSettings.colorScheme && { colorScheme: browserSettings.colorScheme },
+			...browserSettings.deviceScaleFactor && { deviceScaleFactor: browserSettings.deviceScaleFactor }
+		};
+		if (browserSettings.outputDirectory) config.outputDirectory = browserSettings.outputDirectory;
+		if (browserSettings.outputFormat) config.outputFormat = browserSettings.outputFormat;
+		else delete config.outputFormat;
+		if (browserSettings.jpegQuality && browserSettings.outputFormat === "jpeg") config.jpegQuality = browserSettings.jpegQuality;
+		if (browserSettings.workers) config.workers = browserSettings.workers;
+		else delete config.workers;
+	}
+	if (hiddenElements && Object.keys(hiddenElements).length > 0) config.hiddenElements = hiddenElements;
+	else delete config.hiddenElements;
+	saveConfig(configPath, config);
+	verbose("Config saved");
+}
+
+//#endregion
+//#region src/browser/handleEvent.ts
+function createEventHandler(state, browser, context) {
+	const save = () => saveCurrentConfig(state.configPath, state.allScreenshots, state.updatedBrowserSettings, state.hiddenElements);
+	return (event) => {
+		switch (event.type) {
+			case "screenshot-added":
+				state.allScreenshots.push(event.data);
+				verbose(`Added: ${event.data.name}`);
+				save();
+				break;
+			case "screenshot-updated": {
+				const index = state.allScreenshots.findIndex(({ id }) => id === event.data.id);
+				if (index !== -1) {
+					state.allScreenshots[index] = event.data;
+					verbose(`Updated: ${event.data.name}`);
+					save();
+				}
+				break;
+			}
+			case "screenshot-removed": {
+				const index = state.allScreenshots.findIndex(({ id }) => id === event.id);
+				if (index !== -1) {
+					const [removed] = state.allScreenshots.splice(index, 1);
+					verbose(`Removed: ${removed?.name ?? event.id}`);
+					save();
+				}
+				break;
+			}
+			case "screenshot-selected": {
+				const [currentPage] = context.pages();
+				if (!currentPage) break;
+				state.selectedId = event.id;
+				state.sidebarExpanded = true;
+				if (currentPage.url() === event.url) {
+					state.pendingJob = {
+						type: "highlight",
+						selector: event.selector,
+						screenshotId: event.id
+					};
+					currentPage.evaluate(dispatchHighlightJob, {
+						selector: event.selector,
+						screenshotId: event.id
+					}).catch(() => {});
+				} else {
+					state.pendingJob = {
+						type: "navigate-and-highlight",
+						url: event.url,
+						selector: event.selector,
+						screenshotId: event.id
+					};
+					currentPage.goto(event.url, { waitUntil: "domcontentloaded" }).catch(() => {});
+				}
+				break;
+			}
+			case "settings-updated":
+				state.updatedBrowserSettings = event.data;
+				verbose(`Settings updated: ${JSON.stringify(event.data)}`);
+				save();
+				break;
+			case "hidden-elements-updated": {
+				const { domain, selectors } = event;
+				state.hiddenElements = selectors.length === 0 ? Object.fromEntries(Object.entries(state.hiddenElements).filter(([k]) => k !== domain)) : {
+					...state.hiddenElements,
+					[domain]: selectors
+				};
+				verbose(`Hidden elements updated for ${domain}: ${selectors.length} selectors`);
+				save();
+				break;
+			}
+			case "job-complete":
+				state.pendingJob = null;
+				break;
+			case "done":
+				(async () => {
+					try {
+						saveSession(await context.storageState(), state.sessionKey);
+						verbose("Session saved");
+					} catch {}
+					await browser.close();
+				})();
+				break;
+		}
+	};
+}
+
 //#endregion
 //#region src/browser/schema.ts
 /**
@@ -118,7 +263,11 @@ const browserSettingsSchema = z.object({
 		height: z.number()
 	}),
 	colorScheme: z.enum(["light", "dark"]).optional(),
-	deviceScaleFactor: z.number().optional()
+	deviceScaleFactor: z.number().optional(),
+	outputDirectory: z.string().optional(),
+	outputFormat: z.enum(["png", "jpeg"]).optional(),
+	jpegQuality: z.number().int().min(1).max(100).optional(),
+	workers: z.number().int().min(1).optional()
 });
 /** Schema for toolbar events (discriminated union) */
 const toolbarEventSchema = z.discriminatedUnion("type", [
@@ -144,6 +293,11 @@ const toolbarEventSchema = z.discriminatedUnion("type", [
 		type: z.literal("settings-updated"),
 		data: browserSettingsSchema
 	}),
+	z.object({
+		type: z.literal("hidden-elements-updated"),
+		domain: z.string(),
+		selectors: z.array(z.string())
+	}),
 	z.object({ type: z.literal("job-complete") }),
 	z.object({ type: z.literal("done") })
 ]);
@@ -202,7 +356,7 @@ async function injectToolbar(page, options) {
 	}
 }
 async function doInjectToolbar(page, options) {
-	const { screenshots, pendingJob, selectedId, sidebarExpanded, onEvent } = options;
+	const { screenshots, settings, pendingJob, selectedId, sidebarExpanded, hiddenElements, onEvent } = options;
 	if (!exposedPages.has(page)) {
 		await page.exposeFunction("__heroshotEmit", (eventJson) => {
 			onEvent(toolbarEventSchema.parse(JSON.parse(eventJson)));
@@ -214,14 +368,16 @@ async function doInjectToolbar(page, options) {
 		return;
 	}
 	const scriptContent = readFileSync(`${EDITOR_DIR}/dist/editor.js`, "utf8");
-	await page.evaluate(`(function(screenshots, pendingJob, selectedId, sidebarExpanded, scriptContent) {
+	await page.evaluate(`(function(screenshots, settings, pendingJob, selectedId, sidebarExpanded, hiddenElements, scriptContent) {
       // Initialize __heroshot global namespace
       globalThis.__heroshot = {
         initialized: false,
         screenshots: screenshots,
+        settings: settings,
         pendingJob: pendingJob,
         selectedId: selectedId,
         sidebarExpanded: sidebarExpanded,
+        hiddenElements: hiddenElements,
         // This emit function is why we use string evaluation.
         // As a nested function property, it would get __name() wrapped
         // if we used a typed function approach.
@@ -235,56 +391,7 @@ async function doInjectToolbar(page, options) {
       var script = document.createElement('script');
       script.textContent = scriptContent;
       document.body.appendChild(script);
-    })(${JSON.stringify(screenshots)}, ${JSON.stringify(pendingJob)}, ${JSON.stringify(selectedId)}, ${JSON.stringify(sidebarExpanded)}, ${JSON.stringify(scriptContent)})`);
-}
-
-//#endregion
-//#region src/browser/toConfigScreenshot.ts
-/**
-* Convert ScreenshotData to Screenshot for config.
-* Filename is derived from name at sync time - not stored in config.
-*/
-function toConfigScreenshot(data) {
-	return {
-		id: data.id,
-		name: data.name,
-		url: data.url,
-		selector: data.selector,
-		...data.padding && { padding: {
-			top: Math.round(data.padding.top),
-			right: Math.round(data.padding.right),
-			bottom: Math.round(data.padding.bottom),
-			left: Math.round(data.padding.left)
-		} },
-		...data.scroll && { scroll: data.scroll },
-		...data.paddingFill && { paddingFill: data.paddingFill },
-		...data.paddingColor && { paddingColor: data.paddingColor },
-		...data.elementFill && { elementFill: data.elementFill },
-		...data.elementColor && { elementColor: data.elementColor },
-		...data.textOverrides && Object.keys(data.textOverrides).length > 0 && { textOverrides: data.textOverrides },
-		...data.annotations && data.annotations.length > 0 && { annotations: data.annotations },
-		...data.borderWidth && { borderWidth: data.borderWidth },
-		...data.borderColor && { borderColor: data.borderColor },
-		...data.borderRadius && { borderRadius: data.borderRadius }
-	};
-}
-
-//#endregion
-//#region src/browser/saveCurrentConfig.ts
-/**
-* Save current screenshot and browser settings state to config file.
-*/
-function saveCurrentConfig(configPath, allScreenshots, browserSettings) {
-	const config = loadConfig(configPath);
-	config.screenshots = allScreenshots.map(toConfigScreenshot);
-	if (browserSettings) config.browser = {
-		...config.browser,
-		viewport: browserSettings.viewport,
-		...browserSettings.colorScheme && { colorScheme: browserSettings.colorScheme },
-		...browserSettings.deviceScaleFactor && { deviceScaleFactor: browserSettings.deviceScaleFactor }
-	};
-	saveConfig(configPath, config);
-	verbose("Config saved");
+    })(${JSON.stringify(screenshots)}, ${JSON.stringify(settings)}, ${JSON.stringify(pendingJob)}, ${JSON.stringify(selectedId)}, ${JSON.stringify(sidebarExpanded)}, ${JSON.stringify(hiddenElements)}, ${JSON.stringify(scriptContent)})`);
 }
 
 //#endregion
@@ -311,12 +418,24 @@ async function setup(options = {}) {
 		}
 	}
 	const allScreenshots = configToScreenshotData(config.screenshots);
-	let pendingJob = null;
-	let selectedId = null;
-	let sidebarExpanded = false;
-	let updatedBrowserSettings = null;
-	const save = () => {
-		saveCurrentConfig(configPath, allScreenshots, updatedBrowserSettings);
+	const initialSettings = {
+		viewport,
+		...options.colorScheme && { colorScheme: options.colorScheme },
+		...config.browser?.deviceScaleFactor && { deviceScaleFactor: config.browser.deviceScaleFactor },
+		outputDirectory: config.outputDirectory,
+		outputFormat: config.outputFormat,
+		jpegQuality: config.jpegQuality,
+		workers: config.workers
+	};
+	const browserState = {
+		allScreenshots,
+		pendingJob: null,
+		selectedId: null,
+		sidebarExpanded: false,
+		updatedBrowserSettings: null,
+		hiddenElements: config.hiddenElements ?? {},
+		configPath,
+		sessionKey
 	};
 	const { browser, context } = await launchBrowser({
 		headless: false,
@@ -325,88 +444,22 @@ async function setup(options = {}) {
 		colorScheme: options.colorScheme
 	});
 	setupSpinner.stop("Browser ready");
-	const handleEvent = (event) => {
-		switch (event.type) {
-			case "screenshot-added":
-				allScreenshots.push(event.data);
-				verbose(`Added: ${event.data.name}`);
-				save();
-				break;
-			case "screenshot-updated": {
-				const index = allScreenshots.findIndex(({ id }) => id === event.data.id);
-				if (index !== -1) {
-					allScreenshots[index] = event.data;
-					verbose(`Updated: ${event.data.name}`);
-					save();
-				}
-				break;
-			}
-			case "screenshot-removed": {
-				const index = allScreenshots.findIndex(({ id }) => id === event.id);
-				if (index !== -1) {
-					const [removed] = allScreenshots.splice(index, 1);
-					verbose(`Removed: ${removed?.name ?? event.id}`);
-					save();
-				}
-				break;
-			}
-			case "screenshot-selected": {
-				const [currentPage] = context.pages();
-				if (!currentPage) break;
-				selectedId = event.id;
-				sidebarExpanded = true;
-				if (currentPage.url() === event.url) {
-					pendingJob = {
-						type: "highlight",
-						selector: event.selector,
-						screenshotId: event.id
-					};
-					currentPage.evaluate(dispatchHighlightJob, {
-						selector: event.selector,
-						screenshotId: event.id
-					}).catch(() => {});
-				} else {
-					pendingJob = {
-						type: "navigate-and-highlight",
-						url: event.url,
-						selector: event.selector,
-						screenshotId: event.id
-					};
-					currentPage.goto(event.url, { waitUntil: "domcontentloaded" }).catch(() => {});
-				}
-				break;
-			}
-			case "settings-updated":
-				updatedBrowserSettings = event.data;
-				verbose(`Settings updated: ${JSON.stringify(event.data)}`);
-				save();
-				break;
-			case "job-complete":
-				pendingJob = null;
-				break;
-			case "done":
-				(async () => {
-					try {
-						saveSession(await context.storageState(), sessionKey);
-						verbose("Session saved");
-					} catch {}
-					await browser.close();
-				})();
-				break;
-		}
-	};
+	const handleEvent = createEventHandler(browserState, browser, context);
+	const injectOptions = () => ({
+		screenshots: browserState.allScreenshots,
+		settings: initialSettings,
+		pendingJob: browserState.pendingJob,
+		selectedId: browserState.selectedId,
+		sidebarExpanded: browserState.sidebarExpanded,
+		hiddenElements: browserState.hiddenElements,
+		onEvent: handleEvent
+	});
 	const setupPage = (page) => {
 		page.on("domcontentloaded", async () => {
 			const url = page.url();
 			if (!url.startsWith("http")) return;
 			try {
-				await injectToolbar(page, {
-					screenshots: allScreenshots,
-					pendingJob,
-					selectedId,
-					sidebarExpanded,
-					onEvent: handleEvent
-				});
+				await injectToolbar(page, injectOptions());
 				verbose(`Toolbar injected on ${url}`);
 			} catch (error) {
 				verbose(`Toolbar injection failed on ${url}: ${error instanceof Error ? error.message : String(error)}`);
@@ -418,22 +471,16 @@ async function setup(options = {}) {
 			if (context.pages().length === 0) browser.close().catch(() => {});
 		});
 	};
-	context.on("page", (page) => {
+	const initPage = (page) => {
 		setupPage(page);
 		handlePageClose(page);
-	});
+	};
+	context.on("page", initPage);
 	const page = context.pages()[0] ?? await context.newPage();
-	setupPage(page);
-	handlePageClose(page);
+	initPage(page);
 	await page.goto("https://heroshot.sh/welcome", { waitUntil: "domcontentloaded" });
 	try {
-		await injectToolbar(page, {
-			screenshots: allScreenshots,
-			pendingJob,
-			selectedId,
-			sidebarExpanded,
-			onEvent: handleEvent
-		});
+		await injectToolbar(page, injectOptions());
 		verbose("Toolbar injected on welcome page");
 	} catch (error) {
 		verbose(`Initial toolbar injection failed: ${error instanceof Error ? error.message : String(error)}`);

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-B6Lg_Ant.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-Fc-PkcTD.js";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/{snippet-B6Lg_Ant.js → snippet-Fc-PkcTD.js}

@@ -190,7 +190,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("Element selectors to hide (display: none)")
+	selectors: z.array(z.string()).describe("Element selectors to hide (visibility: hidden)")
 }).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", [
@@ -370,7 +370,8 @@ const configSchema = z.object({
 	jpegQuality: z.number().int().min(1).max(100).default(80).describe("JPEG compression quality (1-100), only used when outputFormat is \"jpeg\""),
 	browser: browserSchema.optional().describe("Default browser settings applied to all screenshots"),
 	workers: z.number().int().min(1).optional().describe("Number of parallel capture workers (default: 1)"),
-	screenshots: z.array(screenshotSchema).default([]).describe("Screenshot definitions")
+	screenshots: z.array(screenshotSchema).default([]).describe("Screenshot definitions"),
+	hiddenElements: z.record(z.string(), z.array(z.string())).optional().describe("Elements to hide per domain (hostname → CSS selectors)")
 });
 
 //#endregion
@@ -793,7 +794,8 @@ function buildCaptureOptions(config, viewportOnly) {
 	return {
 		format: config.outputFormat ?? "png",
 		quality: config.jpegQuality,
-		fullPage: !viewportOnly
+		fullPage: !viewportOnly,
+		hiddenElements: config.hiddenElements
 	};
 }
 /**
@@ -957,11 +959,11 @@ function executeHandleDialog(page, action) {
 
 //#endregion
 //#region src/sync/actions/hide.ts
-/** Hide elements by setting display: none */
+/** Hide elements by setting visibility: hidden (preserves layout) */
 async function executeHide(page, action) {
 	if (action.type !== "hide") return;
 	for (const selector of action.selectors) await page.locator(selector).evaluateAll((elements) => {
-		for (const element of elements) element.style.display = "none";
+		for (const element of elements) element.style.setProperty("visibility", "hidden", "important");
 	});
 }
 
@@ -1861,6 +1863,14 @@ async function captureScreenshot(page, screenshot, outputDirectory, captureOptio
 		...navResult,
 		filename
 	};
+	if (captureOptions.hiddenElements) {
+		const { hiddenElements: hiddenByDomain } = captureOptions;
+		const { hostname } = new URL(url);
+		if (hiddenByDomain[hostname]?.length) await executeHide(page, {
+			type: "hide",
+			selectors: hiddenByDomain[hostname]
+		});
+	}
 	if (screenshot.actions && screenshot.actions.length > 0) try {
 		await executeActions(page, screenshot.actions);
 		await page.waitForTimeout(500);