truepane

# Truepane

**Truepane** is a small, fast, browser-based app screenshot generator for the App Store
and Google Play — title + subhead text, a device frame, your screenshot, and a generated
background, exported as individual PNGs, a horizontal strip, or a ZIP.

Everything renders to `<canvas>` in the browser. Screenshots stay on your machine.
Optional AI helpers send only the text you ask them to process (and, when supplied,
your Groq API key) to the configured Edge Function and model provider. Google Fonts
are also loaded from Google's CDN unless you use a system or uploaded font.

## Why this exists

Most screenshot generators composite a pre-rendered PNG of a phone. This one **draws
the device frame procedurally** on a canvas — body, bezel, buttons, camera, and the
screen mask are all geometry, not bitmaps. That choice drives most of what makes the
tool small, sharp, and cheap to run.

## Features

- **Procedural device frames** at exact store sizes: iPhone 6.9″ (1320×2868), iPad 13″
  (2064×2752), Android phone (1080×2400), Android tablet (1600×2560).
- **Backgrounds = fill + shape.** A fill layer (solid, or linear/radial gradient) plus an
  optional shape overlay (rings, blobs, waves, dots, mesh, arcs, triangles, grid, zigzag,
  bubbles), each with independent colors. Shapes flow continuously across the strip and
  reproduce exactly from a stored seed.
- **Color tools**: content-based palette extraction from your screenshot, harmonized shape
  suggestions, an eyedropper (native EyeDropper API + a click-a-slide fallback for
  Safari/Firefox), and curated color-science presets.
- **AI prompt → style** (optional): describe a vibe ("calm, warm, organic") and a Groq
  model returns a style + palette. Bring your own Groq key, or use the hosted endpoint.
- **Typography**: curated Google Fonts (incl. Apple/Android system fonts and Noto
  multi-script + CJK) plus custom `.ttf/.otf/.woff(2)` upload.
- **Flexible composition**: choose a preset or place text and devices directly,
  resize them, rotate devices from −20° to +20°, and drag or nudge mockups on canvas.
- **Cross-slide devices**: span one synchronized device across two adjacent slides.
  Both clipped halves share their screenshot, position, scale, and rotation.
- **Export**: per-slide PNG, one horizontal strip PNG, or a ZIP of everything. Plus JSON
  project import/export. State auto-saves to `localStorage`.
- **Multi-platform projects**: keep separate iPhone, iPad, Android phone, and Android
  tablet captures on the same ordered slides. Locale screenshots fall back only to
  their own target's source capture; they never borrow another platform's image.
- **Preview-first bulk import**: choose a folder or ZIP, review deterministic
  target/locale/slide mappings, correct rows, then apply once. Explicit
  `target/locale/NN-name.png` paths take priority; conflicts never overwrite silently.
- **Shared release preflight**: the editor and MCP report the same stable issue
  codes for missing captures/translations, locale fallbacks, crop risk, composition,
  fonts, and fill/text contrast. Warnings are advisory and require “export anyway”
  in the web editor.
- **Local brand kits**: save typography, text colors, background, custom font, and
  default composition for reuse. Kits are portable `.truepane-brand.json` files and
  never contain slides, screenshots, targets, translations, credentials, or history.
- **Flexible output surfaces**: keep the four native store screenshot sizes, render a
  Google Play feature graphic at exactly 1024×500, or choose bounded custom dimensions.
  The procedural device is scaled and placed as a layer; captures are never stretched.
- **Release update mode**: explicitly save deterministic release signatures, compare
  added/changed/unchanged/removed assets later, and export a changed-only ZIP with a
  manifest. Baselines contain hashes, not rendered PNGs, and never update implicitly.

## Design decisions (the interesting part)

Each of these was a deliberate fork, chosen for a reason:

- **Procedural frames, not image mockups.** The target is *flat store-submission*
  screenshots at exact required resolutions — which procedural drawing nails: crisp at
  any scale, no asset pipeline, and **no licensing exposure** (most "free" device-mockup
  packs are not actually clean for commercial redistribution). Flat 2D rotation is
  supported; perspective and photographic mockups remain out of scope.
- **Parametric backgrounds, not diffusion images.** Backgrounds are seeded procedural
  shapes that reproduce exactly and stay tasteful. A raster image model would be
  unpredictable, costly per call, hard to keep consistent across a set, and would force a
  heavier backend. AI is used only as a thin **prompt → parameters** layer.
- **Content-based palette** runs entirely client-side — no model, no cost.
- **$0-egress architecture.** The app is static and all image work happens in the
  browser, so hosting bandwidth is effectively free. The only metered cost is the
  optional AI prompt call, which is rate-limited and can be replaced with your own key.

## Architecture

