@sampleapp.ai/sdk 1.0.29 → 1.0.31

package/dist/components/sandbox/guardian/code-focus-section.js

@@ -0,0 +1,174 @@
+"use client";
+import React, { useEffect, useMemo, useRef } from "react";
+import { useGuardianContext } from "./context/guardian-context";
+// Helper function to find a node in the file tree by path
+function getTargetNode(fileTree, targetPath) {
+    const parts = targetPath.split("/").filter(Boolean);
+    let current = fileTree;
+    for (const part of parts) {
+        if (!current.children || !current.children[part]) {
+            return null;
+        }
+        current = current.children[part];
+    }
+    return current;
+}
+/**
+ * Component that focuses on a specific file and line range in the code editor
+ * when it comes into view while scrolling, or when the user clicks "View Code".
+ */
+export default function CodeFocusSection({ filePath, lineRange, title, description, children, threshold = 0, themeColor, }) {
+    const sectionRef = useRef(null);
+    const { generatedCode, fileTree, setActiveFilePath, setActiveFileName, setActiveLineNumber, setActiveLineRange, updateCode, setLanguage, filesEdited, activeFilePath, activeLineRange, } = useGuardianContext();
+    // Moves the editor's focus to this file/lines
+    const focusCode = () => {
+        // Get the file code from generatedCode or fileTree
+        // Always search by file_path property first, as that's the source of truth
+        let code = "";
+        let language;
+        let resolvedFilePath;
+        let codeOutput;
+        // First, search through all code outputs to find one matching file_path
+        const matchingCodeOutput = Object.values(generatedCode).find((output) => output.file_path === filePath);
+        if (matchingCodeOutput) {
+            codeOutput = matchingCodeOutput;
+            code = codeOutput.full_code;
+            language = codeOutput.code_language;
+            resolvedFilePath = codeOutput.file_path;
+        }
+        else {
+            // Fallback: try to get from generatedCode by key, but still use file_path from the object
+            if (generatedCode[filePath]) {
+                codeOutput = generatedCode[filePath];
+                code = codeOutput.full_code;
+                language = codeOutput.code_language;
+                // Always use the file_path from the code output object as source of truth
+                resolvedFilePath = codeOutput.file_path || filePath;
+            }
+            else {
+                // Fallback to fileTree
+                try {
+                    const targetNode = getTargetNode(fileTree, filePath);
+                    if (targetNode === null || targetNode === void 0 ? void 0 : targetNode.metadata) {
+                        code = targetNode.metadata.full_code || "";
+                        language = targetNode.metadata.code_language;
+                        // Use file_path from metadata if available, otherwise use the provided filePath
+                        resolvedFilePath = targetNode.metadata.file_path || filePath;
+                    }
+                }
+                catch (error) {
+                    console.warn(`Failed to get code for file ${filePath}:`, error);
+                    resolvedFilePath = filePath;
+                }
+            }
+        }
+        // If we still don't have a resolved file path, use the provided filePath
+        if (!resolvedFilePath) {
+            resolvedFilePath = filePath;
+        }
+        // Check if file has been edited - use resolvedFilePath for lookup
+        const editedCode = filesEdited[resolvedFilePath] || filesEdited[filePath];
+        const finalCode = editedCode ? editedCode.full_code : code;
+        if (finalCode) {
+            // Extract filename from path - prefer code_file_name from code output
+            const fileName = (codeOutput === null || codeOutput === void 0 ? void 0 : codeOutput.code_file_name) ||
+                resolvedFilePath.split("/").pop() ||
+                resolvedFilePath;
+            // Set the active file using the resolved file path
+            setActiveFilePath(resolvedFilePath);
+            setActiveFileName(fileName);
+            updateCode(finalCode);
+            // Set language if available
+            if (language) {
+                setLanguage(language);
+            }
+            // Set line number/range if provided
+            if (lineRange) {
+                setActiveLineRange({
+                    start: lineRange.start,
+                    end: lineRange.end,
+                });
+            }
+            else {
+                setActiveLineRange(undefined);
+                setActiveLineNumber(undefined);
+            }
+        }
+    };
+    useEffect(() => {
+        const element = sectionRef.current;
+        if (!element)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+                // Trigger when the element enters the middle of the viewport
+                if (entry.isIntersecting) {
+                    focusCode();
+                }
+            });
+        }, {
+            threshold,
+            rootMargin: "-40% 0px -40% 0px", // Trigger when element enters the middle 20% of viewport
+        });
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        filePath,
+        lineRange,
+        generatedCode,
+        fileTree,
+        setActiveFilePath,
+        setActiveFileName,
+        setActiveLineNumber,
+        setActiveLineRange,
+        updateCode,
+        setLanguage,
+        filesEdited,
+        threshold,
+    ]);
+    // Get the resolved file path for comparison
+    // This ensures we compare against the actual file_path from the code structure
+    const resolvedFilePathForComparison = useMemo(() => {
+        var _a, _b;
+        // Search by file_path property first (this is the source of truth)
+        const matchingCodeOutput = Object.values(generatedCode).find((output) => output.file_path === filePath);
+        if (matchingCodeOutput) {
+            return matchingCodeOutput.file_path;
+        }
+        // Fallback to key lookup
+        if ((_a = generatedCode[filePath]) === null || _a === void 0 ? void 0 : _a.file_path) {
+            return generatedCode[filePath].file_path;
+        }
+        // Fallback to fileTree
+        try {
+            const targetNode = getTargetNode(fileTree, filePath);
+            if ((_b = targetNode === null || targetNode === void 0 ? void 0 : targetNode.metadata) === null || _b === void 0 ? void 0 : _b.file_path) {
+                return targetNode.metadata.file_path;
+            }
+        }
+        catch (_c) {
+            // Ignore errors
+        }
+        return filePath;
+    }, [filePath, generatedCode, fileTree]);
+    return (React.createElement("div", { ref: sectionRef, className: `relative transition-colors py-6 cursor-pointer`, onClick: focusCode },
+        React.createElement("div", { className: "pointer-events-none absolute inset-x-[-2rem] top-0 border-t border-border" }),
+        React.createElement("div", { className: "pointer-events-none absolute inset-x-[-2rem] bottom-0 border-b border-border" }),
+        (activeFilePath === resolvedFilePathForComparison ||
+            activeFilePath === filePath) &&
+            (activeLineRange
+                ? lineRange &&
+                    activeLineRange.start === lineRange.start &&
+                    activeLineRange.end === lineRange.end
+                : !lineRange) && (React.createElement("div", { className: "absolute left-0 top-0 h-full w-1", style: {
+                backgroundColor: themeColor,
+                marginLeft: "-2rem",
+            } })),
+        React.createElement("div", { className: "flex items-center gap-2" },
+            React.createElement("h3", { className: "text-md font-semibold text-gray-900 dark:text-gray-100" }, title)),
+        description && (React.createElement("p", { className: "text-sm text-gray-400 mt-3" }, description)),
+        children && React.createElement("div", { className: "mt-3" }, children)));
+}

