heroshot 0.12.1 → 0.13.1

package/dist/cli/cli.js

@@ -1,7 +1,8 @@
 #!/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-3pBmpUTB.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-CqBg-092.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { z } from "zod";
 
@@ -20,8 +21,14 @@ function configToScreenshotData(screenshots) {
 		...screenshot.padding && { padding: screenshot.padding },
 		...screenshot.scroll && { scroll: screenshot.scroll },
 		...screenshot.paddingFill && { paddingFill: screenshot.paddingFill },
+		...screenshot.paddingColor && { paddingColor: screenshot.paddingColor },
 		...screenshot.elementFill && { elementFill: screenshot.elementFill },
-		...screenshot.textOverrides && { textOverrides: screenshot.textOverrides }
+		...screenshot.elementColor && { elementColor: screenshot.elementColor },
+		...screenshot.textOverrides && { textOverrides: screenshot.textOverrides },
+		...screenshot.annotations && { annotations: screenshot.annotations },
+		...screenshot.borderWidth && { borderWidth: screenshot.borderWidth },
+		...screenshot.borderColor && { borderColor: screenshot.borderColor },
+		...screenshot.borderRadius && { borderRadius: screenshot.borderRadius }
 	}));
 }
 
@@ -86,12 +93,23 @@ const screenshotDataSchema = z.object({
 		"solid",
 		"transparent"
 	]).optional(),
+	paddingColor: z.string().optional(),
 	elementFill: z.enum([
 		"original",
 		"solid",
 		"transparent"
 	]).optional(),
-	textOverrides: z.record(z.string(), z.string()).optional()
+	elementColor: z.string().optional(),
+	textOverrides: z.record(z.string(), z.string()).optional(),
+	annotations: z.array(z.object({
+		id: z.string(),
+		type: z.string(),
+		points: z.array(z.number()),
+		style: z.record(z.string(), z.union([z.string(), z.number()])).optional()
+	})).optional(),
+	borderWidth: z.number().optional(),
+	borderColor: z.string().optional(),
+	borderRadius: z.number().optional()
 });
 /** Schema for browser settings from toolbar */
 const browserSettingsSchema = z.object({
@@ -232,11 +250,22 @@ function toConfigScreenshot(data) {
 		name: data.name,
 		url: data.url,
 		selector: data.selector,
-		...data.padding && { padding: data.padding },
+		...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.textOverrides && Object.keys(data.textOverrides).length > 0 && { textOverrides: data.textOverrides }
+		...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 }
 	};
 }
 
