Snippet Image Rendering

---
name: snippet-image-rendering
description: 'Use when the user explicitly names snipgrapher and wants code rendered to a polished PNG, SVG, or WebP at an explicit local path. Probes the installed CLI for supported flags and writes only the named image file. Not for other renderers, publishing, or remote actions.'
---

# Snippet image rendering

## Refuse first

- Do not substitute another renderer when snipgrapher is missing.
- Do not publish, upload, or touch credentials or remote systems.
- Do not guess CLI flags; use only options exposed by the installed version.

## Contract

| Field | Bound contract |
|---|---|
| Trigger | User explicitly mentions snipgrapher and wants code rendered as an image |
| Authority | Reversible-local: write only the named image file and, only when the user asks, a snipgrapher config file whose path and format are stated before writing. Rollback deletes only files this run created. If the output path existed before the run, the pre-existing bytes are captured before overwrite and restored on failure. |
| Side effect | Writes one image file to the explicit output path; optionally writes a config file when the user requests it and its path and format are stated before writing |
| Done | The requested PNG, SVG, or WebP exists at the explicit path with non-zero size, produced through the profile actually used (default named when none supplied), with a one-line report of path and byte count |

## Inputs

- Source code (required): the code snippet to render, supplied as a file path or inline code block.
- Output path (required): explicit path with a .png, .svg, or .webp extension.
- Profile (optional): a snipgrapher profile name. If omitted, snipgrapher uses its default.
- Language (optional): a language hint for syntax highlighting. If omitted, snipgrapher infers from the file extension or content.

## Procedure

1. **Verify snipgrapher resolves from PATH.**
   ```
   command -v snipgrapher
   ```
   If not found, stop with: `snipgrapher is not installed or not in PATH. Install it before proceeding.`
   Done when: the executable resolves, or the workflow stops with the missing-dependency report.

2. **Normalize the source.** If a file path was supplied, verify it exists:
   ```
   test -f <source_path>
   ```
   If not found, stop with the missing-file report. If inline code was supplied, write it to a temp file with an extension derived from the language hint when the installed CLI consumes paths. If `snipgrapher --help` exposes a stdin pipe, pipe the inline snippet directly instead.
   Done when: a readable source is available as a path or stdin stream, or the workflow stops with source-missing.

3. **Construct the command from the installed version.** Check available flags:
   ```
   snipgrapher --help
   ```
   Include `--profile <name>` only when help exposes `--profile` and a profile was supplied. Include `--language <lang>` only when help exposes `--language` and a language was supplied. If a requested flag is not exposed by the installed version, stop with unsupported-flag and report which flag was requested and what the help output shows.
   Done when: every selected optional flag is both requested and supported by the installed CLI.

4. **Render to the explicit output path.** If the output path already exists, capture its bytes before overwriting:
   ```
   cp <output_path> <output_path>.pre-existing
   ```
   Run:
   ```
   snipgrapher <source> --output <output_path> [validated flags]
   ```
   Done when: snipgrapher exits successfully targeting the explicit output path.

5. **Verify the artifact and report.**
   ```
   test -s <output_path> && wc -c <output_path>
   ```
   If the file is missing or empty, stop with empty-or-missing-output and trigger rollback. On success, report the path, byte count, and the profile actually used (default named when none supplied). Remove the pre-existing backup if the render succeeded.
   Done when: the artifact exists with non-zero size and the one-line report is returned.

## Failure and recovery

| Failure class | Rule |
|---|---|
| `snipgrapher-missing` | Stop and report the missing dependency. Do not attempt alternative renderers. |
| `source-missing` | Stop and report the nonexistent source path. |
| `unsupported-flag` | Stop and report which flag was requested and what `snipgrapher --help` exposes. Do not retry with different flags unless the user instructs. |
| `render-failure` | Stop and report snipgrapher's stderr. Do not retry with different flags unless the user instructs. |
| `empty-or-missing-output` | Stop and report that rendering produced no output. Trigger rollback. |
| `rollback` | If a pre-existing backup exists, restore it to the output path. Delete only files this run created (the output file if it did not pre-exist, any temp file, the backup). Do not delete files the user created before this run. |

## Output

The rendered image at the explicit path, then one report line naming the path, byte count, and profile used.