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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