- **`src/render.ts`** — the rendering engine. Pure canvas drawing, no React. Defines the
  device frames and paints every pixel.
  - **Concentric-corner invariant:** the BODY / BEZEL / SCREEN rounded rects share a
    center of curvature (`x + r` equal across all three; same for `y + r`). Breaking it
    produces "laddery" corner kinks. New frames go through `defineFrame()`, which throws
    on violation; the `shell()` helper derives the inner rects so the invariant holds by
    construction.
  - Backgrounds render in two layers: a **fill** (solid / linear / radial gradient) then an
    optional **shape** overlay from a generator registry. Each shape lays out in strip-space
    so it flows across slides; a seeded `mulberry32` PRNG keeps a strip reproducible.
  - Masking uses offscreen canvases with `destination-in` / `destination-out` (rather
    than `ctx.clip()`) to get antialiased edges.
- **`src/App.tsx`** — single source of truth for `{ slides, settings }`, persistence
  (`localStorage`), font loading, and all export paths.
- **`src/Sidebar.tsx`** — the control panel. **`src/components.tsx`** — reusable controls
  and the slide preview. **`src/palette.ts`** — screenshot palette extraction.
  **`src/ai.ts`** — client for the AI endpoint.
- **`supabase/functions/generator-bg-prompt/`** — the Edge Function that turns a prompt
  into validated, clamped style params (raw model output never reaches the renderer).

## Running locally

```sh
npm install
npm run dev        # http://localhost:5173
npm run build      # tsc -b && vite build → dist/
npm run preview    # serve the production build
npm run typecheck
npm test           # vitest (pure-logic suite)
```

## Configuration

The AI prompt feature is optional. Without it, the app is fully functional and the
AI controls are hidden. To enable them, copy `.env.example` to `.env` and opt in:

```
VITE_ENABLE_AI=true
VITE_BG_PROMPT_URL=https://YOUR-PROJECT.supabase.co/functions/v1/generator-bg-prompt
VITE_SUPABASE_ANON_KEY=your-anon-key
```

The Edge Function reads `GROQ_API_KEY` from its Supabase secrets (and an optional
`BG_PROMPT_MODEL`, default `llama-3.3-70b-versatile`). Deploy it with:

```sh
supabase functions deploy generator-bg-prompt --project-ref YOUR-REF --no-verify-jwt
```

Server-side rate limiting is currently best-effort (in-memory, per isolate). Add a
durable limiter before a high-traffic public launch.

### Temporary beta gate

A soft, client-side password gate can be enabled during private beta by setting
`VITE_GATE_PASSWORD_HASH` to the SHA-256 of your password (unset = no gate):

```sh
printf '%s' 'your-password' | shasum -a 256   # put the hash in .env
```

It's a deterrent, not real security (it's a static client app) — meant to be removed
after beta.

## Use with AI agents (MCP)

Truepane ships a local [MCP](https://modelcontextprotocol.io) server, so an AI agent
(Claude Code, Codex, …) can take simulator screenshots and turn them into store-ready
slides without a human driving the browser UI. It renders with a native canvas
(`@napi-rs/canvas`) — screenshots are read from local paths and PNGs are written to
local paths; nothing is uploaded anywhere, and no configuration or env vars are
needed: the agent is the LLM, so styling and translation are its own judgment calls
(the web app's AI helpers are not involved).

It's a standard stdio MCP server published to npm as
[`truepane-mcp`](https://www.npmjs.com/package/truepane-mcp), so any MCP-capable
client can launch it with `npx -y truepane-mcp` — no checkout needed. Setup for
the common ones:

**Claude Code**

```sh
claude mcp add truepane -- npx -y truepane-mcp
```

**Codex CLI** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.truepane]
command = "npx"
args = ["-y", "truepane-mcp"]
```

**Cursor, Windsurf, Claude Desktop, and other JSON-config clients** — add to the
client's `mcpServers` block (e.g. `.cursor/mcp.json`,
`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "truepane": { "command": "npx", "args": ["-y", "truepane-mcp"] }
  }
}
```

The server lives in [`packages/truepane-mcp`](packages/truepane-mcp). To run it
from a repo checkout instead (for development), point the client's command at
`npx tsx server/mcp/index.ts`, or `npm run mcp:build` and run
`node packages/truepane-mcp/dist/index.js`.

### Workflow the tools expect

1. `list_options` — start here to discover the full workflow, platforms (with exact
   store pixel sizes), output surfaces, fonts, fills, shapes, and composition presets.
2. `create_project` — slide titles/subheads + absolute screenshot file paths. Pass
   `targets` to start a multi-platform project.
3. `set_style` — colors, background, typography (font, `titleScale`/`subtitleScale`,
   and `titleWeight`/`subtitleWeight` from 100–900), chosen with the agent's own
   design judgment (`suggest_palette_from_screenshot` extra