feat: add branching

CLAUDE.md

@@ -2,3 +2,51 @@
 - Unit tests can be run with `bun test`
 - Run type checking with `bun run typecheck`
 - Apply database updates to local dev with `bun run db:push`
+- Refrain from running the dev server
+
+## MobX + React Best Practices
+
+### Pattern for Provider Components with Observable Stores
+
+When creating React providers that manage MobX observable stores (like
+EditorEngine):
+
+**✅ DO:**
+
+- Use `useState(() => new Store())` for stable observable instances (MobX
+  recommended pattern)
+- Keep refs (`engineRef.current`) to avoid stale closures in effects
+- Use `setTimeout(() => store.clear(), 0)` for delayed cleanup to avoid race
+  conditions
+- Separate project changes from branch updates with proper dependency arrays
+
+**❌ DON'T:**
+
+- Use `useMemo` for observable references - React may randomly "forget" them
+  (data loss risk)
+- Clean up stores synchronously during navigation - causes "No branch selected"
+  errors
+- Include the store instance in effect dependency arrays if it causes infinite
+  loops
+
+### Example Pattern:
+
+```tsx
+const [store, setStore] = useState(() => new Store(props));
+const storeRef = useRef<Store | null>(store);
+
+useEffect(() => {
+    if (propChanged) {
+        setTimeout(() => storeRef.current?.clear(), 0); // Delayed cleanup
+        const newStore = new Store(newProps);
+        storeRef.current = newStore;
+        setStore(newStore);
+    }
+}, [propChanged]);
+
+useEffect(() => {
+    return () => setTimeout(() => storeRef.current?.clear(), 0);
+}, []);
+```
+
+This maintains MobX reactivity while preventing cleanup race conditions.

apps/backend/README.md

@@ -1,10 +1,13 @@
 ## Why a backend stack?
 
-This is our server stack built in Supabase which you can also run locally or self-host.
+This is our server stack built in Supabase which you can also run locally or
+self-host.
 
-Used to enable online capabilities such as managing users, collaborating, persisting data, etc.
+Used to enable online capabilities such as managing users, collaborating,
+persisting data, etc.
 
-We will offer this as a hosted instance at some point. Ideally, the product should still work offline with no backend connection.
+We will offer this as a hosted instance at some point. Ideally, the product
+should still work offline with no backend connection.
 
 ## Usage
 
@@ -14,17 +17,17 @@ We will offer this as a hosted instance at some point. Ideally, the product shou
 2. Install necessary packages
 
 ```bash
-npm install
+bun install
 ```
 
 3. Run the supabase instance locally
 
 ```bash
-npm run start
+bun run start
 ```
 
 4. Set up the latest snapshot of the database
 
 ```bash
-npm run reset
+bun run reset
 ```

apps/web/client/.gitignore

@@ -47,6 +47,3 @@ yarn-error.log*
 
 # mastra
 .mastra/
-
-# Ignore preload script changes unless the script should be updated. Uncomment to update.
-/public/onlook-preload-script.*

apps/web/client/messages/en.d.json.ts

@@ -287,6 +287,7 @@ declare const messages: {
                         "emptyState": "Select a window to edit its settings"
                     },
                     "brand": "Brand",
+                    "branches": "Branches",
                     "apps": "Apps"
                 }
             }

apps/web/client/messages/en.json

@@ -284,6 +284,7 @@
                         "emptyState": "Select a window to edit its settings"
                     },
                     "brand": "Brand",
+                    "branches": "Branches",
                     "apps": "Apps"
                 }
             }

apps/web/client/messages/es.json

@@ -284,6 +284,7 @@
                         "emptyState": "Seleccione una ventana para editar su configuración"
                     },
                     "brand": "Marca",
+                    "branches": "Ramas",
                     "apps": "Aplicaciones"
                 }
             }

apps/web/client/messages/ja.json

@@ -182,6 +182,7 @@
                         "emptyState": "編集するウィンドウを選択してください"
                     },
                     "brand": "ブランド",
+                    "branches": "ブランチ",
                     "apps": "アプリ"
                 }
             }

apps/web/client/messages/ko.json

@@ -284,6 +284,7 @@
                         "emptyState": "설정을 편집할 창(윈도우)을 선택하세요"
                     },
                     "brand": "브랜드",
+                    "branches": "브랜치",
                     "apps": "앱"
                 }
             }

apps/web/client/messages/zh.json

@@ -284,6 +284,7 @@
                         "emptyState": "选择一个窗口以编辑其设置"
                     },
                     "brand": "品牌",
+                    "branches": "分支",
                     "apps": "应用"
                 }
             }

apps/web/client/package.json

@@ -72,15 +72,15 @@
         "clsx": "^2.1.1",
         "culori": "^4.0.1",
         "date-fns": "^4.1.0",
