Stream branching and seeding stages during sandbox prep

[exekias]

Summary

Branch preparation previously ran as a single opaque server-side step behind a static "Forking a fresh Postgres branch…" spinner — the user couldn't tell whether the branch was being forked or seeded. This differentiates the two stages and streams them live.

• The slow create/seed work moves out of the server component into a new streaming NDJSON endpoint (/api/lessons/[slug]/prepare) that emits distinct branching → seeding → ready (or error) phase events.
• A new client bootstrapper drives the stream on first visit and shows a live two-step checklist, then refreshes into the interactive panel. Reset uses the same stream, so it shows the same phased progress instead of a generic "Resetting sandbox…".
• The server component (SandboxSection) now only does the fast "is a ready branch present?" check, so it streams in quickly; creation is client-driven (after hydration), which is what enables the live progress.

Lessons-.-Learn-Postgres.mp4

Changed

• lib/branch-manager.ts — ensureBranchForLesson/resetBranchForLesson accept an optional onPhase callback; new getReadyBranch() for the fast existence check.
• app/api/lessons/[slug]/prepare/route.ts (new) — streaming endpoint, handles create and reset.
• components/lesson/SandboxBootstrap.tsx, SandboxPrepProgress.tsx, usePrepareStream.ts (new) — client bootstrapper, shared checklist UI, and the NDJSON-reading hook.
• SandboxSection.tsx / SandboxPanel.tsx / SandboxLoading.tsx — updated to the new flow.
• Removed app/api/lessons/[slug]/reset/route.ts (its only caller now uses /prepare).

Test plan

• tsc --noEmit, eslint, and next build pass.
• Not verified in-browser (auth-gated + needs real Xata credentials): open a lesson logged in and confirm the checklist advances Forking → Seeding → ready on first load.
• Click Reset and confirm the same phased progress shows, then the panel refreshes with the new branch.
• Trigger a failure (e.g. bad seed / rate limit) and confirm the inline error + "Try again" path works.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
learn-postgres	Ready	Preview	May 25, 2026 1:09pm