package/dist/components/sandbox/guardian/context/guardian-context.js

@@ -0,0 +1,94 @@
+"use client";
+import React, { createContext, useContext, useState, useCallback, } from "react";
+import { CodeLanguage, } from "../types/ide-types";
+const GuardianContext = createContext(undefined);
+export function GuardianProvider({ children }) {
+    const [previewUrl, setPreviewUrlState] = useState("");
+    const [isBrowserMaximized, setIsBrowserMaximized] = useState(false);
+    const [currentView, setCurrentViewState] = useState("preview");
+    // Code state
+    const [code, setCode] = useState("");
+    const [language, setLanguage] = useState(CodeLanguage.TEXT);
+    const [activeFileName, setActiveFileName] = useState("");
+    const [activeFilePath, setActiveFilePath] = useState("");
+    const [activeLineNumber, setActiveLineNumber] = useState(undefined);
+    const [activeLineRange, setActiveLineRange] = useState(undefined);
+    const [isGeneratingCode, setIsGeneratingCode] = useState(false);
+    // Generated code and file tree
+    const [generatedCode, setGeneratedCodeState] = useState({});
+    const [fileTree, setFileTree] = useState({
+        name: "root",
+        children: {},
+        type: "folder",
+        metadata: {
+            response_type: "CodeOutput",
+            file_path: "",
+            code_file_name: "",
+            code_language: CodeLanguage.TEXT,
+            dependencies_to_install: [],
+            framework: null,
+            full_code: "",
+        },
+    });
+    // Dependencies and edited files
+    const [activeDependenciesToInstall, setActiveDependenciesToInstall] = useState([]);
+    const [filesEdited, setFilesEdited] = useState({});
+    const setPreviewUrl = useCallback((url) => {
+        setPreviewUrlState(url);
+    }, []);
+    const setIsBrowserMaximizedState = useCallback((maximized) => {
+        setIsBrowserMaximized(maximized);
+    }, []);
+    const setCurrentView = useCallback((view) => {
+        setCurrentViewState(view);
+    }, []);
+    const updateCode = useCallback((newCode) => {
+        setCode(newCode);
+    }, []);
+    const setGeneratedCode = useCallback((generatedCode) => {
+        if (typeof generatedCode === "function") {
+            setGeneratedCodeState((prev) => generatedCode(prev));
+        }
+        else {
+            setGeneratedCodeState(generatedCode);
+        }
+    }, []);
+    const value = {
+        previewUrl,
+        setPreviewUrl,
+        isBrowserMaximized,
+        setIsBrowserMaximized: setIsBrowserMaximizedState,
+        currentView,
+        setCurrentView,
+        code,
+        updateCode,
+        language,
+        setLanguage,
+        activeFileName,
+        setActiveFileName,
+        activeFilePath,
+        setActiveFilePath,
+        activeLineNumber,
+        setActiveLineNumber,
+        activeLineRange,
+        setActiveLineRange,
+        isGeneratingCode,
+        setIsGeneratingCode,
+        generatedCode,
+        setGeneratedCode,
+        fileTree,
+        setFileTree,
+        activeDependenciesToInstall,
+        setActiveDependenciesToInstall,
+        filesEdited,
+        setFilesEdited,
+    };
+    return (React.createElement(GuardianContext.Provider, { value: value }, children));
+}
+export function useGuardianContext() {
+    const context = useContext(GuardianContext);
+    if (!context) {
+        throw new Error("useGuardianContext must be used within a GuardianProvider");
+    }
+    return context;
+}