@@ -693,7 +722,7 @@ function listAction(options, globalOptions) {
 function getVersion() {
 	if (typeof HEROSHOT_VERSION !== "undefined") return HEROSHOT_VERSION;
 	try {
-		const packageJsonPath = path.join(import.meta.dirname, "..", "..", "package.json");
+		const packageJsonPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 		if (packageJson && typeof packageJson === "object" && "version" in packageJson) return String(packageJson.version);
 	} catch {}

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-3pBmpUTB.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-CqBg-092.js";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { intro, log, note, outro, spinner } from "@clack/prompts";
 import { z } from "zod";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "node:crypto";
@@ -255,10 +256,10 @@ const colorSchemeSchema = z.enum(["light", "dark"]);
 const outputFormatSchema = z.enum(["png", "jpeg"]).default("png");
 /** Padding around element (can expand capture area) */
 const paddingSchema = z.object({
-	top: z.number().int().min(0).default(0).describe("Top padding in pixels"),
-	right: z.number().int().min(0).default(0).describe("Right padding in pixels"),
-	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")
+	top: z.number().min(0).default(0).describe("Top padding in pixels"),
+	right: z.number().min(0).default(0).describe("Right padding in pixels"),
+	bottom: z.number().min(0).default(0).describe("Bottom padding in pixels"),
+	left: z.number().min(0).default(0).describe("Left padding in pixels")
 });
 /**
 * Scroll position saved from editor.
@@ -300,6 +301,13 @@ const viewportVariantSchema = z.string().refine((value) => {
 	const height = Number.parseInt(match[2] ?? "0", 10);
 	return width > 0 && height > 0;
 }, { message: "Must be \"desktop\", \"tablet\", \"mobile\", or \"WIDTHxHEIGHT\" (e.g., \"400x500\")" });
+/** Visual annotation drawn over a screenshot */
+const annotationSchema = z.object({
+	id: z.string().min(1).default(generateUid).describe("Unique identifier (auto-generated if omitted)"),
+	type: z.string().describe("Annotation type: arrow, rect, or ellipse"),
+	points: z.array(z.number()).describe("Geometry points - meaning depends on type"),
+	style: z.record(z.string(), z.union([z.string(), z.number()])).optional().describe("CSS/SVG style properties (stroke, stroke-width, fill, opacity, etc.)")
+});
 /** Single screenshot definition */
 const screenshotSchema = z.object({
 	id: z.string().min(1).default(generateUid).describe("Unique identifier (auto-generated if omitted)"),
@@ -309,9 +317,15 @@ const screenshotSchema = z.object({
 	padding: paddingSchema.optional().describe("Expand capture area beyond element bounds"),
 	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"),
+	paddingColor: z.string().optional().describe("Custom color for padding fill when set to \"solid\" (hex, defaults to auto-detected background)"),
 	elementFill: elementFillSchema.optional().describe("Background fill for element area: \"original\" (default) keeps actual background, \"solid\" replaces with detected color"),
+	elementColor: z.string().optional().describe("Custom color for element fill when set to \"solid\" (hex, defaults to auto-detected background)"),
 	viewports: z.array(viewportVariantSchema).optional().describe("Viewport variants to generate — preset names (\"desktop\", \"tablet\", \"mobile\") or custom \"WIDTHxHEIGHT\""),
 	textOverrides: z.record(z.string(), z.string()).optional().describe("Replace text content before capture. Keys are CSS selectors, values are replacement text"),
+	annotations: z.array(annotationSchema).optional().describe("Visual annotations drawn over the screenshot (arrows, rectangles, ellipses)"),
+	borderWidth: z.number().int().min(0).optional().describe("Border width around capture area in pixels (default 0)"),
+	borderColor: z.string().optional().describe("Border color (hex, default \"#000000\")"),
+	borderRadius: z.number().int().min(0).optional().describe("Corner radius in pixels — rounds the screenshot corners with transparency (PNG only)"),
 	actions: actionsSchema.optional()
 });
 /** Browser settings */
@@ -374,7 +388,8 @@ function parseConfig(input) {
 //#region src/configFile.ts
 const HEROSHOT_DIRECTORY_NAME = ".heroshot";
 const CONFIG_FILENAME = "config.json";
-const README_TEMPLATE_PATH = path.join(import.meta.dirname, "templates", "heroshotReadme.txt");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const README_TEMPLATE_PATH = path.join(__dirname, "templates", "heroshotReadme.txt");
 /**
 * Get the .heroshot directory path for a project
 */
@@ -563,7 +578,7 @@ function findPackageRoot(startDirectory) {
 	return startDirectory;
 }
 /** Path to editor directory */
-const EDITOR_DIR = path.join(findPackageRoot(import.meta.dirname), "editor");
+const EDITOR_DIR = path.join(findPackageRoot(path.dirname(fileURLToPath(import.meta.url))), "editor");
 
 //#endregion
 //#region src/browser/browserDetect.ts
@@ -1045,6 +1060,310 @@ async function executeActions(page, actions) {
 	}
 }
 
+//#endregion
+//#region src/sync/annotationOverlay.ts
+const OVERLAY_ID$1 = "heroshot-annotation-overlay";
+/** Default style values */
+const DEFAULT_STYLE = {
+	stroke: "#ef4444",
+	"stroke-width": 3,
+	opacity: 1
+};
+/**
+* Calculate the required padding expansion for annotations that extend beyond element bounds.
+*/
+function calculateAnnotationPadding(annotations, tolerance = 20) {
+	let minX = 0;
+	let minY = 0;
+	let maxX = 0;
+	let maxY = 0;
+	for (const ann of annotations) {
+		const bbox = getAnnotationBBox(ann);
+		minX = Math.min(minX, bbox.minX);
+		minY = Math.min(minY, bbox.minY);
+		maxX = Math.max(maxX, bbox.maxX);
+		maxY = Math.max(maxY, bbox.maxY);
+	}
+	return {
+		top: Math.max(0, -(minY - tolerance)),
+		right: Math.max(0, tolerance),
+		bottom: Math.max(0, tolerance),
+		left: Math.max(0, -(minX - tolerance))
+	};
+}
+/** Get bounding box for a single annotation */
+function getAnnotationBBox(ann) {
+	const { points } = ann;
+	switch (ann.type) {
+		case "arrow": {
+			const [x1 = 0, y1 = 0, x2 = 0, y2 = 0] = points;
+			return {
+				minX: Math.min(x1, x2),
+				minY: Math.min(y1, y2),
+				maxX: Math.max(x1, x2),
+				maxY: Math.max(y1, y2)
+			};
+		}
+		case "rect": {
+			const [x = 0, y = 0, w = 0, h = 0] = points;
+			return {
+				minX: x,
+				minY: y,
+				maxX: x + w,
+				maxY: y + h
+			};
+		}
+		case "ellipse": {
+			const [cx = 0, cy = 0, rx = 0, ry = 0] = points;
+			return {
+				minX: cx - rx,
+				minY: cy - ry,
+				maxX: cx + rx,
+				maxY: cy + ry
+			};
+		}
+		default: return {
+			minX: 0,
+			minY: 0,
+			maxX: 0,
+			maxY: 0
+		};
+	}
+}
+/**
+* Inject SVG annotation overlay at element position.
+*/
+async function injectAnnotationOverlay(page, element, annotations, padding) {
+	if (annotations.length === 0) return;
+	const box = await element.boundingBox();
+	if (!box) return;
+	await page.evaluate(`(function(config) {
+      var OVERLAY_ID = ${JSON.stringify(OVERLAY_ID$1)};
+      var DEFAULT_STYLE = ${JSON.stringify(DEFAULT_STYLE)};
+      var box = config.box;
+      var annotations = config.annotations;
+      var padding = config.padding;
+
+      // Remove existing overlay
+      var existing = document.querySelector('#' + OVERLAY_ID);
+      if (existing) existing.remove();
+
+      function buildStyle(ann) {
+        var merged = { fill: 'none' };
+        for (var k in DEFAULT_STYLE) merged[k] = DEFAULT_STYLE[k];
+        if (ann.style) {
+          for (var k in ann.style) merged[k] = ann.style[k];
+        }
+        var parts = [];
+        for (var k in merged) parts.push(k + ':' + merged[k]);
+        return parts.join(';');
+      }
+
+      function renderAnnotation(ann) {
+        var style = buildStyle(ann);
+        switch (ann.type) {
+          case 'arrow': {
+            var x1 = ann.points[0] || 0, y1 = ann.points[1] || 0;
+            var x2 = ann.points[2] || 0, y2 = ann.points[3] || 0;
+            var strokeWidth = (ann.style && ann.style['stroke-width']) || 3;
+            var headLength = 8 + strokeWidth * 2;
+            var headAngle = Math.PI / 7;
+            var angle = Math.atan2(y2 - y1, x2 - x1);
+            var a1x = x2 - headLength * Math.cos(angle - headAngle);
+            var a1y = y2 - headLength * Math.sin(angle - headAngle);
+            var a2x = x2 - headLength * Math.cos(angle + headAngle);
+            var a2y = y2 - headLength * Math.sin(angle + headAngle);
+            var baseFactor = Math.cos(headAngle);
+            var baseX = x2 - headLength * baseFactor * Math.cos(angle);
+            var baseY = y2 - headLength * baseFactor * Math.sin(angle);
+            var strokeColor = (ann.style && ann.style.stroke) || '#ef4444';
+            var opacity = (ann.style && ann.style.opacity) || 1;
+            var lineStyle = 'stroke:' + strokeColor + ';stroke-width:' + strokeWidth + ';fill:none';
+            return '<g style="opacity:' + opacity + '">'
+              + '<line x1="' + x1 + '" y1="' + y1 + '" x2="' + baseX + '" y2="' + baseY + '" style="' + lineStyle + '" />'
+              + '<polygon points="' + x2 + ',' + y2 + ' ' + a1x + ',' + a1y + ' ' + a2x + ',' + a2y + '" '
+              + 'fill="' + strokeColor + '" />'
+              + '</g>';
+          }
+          case 'rect': {
+            var x = ann.points[0] || 0, y = ann.points[1] || 0;
+            var w = ann.points[2] || 0, h = ann.points[3] || 0;
+            var borderRadius = (ann.style && ann.style['border-radius'] != null) ? ann.style['border-radius'] : 4;
+            return '<rect x="' + x + '" y="' + y + '" width="' + w + '" height="' + h + '" rx="' + borderRadius + '" style="' + style + '" />';
+          }
+          case 'ellipse': {
+            var cx = ann.points[0] || 0, cy = ann.points[1] || 0;
+            var rx = ann.points[2] || 0, ry = ann.points[3] || 0;
+            return '<ellipse cx="' + cx + '" cy="' + cy + '" rx="' + rx + '" ry="' + ry + '" style="' + style + '" />';
+          }
+          default:
+            return '';
+        }
+      }
+
+      // Create container at element position
+      var container = document.createElement('div');
+      container.id = OVERLAY_ID;
+      container.style.cssText = 'position:fixed;pointer-events:none;z-index:2147483646;'
+        + 'top:' + (box.y - padding.top) + 'px;'
+        + 'left:' + (box.x - padding.left) + 'px;'
+        + 'width:' + (box.width + padding.left + padding.right) + 'px;'
+        + 'height:' + (box.height + padding.top + padding.bottom) + 'px;';
+
+      // Build SVG content
+      var svgParts = [];
+      var svgWidth = box.width + padding.left + padding.right;
+      var svgHeight = box.height + padding.top + padding.bottom;
+      svgParts.push('<svg xmlns="http://www.w3.org/2000/svg" width="' + svgWidth + '" height="' + svgHeight + '" style="overflow:visible;">');
+      // Translate so (0,0) = element top-left
+      svgParts.push('<g transform="translate(' + padding.left + ',' + padding.top + ')">');
+      for (var i = 0; i < annotations.length; i++) {
+        svgParts.push(renderAnnotation(annotations[i]));
+      }
+      svgParts.push('</g></svg>');
+
+      container.innerHTML = svgParts.join('');
+      document.body.appendChild(container);
+    })(${JSON.stringify({
+		box,
+		annotations,
+		padding
+	})})`);
+}
+/**
+* Remove injected annotation overlay.
+*/
+async function removeAnnotationOverlay(page) {
+	await page.evaluate(`(function() {
+      var OVERLAY_ID = ${JSON.stringify(OVERLAY_ID$1)};
+      var existing = document.querySelector('#' + OVERLAY_ID);
+      if (existing) existing.remove();
+    })()`);
+}
+
+//#endregion
+//#region src/sync/borderOverlay.ts
+const OVERLAY_ID = "heroshot-border-overlay";
+/**
+* Inject a border overlay div positioned over the clip region.
+*/
+async function injectBorderOverlay(page, clip, borderWidth, borderColor, borderRadius) {
+	await page.evaluate(`(function(config) {
+      var OVERLAY_ID = ${JSON.stringify(OVERLAY_ID)};
+      var existing = document.querySelector('#' + OVERLAY_ID);
+      if (existing) existing.remove();
+
+      var div = document.createElement('div');
+      div.id = OVERLAY_ID;
+      div.style.cssText = 'position:fixed;'
+        + 'left:' + config.x + 'px;'
+        + 'top:' + config.y + 'px;'
+        + 'width:' + config.width + 'px;'
+        + 'height:' + config.height + 'px;'
+        + 'border:' + config.borderWidth + 'px solid ' + config.borderColor + ';'
+        + 'border-radius:' + config.borderRadius + 'px;'
+        + 'box-sizing:border-box;'
+        + 'pointer-events:none;'
+        + 'z-index:2147483646;';
+      document.body.appendChild(div);
+    })(${JSON.stringify({
+		...clip,
+		borderWidth,
+		borderColor,
+		borderRadius
+	})})`);
+}
+/**
+* Remove border overlay.
+*/
+async function removeBorderOverlay(page) {
+	await page.evaluate(`(function() {
+      var el = document.querySelector('#${OVERLAY_ID}');
+      if (el) el.remove();
+    })()`);
+}
+
+//#endregion
+//#region src/sync/borderRadiusMask.ts
+/**
+* Apply CSS clip-path with rounded inset to <html> and remove backgrounds.
+* Coordinates are viewport-relative (from Playwright boundingBox/clip).
+*/
+async function injectBorderRadiusMask(page, clip, borderRadius) {
+	await page.evaluate(`(function(config) {
+      var scrollX = window.scrollX || 0;
+      var scrollY = window.scrollY || 0;
+      var docWidth = document.documentElement.scrollWidth;
+      var docHeight = document.documentElement.scrollHeight;
+
+      // Convert viewport coords to document coords for inset calculation
+      var top = config.y + scrollY;
+      var left = config.x + scrollX;
+      var bottom = docHeight - (top + config.height);
+      var right = docWidth - (left + config.width);
+
+      // Clamp to non-negative (avoid invalid inset values)
+      top = Math.max(0, top);
+      left = Math.max(0, left);
+      bottom = Math.max(0, bottom);
+      right = Math.max(0, right);
+
+      var html = document.documentElement;
+      var body = document.body;
+
+      // Save original styles
+      html.dataset.heroshotOriginalClip = html.style.clipPath || '';
+      html.dataset.heroshotOriginalHtmlBg = html.style.background || '';
+      html.dataset.heroshotOriginalBodyBg = body.style.background || '';
+      html.dataset.heroshotOriginalHtmlBgColor = html.style.backgroundColor || '';
+      html.dataset.heroshotOriginalBodyBgColor = body.style.backgroundColor || '';
+
+      // Apply clip-path with rounded corners
+      html.style.clipPath = 'inset(' + top + 'px ' + right + 'px ' + bottom + 'px ' + left + 'px round ' + config.borderRadius + 'px)';
+
+      // Remove html/body backgrounds so canvas is transparent
+      // (CSS spec: root element bg propagates to canvas, bypassing clip-path)
+      html.style.setProperty('background', 'transparent', 'important');
+      html.style.setProperty('background-color', 'transparent', 'important');
+      body.style.setProperty('background', 'transparent', 'important');
+      body.style.setProperty('background-color', 'transparent', 'important');
+    })(${JSON.stringify({
+		...clip,
+		borderRadius
+	})})`);
+}
+/**
+* Remove border radius clip mask and restore original styles.
+*/
+async function removeBorderRadiusMask(page) {
+	await page.evaluate(`(function() {
+      var html = document.documentElement;
+      var body = document.body;
+
+      // Restore clip-path
+      if (html.dataset.heroshotOriginalClip !== undefined) {
+        html.style.clipPath = html.dataset.heroshotOriginalClip;
+        delete html.dataset.heroshotOriginalClip;
+      }
+
+      // Restore html background
+      if (html.dataset.heroshotOriginalHtmlBg !== undefined) {
+        html.style.background = html.dataset.heroshotOriginalHtmlBg;
+        html.style.backgroundColor = html.dataset.heroshotOriginalHtmlBgColor || '';
+        delete html.dataset.heroshotOriginalHtmlBg;
+        delete html.dataset.heroshotOriginalHtmlBgColor;
+      }
+
+      // Restore body background
+      if (html.dataset.heroshotOriginalBodyBg !== undefined) {
+        body.style.background = html.dataset.heroshotOriginalBodyBg;
+        body.style.backgroundColor = html.dataset.heroshotOriginalBodyBgColor || '';
+        delete html.dataset.heroshotOriginalBodyBg;
+        delete html.dataset.heroshotOriginalBodyBgColor;
+      }
+    })()`);
+}
+
 //#endregion
 //#region src/sync/elementFinder.ts
 /**
@@ -1310,7 +1629,7 @@ async function takeScreenshot(options) {
 * Capture element with selector and optional text overrides.
 */
 async function captureElementWithOptions(options) {
-	const { page, selector, outputPath, format, quality, padding, paddingFill, elementFill, textOverrides } = options;
+	const { page, selector, textOverrides, ...rest } = options;
 	const element = await findElement(page, selector);
 	if (!element) return {
 		success: false,
@@ -1321,64 +1640,88 @@ async function captureElementWithOptions(options) {
 		page,
 		element,
 		selector,
-		outputPath,
-		format,
-		quality,
-		padding,
-		paddingFill,
-		elementFill
+		...rest
 	});
 }
-/**
-* Capture element with padding using clip region.
-*/
+/** Capture element with padding using clip region. */
 async function captureWithPadding(options) {
-	const { page, element, padding, paddingFill, bgColor, outputPath, format, quality, needsTransparent } = options;
+	const { page, element, padding, paddingFill, bgColor, outputPath, format, quality, needsTransparent, annotations, borderWidth, borderColor, borderRadius } = options;
 	const box = await element.boundingBox();
 	if (!box) return {
 		success: false,
 		error: "Could not get element bounding box"
 	};
 	if (paddingFill === "solid") await injectPaddingMask(page, element, padding, bgColor);
+	const hasAnnotations = annotations && annotations.length > 0;
+	if (hasAnnotations) await injectAnnotationOverlay(page, element, annotations, padding);
+	const clip = {
+		x: Math.max(0, box.x - padding.left),
+		y: Math.max(0, box.y - padding.top),
+		width: box.width + padding.left + padding.right,
+		height: box.height + padding.top + padding.bottom
+	};
+	const hasBorder = borderWidth != null && borderWidth > 0 && borderColor != null;
+	if (hasBorder) await injectBorderOverlay(page, clip, borderWidth, borderColor, borderRadius ?? 0);
+	const hasBorderRadius = borderRadius != null && borderRadius > 0;
+	if (hasBorderRadius) await injectBorderRadiusMask(page, clip, borderRadius);
 	await takeScreenshot({
 		target: page,
 		outputPath,
 		format,
 		quality,
-		clip: {
-			x: Math.max(0, box.x - padding.left),
-			y: Math.max(0, box.y - padding.top),
-			width: box.width + padding.left + padding.right,
-			height: box.height + padding.top + padding.bottom
-		},
-		omitBackground: needsTransparent
+		clip,
+		omitBackground: needsTransparent || hasBorderRadius
 	});
+	if (hasBorderRadius) await removeBorderRadiusMask(page);
+	if (hasBorder) await removeBorderOverlay(page);
+	if (hasAnnotations) await removeAnnotationOverlay(page);
 	if (paddingFill === "solid") await removePaddingMask(page);
 	return { success: true };
 }
+/** Expand padding to fit annotations that extend beyond current bounds. */
+function expandPaddingForAnnotations(padding, annotations) {
+	if (!annotations || annotations.length === 0) return padding;
+	const ap = calculateAnnotationPadding(annotations);
+	return {
+		top: Math.max(padding.top, ap.top),
+		right: Math.max(padding.right, ap.right),
+		bottom: Math.max(padding.bottom, ap.bottom),
+		left: Math.max(padding.left, ap.left)
+	};
+}
 /**
 * Capture element screenshot with optional padding and background fill modes.
 */
 async function captureElementScreenshot(options) {
-	const { page, element, selector, outputPath, format, quality, padding, paddingFill, elementFill } = options;
-	const hasPadding = padding && (padding.top > 0 || padding.right > 0 || padding.bottom > 0 || padding.left > 0);
+	const { page, element, selector, outputPath, format, quality, padding, paddingFill, elementFill, annotations, borderWidth, borderColor, borderRadius } = options;
+	const effectivePadding = expandPaddingForAnnotations(padding ?? {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	}, annotations);
+	const hasAnnotations = annotations && annotations.length > 0;
+	const hasPadding = effectivePadding.top + effectivePadding.right + effectivePadding.bottom + effectivePadding.left > 0;
 	const needsTransparent = format === "png" && (paddingFill === "transparent" || elementFill === "transparent");
-	const needsBgColor = paddingFill === "solid" || elementFill === "solid";
 	let bgColor = "#ffffff";
-	if (needsBgColor) bgColor = await getElementBackgroundColor(page, selector);
+	if (paddingFill === "solid" || elementFill === "solid") bgColor = await getElementBackgroundColor(page, selector);
 	if (elementFill === "solid") await applyElementBackground(page, selector, bgColor);
 	else if (elementFill === "transparent") await applyElementBackground(page, selector, "transparent");
-	if (hasPadding && padding) {
+	if (hasPadding || hasAnnotations || borderRadius != null && borderRadius > 0 || borderWidth != null && borderWidth > 0) {
 		const result = await captureWithPadding({
 			page,
 			element,
-			padding,
+			padding: effectivePadding,
 			paddingFill,
 			bgColor,
 			outputPath,
 			format,
 			quality,
-			needsTransparent
+			needsTransparent,
+			annotations,
+			borderWidth,
+			borderColor,
+			borderRadius
 		});
 		if (!result.success) return result;
 	} else await takeScreenshot({
@@ -1499,7 +1842,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, paddingFill, elementFill, textOverrides } = screenshot;
+	const { name, url, selector, padding, paddingFill, elementFill, textOverrides, annotations, borderWidth, borderColor, borderRadius } = screenshot;
 	const { format, quality, fullPage } = captureOptions;
 	const filename = generateScreenshotFilename({
 		name,
@@ -1536,7 +1879,11 @@ async function captureScreenshot(page, screenshot, outputDirectory, captureOptio
 		padding,
 		paddingFill,
 		elementFill,
-		textOverrides
+		textOverrides,
+		annotations,
+		borderWidth,
+		borderColor,
+		borderRadius
 	}) : await capturePageScreenshot(page, outputPath, format, quality, fullPage ?? true);
 	return captureResult.success ? {
 		success: true,