feat: add snippet command for GitHub README/Wiki integration (#32)

## Summary

- Add `heroshot snippet [pattern]` command for generating markdown/HTML
snippets
- Pattern matches against screenshot `id` and `name` (case-insensitive)
- Generates `<picture>` elements with `prefers-color-scheme` media
queries for light/dark mode support
- Supports custom path prefix via `--path-prefix` flag

## Usage

```bash
# Generate snippets for all screenshots
heroshot snippet

# Filter by pattern (matches id or name)
heroshot snippet dashboard

# Custom image path prefix
heroshot snippet --path-prefix ./images/screenshots/
```

## Example Output

```html
<!-- heroshot: Dashboard (abc123) -->
<picture>
  <source srcset="./heroshots/dashboard-dark.png" media="(prefers-color-scheme: dark)">
  <img src="./heroshots/dashboard-light.png" alt="Dashboard">
</picture>
```

## Test plan

- [x] Unit tests for snippet generation logic (12 tests)
- [x] CLI integration tests (8 tests)
- [x] Lint passes
- [x] TypeScript compiles

---------

Co-authored-by: Ondrej Machala <[email protected]>

Author: omachala

.changeset/snippet-command.md

@@ -0,0 +1,5 @@
+---
+'heroshot': minor
+---
+
+Add `heroshot snippet [pattern]` command for generating markdown/HTML snippets for GitHub README and Wiki integration. Generates `<picture>` elements with `prefers-color-scheme` media queries for automatic light/dark mode support.

docs/docs/cli.md

@@ -211,6 +211,43 @@ Or set it in your config to use by default:
 Each worker captures a portion of your screenshots concurrently. More workers = faster captures, but requires more system resources. Start with 2-4 and adjust based on your machine.
 :::
 
+### `heroshot snippet [pattern]`
+
+Generate `<picture>` HTML snippets for use in GitHub READMEs, wikis, or any plain Markdown file. This saves you from manually writing the light/dark mode markup.
+
+```bash
+heroshot snippet                      # Generate snippets for all screenshots
+heroshot snippet dashboard            # Only screenshots matching "dashboard"
+heroshot snippet --path-prefix ./img/ # Custom image path prefix
+```
+
+| Option                   | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `--path-prefix <prefix>` | Image path prefix (default: `./heroshots/`) |
+
+The pattern matches against screenshot **id** and **name** (case-insensitive). More matches = more snippets output.
+
+**Example output:**
+
+```html
+<!-- heroshot: Dashboard (abc123) -->
+<picture>
+  <source srcset="./heroshots/dashboard-dark.png" media="(prefers-color-scheme: dark)" />
+  <img src="./heroshots/dashboard-light.png" alt="Dashboard" />
+</picture>
+```
+
+Copy-paste this into your README.md and GitHub will automatically show the right variant based on the user's color scheme preference.
+
+::: tip Single Color Scheme
+If your config has `browser.colorScheme` set to `light` or `dark` (not both), the snippet outputs simple Markdown instead:
+
+```md
+![Dashboard](./heroshots/dashboard-light.png)
+```
+
+:::
+
 ### `heroshot session-key`
 
 When you log into a site during `heroshot config`, that session is saved encrypted. The encryption key is machine-specific by default, which is fine for local use.
@@ -262,6 +299,10 @@ heroshot session-key
 # Parallel capture with 4 workers
 heroshot --workers 4
 
+# Generate README snippets for GitHub
+heroshot snippet
+heroshot snippet dashboard --path-prefix ./images/
+
 # Verbose output (works with any command)
 heroshot -v
 heroshot config -v

docs/docs/integrations/markdown.md

@@ -8,6 +8,27 @@ For plain Markdown files (GitHub READMEs, GitLab wikis, or any Markdown renderer
 
 This works on GitHub, GitLab, and anywhere that respects `prefers-color-scheme` media queries.
 
+## Generate Snippets Automatically
+
+Use the `heroshot snippet` command to generate the `<picture>` markup automatically:
+
+```bash
+heroshot snippet              # All screenshots
+heroshot snippet dashboard    # Filter by name/id
+```
+
+Output:
+
+```html
+<!-- heroshot: Dashboard (abc123) -->
+<picture>
+  <source srcset="./heroshots/dashboard-dark.png" media="(prefers-color-scheme: dark)" />
+  <img src="./heroshots/dashboard-light.png" alt="Dashboard" />
+</picture>
+```
+
+Copy-paste into your README. See [CLI Reference](/docs/cli#heroshot-snippet-pattern) for all options.
+
 ## Light/Dark Mode Images
 
 Use the `<picture>` element with `prefers-color-scheme` media queries:

src/cli/cli.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import type { ShotCommandOptions } from '../types';
 import { intro, setVerbose } from '../ui';
 import { configAction, sessionKeyAction, shotAction } from './handlers';
+import { type SnippetOptions, snippetAction } from './snippet';
 import type { ConfigActionOptions, GlobalOptions } from './types';
 
 // Version is injected at build time for standalone binaries, or read from package.json for development
@@ -94,4 +95,14 @@ program
     if (!success) process.exitCode = 1;
   });
 
+program
+  .command('snippet [pattern]')
+  .description('Generate markdown/HTML snippets for GitHub README and Wiki')
+  .option('--path-prefix <prefix>', 'Image path prefix (default: ./heroshots/)')
+  .action((pattern?: string, options?: SnippetOptions) => {
+    const globalOptions = program.opts<GlobalOptions>();
+    const success = snippetAction(pattern, options ?? {}, globalOptions.config);
+    if (!success) process.exitCode = 1;
+  });
+
 program.parse();

src/cli/snippet.ts

@@ -0,0 +1,137 @@
+/**
+ * Generate markdown/HTML snippets for GitHub README and Wiki.
+ *
+ * Generates `<picture>` elements with prefers-color-scheme media queries
+ * for light/dark mode support in pure markdown environments.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { getConfigPath, loadConfig } from '../configFile';
+import { filterScreenshots } from '../sync/configHelpers';
+import type { Config, Screenshot } from '../types';
+import { error, log } from '../ui';
+import { generateScreenshotFilename } from '../utils/screenshotPath';
+
+export type SnippetOptions = {
+  /** Output format */
+  format?: 'html' | 'markdown';
+  /** Custom path prefix for images (default: ./heroshots/) */
+  pathPrefix?: string;
+};
+
+type SnippetResult = {
+  screenshot: Screenshot;
+  snippet: string;
+};
+
+/**
+ * Check if a screenshot has light/dark variants (colorScheme not set = both).
+ */
+function hasColorSchemeVariants(config: Config): boolean {
+  return config.browser?.colorScheme === undefined;
+}
+
+/**
+ * Generate a single snippet for a screenshot.
+ */
+function generateSnippet(screenshot: Screenshot, config: Config, options: SnippetOptions): string {
+  const { pathPrefix = './heroshots/' } = options;
+  const format = config.outputFormat ?? 'png';
+  const hasVariants = hasColorSchemeVariants(config);
+  const viewports = screenshot.viewports ?? [];
+
+  // For simplicity, use the first viewport or no viewport suffix
+  const viewport = viewports.length > 0 ? viewports[0] : undefined;
+
+  if (hasVariants) {
+    // Generate <picture> with prefers-color-scheme
+    const lightFile = generateScreenshotFilename({
+      name: screenshot.name,
+      viewport,
+      colorScheme: 'light',
+      format,
+    });
+    const darkFile = generateScreenshotFilename({
+      name: screenshot.name,
+      viewport,
+      colorScheme: 'dark',
+      format,
+    });
+
+    const lightPath = `${pathPrefix}${lightFile}`;
+    const darkPath = `${pathPrefix}${darkFile}`;
+
+    return `<picture>
+  <source srcset="${darkPath}" media="(prefers-color-scheme: dark)">
+  <img src="${lightPath}" alt="${screenshot.name}">
+</picture>`;
+  }
+
+  // Single color scheme - just an img tag
+  const filename = generateScreenshotFilename({
+    name: screenshot.name,
+    viewport,
+    colorScheme: config.browser?.colorScheme,
+    format,
+  });
+
+  return `![${screenshot.name}](${pathPrefix}${filename})`;
+}
+
+/**
+ * Generate snippets for screenshots matching pattern.
+ */
+export function generateSnippets(
+  config: Config,
+  pattern?: string,
+  options: SnippetOptions = {}
+): SnippetResult[] {
+  const filtered = filterScreenshots(config.screenshots, pattern);
+
+  return filtered.map(screenshot => ({
+    screenshot,
+    snippet: generateSnippet(screenshot, config, options),
+  }));
+}
+
+/**
+ * Snippet command handler.
+ */
+export function snippetAction(
+  pattern: string | undefined,
+  options: SnippetOptions,
+  configPath?: string
+): boolean {
+  const resolvedConfigPath = configPath ? path.resolve(configPath) : getConfigPath();
+
+  if (!existsSync(resolvedConfigPath)) {
+    error(`Config file not found: ${resolvedConfigPath}`);
+    error('Run "heroshot config" to create one.');
+    return false;
+  }
+
+  const config = loadConfig(resolvedConfigPath);
+
+  if (config.screenshots.length === 0) {
+    error('No screenshots defined in config.');
+    return false;
+  }
+
+  const results = generateSnippets(config, pattern, options);
+
+  if (results.length === 0) {
+    error(`No screenshots matching "${pattern ?? ''}"`);
+    return false;
+  }
+
+  // Output snippets
+  for (const { screenshot, snippet } of results) {
+    log(`\n<!-- heroshot: ${screenshot.name} (${screenshot.id}) -->`);
+    log(snippet);
+  }
+
+  log('');
+
+  return true;
+}