@sampleapp.ai/sdk 1.0.42 → 1.0.44

package/dist/index.d.ts

@@ -8,6 +8,150 @@ export declare interface AiChatSettings {
     [key: string]: any;
 }
 
+/**
+ * Main API client class
+ */
+declare class ApiClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: ApiClientConfig);
+    /**
+     * Makes a request to the API
+     * Automatically includes Authorization: Bearer {apiKey} header
+     */
+    private request;
+    /**
+     * Sandbox content endpoints
+     */
+    sandboxContent: {
+        /**
+         * Get public sandbox content by UID
+         * @param sandboxContentUid - The UID of the sandbox content
+         * @returns The sandbox content data
+         */
+        getPublic: (sandboxContentUid: string) => Promise<SandboxContent>;
+        /**
+         * Get all sandbox contents for a specific playground (public access with truncated fields)
+         * @param playgroundUid - The UID of the playground
+         * @param skip - Number of records to skip (default: 0)
+         * @param limit - Maximum number of records to return (default: 100)
+         * @returns Array of sandbox content data with only uid and markdown fields
+         */
+        getByPlayground: (playgroundUid: string, skip?: number, limit?: number) => Promise<SandboxContentPublic[]>;
+        /**
+         * Get all sandbox contents for a specific use case
+         * Used for upfront loading to enable local filtering
+         * @param useCaseId - The ID of the use case
+         * @param skip - Number of records to skip (default: 0)
+         * @param limit - Maximum number of records to return (default: 100)
+         * @returns Array of sandbox content data
+         */
+        getByUseCaseId: (useCaseId: number, skip?: number, limit?: number) => Promise<SandboxContent[]>;
+    };
+    /**
+     * Sandbox use case endpoints
+     */
+    sandboxUseCase: {
+        /**
+         * Get a sandbox use case by UID
+         * @param uid - The UID of the use case
+         * @returns The use case data including tech_stack_config
+         */
+        getByUid: (uid: string) => Promise<SandboxUseCase>;
+        /**
+         * Get a sandbox use case by ID
+         * @param id - The numeric ID of the use case
+         * @returns The use case data including tech_stack_config
+         */
+        getById: (id: number) => Promise<SandboxUseCase>;
+        /**
+         * Get all sandbox use cases for a specific playground
+         * @param playgroundUid - The UID of the playground
+         * @param skip - Number of records to skip (default: 0)
+         * @param limit - Maximum number of records to return (default: 100)
+         * @returns Array of use case data
+         */
+        getByPlayground: (playgroundUid: string, skip?: number, limit?: number) => Promise<SandboxUseCase[]>;
+        /**
+         * Get all template use cases (public access)
+         * @param skip - Number of records to skip (default: 0)
+         * @param limit - Maximum number of records to return (default: 100)
+         * @returns Array of template use case data
+         */
+        getTemplates: (skip?: number, limit?: number) => Promise<SandboxUseCase[]>;
+        /**
+         * Get all public use cases
+         * @param skip - Number of records to skip (default: 0)
+         * @param limit - Maximum number of records to return (default: 100)
+         * @returns Array of public use case data
+         */
+        getPublic: (skip?: number, limit?: number) => Promise<SandboxUseCase[]>;
+    };
+    /**
+     * SDK endpoints
+     */
+    sdk: {
+        /**
+         * Start a sandbox
+         *
+         * Authentication: API key is sent as Bearer token in Authorization header.
+         * The apiKey must be set in ApiClientConfig when creating the client.
+         *
+         * @param request - The start sandbox request (env and chatUid)
+         * @returns The sandbox response with container URL
+         *
+         * @example
+         * ```typescript
+         * const client = createApiClient({ apiKey: "your-api-key" });
+         * const response = await client.sdk.startSandbox({
+         *   env: { ENV_VAR: "value" }, // required when published_url is not available
+         *   chatUid: "chat-uid-123"
+         * });
+         * ```
+         */
+        startSandbox: (request: StartSandboxRequest) => Promise<StartSandboxResponse>;
+        /**
+         * Download code as zip file from GitHub repository
+         *
+         * Authentication: API key is sent as Bearer token in Authorization header.
+         * The apiKey must be set in ApiClientConfig when creating the client.
+         *
+         * @param sandboxId - The sandbox content UID
+         * @returns Promise that resolves when download is initiated
+         */
+        downloadCode: (sandboxId: string) => Promise<void>;
+        /**
+         * Start VM endpoint that starts a desktop sandbox, launches Chrome,
+         * navigates to the target URL, and returns a VNC viewer URL
+         *
+         * Authentication: API key is sent as Bearer token in Authorization header.
+         * The apiKey must be set in ApiClientConfig when creating the client.
+         *
+         * @param request - The start VM request with url, optional mode, and optional resolution
+         * @returns The sandbox response with sandboxId and vncUrl (if mode=json)
+         *
+         * @example
+         * ```typescript
+         * const client = createApiClient({ apiKey: "your-api-key" });
+         * const response = await client.sdk.startVm({
+         *   url: "https://example.com",
+         *   mode: "json",
+         *   resolution: [1920, 1080]
+         * });
+         * ```
+         */
+        startVm: (request: StartVmRequest) => Promise<StartVmResponse>;
+    };
+}
+
+export declare interface ApiClientConfig {
+    /**
+     * API key for authentication. Will be sent as Bearer token in Authorization header.
+     * Required for all authenticated endpoints.
+     */
+    apiKey: string;
+}
+
 export declare interface BaseSettings {
     apiKey: string;
     primaryBrandColor: string;
@@ -15,6 +159,11 @@ export declare interface BaseSettings {
     [key: string]: any;
 }
 
+/**
+ * Build SandboxConfig from any SandboxContent (for switching between selections)
+ */
+export declare function buildConfigFromContent(content: SandboxContent): SandboxConfig;
+
 /**
  * Builds a nested GuardianConfig from use cases with nested frameworks.
  * Returns a structure where config[useCaseId].frameworks[frameworkKey] gives you the full config.
@@ -117,8 +266,77 @@ declare interface CodeOutput {
     full_code: string;
 }
 
+/**
+ * Create an API client instance
+ *
+ * @param config - Configuration for the API client
+ * @param config.apiKey - API key for authentication (sent as Bearer token in Authorization header)
+ * @returns An API client instance
+ *
+ * @example
+ * ```typescript
+ * // Create client with API key
+ * const client = createApiClient({
+ *   apiKey: process.env.NEXT_PUBLIC_SAMPLEAPP_API_KEY
+ * });
+ *
+ * // All requests will automatically include: Authorization: Bearer {apiKey}
+ * ```
+ */
+export declare function createApiClient(config: ApiClientConfig): ApiClient;
+
+/**
+ * Create a TreeSelection object from a path
+ */
+export declare function createSelection(config: TechStackConfig, path: string[]): TreeSelection;
+
 export declare const DEFAULT_THEME: ThemeName;
 
+/**
+ * Extract container ID from a browser URL
+ * @param browserUrl - URL like "https://nextjs-a3fcd2bb-2a15-4f9b-bd13-aeac52baebd2.sampleapp.love/?_ts=1767897000670"
+ * @returns Container ID like "nextjs-a3fcd2bb-2a15-4f9b-bd13-aeac52baebd2" or null if not found
+ */
+export declare function extractContainerIdFromUrl(browserUrl: string): string | null;
+
+/**
+ * Fetches sandbox configuration from the API (legacy method)
+ * @param apiKey - API key from SandboxProps
+ * @param sandboxId - Sandbox content UID (maps to sandbox_content_uid)
+ * @returns Sandbox configuration
+ * @deprecated Use fetchSandboxConfigWithContent for tree-based selection
+ */
+export declare function fetchSandboxConfig(apiKey: string, sandboxId: string): Promise<SandboxConfig>;
+
+/**
+ * Fetches sandbox configuration with all content for upfront loading
+ * This enables instant switching between tech stack options without API calls
+ *
+ * @param apiKey - API key from SandboxProps
+ * @param sandboxId - Sandbox content UID (maps to sandbox_content_uid)
+ * @returns Extended sandbox configuration with all content
+ */
+export declare function fetchSandboxConfigWithContent(apiKey: string, sandboxId: string): Promise<SandboxConfigWithContent>;
+
+/**
+ * Filter content entries by multiple criteria
+ *
+ * @param allContent - All sandbox content entries
+ * @param filters - Object with field names and values to filter by
+ * @returns Filtered array of content entries
+ */
+export declare function filterContent(allContent: SandboxContent[], filters: Partial<Pick<SandboxContent, "product" | "product_version" | "architecture" | "frontend" | "backend" | "framework">>): SandboxContent[];
+
+/**
+ * Find sandbox content that matches the current tree selection
+ * Matches against flat fields: product, product_version, architecture, frontend, backend, framework
+ *
+ * @param allContent - All sandbox content entries for the use case
+ * @param selection - Current tree selection
+ * @returns Matching content or null if not found
+ */
+export declare function findMatchingContent(allContent: SandboxContent[], selection: TreeSelection): SandboxContent | null;
+
 export declare enum Framework {
     FLASK = "flask",
     EXPRESS = "express",
@@ -129,29 +347,70 @@ export declare enum Framework {
     FASTMCP = "fastmcp"
 }
 
+/**
+ * Get the default path through the tree (following isDefault flags or first child)
+ * @param root - The root node
+ * @returns Array of keys representing the default selection path
+ */
+export declare function getDefaultPath(root: TreeNode): string[];
+
+/**
+ * Navigate the tree to find a node at a specific path
+ * @param root - The root node to start from
+ * @param path - Array of keys to follow
+ * @returns The node at the path, or null if not found
+ */
+export declare function getNodeAtPath(root: TreeNode, path: string[]): TreeNode | null;
+
+/**
+ * Get the display label for a node (falls back to key if no label)
+ */
+export declare function getNodeLabel(node: TreeNode): string;
+
+/**
+ * Get all nodes along a path (including the root)
+ * @param root - The root node
+ * @param path - Array of keys to follow
+ * @returns Array of nodes from root to the final node
+ */
+export declare function getNodesAlongPath(root: TreeNode, path: string[]): TreeNode[];
+
+/**
+ * Get selectable sections based on current selection path
+ * This builds the button groups shown in the header
+ * @param config - The tech stack configuration
+ * @param currentPath - Current selection path
+ * @returns Array of sections with their options
+ */
+export declare function getSelectableSections(config: TechStackConfig, currentPath: string[]): SelectorSection[];
+
 export declare const getTheme: (themeName?: ThemeName) => ThemeColors;
 
-export declare function GuardianComponent({ demoOptions, frameworkOptions, firstFrameworkByUseCase, currentFramework, currentUseCase, CustomConsole, GuideView, playgroundLogo, playgroundUid, browserUrl, useVm, sandboxUid, codeZipFile, completeCodeZipFile, variant, themeColor, hasPreview, isFrame, apiKey, env, chatUid, hideHeader, // Hardcoded to true by default, not exposed in Sandbox.tsx
-    gitUrl, }: GuardianComponentProps): default_2.JSX.Element;
+/**
+ * Get all unique values for a specific field from content entries
+ * Useful for building filter options
+ *
+ * @param allContent - All sandbox content entries
+ * @param field - The field to extract unique values from
+ * @returns Array of unique non-null values
+ */
+export declare function getUniqueFieldValues(allContent: SandboxContent[], field: keyof Pick<SandboxContent, "product" | "product_version" | "architecture" | "frontend" | "backend" | "framework">): string[];
+
+export declare function GuardianComponent({ sections, onSelect, currentFramework, currentUseCase, CustomConsole, GuideView, playgroundLogo, playgroundUid, browserUrl, useVm, sandboxUid, codeZipFile, completeCodeZipFile, variant, themeColor, hasPreview, isFrame, apiKey, env, chatUid, hideHeader, // Hardcoded to true by default, not exposed in Sandbox.tsx
+    gitUrl, hasNetworkView, stationaryPublishedUrl }: GuardianComponentProps): default_2.JSX.Element;
 
 export declare interface GuardianComponentProps {
     name: string;
     description: string;
-    demoOptions: {
-        label: string;
-        value: string;
-    }[];
-    frameworkOptions: {
-        label: string;
-        value: string;
-    }[];
+    /** Dynamic sections from useTreeSelector hook */
+    sections: SelectorSection[];
+    /** Handler when user selects an option */
+    onSelect: (nodeType: string, key: string) => void;
     CustomConsole: default_2.ComponentType<{
         onReloadPreview: () => void;
         onStageChange: (stage: "hidden" | "error" | "rebuilding") => void;
         themeColor: string;
     }> | string;
-    /** Maps use case ID to first available framework key */
-    firstFrameworkByUseCase?: Record<string, string>;
     /** The current framework key for this sandbox */
     currentFramework: string;
     /** The current use case ID (for nested config navigation) */
@@ -186,6 +445,10 @@ export declare interface GuardianComponentProps {
     /* Excluded from this release type: hideHeader */
     /** Optional Git URL for opening the project in VSCode */
     gitUrl?: string;
+    /** Whether to show the network requests view tab */
+    hasNetworkView?: boolean;
+    /** When true, keeps the first browserUrl per use case (prevents URL changes when toggling options) */
+    stationaryPublishedUrl?: boolean;
 }
 
 /**
@@ -231,17 +494,25 @@ declare interface GuardianFrameworkConfig extends Omit<GuardianComponentProps, '
 export declare type GuardianNestedConfig = Record<string, GuardianUseCaseConfig>;
 
 /**
- * Guardian Playground component with nested config structure.
- * Expects config[useCaseId].frameworks[frameworkKey] structure.
+ * Guardian Playground component with tree-based tech stack selection.
+ * Uses sections from useTreeSelector for dynamic header rendering.
  *
- * When isFrame=true, reads framework from URL params client-side.
+ * Note: Frame param overrides for node types (architecture, frontend, backend, etc.)
+ * are now handled in Sandbox.tsx via the tree selector sync mechanism.
+ * This component receives the already-resolved framework from the tree selector.
  */
-export declare function GuardianPlayground({ nestedConfig, useCase, framework: serverFramework, isFrame, apiKey, env, chatUid, theme, }: {
-    /** Nested config structure (use case → framework → config) */
-    nestedConfig: GuardianNestedConfig;
+export declare function GuardianPlayground({ sandboxConfig, sections, onSelect, useCase, framework, isFrame, apiKey, env, chatUid, theme, hasNetworkView, stationaryPublishedUrl }: GuardianPlaygroundProps): default_2.JSX.Element;
+
+declare interface GuardianPlaygroundProps {
+    /** Sandbox configuration */
+    sandboxConfig: SandboxConfig;
+    /** Dynamic sections from useTreeSelector hook */
+    sections: SelectorSection[];
+    /** Handler when user selects an option */
+    onSelect: (nodeType: string, key: string) => void;
     /** Current use case ID */
     useCase: string;
-    /** Current framework key (from server-side props) */
+    /** Current framework key (from tree selector) */
     framework: string;
     /** Whether to render in frame mode (just the right view) */
     isFrame?: boolean;
@@ -253,7 +524,11 @@ export declare function GuardianPlayground({ nestedConfig, useCase, framework: s
     chatUid?: string;
     /** Theme mode - "light", "dark", or "system". Defaults to "dark" */
     theme?: ThemeMode;
-}): default_2.JSX.Element;
+    /** Whether to show the network requests view tab */
+    hasNetworkView?: boolean;
+    /** When true, keeps the first browserUrl per use case (prevents URL changes when toggling options) */
+    stationaryPublishedUrl?: boolean;
+}
 
 export declare function GuardianProvider({ children }: {
     children: ReactNode;
@@ -296,6 +571,40 @@ export declare interface GuardianUseCaseConfig {
     frameworks: Record<string, GuardianFrameworkConfig>;
 }
 
+/**
+ * Check if content exists for a potential selection
+ * Used to disable/gray out options that have no content
+ *
+ * @param allContent - All sandbox content entries for the use case
+ * @param partialSelection - Partial selection to check (only specified fields are matched)
+ * @returns True if at least one content entry matches
+ */
+export declare function hasContentForSelection(allContent: SandboxContent[], partialSelection: Partial<TreeSelection["byType"]>): boolean;
+
+/**
+ * Header component for dynamic tech stack selection
+ *
+ * Uses sections from useTreeSelector to render selector buttons
+ * based on the tech_stack_config tree structure.
+ */
+export declare function Header({ sections, onSelect, playgroundLogo, themecolor }: HeaderProps): default_2.JSX.Element;
+
+export declare interface HeaderProps {
+    /** Dynamic sections from useTreeSelector hook */
+    sections: SelectorSection[];
+    /** Handler when user selects an option */
+    onSelect: (nodeType: string, key: string) => void;
+    /** Optional playground logo */
+    playgroundLogo?: default_2.ReactNode;
+    /** Theme color for selected state */
+    themecolor?: string;
+}
+
+/**
+ * Check if a path is complete (reaches a leaf node)
+ */
+export declare function isPathComplete(config: TechStackConfig, path: string[]): boolean;
+
 export declare const ModalSearchAndChat: default_2.FC<ModalSearchAndChatProps>;
 
 declare interface ModalSearchAndChatProps {
@@ -303,6 +612,29 @@ declare interface ModalSearchAndChatProps {
     onClose?: () => void;
 }
 
+/**
+ * Human-readable labels for node types
+ */
+export declare const NODE_TYPE_LABELS: Record<string, string>;
+
+/**
+ * All supported node types for tech stack selection
+ */
+export declare const NODE_TYPES: readonly ["root", "product", "version", "architecture", "frontend", "backend", "framework", "integration", "platform"];
+
+/**
+ * Type for node types
+ */
+export declare type NodeType = (typeof NODE_TYPES)[number];
+
+/**
+ * Convert a path to a byType map
+ * @param root - The root node
+ * @param path - Array of keys
+ * @returns Map of nodeType to selected key
+ */
+export declare function pathToByType(root: TreeNode, path: string[]): Record<string, string>;
+
 declare class SampleAppSDK {
     ModalSearchAndChat: (settings: SDKSettings, container?: HTMLElement) => {
         unmount: () => void;
@@ -342,7 +674,102 @@ declare class SampleAppSDK {
  * />
  * ```
  */
-export declare function Sandbox({ apiKey, sandboxId, env, themeColor, theme, }: SandboxProps): default_2.JSX.Element | null;
+/**
+ *
+ * Configurations for the config param
+ * {
+ *  isFrame: boolean;
+ * }
+ *
+ *
+ */
+export declare function Sandbox({ apiKey, sandboxId, env, themeColor, theme, config }: SandboxProps): default_2.JSX.Element | null;
+
+/**
+ * Configuration fetched from the API for a sandbox
+ */
+declare interface SandboxConfig {
+    /** Sandbox identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Theme color */
+    themeColor: string;
+    /** Whether preview is available */
+    hasPreview: boolean;
+    /** Optional playground logo */
+    playgroundLogo?: React.ReactNode;
+    /**
+     * Chat UID for starting the sandbox via API.
+     * NOTE: This is only used as a fallback when published_url is not available.
+     * If published_url exists in the framework config, it takes precedence and chatUid is not needed.
+     */
+    chatUid?: string;
+    /** List of use cases with frameworks */
+    useCases: GuardianUseCase[];
+}
+
+/**
+ * Configuration options for the Sandbox component
+ */
+declare interface SandboxConfigOptions {
+    /** Whether to render in frame mode (just the right view) */
+    isFrame?: boolean;
+    /** Whether to show the network requests view tab. Defaults to false */
+    hasNetworkView?: boolean;
+    /** Whether to keep the first browserUrl per use case (prevents URL changes when toggling options) */
+    stationaryPublishedUrl?: boolean;
+}
+
+/**
+ * Extended sandbox configuration with tree-based tech stack selection
+ */
+export declare interface SandboxConfigWithContent {
+    /** The use case containing the tech stack config */
+    useCase: SandboxUseCase;
+    /** Parsed tech stack configuration tree */
+    techStackConfig: TechStackConfig;
+    /** ALL sandbox content entries for this use case (for local filtering) */
+    allContent: SandboxContent[];
+    /** The initially requested sandbox content */
+    initialContent: SandboxContent;
+    /** Initial selection path from the content */
+    initialSelectionPath: string[];
+    /** Legacy config for backward compatibility */
+    legacyConfig: SandboxConfig;
+}
+
+export declare interface SandboxContent {
+    id: number;
+    uid: string;
+    use_case_id: number;
+    product: string | null;
+    product_version: string | null;
+    architecture: string | null;
+    frontend: string | null;
+    backend: string | null;
+    framework: string | null;
+    selection_path: string[] | null;
+    markdown: string | null;
+    github_url: string | null;
+    published_url: string | null;
+    is_vm_enabled: boolean;
+    generated_code_id: number | null;
+    generated_code?: UpdateContainerCodebaseType | null;
+    chat_uid: string | null;
+    playground_uid: string | null;
+    user_id: string | null;
+    has_preview: boolean;
+    created_at: string;
+    updated_at: string;
+}
+
+export declare interface SandboxContentPublic {
+    uid: string;
+    markdown: string | null;
+}
 
 export declare const SandboxHome: React_2.FC<SandboxHomeProps>;
 
@@ -351,6 +778,7 @@ export declare interface SandboxHomeProps {
     orgid: string;
     sandboxes?: SandboxItem[];
     basePath?: string;
+    theme?: ThemeMode;
 }
 
 export declare interface SandboxItem {
@@ -378,6 +806,21 @@ export declare interface SandboxProps {
     themeColor?: string;
     /** Theme mode - "light", "dark", or "system". Defaults to "dark" */
     theme?: ThemeMode;
+    /** Configuration options for the sandbox */
+    config?: SandboxConfigOptions;
+}
+
+export declare interface SandboxUseCase {
+    id: number;
+    uid: string;
+    name: string;
+    description: string | null;
+    tech_stack_config: Record<string, any>;
+    playground_uid: string | null;
+    is_public: boolean;
+    is_template: boolean;
+    created_at: string;
+    updated_at: string;
 }
 
 declare const sdk: SampleAppSDK;
@@ -388,6 +831,68 @@ export declare interface SDKSettings {
     aiChatSettings?: AiChatSettings;
 }
 
+/**
+ * Selectable node types (excludes "root" which is not user-selectable)
+ */
+export declare const SELECTABLE_NODE_TYPES: Exclude<NodeType, "root">[];
+
+/**
+ * A single option within a selector section
+ */
+export declare interface SelectorOption {
+    /** Unique key for this option */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Whether this option is currently selected */
+    isSelected: boolean;
+    /** Whether this option has content available (for disabling unavailable options) */
+    hasContent?: boolean;
+    /** Whether this option is a leaf node (has no children) */
+    isLeaf?: boolean;
+}
+
+/**
+ * A section of the selector (e.g., "Architecture:", "Frontend:", "Backend:")
+ */
+export declare interface SelectorSection {
+    /** The nodeType this section represents */
+    nodeType: string;
+    /** Display label for this section (e.g., "Architecture:") */
+    label: string;
+    /** Available options in this section */
+    options: SelectorOption[];
+}
+
+declare interface StartSandboxRequest {
+    /**
+     * Environment variables to pass to the sandbox.
+     * Required when published_url is not available (when starting a new sandbox).
+     * Optional when published_url exists (sandbox already exists).
+     */
+    env?: Record<string, any>;
+    /** Chat UID for starting the sandbox */
+    chatUid: string;
+}
+
+declare interface StartSandboxResponse {
+    container_url: string;
+}
+
+declare interface StartVmRequest {
+    /** Target URL to navigate to in Chrome */
+    url: string;
+    /** Response mode: 'redirect' or 'json' (default: 'json') */
+    mode?: "redirect" | "json";
+    /** Desktop resolution [width, height] in pixels */
+    resolution?: [number, number];
+}
+
+declare interface StartVmResponse {
+    sandboxId: string;
+    vncUrl: string;
+}
+
 export declare const TailwindExample: React_2.FC<TailwindExampleProps>;
 
 export declare interface TailwindExampleProps {
@@ -395,6 +900,13 @@ export declare interface TailwindExampleProps {
     description?: string;
 }
 
+/**
+ * Root structure of the tech stack configuration
+ */
+export declare interface TechStackConfig {
+    root: TreeNode;
+}
+
 export declare interface ThemeColors {
     primary: string;
     shadow: {
@@ -434,8 +946,106 @@ export declare type ThemeName = "ocean" | "autumn" | "mint" | "sunset" | "lavend
 
 export declare const themes: Record<ThemeName, ThemeColors>;
 
+/**
+ * Tree configuration types for dynamic tech stack selection
+ * Matches the tech_stack_config structure from SandboxUseCase
+ */
+/**
+ * A node in the tech stack tree
+ */
+export declare interface TreeNode {
+    /** Unique key for this node (e.g., "javascript-sdk", "react", "node.js") */
+    key: string;
+    /** Human-readable label (defaults to key if not provided) */
+    label?: string;
+    /** Type of this node - determines which selector group it belongs to */
+    nodeType: string;
+    /** Child nodes (next level of selection) */
+    children?: TreeNode[];
+    /** Whether this is the default selection at this level */
+    isDefault?: boolean;
+    /** Optional metadata for this node */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Current selection state in the tree
+ */
+export declare interface TreeSelection {
+    /** Array of selected keys from root to leaf (e.g., ["javascript-sdk", "react", "node.js"]) */
+    path: string[];
+    /** Map of nodeType to selected key (e.g., { architecture: "javascript-sdk", frontend: "react", backend: "node.js" }) */
+    byType: Record<string, string>;
+}
+
 declare type UpdateContainerCodebaseType = Record<string, CodeOutput>;
 
+/**
+ * Update the selection path when a user selects an option
+ * @param config - The tech stack configuration
+ * @param currentPath - Current selection path
+ * @param nodeType - The nodeType of the selection being changed
+ * @param selectedKey - The key of the newly selected option
+ * @returns New selection path
+ */
+export declare function updateSelectionPath(config: TechStackConfig, currentPath: string[], nodeType: string, selectedKey: string): string[];
+
+/**
+ * Hook for managing tree-based tech stack selection
+ *
+ * @example
+ * ```tsx
+ * const { selection, sections, currentContent, selectOption } = useTreeSelector({
+ *   config: techStackConfig,
+ *   allContent: sandboxContents,
+ *   initialPath: ["javascript-sdk", "react", "node.js"],
+ * });
+ *
+ * // Render sections
+ * {sections.map(section => (
+ *   <div key={section.nodeType}>
+ *     <span>{section.label}</span>
+ *     {section.options.map(opt => (
+ *       <button
+ *         key={opt.key}
+ *         onClick={() => selectOption(section.nodeType, opt.key)}
+ *         className={opt.isSelected ? "selected" : ""}
+ *       >
+ *         {opt.label}
+ *       </button>
+ *     ))}
+ *   </div>
+ * ))}
+ * ```
+ */
+export declare function useTreeSelector({ config, allContent, initialPath, onSelectionChange }: UseTreeSelectorOptions): UseTreeSelectorReturn;
+
+export declare interface UseTreeSelectorOptions {
+    /** The tech stack configuration tree */
+    config: TechStackConfig;
+    /** All sandbox content entries for this use case (for local filtering) */
+    allContent: SandboxContent[];
+    /** Initial selection path (from URL or saved state) */
+    initialPath?: string[];
+    /** Callback when selection changes */
+    onSelectionChange?: (selection: TreeSelection, content: SandboxContent | null) => void;
+}
+
+export declare interface UseTreeSelectorReturn {
+    /** Current selection state */
+    selection: TreeSelection;
+    /** Sections to render in the UI (button groups) */
+    sections: SelectorSection[];
+    /** Currently matched content based on selection */
+    currentContent: SandboxContent | null;
+    /** Handler for when user selects an option */
+    selectOption: (nodeType: string, key: string) => void;
+    /** Reset to default selection */
+    resetToDefault: () => void;
+    /** Set selection from a path */
+    setSelectionPath: (path: string[]) => void;
+}
+
 export declare const VmProvider: ({ children }: {
     children: ReactNode;
 }) => default_2.JSX.Element;