-        "embla-carousel-react": "^8.6.0",
         "flexsearch": "^0.8.160",
         "freestyle-sandboxes": "^0.0.78",
         "langfuse-vercel": "^3.38.4",
         "localforage": "^1.10.0",
+        "lru-cache": "^11.2.1",
         "lucide-react": "^0.486.0",
         "mobx-react-lite": "^4.1.0",
         "motion": "^12.6.3",
-        "next": ">=15.4.7",
+        "next": ">=15.5.2",
         "next-intl": "^4.0.2",
         "next-themes": "^0.4.6",
         "octokit": "^5.0.3",
@@ -119,7 +119,7 @@
         "@types/react-dom": "^19.0.0",
         "@types/webfontloader": "^1.6.38",
         "eslint": "^9.23.0",
-        "eslint-config-next": "^15.2.3",
+        "eslint-config-next": "^15.5.2",
         "postcss": "^8.5.3",
         "prettier": "^3.5.3",
         "prettier-plugin-tailwindcss": "^0.6.11",

apps/web/client/src/app/_components/hero/start-blank.tsx

@@ -46,11 +46,11 @@ export function StartBlank({
             const newProject = await createProject({
                 project: {
                     name: 'New Project',
-                    sandboxId,
-                    sandboxUrl: previewUrl,
                     description: 'Your new blank project',
                     tags: ['blank'],
                 },
+                sandboxId,
+                sandboxUrl: previewUrl,
                 userId: user.id,
             });
 

apps/web/client/src/app/_components/landing-page/feature-blocks/responsive-website.tsx

@@ -1,6 +1,5 @@
-import React, { useState, useRef, useEffect } from 'react';
-import { Icons } from '@onlook/ui/icons';
-import { Menu, Laptop } from 'lucide-react';
+import { Laptop, Menu } from 'lucide-react';
+import React, { useEffect, useRef, useState } from 'react';
 
 export function ResponsiveWebsiteBlock() {
     const [websiteWidth, setWebsiteWidth] = useState(400); // Initial width in pixels
@@ -52,7 +51,7 @@ export function ResponsiveWebsiteBlock() {
     useEffect(() => {
         document.addEventListener('mousemove', handleMouseMove);
         document.addEventListener('mouseup', handleMouseUp);
-        
+
         return () => {
             document.removeEventListener('mousemove', handleMouseMove);
             document.removeEventListener('mouseup', handleMouseUp);
@@ -63,7 +62,7 @@ export function ResponsiveWebsiteBlock() {
         <div className="flex flex-col gap-4">
             <div className="w-full h-100 bg-[#2E2C2D] rounded-lg mb-6 relative overflow-hidden" ref={containerRef}>
                 {/* Mini Website Container */}
-                <div 
+                <div
                     className="h-80 bg-[#E5E3DE] rounded-lg border border-[#D1CFC9] shadow-lg absolute left-1/2 top-12 transform -translate-x-1/2"
                     style={{ width: `${websiteWidth}px` }}
                 >
@@ -92,7 +91,7 @@ export function ResponsiveWebsiteBlock() {
                             <h1 className="text-xl font-serif mb-3">Le Fidgette</h1>
                             <p className="text-xs opacity-90 mb-6 text-balance">Creating natural shapes inspired by the natural world.</p>
                         </div>
-                        
+
                         {/* "View Work" Button */}
                         <div className="w-24 bg-[#8E837D] p-2 text-center cursor-pointer hover:bg-opacity-90 transition-opacity mb-12">
                             <p className="text-[10px] text-white font-medium tracking-wider">VIEW WORK</p>
@@ -117,21 +116,21 @@ export function ResponsiveWebsiteBlock() {
                         </div>
                     </div>
                     {/* Responsive Handles */}
-                    <div 
+                    <div
                         className="absolute left-[-16px] top-1/2 transform -translate-y-1/2 p-4 py-20 -m-4 cursor-ew-resize group"
                         onMouseDown={(e) => handleMouseDown(e, 'left')}
                     >
                         <div className="w-1.5 h-20 bg-gray-400 group-hover:bg-gray-500 rounded-full transition-colors duration-200 shadow-lg"></div>
                     </div>
-                    <div 
+                    <div
                         className="absolute right-[-16px] top-1/2 transform -translate-y-1/2 p-4 py-20 -m-4 cursor-ew-resize group"
                         onMouseDown={(e) => handleMouseDown(e, 'right')}
                     >
                         <div className="w-1.5 h-20 bg-gray-400 group-hover:bg-gray-500 rounded-full transition-colors duration-200 shadow-lg"></div>
                     </div>
                 </div>
             </div>
-            
+
             <div className="flex flex-row items-start gap-8 w-full">
                 {/* Icon + Title */}
                 <div className="flex flex-col items-start w-1/2">

apps/web/client/src/app/project/[id]/_components/bottom-bar/terminal-area.tsx

@@ -10,20 +10,44 @@ import { Terminal } from './terminal';
 
 export const TerminalArea = observer(({ children }: { children: React.ReactNode }) => {
     const editorEngine = useEditorEngine();
-    const terminalSessions = editorEngine.sandbox.session.terminalSessions;
-    const activeSessionId = editorEngine.sandbox.session.activeTerminalSessionId;
+    const branches = editorEngine.branches;
 
-    const [terminalHidden, setTerminalHidden] = useState(true);
+    // Collect terminal sessions from all branches
+    const allTerminalSessions = new Map<string, { name: string; branchName: string; branchId: string; sessionId: string; session: any }>();
+    let activeSessionId: string | null = null;
+
+    for (const branch of branches.allBranches) {
+        try {
+            const branchData = branches.getBranchById(branch.id);
+            if (!branchData) continue;
+
+            // Get the sandbox manager for this branch
+            const sandbox = branches.getSandboxById(branch.id);
+            if (!sandbox?.session?.terminalSessions) continue;
+
+            for (const [sessionId, session] of sandbox.session.terminalSessions) {
+                const key = `${branch.id}-${sessionId}`;
+                allTerminalSessions.set(key, {
+                    name: session.name,
+                    branchName: branch.name,
+                    branchId: branch.id,
+                    sessionId: sessionId,
+                    session: session
+                });
 
-    if (!terminalSessions.size) {
-        return (
-            <div className="flex items-center justify-center h-full p-1 gap-2">
-                <Icons.LoadingSpinner className="animate-spin" />
-                <p className="text-foreground-secondary">Initializing Sandbox...</p>
-            </div>
-        )
+                // Set active session if this is the currently active branch and session
+                if (branch.id === branches.activeBranch.id && sessionId === sandbox.session.activeTerminalSessionId) {
+                    activeSessionId = key;
+                }
+            }
+        } catch (error) {
+            // Skip branches that aren't properly initialized
+            continue;
+        }
     }
 
+    const [terminalHidden, setTerminalHidden] = useState(true);
+
     return (
         <>
             {terminalHidden ? (
@@ -77,21 +101,43 @@ export const TerminalArea = observer(({ children }: { children: React.ReactNode
                     terminalHidden ? 'h-0 w-0 invisible' : 'h-[22rem] w-[37rem]',
                 )}
             >
-                <Tabs defaultValue={'cli'} value={activeSessionId} onValueChange={(value) => editorEngine.sandbox.session.activeTerminalSessionId = value}
-                    className="w-full h-full">
-                    <TabsList className="w-full h-8 rounded-none border-b border-border">
-                        {Array.from(terminalSessions).map(([id, terminal]) => (
-                            <TabsTrigger key={id} value={id} className="flex-1">{terminal.name}</TabsTrigger>
-                        ))}
-                    </TabsList>
-                    <div className="w-full h-full overflow-auto">
-                        {Array.from(terminalSessions).map(([id]) => (
-                            <TabsContent key={id} forceMount value={id} className="h-full" hidden={activeSessionId !== id}>
-                                <Terminal hidden={terminalHidden} terminalSessionId={id} />
-                            </TabsContent>
-                        ))}
+                {allTerminalSessions.size > 0 ? (
+                    <Tabs defaultValue={'cli'} value={activeSessionId || ''} onValueChange={(value) => {
+                        // Extract branch and session from the combined key
+                        const terminalData = allTerminalSessions.get(value);
+                        if (terminalData) {
+                            // Switch to the branch first
+                            editorEngine.branches.switchToBranch(terminalData.branchId);
+                            // Then set the active terminal session for that branch
+                            const sandbox = branches.getSandboxById(terminalData.branchId);
+                            if (sandbox) {
+                                sandbox.session.activeTerminalSessionId = terminalData.sessionId;
+                            }
+                        }
+                    }}
+                        className="w-full h-full">
+                        <TabsList className="w-full h-8 rounded-none border-b border-border overflow-x-auto justify-start">
+                            {Array.from(allTerminalSessions).map(([key, terminalData]) => (
+                                <TabsTrigger key={key} value={key} className="flex-1">
+                                    <span className="truncate">
+                                        {terminalData.name} • {terminalData.branchName}
+                                    </span>
+                                </TabsTrigger>
+                            ))}
+                        </TabsList>
+                        <div className="w-full h-full overflow-auto">
+                            {Array.from(allTerminalSessions).map(([key, terminalData]) => (
+                                <TabsContent key={key} forceMount value={key} className="h-full" hidden={activeSessionId !== key}>
+                                    <Terminal hidden={terminalHidden} terminalSessionId={terminalData.sessionId} branchId={terminalData.branchId} />
+                                </TabsContent>
+                            ))}
+                        </div>
+                    </Tabs>
+                ) : (
+                    <div className="flex items-center justify-center h-full text-muted-foreground">
+                        <span className="text-sm">No terminal sessions available</span>
                     </div>
-                </Tabs>
+                )}
             </div >
         </>
     );