package/dist/components/sandbox/guardian/context/vm-context.js

@@ -0,0 +1,28 @@
+"use client";
+import React, { createContext, useContext, useState } from "react";
+const VmContext = createContext(undefined);
+export const VmProvider = ({ children }) => {
+    const [vmUrlMap, setVmUrlMap] = useState({});
+    const setVmUrl = (uid, url) => {
+        setVmUrlMap((prev) => (Object.assign(Object.assign({}, prev), { [uid]: url })));
+    };
+    const getVmUrl = (uid) => {
+        const value = vmUrlMap[uid];
+        // Return undefined if it's an error marker
+        return value === "error" ? undefined : value;
+    };
+    const setVmError = (uid) => {
+        setVmUrlMap((prev) => (Object.assign(Object.assign({}, prev), { [uid]: "error" })));
+    };
+    const hasError = (uid) => {
+        return vmUrlMap[uid] === "error";
+    };
+    return (React.createElement(VmContext.Provider, { value: { vmUrlMap, setVmUrl, getVmUrl, setVmError, hasError } }, children));
+};
+export const useVmContext = () => {
+    const context = useContext(VmContext);
+    if (!context) {
+        throw new Error("useVmContext must be used within a VmProvider");
+    }
+    return context;
+};

package/dist/components/sandbox/guardian/default-guide-view.js

@@ -0,0 +1,34 @@
+"use client";
+import React from "react";
+import { Markdown } from "./ui/markdown";
+export default function DefaultGuideView({ themeColor, }) {
+    return (React.createElement("div", { className: "h-full flex flex-col" },
+        React.createElement("div", { className: "flex-1 px-8 py-6" },
+            React.createElement(Markdown, { className: "text-gray-100", themeColor: themeColor }, `# Guardian Guide
+
+Learn how to use Guardian to build and deploy your application with confidence.
+
+## Getting Started
+
+Guardian provides a comprehensive development environment with real-time preview, code editing, and AI assistance.
+
+### Features
+
+- **Live Preview**: See your changes instantly as you code
+- **Code Editor**: Edit files directly in the browser
+- **AI Assistant**: Get help with your code using the Ask AI feature
+
+### Navigation
+
+Use the tabs at the top to switch between:
+- **Guide**: View this documentation
+- **Ask AI**: Get AI-powered assistance with your code
+
+### Code Editing
+
+Select files from the file selector to view and edit them. The editor supports syntax highlighting and automatic formatting.
+
+### Preview
+
+The preview panel shows your running application. Use the reload button to refresh the preview when needed.`))));
+}

package/dist/components/sandbox/guardian/demo/guardian-demo.js

