This repository has been archived and is frozen. No new features, bug fixes, or commits will be made. It is preserved here for historical reference only.
A web application that recreates the GitHub Spark experience: authenticate with an AI provider, describe your idea in plain language, and get a fully functional React application generated in seconds. Iterate with refinements, preview live, and export as a ZIP.
- AI Code Generation — Generate complete React + TypeScript applications from a text prompt using GitHub Models or 1min.ai
- Live Preview — Instantly preview the generated app directly in the browser (no iframe, executed via
new Function()in the React context) - Iterative Refinement — Refine the current generation with follow-up instructions; full refinement history with rollback support
- AI Suggestions — Automatically generates 3–5 contextual improvement suggestions after each generation
- Code Viewer — Browse generated files in a resizable split panel with syntax highlighting and inline editing
- Split View — Side-by-side code + preview layout
- Generation History — Persist up to 10 projects per provider (+ 2 pinned), with session restore on reload
- Export to ZIP — Download any generation as a ZIP archive ready for local development
- Multi-Provider — Pluggable provider architecture; currently supports GitHub Models and 1min.ai
- Model Routing — Per-task model selection (generate / refine / review / suggest) with quality tiers (quality / intermediate / fast)
- Token Usage — Real-time token counter displayed per session
- Raw Response Inspector — Inspect and replay the raw LLM response for debugging
| Layer | Technology |
|---|---|
| UI Framework | React 19 + TypeScript |
| Build Tool | Vite 7 + SWC |
| Styling | Tailwind CSS v4 + shadcn/ui (Radix UI) |
| Icons | Phosphor Icons + Lucide |
| AI Runtime | esbuild-wasm (in-browser compilation) |
| Data Viz | Recharts + D3 |
| Forms | React Hook Form + Zod |
| Animations | Framer Motion |
| Export | JSZip |
| State | React hooks + localStorage |
| Toasts | Sonner |
src/
├── App.tsx # Main application shell & orchestration
├── components/
│ ├── CodeViewer.tsx # Syntax-highlighted file viewer with inline edit
│ ├── FileTree.tsx # Generated file tree navigation
│ ├── GenerationHistory.tsx # History panel
│ ├── GenerationLoader.tsx # Generation progress indicator
│ ├── LivePreview.tsx # In-browser live preview renderer
│ ├── RawResponseEditor.tsx # LLM raw response inspector & replay
│ ├── RefinementHistory.tsx # Refinement steps timeline with rollback
│ ├── SuggestionCard.tsx # AI improvement suggestion card
│ └── ui/ # shadcn/ui component library
├── hooks/
│ ├── use-generation-engine.ts # Core generation / refine / suggest orchestration
│ ├── use-suggestions-engine.ts # AI suggestions pipeline
│ ├── use-template-files.ts # Template loader hook
│ ├── use-local-storage.ts # Typed localStorage hook
│ └── use-mobile.ts # Responsive breakpoint hook
├── lib/
│ ├── generation-pipeline.ts # Full generate → parse → validate → merge pipeline
│ ├── prompt-builders.ts # System / generate / refine / review / suggest prompts
│ ├── model-router.ts # Task-based model & token-limit resolution
│ ├── output-validator.ts # Validates generated files against the template contract
│ ├── response-parser.ts # Parses LLM JSON output into file objects
│ ├── json-repairer.ts # Repairs malformed JSON from LLM responses
│ ├── code-reviewer.ts # Post-generation code review pass
│ ├── template-loader.ts # Loads the Spark template files at runtime
│ ├── template-manifest.ts # Declares allowed/forbidden files and imports
│ ├── token-estimator.ts # Client-side token count estimation
│ ├── observability.ts # Generation tracing (model, duration, tokens, files)
│ ├── retry.ts # Retry + exponential backoff for LLM calls
│ ├── export.ts # ZIP export logic
│ ├── syntax-highlighter.ts # PrismJS-based syntax highlighting
│ └── utils.ts # Shared utilities (cn, etc.)
├── providers/
│ ├── types.ts # AIProvider interface + AuthenticatedUser type
│ ├── github-models/ # GitHub Models provider (PAT-based)
│ └── 1minai/ # 1min.ai provider (API key-based, disabled by default)
└── types/
└── index.ts # Shared domain types (Generation, Suggestion, etc.)
- Node.js 20+
- pnpm (recommended) or npm
- A GitHub Personal Access Token with
models:readpermission (for GitHub Models provider)
pnpm installpnpm devThe app runs on http://localhost:5173 by default.
pnpm buildpnpm preview- Go to github.com/settings/tokens
- Generate a new token (classic or fine-grained) with
models:readscope - Paste it in the app login screen
Credentials are stored in sessionStorage (cleared when the tab closes) and never sent to any server other than models.github.ai via the Vite dev proxy.
Disabled by default. To enable it, set enabled: true in src/providers/1minai/index.ts and provide your 1min.ai API key.
User prompt
└─ intent classification (task type)
└─ model routing (modelId + tokenLimit per task)
└─ prompt builder (system + task prompts)
└─ callLLM (streaming or JSON mode)
└─ response parser (JSON → GeneratedFile[])
└─ JSON repairer (if malformed)
└─ output validator (allowed files, imports, export default)
└─ code reviewer (optional review pass)
└─ template merge (inject into Spark template)
└─ Generation saved → suggestions triggered
All providers implement the AIProvider interface (src/providers/types.ts):
interface AIProvider {
authenticate(credential: string): Promise<AuthenticatedUser>
loadModelConfigs(): Promise<ModelConfig[]>
callLLM(user: AuthenticatedUser, options: CallLLMOptions): Promise<string>
}Adding a new provider requires implementing this interface and registering it in App.tsx.
Three named tiers are defined per provider:
| Tier | Use case |
|---|---|
quality |
Initial generation, complex apps |
intermediate |
Default — balanced speed/quality |
fast |
Quick refinements and suggestions |
Each tier maps every task (generate, refine, review, suggest) to a specific modelId and tokenLimit.
| Scope | Hook | Storage |
|---|---|---|
| Builder history & session | useLocalStorage |
localStorage |
| Authentication credentials | — | sessionStorage (tab-scoped) |
| Generated app state | useKV (injected into generated code) |
Spark KV (in generated apps only) |
These boundaries must never cross:
useKVmust not be used in builder code.
pnpm dev # Start dev server
pnpm build # Production build
pnpm preview # Preview production build
pnpm lint # Run ESLint
# BMAD tooling
pnpm tools:bmad:status # Check BMAD method status
pnpm tools:bmad:update # Update BMAD method
pnpm tools:bmad:viewer # Open BMAD viewerMIT