# pi-poster
🎨 [Poster](https://github.com/Michaelliv/poster) for [pi](https://github.com/badlogic/pi-mono) — turn agent intent into a rendered image.
Give pi the ability to author a single-file React poster and render it to **PNG / SVG / PDF / JPG / WebP** during a session. Tailwind, Recharts, lucide-react, Inter / Source Serif 4 / JetBrains Mono — all available out of the box.
```
"Make me a share image for the v0.2 release" → hero PNG
"One-page PDF report from this CSV" → editorial layout → PDF
"Year-in-review for our top 10 customers" → wrapped-style story poster
"OG image for the new docs site" → 1200×630 social card
"Cover for this README" → README hero
```
## Install
```bash
pi install npm:pi-poster
```
That's it. `poster-ai` ships a headless Chromium binary, so the first render is ready to go.
## How the agent uses it
One tool, **`poster_render`**, with two ways to source the TSX:
| Param | When | Why |
|---|---|---|
| `tsx` | First render | Inline source string. The agent authors a fresh component. |
| `tsxPath` | Iterative edits | Path to a `.tsx` file. The agent edits the previously-archived source instead of resending the whole component. |
The two are mutually exclusive — pass exactly one.
### First render (inline)
```
poster_render({
tsx: `
export default () => (
<div className="w-[1200px] p-12 bg-black text-white">
<div className="text-[14px] font-bold uppercase tracking-[0.3em] text-cyan-300/70">
Release · v0.2
</div>
<h1 className="text-7xl font-black mt-3">Shipped.</h1>
</div>
)
`,
out: "./release.png"
})
→ Rendered /Users/you/proj/release.png · 24.3 KB · 1200×180 · png
```
### Iterative edit (by path)
Every render archives a paired `<name>-<ts>.{format,tsx}` into `.poster/output/`. To iterate, the agent edits that `.tsx` file directly and re-renders by path — no need to resend the whole component each turn.
```
poster_render({
tsxPath: ".poster/output/release-1776359608903.tsx",
out: "./release.png"
})
```
### Canvas comes from the TSX
There is **no** `width` / `height` tool param. The root element declares the canvas via Tailwind:
```tsx
<div className="w-[1600px] p-10 ..."> // landscape / dashboard / twitter
<div className="w-[1200px] p-10 ..."> // square / cover / instagram
<div className="w-[1080px] p-10 ..."> // story / wrapped
<div className="w-[1400px] p-10 ..."> // editorial / magazine
<div className="w-[1200px] h-[630px] p-10 ..."> // OG image (the only fixed-aspect case)
```
One source of truth. Two sources = overflow + empty-strip bugs.
## What the agent gets, for free
- **`poster` skill** — authoring contract, layout grammar, color systems, signature patterns (kicker rows, italic reveal words, gradient text, card recipes), and a catalog of pitfalls. Loaded automatically when the agent reaches for a visual deliverable.
- **Pre-flight validation** — broken canvases (`min-h-screen`, `w-full` on root, illegal font sizes, percentage-height traps) are caught before the puppeteer launch, with concrete fix suggestions in the error.
- **Inline preview** — when the terminal supports images, the rendered PNG/JPG/WebP appears directly under the tool result.
- **Source archive** — `.poster/output/<name>-<ts>.{ext,tsx}` keeps the full history of what the agent produced. Add `.poster/` to `.gitignore` if you don't want it in version control.
## What posters look like
Every one of these is a single `.tsx` file the agent can author the same way — click any source link to see exactly what the model produced.
<table>
<tr>
<td width="50%" valign="top"><a href="examples/dashboard.png"><img src="examples/dashboard.png" alt="dashboard" /></a></td>
<td valign="top"><strong><code>dashboard</code></strong> · <a href="examples/dashboard.tsx">source</a><br/><br/><sub>Single-page analytics dashboard — area + bar charts, top-customer table, traffic source breakdown, KPI tiles. Dark theme with gradient fills, precise tabular numbers.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/devwrap.png"><img src="examples/devwrap.png" alt="devwrap" /></a></td>
<td valign="top"><strong><code>devwrap</code></strong> · <a href="examples/devwrap.tsx">source</a><br/><br/><sub>Developer year-in-review poster — GitHub-style contribution heatmap, language mix donut, top repos, KPI tiles for commits / PRs / reviews / longest streak. Code-tool aesthetic.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/bloomberg.png"><img src="examples/bloomberg.png" alt="bloomberg" /></a></td>
<td valign="top"><strong><code>bloomberg</code></strong> · <a href="examples/bloomberg.tsx">source</a><br/><br/><sub>Market dashboard styled like a Bloomberg Terminal — black background, monospaced amber-on-black, dense rows of tickers with bid / ask / last / chg / vol.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/editorial.png"><img src="examples/editorial.png" alt="editorial" /></a></td>
<td valign="top"><strong><code>editorial</code></strong> · <a href="examples/editorial.tsx">source</a><br/><br/><sub>Tall editorial data-story magazine spread on climate emissions — magazine-grade typography, inline charts, pull quotes, target-line annotations. Long-form data journalism feel.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/brutalist.png"><img src="examples/brutalist.png" alt="brutalist" /></a></td>
<td valign="top"><strong><code>brutalist</code></strong> · <a href="examples/brutalist.tsx">source</a><br/><br/><sub>Brutalist product spec card — flat saturated yellow, white inner panel with thick black borders, all-caps Inter, hard rectangles. 1990s industrial parts catalog energy.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/travelposter.png"><img src="examples/travelposter.png" alt="travelposter" /></a></td>
<td valign="top"><strong><code>travelposter</code></strong> · <a href="examples/travelposter.tsx">source</a><br/><br/><sub>1930s WPA-style travel poster for 'Iceland — Land of Fire and Ice' — flat geometric mountains and aurora, art deco type, limited 4-color palette, cream paper texture.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/vinyl.png"><img src="examples/vinyl.png" alt="vinyl" /></a></td>
<td valign="top"><strong><code>vinyl</code></strong> · <a href="examples/vinyl.tsx">source</a><br/><br/><sub>Square Blue Note Records-style jazz album cover — cool muted palette, bold sans serif credits, generous whitespace, one big abstract shape suggesting horns.</sub></td>
</tr>
<tr>
<td valign="top"><a href="examples/subway.png"><img src="examples/subway.png" alt="subway" /></a></td>
<td valign="top"><strong><code>subway</code></strong> · <a href="examples/subway.tsx">source</a><br/><br/><sub>Tokyo subway-map style schematic — 6 colored transit lines with named stations and interchange points. Geometric, 45° / 90° angles only, line legend, route numbers in colored circles.</sub></td>
</tr>
</table>
For 40+ more examples — anatomy diagrams, neon synthwave, NYT-style crosswords, tarot cards, illuminated manuscripts, weather widgets, sankey flows — see the full [poster-ai gallery](https://github.com/Michaelliv/poster#gallery).
## License
MIT