feat: add branching

apps/web/client/src/app/project/[id]/_components/canvas/frame/gesture.tsx

@@ -1,7 +1,7 @@
 import { useEditorEngine } from '@/components/store/editor';
 import type { FrameData } from '@/components/store/editor/frames';
 import { getRelativeMousePositionToFrameView } from '@/components/store/editor/overlay/utils';
-import type { DomElement, ElementPosition, WebFrame } from '@onlook/models';
+import type { DomElement, ElementPosition, Frame } from '@onlook/models';
 import { EditorMode, MouseAction } from '@onlook/models';
 import { toast } from '@onlook/ui/sonner';
 import { cn } from '@onlook/ui/utils';
@@ -10,7 +10,7 @@ import { observer } from 'mobx-react-lite';
 import { useCallback, useEffect, useMemo } from 'react';
 import { RightClickMenu } from './right-click';
 
-export const GestureScreen = observer(({ frame, isResizing }: { frame: WebFrame, isResizing: boolean }) => {
+export const GestureScreen = observer(({ frame, isResizing }: { frame: Frame, isResizing: boolean }) => {
     const editorEngine = useEditorEngine();
 
     const getFrameData: () => FrameData | undefined = useCallback(() => {
@@ -94,19 +94,19 @@ export const GestureScreen = observer(({ frame, isResizing }: { frame: WebFrame,
         () =>
             throttle(async (e: React.MouseEvent<HTMLDivElement>) => {
 
-            if (editorEngine.move.shouldDrag) {
-                await editorEngine.move.drag(e, getRelativeMousePosition);
-            } else if (
-                editorEngine.state.editorMode === EditorMode.DESIGN ||
-                ((editorEngine.state.editorMode === EditorMode.INSERT_DIV ||
-                    editorEngine.state.editorMode === EditorMode.INSERT_TEXT ||
-                    editorEngine.state.editorMode === EditorMode.INSERT_IMAGE) &&
-                    !editorEngine.insert.isDrawing)
-            ) {
-                await handleMouseEvent(e, MouseAction.MOVE);
-            } else if (editorEngine.insert.isDrawing) {
-                editorEngine.insert.draw(e);
-            }
+                if (editorEngine.move.shouldDrag) {
+                    await editorEngine.move.drag(e, getRelativeMousePosition);
+                } else if (
+                    editorEngine.state.editorMode === EditorMode.DESIGN ||
+                    ((editorEngine.state.editorMode === EditorMode.INSERT_DIV ||
+                        editorEngine.state.editorMode === EditorMode.INSERT_TEXT ||
+                        editorEngine.state.editorMode === EditorMode.INSERT_IMAGE) &&
+                        !editorEngine.insert.isDrawing)
+                ) {
+                    await handleMouseEvent(e, MouseAction.MOVE);
+                } else if (editorEngine.insert.isDrawing) {
+                    editorEngine.insert.draw(e);
+                }
             }, 16),
         [editorEngine, getRelativeMousePosition, handleMouseEvent],
     );
@@ -148,9 +148,9 @@ export const GestureScreen = observer(({ frame, isResizing }: { frame: WebFrame,
         if (!frameData) {
             return;
         }
-        
+
         editorEngine.move.cancelDragPreparation();
-        
+
         await editorEngine.move.end(e);
         await editorEngine.insert.end(e, frameData.view);
     }

apps/web/client/src/app/project/[id]/_components/canvas/frame/index.tsx

@@ -1,14 +1,13 @@
-import { FrameType, type Frame, type WebFrame } from '@onlook/models';
+import { type Frame } from '@onlook/models';
 import { observer } from 'mobx-react-lite';
-import { useRef, useState } from 'react';
+import { useState } from 'react';
 import { GestureScreen } from './gesture';
 import { ResizeHandles } from './resize-handles';
 import { RightClickMenu } from './right-click';
 import { TopBar } from './top-bar';
-import { WebFrameComponent, type WebFrameView } from './web-frame';
+import { FrameComponent } from './view';
 
 export const FrameView = observer(({ frame }: { frame: Frame }) => {
-    const webFrameRef = useRef<WebFrameView>(null);
     const [isResizing, setIsResizing] = useState(false);
 
     return (
@@ -17,14 +16,12 @@ export const FrameView = observer(({ frame }: { frame: Frame }) => {
             style={{ transform: `translate(${frame.position.x}px, ${frame.position.y}px)` }}
         >
             <RightClickMenu>
-                <TopBar frame={frame as WebFrame} />
+                <TopBar frame={frame} />
             </RightClickMenu>
             <div className="relative">
                 <ResizeHandles frame={frame} setIsResizing={setIsResizing} />
-                {frame.type === FrameType.WEB && (
-                    <WebFrameComponent frame={frame as WebFrame} ref={webFrameRef} />
-                )}
-                <GestureScreen frame={frame as WebFrame} isResizing={isResizing} />
+                <FrameComponent frame={frame} />
+                <GestureScreen frame={frame} isResizing={isResizing} />
             </div>
         </div>
     );

apps/web/client/src/app/project/[id]/_components/canvas/frame/page-selector.tsx

@@ -1,5 +1,5 @@
 import { useEditorEngine } from '@/components/store/editor';
-import { LeftPanelTabValue, type PageNode, type WebFrame } from '@onlook/models';
+import { LeftPanelTabValue, type Frame, type PageNode } from '@onlook/models';
 import { Button } from '@onlook/ui/button';
 import {
     DropdownMenu,
@@ -16,7 +16,7 @@ import React, { useEffect, useMemo, useState } from 'react';
 import { PageModal } from '../../left-panel/page-tab/page-modal';
 
 interface PageSelectorProps {
-    frame: WebFrame;
+    frame: Frame;
     className?: string;
 }
 

apps/web/client/src/app/project/[id]/_components/canvas/frame/top-bar.tsx

@@ -1,5 +1,5 @@
 import { useEditorEngine } from '@/components/store/editor';
-import type { WebFrame } from '@onlook/models';
+import type { Frame } from '@onlook/models';
 import { Button } from '@onlook/ui/button';
 import { Icons } from '@onlook/ui/icons';
 import { cn } from '@onlook/ui/utils';
@@ -10,7 +10,7 @@ import { HoverOnlyTooltip } from '../../editor-bar/hover-tooltip';
 import { PageSelector } from './page-selector';
 
 export const TopBar = observer(
-    ({ frame }: { frame: WebFrame }) => {
+    ({ frame }: { frame: Frame }) => {
         const editorEngine = useEditorEngine();
         const isSelected = editorEngine.frames.isSelected(frame.id);
         const topBarRef = useRef<HTMLDivElement>(null);

apps/web/client/src/app/project/[id]/_components/canvas/frame/web-frame.tsx → apps/web/client/src/app/project/[id]/_components/canvas/frame/view.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEditorEngine } from '@/components/store/editor';
-import type { WebFrame } from '@onlook/models';
+import type { Frame } from '@onlook/models';
 import {
     PENPAL_PARENT_CHANNEL,
     type PenpalChildMethods,
@@ -22,19 +22,19 @@ import {
     type IframeHTMLAttributes,
 } from 'react';
 
-export type WebFrameView = HTMLIFrameElement & {
+export type FrameView = HTMLIFrameElement & {
     setZoomLevel: (level: number) => void;
     supportsOpenDevTools: () => boolean;
     reload: () => void;
     isLoading: () => boolean;
 } & PromisifiedPendpalChildMethods;
 
-interface WebFrameViewProps extends IframeHTMLAttributes<HTMLIFrameElement> {
-    frame: WebFrame;
+interface FrameViewProps extends IframeHTMLAttributes<HTMLIFrameElement> {
+    frame: Frame;
 }
 
-export const WebFrameComponent = observer(
-    forwardRef<WebFrameView, WebFrameViewProps>(({ frame, ...props }, ref) => {
+export const FrameComponent = observer(
+    forwardRef<FrameView, FrameViewProps>(({ frame, ...props }, ref) => {
         const editorEngine = useEditorEngine();
         const iframeRef = useRef<HTMLIFrameElement>(null);
         const zoomLevel = useRef(1);
@@ -229,11 +229,11 @@ export const WebFrameComponent = observer(
             };
         }, [penpalChild]);
 
-        useImperativeHandle(ref, (): WebFrameView => {
+        useImperativeHandle(ref, (): FrameView => {
             const iframe = iframeRef.current;
             if (!iframe) {
                 console.error(`${PENPAL_PARENT_CHANNEL} (${frame.id}) - Iframe - Not found`);
-                return {} as WebFrameView;
+                return {} as FrameView;
             }
 
             const syncMethods = {
@@ -252,11 +252,11 @@ export const WebFrameComponent = observer(
                 console.warn(
                     `${PENPAL_PARENT_CHANNEL} (${frame.id}) - Failed to setup penpal connection: iframeRemote is null`,
                 );
-                return Object.assign(iframe, syncMethods, remoteMethods) as WebFrameView;
+                return Object.assign(iframe, syncMethods, remoteMethods) as FrameView;
             }
 
             // Register the iframe with the editor engine
-            editorEngine.frames.registerView(frame, iframe as WebFrameView);
+            editorEngine.frames.registerView(frame, iframe as FrameView);
 
             return Object.assign(iframe, {
                 ...syncMethods,

apps/web/client/src/app/project/[id]/_hooks/use-start-project.tsx

@@ -27,6 +27,7 @@ export const useStartProject = () => {
     const apiUtils = api.useUtils();
     const { data: user, isLoading: isUserLoading, error: userError } = api.user.get.useQuery();
     const { data: project, isLoading: isProjectLoading, error: projectError } = api.project.get.useQuery({ projectId: editorEngine.projectId });
+    const { data: branch, isLoading: isBranchLoading, error: branchError } = api.branch.get.useQuery({ projectId: editorEngine.projectId });
     const { data: canvasWithFrames, isLoading: isCanvasLoading, error: canvasError } = api.userCanvas.getWithFrames.useQuery({ projectId: editorEngine.projectId });
     const { data: conversations, isLoading: isConversationsLoading, error: conversationsError } = api.chat.conversation.getAll.useQuery({ projectId: editorEngine.projectId });
     const { data: creationRequest, isLoading: isCreationRequestLoading, error: creationRequestError } = api.project.createRequest.getPendingRequest.useQuery({ projectId: editorEngine.projectId });
@@ -40,7 +41,7 @@ export const useStartProject = () => {
     useEffect(() => {
         if (project) {
             startSandbox(project);
-            editorEngine.screenshot.lastScreenshotAt = project.metadata.updatedPreviewImgAt;
+            editorEngine.screenshot.lastScreenshotAt = project.metadata.previewImg?.updatedAt ?? null;
         }
     }, [project]);
 
@@ -129,10 +130,11 @@ export const useStartProject = () => {
             !isCanvasLoading &&
             !isConversationsLoading &&
             !isCreationRequestLoading &&
-            !isSandboxLoading;
+            !isSandboxLoading &&
+            !isBranchLoading;
 
         setIsProjectReady(allQueriesResolved);
-    }, [isUserLoading, isProjectLoading, isCanvasLoading, isConversationsLoading, isCreationRequestLoading, isSandboxLoading]);
+    }, [isUserLoading, isProjectLoading, isCanvasLoading, isConversationsLoading, isCreationRequestLoading, isSandboxLoading, isBranchLoading]);
 
     useEffect(() => {
         setError(userError?.message ?? projectError?.message ?? canvasError?.message ?? conversationsError?.message ?? creationRequestError?.message ?? null);

apps/web/client/src/app/projects/_components/select/index.tsx

@@ -42,8 +42,8 @@ export const SelectProject = ({ externalSearchQuery }: { externalSearchQuery?: s
     const [spacing] = useState<number>(24);
 
     // Templates
-    const projects = fetchedProjects?.filter(project => !project.tags?.includes(Tags.TEMPLATE)) ?? [];
-    const templateProjects = fetchedProjects?.filter(project => project.tags?.includes(Tags.TEMPLATE)) ?? [];
+    const projects = fetchedProjects?.filter(project => !project.metadata.tags.includes(Tags.TEMPLATE)) ?? [];
+    const templateProjects = fetchedProjects?.filter(project => project.metadata.tags.includes(Tags.TEMPLATE)) ?? [];
     const shouldShowTemplate = templateProjects.length > 0;
     const [selectedTemplate, setSelectedTemplate] = useState<Project | null>(null);
     const [isTemplateModalOpen, setIsTemplateModalOpen] = useState(false);

apps/web/client/src/app/projects/_components/settings.tsx

@@ -37,7 +37,7 @@ export function Settings({ project, refetch }: { project: Project; refetch: () =
     const [showRenameDialog, setShowRenameDialog] = useState(false);
     const [projectName, setProjectName] = useState(project.name);
     const isProjectNameEmpty = useMemo(() => projectName.length === 0, [projectName]);
-    const isTemplate = project.tags?.includes(Tags.TEMPLATE) || false;
+    const isTemplate = project.metadata.tags.includes(Tags.TEMPLATE) || false;
 
     useEffect(() => {
         setProjectName(project.name);

apps/web/client/src/components/store/editor/branch/manager.ts

@@ -0,0 +1,137 @@
+import type { Branch } from '@onlook/models';
+import { makeAutoObservable } from 'mobx';
+import type { EditorEngine } from '../engine';
+import { SandboxManager } from '../sandbox';
+
+export class BranchManager {
+    private editorEngine: EditorEngine;
+    private currentBranchId: string | null = null;
+    private branchIdToSandboxManager = new Map<string, SandboxManager>();
+
+    constructor(editorEngine: EditorEngine) {
+        this.editorEngine = editorEngine;
+        makeAutoObservable(this);
+    }
+
+    get currentBranch(): string | null {
+        return this.currentBranchId;
+    }
+
+    getCurrentSandbox(): SandboxManager {
+        if (!this.currentBranchId) {
+            throw new Error('No branch selected. Call switchToBranch() first.');
+        }
+
+        if (!this.branchIdToSandboxManager.has(this.currentBranchId)) {
+            const sandboxManager = new SandboxManager(this.editorEngine);
+            this.branchIdToSandboxManager.set(this.currentBranchId, sandboxManager);
+        }
+
+        return this.branchIdToSandboxManager.get(this.currentBranchId)!;
+    }
+
+    async startCurrentBranchSandbox(): Promise<void> {
+        if (!this.currentBranchId) {
+            throw new Error('No branch selected. Call switchToBranch() first.');
+        }
+
+        const branch = await this.getBranchById(this.currentBranchId);
+        await this.getCurrentSandbox().session.start(branch.sandbox.id);
+    }
+
+    async switchToBranch(branchId: string): Promise<void> {
+        if (this.currentBranchId === branchId) {
+            return;
+        }
+
+        this.currentBranchId = branchId;
+    }
+
+    async createBranch(
+        name: string,
+        description?: string,
+        fromBranchId?: string,
+        isDefault = false
+    ): Promise<Branch> {
+        const newBranch: Branch = {
+            id: `branch-${Date.now()}`,
+            name,
+            description: description || null,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            git: null,
+            sandbox: {
+                id: `sandbox-${Date.now()}`,
+            },
+        };
+
+        return newBranch;
+    }
+
+    async deleteBranch(branchId: string): Promise<void> {
+        if (branchId === this.currentBranchId) {
+            throw new Error('Cannot delete the currently active branch');
+        }
+
+        const sandboxManager = this.branchIdToSandboxManager.get(branchId);
+        if (sandboxManager) {
+            sandboxManager.clear();
+            this.branchIdToSandboxManager.delete(branchId);
+        }
+    }
+
+    async getDefaultBranch(): Promise<Branch> {
+        return {
+            id: 'main-branch-id',
+            name: 'main',
+            description: 'Default main branch',
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            git: null,
+            sandbox: {
+                id: 'main-sandbox-id',
+            },
+        };
+    }
+
+    async getBranchById(branchId: string): Promise<Branch> {
+        return {
+            id: branchId,
+            name: branchId === 'main-branch-id' ? 'main' : `branch-${branchId}`,
+            description: null,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            git: null,
+            sandbox: {
+                id: `${branchId}-sandbox`,
+            },
+        };
+    }
+
+
+    private async createMainBranch(): Promise<Branch> {
+        return {
+            id: 'main-branch-id',
+            name: 'main',
+            description: 'Default main branch',
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            git: null,
+            sandbox: {
+                id: 'main-sandbox-id',
+            },
+        };
+    }
+
+    async listBranches(): Promise<Branch[]> {
+        return [];
+    }
+
+    clear(): void {
+        for (const sandboxManager of this.branchIdToSandboxManager.values()) {
+            sandboxManager.clear();
+        }
+        this.branchIdToSandboxManager.clear();
+        this.currentBranchId = null;
+    }
+}