Shotluma

An AI-first, local-first canvas editor for creating complete iOS App Store screenshot sets in the browser. The AI agent builds real, editable designs instead of flattening your ideas into generated images.

Describe your app, upload raw screenshots, and an AI agent designs the full set — not as opaque bitmaps, but by driving the same editor operations you'd use by hand. Every text layer, gradient, shape, and device mockup it places stays a real canvas element: select it, restyle it, move it, or redo it manually. Then export every artboard at exact store resolutions.

Projects live entirely in your browser — no Shotluma account or project backend. The editor itself works without AI credentials. For AI generation, connect a local Codex app/CLI signed in with your ChatGPT plan, or bring your own provider key.

Features

• AI that designs, not renders — the agent works through editor tool calls, so its output is a normal project: every element it creates is selectable and editable, and you can revise a single screen with the magic-cursor action instead of regenerating everything.
• Use your ChatGPT plan — connect the Codex app or CLI to the hosted editor without giving Shotluma an API key.
• Bring your own model — also works with Moonshot, Google, Qwen, OpenAI, Anthropic, xAI, OpenRouter, and OpenCode Zen/Go; pick provider and model per run.
• Full screenshot sets — design a multi-screen story on portrait artboards, not one image at a time.
• Direct manipulation — typography, gradients, shapes, images, mockups, alignment, stacking, and spacing are all hand-editable, with or without AI.
• Perspective device mockups — drop a raw screenshot into a device frame with correct 3D geometry.
• Local-first — projects and uploads are stored in IndexedDB in your browser.
• Store-ready export — download the whole set as 1290 × 2796 or 1242 × 2688 PNGs in one ZIP.

Refine one screen with AI

Select any artboard, describe the change, and let the AI agent revise just that screen. The result uses the same editor operations as the full-set generator and stays fully editable.

Quick start

Requires Bun 1.3+ and a current desktop browser.

bun install
bun run dev

Open http://127.0.0.1:4173 and start editing.

Using the editor

1. Start from a template or an empty screen.
2. Add text, device mockups, shapes, backgrounds, or uploads from the left sidebar.
3. Select an element to edit it; drag the handles to move, resize, or rotate.
4. Drop an uploaded PNG, JPG, or WebP anywhere on the canvas — or into a selected device frame.
5. Optionally use Generate with AI to create a set, or the magic-cursor action on a single screen to revise just that screen.
6. Export all as ZIP and pick a format.

Projects save automatically to the current browser profile. Clearing site data deletes them, so export anything important before wiping browser storage.

Set up AI generation

The recommended hosted flow uses your ChatGPT plan and needs no API key:

1. Open app.shotluma.com, choose Generate with AI, select a Codex model, and click Connect Codex.
2. Click Open in ChatGPT. The desktop app opens a new local Codex chat with the setup prompt filled in; press Send. If the app is unavailable, copy the prompt and paste it into the Codex app or CLI instead.
3. Let Codex download and inspect Shotluma's small local connector. Return to the browser and click Check connection.
4. Keep using the hosted editor normally. You do not clone, build, or self-host Shotluma.

The connector listens only on 127.0.0.1, accepts the exact paired Shotluma origin and a random browser pairing token, and delegates authentication to Codex App Server. It does not read or copy ChatGPT tokens. Codex must already be installed and signed in with ChatGPT on that computer. Stop it with the same runtime used during setup: node ~/.local/share/shotluma/shotluma-codex-bridge.mjs stop or bun ~/.local/share/shotluma/shotluma-codex-bridge.mjs stop.

Alternatively, enter a provider key in the generation dialog (API keys / Enter API key). Keys are stored unencrypted in this browser's localStorage. Use dedicated keys with restrictive quotas, and remove them before sharing the browser profile or device.

For local development you can still use .env.local as a fallback:

cp .env.example .env.local

VITE_MOONSHOT_API_KEY=
VITE_GOOGLE_GENERATIVE_AI_API_KEY=
VITE_ALIBABA_API_KEY=
VITE_OPENAI_API_KEY=
VITE_ANTHROPIC_API_KEY=
VITE_XAI_API_KEY=
VITE_OPENCODE_API_KEY=

Restart the dev server after changing .env.local keys. Pick the provider and model in the generation dialog — models with configurable reasoning also expose their effort levels there. If a selected provider has no key, the dialog offers Enter API key and disables generation until one is saved.

How it works, and what to know:

• Codex runs go from the hosted browser to the paired loopback connector and then to Codex App Server. The connector exposes only the account, model, thread, turn, and Shotluma dynamic-tool RPC surface; Codex gets a read-only empty workspace with network access disabled.
• Google, Qwen, OpenAI, Anthropic, xAI, and OpenRouter are called directly from the browser via the AI SDK. Moonshot works only on localhost through the local /api/moonshot CORS proxy. OpenCode Zen and Go use a same-origin /api/opencode proxy (Vite locally, Cloudflare Worker when hosted) because those APIs do not answer browser CORS preflight. Models without native vision send screenshots and previews through a second OpenCode vision model first.
• When you start a run, your description and selected screenshots are sent to the selected provider or through Codex. Normal editing, persistence, and export never call any AI service. Provider limits or charges may apply.
• Browser-stored keys are visible to same-origin JavaScript by design. Optional VITE_* keys are exposed only by the local dev server; production builds replace every provider env key with an empty value. Never commit .env.local (see Self-hosting).
• Prompts can be written in any language; generated canvas copy and summaries are in English.

For debugging, set SHOTLUMA_AI_LOGGING=true in .env.local to write one JSON file per run to the git-ignored ai-logs/ directory. Logs record provider, model, timing, visible model output, tool activity, and token usage — never prompt text, screenshots, or API keys.

Commands

Changes to rendering, export, or AI behavior also need manual verification in the browser — the automated suite doesn't cover pixels.

Self-hosting

bun run build produces a static app in dist/, including the downloadable Codex connector at codex/shotluma-codex-bridge.mjs. Provider env values are stripped from the bundle, so it can be hosted as a static site while users connect Codex or supply their own direct-provider keys in the browser. OpenCode on a hosted origin also needs the /api/opencode Worker in scripts/shotluma-worker.ts (the official app.shotluma.com deploy includes it).

The official editor is deployed at https://app.shotluma.com. The marketing site at https://shotluma.com is maintained and deployed separately; its source and production configuration are not part of this repository.

Codex connection prompts pair against the deployment's own origin. Google, Qwen, OpenAI, Anthropic, xAI, OpenRouter, and OpenCode work with browser-entered keys. Moonshot remains local-only; offering it on a hosted deployment requires an authenticated proxy. A hosted workflow with shared credentials likewise needs a backend or short-lived credential exchange.

Architecture

Shotluma is a single-package React 19 + TypeScript + Vite + Tailwind CSS app.

src/App.tsx              Application composition
src/app/                 Project lifecycle, app shell, and export
src/editor/              History, ed