@@ -0,0 +1,35 @@
+"use client";
+import React, { useEffect, useState, useCallback } from "react";
+import ConsoleWithApp from "../ui/console-with-app";
+import { useGuardianContext } from "../context/guardian-context";
+import ConsoleWithGuide from "./left-view";
+import RightView from "../right-view/right-view";
+export default function GuardianDemo({ CustomConsole, GuideView, browserUrl, playgroundUid, useVm, codeZipFile, completeCodeZipFile, variant, themeColor, hasPreview, isFrame = false, isGuardian = false, gitUrl, }) {
+    const { isBrowserMaximized } = useGuardianContext();
+    const { setCurrentView } = useGuardianContext();
+    const [reloadCounter, setReloadCounter] = useState(0);
+    const [overlayStage, setOverlayStage] = useState("hidden");
+    const handleReloadPreview = useCallback(() => {
+        setReloadCounter((c) => c + 1);
+    }, []);
+    const handleStageChange = useCallback((stage) => {
+        setOverlayStage(stage);
+        if (stage === "rebuilding") {
+            // Simulate a 3-second rebuild then hide
+            setTimeout(() => setOverlayStage("hidden"), 3000);
+        }
+    }, []);
+    useEffect(() => {
+        setCurrentView("preview");
+    }, [setCurrentView]);
+    // If isFrame, just return RightView directly
+    if (isFrame) {
+        return (React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian }));
+    }
+    // If browser is maximized, render RightView at full size without the console
+    if (isBrowserMaximized && isGuardian) {
+        return (React.createElement("div", { className: "w-full h-full rounded-2xl border border-border overflow-hidden" },
+            React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian, isBrowserMaximized: true })));
+    }
+    return (React.createElement(ConsoleWithApp, { containerClassName: "rounded-2xl border border-border", console: React.createElement(ConsoleWithGuide, { CustomConsole: CustomConsole, GuideView: GuideView, playgroundUid: playgroundUid, onReloadPreview: handleReloadPreview, onStageChange: handleStageChange, codeZipFile: codeZipFile, themeColor: themeColor, browserUrl: browserUrl, gitUrl: gitUrl }), app: React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian }) }));
+}

package/dist/components/sandbox/guardian/demo/left-view/toggle.js

@@ -0,0 +1,28 @@
+"use client";
+import React from "react";
+import { motion } from "framer-motion";
+import { cn } from "../../../../../lib/utils";
+export default function SlidingEditPreviewToggle({ playgroundUid, variant = "default", buttonClassName = "", tabs = [
+    { id: "editor", label: "Edit" },
+    { id: "preview", label: "Preview" },
+], currentView, setCurrentView, }) {
+    // Outer div and button shape depending on variant
+    const rootClasses = variant === "pill"
+        ? "relative inline-flex items-center bg-muted/30 rounded-full p-1 border border-border/50"
+        : "relative inline-flex items-center bg-muted/30 rounded-lg p-1";
+    const btnShape = variant === "pill" ? "rounded-full" : "rounded-md";
+    const highlightShape = variant === "pill" ? "rounded-full" : "rounded-md";
+    // Default button padding if none provided
+    const defaultButtonPadding = variant === "pill" ? "px-5 py-2" : "px-4 py-1.5";
+    return (React.createElement("div", { className: rootClasses }, tabs.map((tab) => (React.createElement("button", { key: tab.id, onClick: () => setCurrentView(tab.id), className: cn(`relative ${defaultButtonPadding} text-sm font-medium transition-colors duration-150 ${btnShape} ${currentView === tab.id
+            ? "text-foreground"
+            : "text-muted-foreground hover:text-foreground/80"}`, buttonClassName), style: {
+            WebkitTapHighlightColor: "transparent",
+        } },
+        currentView === tab.id && (React.createElement(motion.div, { layoutId: "activeTabGuide", className: cn(`absolute inset-0 bg-neutral-200 dark:bg-neutral-700 ${highlightShape} shadow-sm border border-border/50`), initial: false, transition: {
+                type: "spring",
+                stiffness: 500,
+                damping: 30,
+            } })),
+        React.createElement("span", { className: "relative z-10" }, tab.label))))));
+}

package/dist/components/sandbox/guardian/demo/left-view.js

