shared/template-preview-rendering.md

# Local Page previews and icon rasterization

Read only when a shortlisted Page has no usable provider/retained image, or an authentic SVG icon needs rasterization. The [preview policy](template-previews.md) owns the form-wide retrieval budget, fallback behavior, and image limits.

Use an existing Node/Playwright runtime and installed Chromium, resolved from the host's dependency metadata. Do not install dependencies or a browser for a picker. If this runtime is unavailable, retain provider images or supported icons.

## Page content

Use the [preview helper](../scripts/prepare-resource-preview.mjs) with the real title and retrieved opening Markdown; otherwise use the search `preview` excerpt. Prefer content already available from discovery. A read for missing content counts against the form-wide budget; never read every candidate in full for previews. With no excerpt, keep the title and authentic icon without rendering a placeholder.

The helper produces a 16:9 white document preview with readable type, the actual Page title as a document heading, and retrieved paragraphs, headings, lists, or a compact table. There is no duplicate header bar or reserved hover/footer band: content fills the height and crops naturally beneath the host's hover label. Preserve content hierarchy; do not invent charts or decorative cover art. It escapes raw HTML and loads no remote images, fonts, or scripts. This is a rendered content preview, not a screenshot of the native Page.

Write inputs and the private cache in the approved task workspace, outside the plugin:

```sh
"<node>" "<data-plugin-root>/scripts/prepare-resource-preview.mjs" \
  --input "<page-metadata.json>" --cache-dir "<task-workspace>/resource-previews" \
  --browser-package-json "<existing-runtime>/package.json" \
  --browser-executable "<installed-chromium>"
```

Input is one object or an array of `{uri, title, markdown?, preview?, revision?, updated_at?}` from retrieved resources. The result names a JSON file containing each `uri`, `thumbnail`, `icons`, and preview provenance. Pass both image fields to the resource: the blue Page icon belongs in `icons` for the host's hover label, not inside the thumbnail. Read results in code without printing image bytes into model context. The helper enforces the per-image limit. Cached images are keyed by identity, revision/update time, content, and renderer version; reuse them only within the same authorized task/account and remove them with task artifacts.

## Official SVG icons

Use the same command with `--icon "<verified-asset.svg>"` instead of `--input`. It renders unchanged artwork to a transparent PNG and returns an `icon` in the result file. Read the result in code and reuse it across candidates in `icons`, not `thumbnail`.

Existing local raster icons need no rendering: encode their bytes as `icons: [{src: "data:image/png;base64,…", mimeType: "image/png"}]`, using the actual MIME type. Omit the icon if neither a supported image nor the existing renderer is available.