@illuma-ai/code-sandbox 1.1.0 → 1.2.1

package/dist/components/Workbench.d.ts

@@ -13,8 +13,9 @@
  *
  * @see bolt.diy: app/components/workbench/Workbench.client.tsx (reference)
  */
+import React from "react";
 import "allotment/dist/style.css";
-import type { CodeSandboxProps } from "../types";
+import type { CodeSandboxProps, CodeSandboxHandle } from "../types";
 /**
  * CodeSandbox — The main entrypoint component.
  *
@@ -25,4 +26,4 @@ import type { CodeSandboxProps } from "../types";
  * A compact toolbar row contains the view toggle and (in preview mode)
  * a URL bar with refresh button.
  */
-export declare function CodeSandbox(props: CodeSandboxProps): import("react/jsx-runtime").JSX.Element;
+export declare const CodeSandbox: React.ForwardRefExoticComponent<CodeSandboxProps & React.RefAttributes<CodeSandboxHandle>>;

package/dist/hooks/useRuntime.d.ts

@@ -4,9 +4,9 @@
  * Manages the Nodepod runtime instance and exposes reactive state
  * for all UI components (progress, files, terminal output, preview URL).
  *
- * Supports two file sources:
- * 1. Direct files (via `files` prop or `template` prop)
- * 2. GitHub repo (via `github` prop) — with branch polling for hot-reload
+ * The sandbox is a pure renderer — it receives files via props (initial
+ * load) and via the imperative handle (updateFiles/updateFile for live
+ * updates). It does NOT interact with any storage backend directly.
  *
  * Error exposure: wires the runtime's structured error system and the
  * preview iframe's browser error capture into a unified `errors[]` array
@@ -14,24 +14,26 @@
  * so the AI agent can auto-fix.
  */
 import { NodepodRuntime } from "../services/runtime";
-import type { CodeSandboxProps, FileMap, RuntimeState, SandboxError } from "../types";
+import type { CodeSandboxProps, FileChangeStatus, FileMap, RuntimeState, SandboxError } from "../types";
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
+ * The sandbox is a pure renderer — it receives files via props or the
+ * imperative handle. No polling, no storage backends.
+ *
  * @param props - CodeSandbox component props
- * @returns Reactive runtime state + control functions
+ * @returns Reactive runtime state + control functions + imperative methods
  *
  * @example
  * ```tsx
- * // Direct files
- * const { state } = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
- *
- * // GitHub repo with auto-polling
- * const { state } = useRuntime({
- *   github: { owner: 'illuma-ai', repo: 'fullstack-starter', branch: 'main' },
- *   gitToken: 'ghp_xxx',
- *   onSandboxError: (err) => agent.fix(err),
- * });
+ * // Direct files (fetched from any source by the host app)
+ * const runtime = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // Later, push updated files from the host:
+ * await runtime.updateFiles(newFiles);
+ *
+ * // Or update a single file:
+ * await runtime.updateFile('server.js', newContent);
  * ```
  */
 export declare function useRuntime(props: CodeSandboxProps): {
@@ -43,6 +45,14 @@ export declare function useRuntime(props: CodeSandboxProps): {
     handleCloseFile: (path: string) => void;
     handleBrowserError: (error: SandboxError) => Promise<void>;
     restart: () => Promise<void>;
+    updateFiles: (newFiles: FileMap, options?: {
+        restartServer?: boolean;
+    }) => Promise<void>;
+    updateFile: (path: string, content: string) => Promise<void>;
+    getFiles: () => FileMap;
     getChangedFiles: () => FileMap;
+    getFileChanges: () => Record<string, FileChangeStatus>;
+    getErrors: () => SandboxError[];
+    getState: () => RuntimeState;
     runtime: import("react").MutableRefObject<NodepodRuntime | null>;
 };