@@ -0,0 +1,70 @@
+"use client";
+import React, { useMemo, useState } from "react";
+import SlidingConsoleGuideToggle from "./left-view/toggle";
+// import AskAiView from "../ask-ai-view";
+// import DefaultGuideView from "../default-guide-view";
+import { Markdown } from "../ui/markdown";
+import sampleappLogo from "../../../../assets/sampleapp-logo.png";
+function Logo({ href, width }) {
+    return (React.createElement("div", { className: "flex justify-center md:justify-start" },
+        React.createElement("a", { href: href ? href : "https://sampleapp.ai", className: "flex", target: "_blank", rel: "noopener noreferrer" },
+            React.createElement("div", { className: "invert dark:invert-0" },
+                React.createElement("img", { src: sampleappLogo, alt: "SampleApp Logo", width: width || 160, height: 40 })))));
+}
+export default function ConsoleWithGuide({ CustomConsole, GuideView, playgroundUid, onReloadPreview, onStageChange, codeZipFile, themeColor, browserUrl, gitUrl, }) {
+    const [currentView, setCurrentView] = useState("console");
+    const isConsoleView = useMemo(() => currentView === "console", [currentView]);
+    // const isGuideView = useMemo(() => currentView === "guide", [currentView]);
+    // const isChatView = useMemo(() => currentView === "chat", [currentView]);
+    const renderCustomConsole = () => {
+        if (typeof CustomConsole === "string") {
+            return (React.createElement("div", { className: "h-full flex flex-col" },
+                React.createElement("div", { className: "flex-1 px-8 py-6" },
+                    React.createElement(Markdown, { className: "text-gray-100", themeColor: themeColor, browserUrl: browserUrl, gitUrl: gitUrl }, CustomConsole))));
+        }
+        const CustomConsoleComponent = CustomConsole;
+        return (React.createElement(CustomConsoleComponent, { onReloadPreview: onReloadPreview !== null && onReloadPreview !== void 0 ? onReloadPreview : (() => { }), onStageChange: onStageChange !== null && onStageChange !== void 0 ? onStageChange : (() => { }), themeColor: themeColor }));
+    };
+    // Determine which guide view to render
+    // const renderGuideView = () => {
+    //   if (!GuideView) {
+    //     // If no GuideView provided, render default
+    //     return (
+    //       <DefaultGuideView
+    //         onReloadPreview={onReloadPreview ?? (() => {})}
+    //         onStageChange={onStageChange ?? (() => {})}
+    //         themeColor={themeColor}
+    //       />
+    //     );
+    //   }
+    //   // If GuideView is a string, render as markdown
+    //   if (typeof GuideView === "string") {
+    //     return (
+    //       <div className="h-full flex flex-col">
+    //         <div className="flex-1 px-8 py-6">
+    //           <Markdown className="text-gray-100" themeColor={themeColor}>
+    //             {GuideView}
+    //           </Markdown>
+    //         </div>
+    //       </div>
+    //     );
+    //   }
+    //   // Otherwise, render as React component
+    //   const GuideComponent = GuideView as ComponentType;
+    //   return <GuideComponent />;
+    // };
+    return (React.createElement("div", { className: "flex-1 min-h-0 relative flex flex-col" },
+        React.createElement("div", { className: "flex justify-center border-b border-border" },
+            React.createElement(SlidingConsoleGuideToggle, { playgroundUid: playgroundUid, variant: "pill", buttonClassName: "text-sm px-4 py-1", currentView: currentView, setCurrentView: setCurrentView, tabs: [
+                    { id: "console", label: "Guide" },
+                    // ...(GuideView ? [{id: "guide-og", label: "Guide OG"}] : []),
+                    // {id: "chat", label: "Ask AI"},
+                ] })),
+        React.createElement("div", { className: "h-[calc(100vh-9.5rem)] min-h-0 overflow-hidden flex-1 flex flex-col" },
+            React.createElement("div", { className: "flex-1 min-h-0 overflow-y-auto" }, isConsoleView && renderCustomConsole()),
+            React.createElement("div", { className: "relative" },
+                React.createElement("div", { className: "flex flex-row w-full items-center text-xs justify-center opacity-30 mt-1 pb-2 bg-background" },
+                    React.createElement("span", { className: "text-gray-300" }, "Powered by"),
+                    React.createElement("span", { className: "hover:bg-accent rounded-sm p-1 mx-1" },
+                        React.createElement(Logo, { width: 100, href: "https://sampleapp.ai" })))))));
+}

package/dist/components/sandbox/guardian/guardian-component.js

