heroshot 0.5.0 → 0.6.1

package/README.md

@@ -18,24 +18,22 @@ The manual fix is tedious: open browser, navigate, log in, screenshot, crop, sav
 
 **Heroshot fixes this.** Define your screenshots once - point and click, no CSS selectors - and regenerate them with one command whenever you need.
 
+```bash
+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>
-    <th></th>
-    <th>Light</th>
-    <th>Dark</th>
-  </tr>
-  <tr>
-    <th>Desktop</th>
     <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>
-    <th>Tablet</th>
     <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>
-    <th>Mobile</th>
     <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>
@@ -43,17 +41,9 @@ The manual fix is tedious: open browser, navigate, log in, screenshot, crop, sav
 
 <p align="center"><em>6 screenshots from one config entry - always in sync with the live site.</em></p>
 
-## Get Started
-
-```bash
-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.
-
 ## Use in Your Docs
 
-**VitePress**
+**VitePress** · [Full guide](https://heroshot.sh/docs/integrations/vitepress)
 
 ```ts
 // .vitepress/config.ts
@@ -62,26 +52,26 @@ export default defineConfig({ vite: { plugins: [heroshot()] } });
 ```
 
 ```vue
+<script setup>
+import { Heroshot } from 'heroshot/vue';
+</script>
+
 <Heroshot name="dashboard" alt="Dashboard" />
 ```
 
-**Docusaurus**
+**Docusaurus** · [Full guide](https://heroshot.sh/docs/integrations/docusaurus)
 
 ```js
 // docusaurus.config.js
 plugins: [['heroshot/plugins/docusaurus', {}]];
 ```
 
-```mdx
+```tsx
 import { Heroshot } from 'heroshot/docusaurus';
-<Heroshot name="dashboard" alt="Dashboard" />
+<Heroshot name="dashboard" alt="Dashboard" />;
 ```
 
-**MkDocs**
-
-```bash
-pip install heroshot
-```
+**MkDocs** · [Full guide](https://heroshot.sh/docs/integrations/mkdocs)
 
 ```yaml
 # mkdocs.yml
@@ -96,53 +86,21 @@ plugins:
 
 One component/macro, all variants - light/dark mode switches automatically, responsive sizes via srcset.
 
-## Automated Updates
-
-Keep screenshots always current by running heroshot in CI. Quick setup:
-
-```bash
-# Get your session key (for authenticated sites)
-npx heroshot session-key
-
-# Add to GitHub secrets
-gh secret set HEROSHOT_SESSION_KEY
-```
-
-Then create `.github/workflows/heroshot.yml`:
-
-```yaml
-name: Update Screenshots
-
-on:
-  workflow_dispatch:
-
-jobs:
-  screenshots:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npx heroshot
-        env:
-          HEROSHOT_SESSION_KEY: ${{ secrets.HEROSHOT_SESSION_KEY }}
-      - run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add heroshots/
-          git diff --staged --quiet || git commit -m "chore: update screenshots" && git push
-```
-
-Go to Actions → Update Screenshots → Run workflow. Done.
+## Learn More
 
-For more options (scheduled runs, PR creation, debugging), see the [full CI guide](https://heroshot.sh/docs/guide/automated-updates).
+|                     |                                                                       |
+| ------------------- | --------------------------------------------------------------------- |
+| **Documentation**   | [heroshot.sh](https://heroshot.sh)                                    |
+| **Getting Started** | [Quick start guide](https://heroshot.sh/docs/getting-started)         |
+| **Configuration**   | [Config options](https://heroshot.sh/docs/config)                     |
+| **CI/CD Setup**     | [Automated updates](https://heroshot.sh/docs/guide/automated-updates) |
+| **CLI Reference**   | [All commands & flags](https://heroshot.sh/docs/cli)                  |
 
-## Learn More
+## Contributing
 
-**Docs:** [heroshot.sh](https://heroshot.sh)
+This is a community project aiming to solve screenshot automation end-to-end and any feedback is valuable. Open an [issue](https://github.com/omachala/heroshot/issues) for bugs, questions, or feature requests. Pull requests are more than welcome.
 
-**Status:** Early alpha. [See releases](https://github.com/omachala/heroshot/releases) for current version.
+If you like it, give the repo a ⭐
 
 ## License
 

package/dist/cli.js

@@ -46,6 +46,8 @@ var scrollPositionSchema = z.object({
   x: z.number().int().min(0).default(0),
   y: z.number().int().min(0).default(0)
 });
+var paddingFillSchema = z.enum(["inherit", "solid", "transparent"]);
+var elementFillSchema = z.enum(["original", "solid", "transparent"]);
 var viewportVariantSchema = z.string().refine(
   (value) => {
     if (value in VIEWPORT_PRESETS) return true;
@@ -66,8 +68,10 @@ var screenshotSchema = z.object({
   padding: paddingSchema.optional(),
   /** Scroll position to restore when capturing */
   scroll: scrollPositionSchema.optional(),
-  /** Fill padding area with detected background color */
-  maskPadding: z.boolean().optional(),
+  /** Background fill mode for padding area */
+  paddingFill: paddingFillSchema.optional(),
+  /** Background fill mode for element area */
+  elementFill: elementFillSchema.optional(),
   /** Viewport variants - generates screenshot for each (e.g., ["desktop", "mobile", "400x500"]) */
   viewports: z.array(viewportVariantSchema).optional(),
   /** Text overrides - selector (relative to main element) -> replacement text */
@@ -108,6 +112,8 @@ var shotCliOptionsSchema = z.object({
   quality: z.number().int().min(1).max(100).optional(),
   /** Omit background for transparent PNG */
   omitBackground: z.boolean().optional(),
+  /** Capture only viewport instead of full page */
+  viewportOnly: z.boolean().optional(),
   /** Timeout in milliseconds */
   timeout: z.number().int().positive().optional()
 });
@@ -415,7 +421,8 @@ function toConfigScreenshot(data) {
     selector: data.selector,
     ...data.padding && { padding: data.padding },
     ...data.scroll && { scroll: data.scroll },
-    ...data.maskPadding && { maskPadding: data.maskPadding },
+    ...data.paddingFill && { paddingFill: data.paddingFill },
+    ...data.elementFill && { elementFill: data.elementFill },
     ...data.textOverrides && Object.keys(data.textOverrides).length > 0 && { textOverrides: data.textOverrides }
   };
 }
@@ -502,7 +509,8 @@ async function setup(options = {}) {
     createdAt: index,
     ...screenshot.padding && { padding: screenshot.padding },
     ...screenshot.scroll && { scroll: screenshot.scroll },
-    ...screenshot.maskPadding && { maskPadding: screenshot.maskPadding },
+    ...screenshot.paddingFill && { paddingFill: screenshot.paddingFill },
+    ...screenshot.elementFill && { elementFill: screenshot.elementFill },
     ...screenshot.textOverrides && { textOverrides: screenshot.textOverrides }
   }));
   let pendingJob = null;
@@ -784,6 +792,58 @@ async function injectPaddingMask(page, element, padding, bgColor) {
 async function removePaddingMask(page) {
   await page.evaluate(`document.querySelector('#heroshot-padding-mask')?.remove()`);
 }
+async function applyElementBackground(page, selector, bgColor) {
+  await page.evaluate(`
+    (() => {
+      const selector = ${JSON.stringify(selector)};
+      const bgColor = ${JSON.stringify(bgColor)};
+
+      const parts = selector.split('>>>').map((p) => p.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;
+        current = found;
+      }
+
+      if (!(current instanceof Element)) return;
+
+      // Store original background for restoration
+      current.dataset.heroshotOriginalBg = current.style.backgroundColor;
+      current.style.backgroundColor = bgColor;
+    })()
+  `);
+}
+async function restoreElementBackground(page, selector) {
+  await page.evaluate(`
+    (() => {
+      const selector = ${JSON.stringify(selector)};
+
+      const parts = selector.split('>>>').map((p) => p.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;
+        current = found;
+      }
+
+      if (!(current instanceof Element)) return;
+
+      // Restore original background
+      const original = current.dataset.heroshotOriginalBg;
+      if (original !== undefined) {
+        current.style.backgroundColor = original;
+        delete current.dataset.heroshotOriginalBg;
+      }
+    })()
+  `);
+}
 async function findElement(page, selector, maxAttempts = 10, intervalMs = 500) {
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     const handle = await page.evaluateHandle(`
@@ -819,22 +879,23 @@ async function findElement(page, selector, maxAttempts = 10, intervalMs = 500) {
   }
   return null;
 }
-async function takeScreenshot(target, outputPath, format, quality, clip) {
+async function takeScreenshot(options) {
+  const { target, outputPath, format, quality, clip, omitBackground, fullPage = true } = options;
   const isPage = "goto" in target;
   if (format === "jpeg") {
     if (isPage && clip) {
       await target.screenshot({ path: outputPath, type: "jpeg", quality, clip });
     } else if (isPage) {
-      await target.screenshot({ path: outputPath, type: "jpeg", quality, fullPage: true });
+      await target.screenshot({ path: outputPath, type: "jpeg", quality, fullPage });
     } else {
       await target.screenshot({ path: outputPath, type: "jpeg", quality });
     }
   } else if (isPage && clip) {
-    await target.screenshot({ path: outputPath, type: "png", clip });
+    await target.screenshot({ path: outputPath, type: "png", clip, omitBackground });
   } else if (isPage) {
-    await target.screenshot({ path: outputPath, type: "png", fullPage: true });
+    await target.screenshot({ path: outputPath, type: "png", fullPage, omitBackground });
   } else {
-    await target.screenshot({ path: outputPath, type: "png" });
+    await target.screenshot({ path: outputPath, type: "png", omitBackground });
   }
 }
 async function applyTextOverrides(page, selector, textOverrides) {
@@ -867,37 +928,60 @@ async function applyTextOverrides(page, selector, textOverrides) {
   `);
   await page.waitForTimeout(50);
 }
+async function getElementBackgroundColor(page, selector) {
+  const bgColorResult = await page.evaluate(`
+    (() => {
+      const selector = ${JSON.stringify(selector)};
+      const parts = selector.split('>>>').map((p) => p.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 '#ffffff';
+        current = found;
+      }
+
+      if (!(current instanceof Element)) return '#ffffff';
+
+      const detectBg = ${GET_BACKGROUND_COLOR_SCRIPT};
+      return detectBg(current);
+    })()
+  `);
+  return typeof bgColorResult === "string" ? bgColorResult : "#ffffff";
+}
 async function captureElementScreenshot(options) {
-  const { page, element, selector, outputPath, format, quality, padding, maskPadding } = 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 needsTransparent = format === "png" && (paddingFill === "transparent" || elementFill === "transparent");
+  const needsBgColor = paddingFill === "solid" || elementFill === "solid";
+  let bgColor = "#ffffff";
+  if (needsBgColor) {
+    bgColor = await getElementBackgroundColor(page, selector);
+    verbose(`Detected background color: ${bgColor}`);
+  }
+  if (elementFill === "solid") {
+    await applyElementBackground(page, selector, bgColor);
+  } else if (elementFill === "transparent") {
+    await applyElementBackground(page, selector, "transparent");
+  }
   if (hasPadding) {
     const box = await element.boundingBox();
     if (!box) {
       return { success: false, error: "Could not get element bounding box" };
     }
-    if (maskPadding) {
-      const bgColorResult = await page.evaluate(`
-        (() => {
-          const selector = ${JSON.stringify(selector)};
-          const parts = selector.split('>>>').map((p) => p.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 '#ffffff';
-            current = found;
-          }
-
-          if (!(current instanceof Element)) return '#ffffff';
-
-          const detectBg = ${GET_BACKGROUND_COLOR_SCRIPT};
-          return detectBg(current);
-        })()
-      `);
-      const bgColor = typeof bgColorResult === "string" ? bgColorResult : "#ffffff";
-      verbose(`Background color: ${bgColor}`);
+    if (paddingFill === "solid") {
       await injectPaddingMask(page, element, padding, bgColor);
     }
     const clip = {
@@ -906,18 +990,34 @@ async function captureElementScreenshot(options) {
       width: box.width + padding.left + padding.right,
       height: box.height + padding.top + padding.bottom
     };
-    await takeScreenshot(page, outputPath, format, quality, clip);
-    if (maskPadding) {
+    await takeScreenshot({
+      target: page,
+      outputPath,
+      format,
+      quality,
+      clip,
+      omitBackground: needsTransparent
+    });
+    if (paddingFill === "solid") {
       await removePaddingMask(page);
     }
   } else {
-    await takeScreenshot(element, outputPath, format, quality);
+    await takeScreenshot({
+      target: element,
+      outputPath,
+      format,
+      quality,
+      omitBackground: needsTransparent
+    });
+  }
+  if (elementFill === "solid" || elementFill === "transparent") {
+    await restoreElementBackground(page, selector);
   }
   return { success: true };
 }
 async function captureScreenshot(page, screenshot, outputDirectory, captureOptions, variant = {}) {
-  const { name, url, selector, padding, scroll, maskPadding, textOverrides } = screenshot;
-  const { format, quality } = captureOptions;
+  const { name, url, selector, padding, scroll, paddingFill, elementFill, textOverrides } = screenshot;
+  const { format, quality, fullPage } = captureOptions;
   const filename = generateScreenshotFilename({
     name,
     viewport: variant.viewportName,
@@ -926,12 +1026,27 @@ async function captureScreenshot(page, screenshot, outputDirectory, captureOptio
   });
   const suffix = [variant.viewportName, variant.colorScheme].filter(Boolean).join("-");
   verbose(`Capturing: ${name}${suffix ? ` (${suffix})` : ""}`);
+  if (variant.colorScheme) {
+    await page.emulateMedia({ colorScheme: variant.colorScheme });
+  }
   try {
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     return { success: false, error: `Failed to navigate: ${message}`, filename };
   }
+  if (variant.colorScheme) {
+    await page.evaluate(`
+      (() => {
+        const isDark = ${variant.colorScheme === "dark"};
+        if (isDark) {
+          document.documentElement.classList.add('dark');
+        } else {
+          document.documentElement.classList.remove('dark');
+        }
+      })()
+    `);
+  }
   await page.waitForTimeout(2e3);
   if (scroll) {
     await page.evaluate(`window.scrollTo(${scroll.x}, ${scroll.y})`);
@@ -959,13 +1074,14 @@ async function captureScreenshot(page, screenshot, outputDirectory, captureOptio
         format,
         quality,
         padding,
-        maskPadding
+        paddingFill,
+        elementFill
       });
       if (!captureResult.success) {
         return { ...captureResult, filename };
       }
     } else {
-      await takeScreenshot(page, outputPath, format, quality);
+      await takeScreenshot({ target: page, outputPath, format, quality, fullPage });
     }
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
@@ -1063,7 +1179,11 @@ function showResults(results, outputDirectory, staleFiles, deletedFiles) {
   } else if (staleFiles.length > 0) {
     parts.push(colors.dim(`${staleFiles.length} stale`));
   }
-  outro(parts.join(", ") + ` to ${colors.dim(outputDirectory + "/")}`);
+  outro(parts.join(", "));
+  for (const result of successfulResults) {
+    const fullPath = path4.join(outputDirectory, result.filename);
+    log(`  ${colors.dim(fullPath)}`);
+  }
   if (staleFiles.length > 0 && deletedFiles.length === 0) {
     warn(`Stale files found: ${staleFiles.join(", ")}`);
     verbose("Run with --clean to delete stale files");
@@ -1113,7 +1233,9 @@ async function sync(options = {}) {
   const schemes = getColorSchemes(colorSchemeSetting);
   const captureOptions = {
     format: config.outputFormat ?? "png",
-    quality: config.jpegQuality
+    quality: config.jpegQuality,
+    fullPage: !options.viewportOnly
+    // Default true, false when --viewport-only
   };
   const defaultViewport = config.browser?.viewport ?? { width: 1280, height: 800 };
   const deviceScaleFactor = config.browser?.deviceScaleFactor;
@@ -1197,7 +1319,7 @@ async function sync(options = {}) {
   captureSpinner.stop("Screenshots captured");
   let staleFiles = [];
   let deletedFiles = [];
-  if (!filterPattern) {
+  if (!filterPattern && !options.skipStaleCheck) {
     const existingFiles = getExistingFiles(outputDirectory);
     const writtenFiles = new Set(
       results.filter(({ success }) => success).map(({ filename }) => filename)
@@ -1263,10 +1385,11 @@ function buildScreenshotEntry(url, options) {
   }
   return screenshot;
 }
-function getColorScheme(options) {
+function getColorScheme(options, bothVariants) {
+  if (options?.dark && options?.light) return void 0;
   if (options?.dark) return "dark";
   if (options?.light) return "light";
-  return void 0;
+  return bothVariants ? void 0 : "light";
 }
 function getDeviceScaleFactor(options, existingConfig) {
   if (options?.retina) return 2;
@@ -1295,7 +1418,8 @@ function buildShotConfig(url, options, existingConfig) {
     jpegQuality: options?.quality ?? existingConfig?.jpegQuality ?? 80,
     browser: {
       viewport: getViewport(options, existingConfig),
-      colorScheme: getColorScheme(options),
+      colorScheme: getColorScheme(options, false),
+      // false = oneshot mode, default to light-only
       deviceScaleFactor: getDeviceScaleFactor(options, existingConfig)
     },
     screenshots: [screenshot]
@@ -1326,7 +1450,10 @@ async function handleUrlCapture(url, options, configPath, sessionKey) {
   const result = await sync({
     config: shotConfig,
     outputDirectory,
-    sessionKey
+    sessionKey,
+    skipStaleCheck: true,
+    // Don't check for stale files in oneshot mode
+    viewportOnly: options?.viewportOnly
   });
   if (options?.save && result.failed === 0) {
     const screenshot = shotConfig.screenshots[0];
@@ -1352,7 +1479,7 @@ async function handleDefaultCommand(configPath, sessionKey, hasExplicitConfig, c
   }
   return true;
 }
-program.command("shot [url]", { isDefault: true, hidden: true }).description("Take a screenshot (URL capture mode, or sync if no URL)").option("--selector <selector...>", "CSS selector(s) to capture").option("-o, --output <file>", "Output filename").option("-p, --padding <pixels>", "Padding around element", parseInt).option("-w, --width <pixels>", "Viewport width", parseInt).option("--height <pixels>", "Viewport height", parseInt).option("--mobile", "Use mobile viewport (375x667)").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)", parseInt).option("--retina", "Use retina scale (2x)").option("-q, --quality <percent>", "JPEG quality (1-100), outputs JPEG", parseInt).option("--omit-background", "Transparent background (PNG only)").option("--timeout <ms>", "Timeout in milliseconds", parseInt).option("--save", "Save screenshot definition to config").option("--clean", "Delete stale files in output directory").action(async (url, options) => {
+program.command("shot [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", parseInt).option("-w, --width <pixels>", "Viewport width", parseInt).option("--height <pixels>", "Viewport height", parseInt).option("--mobile", "Use mobile viewport (375x667)").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)", parseInt).option("--retina", "Use retina scale (2x)").option("-q, --quality <percent>", "JPEG quality (1-100), outputs JPEG", parseInt).option("--omit-background", "Transparent background (PNG only)").option("--viewport-only", "Capture only viewport (not full page)").option("--timeout <ms>", "Timeout in milliseconds", parseInt).option("--save", "Save screenshot definition to config").option("--clean", "Delete stale files in output directory").action(async (url, options) => {
   const globalOptions = program.opts();
   const configPath = globalOptions.config ? path5.resolve(globalOptions.config) : getConfigPath();
   if (url?.startsWith("http")) {