blastimage

Local Next.js app for coordinated AI image generation workflows. Define prompt tasks, attach reference photos, generate batches, review and iterate, then export approved images with a full provenance manifest.

Install & Run

npm install
npm run dev   # http://127.0.0.1:3003
npm test      # vitest + happy-dom
npx playwright install chromium webkit   # once
npm run test:e2e   # Playwright on :3009 (`just dev` on :3003 can stay up)

The local app supports desktop browsers at least 1024 px wide. Phones aren't supported, since the server is loopback-only. The public landing/ page is separate.

Commits are gated by a gitleaks secret scan (.pre-commit-config.yaml, tuned by .gitleaks.toml). The config is inert until the hook is armed, and arming is per clone — a fresh checkout scans nothing until you run it:

brew install gitleaks && uv tool install pre-commit   # once per machine
pre-commit install                                    # once per clone

Dependencies are gated in CI (npm audit --omit=dev --audit-level=high, last step of the main job in .github/workflows/ci.yml; the landing job runs the same audit on landing/). Dependabot version-update PRs are off by policy (open-pull-requests-limit: 0 on every entry in .github/dependabot.yml, landing/ included); Dependabot alerts and security updates are enabled (DEPLOY-014.5) and come from the repo's Dependabot setting (Settings → Code security), not from that file. GitHub secret scanning and push protection are enabled there too (CORE-014), on top of gitleaks, not instead of it. The same workflow runs a pinned gitleaks working-tree scan (separate secrets job) as the backstop for clones that never armed the pre-commit hook, and a Playwright e2e job (TEST-007.2) on port 3009.

Workflow

Adopter loop (terminal generate → frontend review)

For submodule adopters, generation runs in a Grok Build terminal session and blastimage is the viewer/selector — the browser never generates. Full contract: docs/REVIEW-LOOP.md.

1. Stage — imagegen/tasks.json + optional refs/ in the host repo (see docs/ADOPT.md §7).
2. Generate — /blast-generate in a terminal session writes imagegen/rounds/r<N>/ + batch.json.
3. Link & load — in blastimage, the sidebar ⋯ menu's 🔗 Link imagegen opens a folder picker (detected imagegen/ folders on top, browse from there, or type an absolute path); every rounds/rN/ auto-ingests, and ↻ Refresh rounds on the open rail re-lists and pulls in new ones. Works in any browser. The folder belongs to the project, not the app: the sidebar header names it, switching project re-links its own folder, and a folder another project already owns is refused with an offer to switch to it. Linking a folder into a fresh, unnamed project names that project after the repo.
4. Review & iterate — keep/approve/discard, rate, edit prompts; iterate writes selection.json (not in-browser generation). Click any thumbnail to view it full-size (← / → step through the round; K / D / A decide and 0–5 rate without leaving it). Renaming a loaded task changes the slug joining it to the files on disk, so the app confirms first — keep imagegen/tasks.json in step if you accept. Deleting one breaks the same join: the app names what stays behind in your repo (approved copies, the task's selection.json entry, the round images) and offers to clear the first two for you — the rounds/ files are never touched, and the task returns on the next load until you remove it from imagegen/tasks.json.
5. Next round — /blast-iterate reads selection.json and writes the next round; repeat until satisfied.
6. Export — approved images land in imagegen/approved/; promote to your site assets.

Install terminal skills from the submodule: docs/ADOPT.md §5.1.

In-app loop (Grok Build only)

This mode only works when blastimage itself runs inside a Grok Build session with the provider bridge wired (docs/GROK-AGENT.md) — a plain browser tab (including a submodule adopter's) has no bridge to call, so Generate stays disabled with the reason stated. When the bridge is present, generation stays in-browser:

1. Create a project — a default session opens on first launch; rename it from the header, or create a new one from the sidebar ⋯ menu.
2. Add tasks — each task has a base prompt and an optional reference photo selection (up to 3 active at once from the session library). To stage many at once, 🛠 Build in the ⋯ menu composes a tasks.json from pasted prompts or prompts/*.txt files, and ⇪ Import loads such a file into the session.
3. Generate — click Generate to produce a batch of candidate images via Grok Imagine. ⚡ Generate All in the sidebar fires a batch for every eligible task at once and opens a stacked bulk-review view for one-pass review across tasks, headed by an N of M tasks decided count and a jump link to each task's section. In a plain browser the button is hidden and the header shows Viewer.
4. Review — keep, discard, or approve each image; each sidebar task shows its undecided / kept / approved counts for the round in view. Clicking the active decision clears it; clearing an approve is fully reversible — the image is removed from imagegen/approved/ and its selection.json entry is rewritten, so a mis-click needs no manual cleanup. imagegen/approved/ is keyed by filename, so approving the same task from a later round would land on the same name — the app confirms first and never replaces an earlier approval silently. Add star ratings and feedback notes. Toggle Use as reference to seed the keeper into the next round. Click any thumbnail (review grid or Gallery) to view it full-size; ← / → step through the set. From the review grid the enlarged view is a review surface too: it shows the prompt and any saved feedback, carries the same Keep / Discard / Approve, stars, Feedback and Iterate controls, and takes K / D / A to decide and 0–5 to rate while it is open.
5. Iterate — undecided cards show Iterate → disabled until Keep (Keep this image first). Click Iterate → on a kept image to open the refine modal, edit the prompt, and generate a new round seeded by that image as the primary reference. Discarded and approved cards omit it (approved is final).
6. Export — approved images collect in the Gallery panel. Folder writes every approved image plus a manifest.json provenance file (full prompt history and reference metadata) into a directory you pick, in one step — falling back to individual downloads on browsers without folder access. JSON downloads the provenance manifest on its own. downloads a self-contained (embedded thumbnails + prompt, rating, and provenance per image) for a repo-durable house-style/consistency pass.

Sessions persist in localStorage — no accounts, no cloud project. Use ⤓ Export / ⤒ Import in the sidebar ⋯ menu to back up a whole workspace to a .json file and restore it (Import lands it as a fresh copy), so a project can move between browsers or devices.

A stored project written by a different schema version — or one whose saved data is corrupt — cannot be opened. Rather than starting over in silence, blastimage names it in a banner (at launch, and again if you pick it from the Project switcher) and leaves its data untouched in browser storage.

Docs

• VISION.md — product vision and the two generation modes
• docs/REVIEW-LOOP.md — terminal-generate / frontend-review loop (adopter SSOT)
• docs/WORKFLOW.md — the directed adopter operating loop, stage to landed assets
• docs/USAGE.md — prompt-writing conventions and reference image preparation
• docs/ADOPT.md — how to add blastimage as a git submodule in another project
• docs/GROK-AGENT.md — Grok Build integration guide for wiring real Grok Imagine
• landing/README.md — the blastimage.com landing page (Astro, Cloudflare Worker; not part of the app)
• AGENTS.md — coding standards and AI workflow (agent-neutral SSOT; CLAUDE.md is the Claude-only addendum)
• .flaitron/PLAN.md — task plan and status