@@ -0,0 +1,99 @@
+"use client";
+import Header from "./header";
+import AppLayoutNoSidebar from "./app-layout-no-sidebar";
+import GuardianDemo from "./demo/guardian-demo";
+import React, { useEffect, useRef } from "react";
+import { useGuardianContext } from "./context/guardian-context";
+import { useSandboxUrlLoader, } from "./hooks/use-sandbox-url-loader";
+import { useFrameMessages } from "./hooks/use-frame-messages";
+import { cn } from "../../../lib/utils";
+export default function GuardianComponent({ demoOptions, frameworkOptions, firstFrameworkByUseCase, currentFramework, currentUseCase, CustomConsole, GuideView, playgroundLogo, playgroundUid, browserUrl, useVm, sandboxUid, codeZipFile, consoleUrlConfigs, completeCodeZipFile, variant, themeColor, hasPreview = true, isFrame = false, apiKey, env, chatUid, hideHeader = true, // Hardcoded to true by default, not exposed in Sandbox.tsx
+gitUrl, }) {
+    const { previewUrl, setPreviewUrl } = useGuardianContext();
+    // Debug: Log the props received for sandbox configuration
+    console.log("[GuardianComponent] API config props:", {
+        apiKey: apiKey ? `${apiKey.substring(0, 8)}...` : undefined,
+        env,
+        chatUid,
+        hasApiKey: !!apiKey,
+        hasEnv: !!env,
+        hasChatUid: !!chatUid,
+    });
+    // Build startSandboxConfig only if all required fields are present and non-empty
+    const startSandboxConfig = apiKey && env && chatUid
+        ? {
+            apiKey,
+            env,
+            chatUid,
+        }
+        : undefined;
+    console.log("[GuardianComponent] startSandboxConfig:", startSandboxConfig ? "configured" : "undefined (missing required fields)");
+    const { getSandboxUrl, loadSandboxUrl, preloadSandboxUrls } = useSandboxUrlLoader(startSandboxConfig);
+    // Initialize postMessage listener for iframe communication
+    // This sends IFRAME_READY and listens for UPDATE_VIEW messages
+    useFrameMessages();
+    // Track which console configs we've preloaded to prevent duplicates
+    const preloadedConfigsRef = useRef("");
+    // Track which main sandbox we've loaded to prevent duplicates
+    const loadedSandboxRef = useRef("");
+    // Preload console URLs when component mounts
+    useEffect(() => {
+        if (consoleUrlConfigs && consoleUrlConfigs.length > 0) {
+            // Create a key from the configs to detect changes
+            const configKey = JSON.stringify(consoleUrlConfigs.map((c) => c.sandboxUid));
+            // Only preload if we haven't already preloaded these configs
+            if (preloadedConfigsRef.current !== configKey) {
+                preloadedConfigsRef.current = configKey;
+                preloadSandboxUrls(consoleUrlConfigs).catch((error) => {
+                    console.error("Failed to preload console URLs:", error);
+                });
+            }
+        }
+        // Only re-run if consoleUrlConfigs changes (not when preloadSandboxUrls changes)
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [consoleUrlConfigs]);
+    useEffect(() => {
+        // Create a key for this sandbox load
+        const sandboxKey = `${sandboxUid}-${browserUrl}-${useVm}`;
+        // Check if we've already initiated a load for this exact sandbox config
+        if (loadedSandboxRef.current === sandboxKey) {
+            return;
+        }
+        // Check if URL is already cached for this sandboxUid + browserUrl combination
+        const existingUrl = getSandboxUrl(sandboxUid, browserUrl);
+        if (existingUrl !== undefined) {
+            // Found cached URL for this exact combination, use it immediately
+            setPreviewUrl(existingUrl);
+            loadedSandboxRef.current = sandboxKey;
+            return;
+        }
+        // Mark as loading to prevent duplicate requests
+        loadedSandboxRef.current = sandboxKey;
+        // Load the sandbox URL (will be cached by sandboxUid + browserUrl)
+        // This allows switching between different browserUrls and reverting back
+        // without losing the cached URLs
+        setPreviewUrl("");
+        loadSandboxUrl({
+            sandboxUid,
+            browserUrl,
+            useVm,
+        })
+            .then((url) => {
+            setPreviewUrl(url);
+        })
+            .catch((error) => {
+            console.error("Failed to load sandbox URL:", error);
+            // Keep preview URL empty on error
+        });
+        // Only re-run if the sandbox parameters change (not when functions change)
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [sandboxUid, browserUrl, useVm]);
+    // If isFrame, just render GuardianDemo without the header/layout wrapper
+    if (isFrame) {
+        return (React.createElement("div", { className: "h-[100vh]" },
+            React.createElement(GuardianDemo, { CustomConsole: CustomConsole, GuideView: GuideView, browserUrl: previewUrl, playgroundUid: playgroundUid, useVm: useVm, codeZipFile: codeZipFile, completeCodeZipFile: completeCodeZipFile, variant: variant, themeColor: themeColor, hasPreview: hasPreview, isFrame: isFrame, isGuardian: true, gitUrl: gitUrl })));
+    }
+    return (React.createElement(AppLayoutNoSidebar, { header: !hideHeader ? (React.createElement(Header, { demoOptions: demoOptions, frameworkOptions: frameworkOptions, currentFramework: currentFramework, currentUseCase: currentUseCase, playgroundLogo: playgroundLogo, firstFrameworkByUseCase: firstFrameworkByUseCase })) : undefined, hasBodyPadding: false },
+        React.createElement("div", { className: cn("flex-1 min-h-0 flex flex-col px-4 pb-4", hideHeader && "pt-4") },
+            React.createElement(GuardianDemo, { CustomConsole: CustomConsole, GuideView: GuideView, browserUrl: previewUrl, playgroundUid: playgroundUid, useVm: useVm, codeZipFile: codeZipFile, completeCodeZipFile: completeCodeZipFile, variant: variant, themeColor: themeColor, hasPreview: hasPreview, isFrame: isFrame, isGuardian: true, gitUrl: gitUrl }))));
+}

package/dist/components/sandbox/guardian/guardian-demo.js

@@ -0,0 +1,35 @@
+"use client";
+import React, { useEffect, useState, useCallback } from "react";
+import ConsoleWithApp from "./ui/console-with-app";
+import { useGuardianContext } from "./context/guardian-context";
+import ConsoleWithGuide from "./demo/left-view";
+import RightView from "./right-view/right-view";
+export default function GuardianDemo({ CustomConsole, GuideView, browserUrl, playgroundUid, useVm, codeZipFile, completeCodeZipFile, variant, themeColor, hasPreview, isFrame = false, isGuardian = false, }) {
+    const { isBrowserMaximized } = useGuardianContext();
+    const { setCurrentView } = useGuardianContext();
+    const [reloadCounter, setReloadCounter] = useState(0);
+    const [overlayStage, setOverlayStage] = useState("hidden");
+    const handleReloadPreview = useCallback(() => {
+        setReloadCounter((c) => c + 1);
+    }, []);
+    const handleStageChange = useCallback((stage) => {
+        setOverlayStage(stage);
+        if (stage === "rebuilding") {
+            // Simulate a 3-second rebuild then hide
+            setTimeout(() => setOverlayStage("hidden"), 3000);
+        }
+    }, []);
+    useEffect(() => {
+        setCurrentView("preview");
+    }, [setCurrentView]);
+    // If isFrame, just return RightView directly
+    if (isFrame) {
+        return (React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian }));
+    }
+    // If browser is maximized, render RightView at full size without the console
+    if (isBrowserMaximized && isGuardian) {
+        return (React.createElement("div", { className: "w-full h-full rounded-2xl border overflow-hidden" },
+            React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian, isBrowserMaximized: true })));
+    }
+    return (React.createElement(ConsoleWithApp, { containerClassName: "rounded-2xl border", console: React.createElement(ConsoleWithGuide, { CustomConsole: CustomConsole, GuideView: GuideView, playgroundUid: playgroundUid, onReloadPreview: handleReloadPreview, onStageChange: handleStageChange, codeZipFile: codeZipFile, themeColor: themeColor }), app: React.createElement(RightView, { reloadCounter: reloadCounter, overlayStage: overlayStage, browserUrl: browserUrl, useVm: useVm, codeZipFile: codeZipFile, hasPreview: hasPreview, variant: variant, themeColor: themeColor, completeCodeZipFile: completeCodeZipFile, isGuardian: isGuardian }) }));
+}

package/dist/components/sandbox/guardian/guardian-home.d.ts

@@ -0,0 +1,4 @@
+import { GuardianNestedConfig } from "./types";
+export default function GuardianHome({ nestedConfig, }: {
+    nestedConfig: GuardianNestedConfig;
+}): import("react").JSX.Element;