sandlot 0.1.0

package/dist/sandbox-manager.d.ts

@@ -0,0 +1,249 @@
+/**
+ * SandboxManager - Manages shared resources for multiple concurrent sandboxes.
+ *
+ * When running many sandboxes concurrently (e.g., for multiple AI agents),
+ * this manager ensures heavy resources are loaded once and shared:
+ *
+ * - TypeScript lib files (~5MB) - loaded once, shared across all sandboxes
+ * - esbuild WASM (~10MB) - already singleton, but pre-initialized here
+ *
+ * Usage:
+ * ```ts
+ * const manager = await createSandboxManager();
+ *
+ * // Create multiple sandboxes - all share the same libs and bundler
+ * const sandbox1 = await manager.createSandbox({ ... });
+ * const sandbox2 = await manager.createSandbox({ ... });
+ *
+ * // ... use sandboxes ...
+ *
+ * // Clean up
+ * manager.destroyAll();
+ * ```
+ */
+import { defineCommand } from "just-bash/browser";
+import { type IndexedDbFsOptions } from "./fs";
+import { type BundleResult } from "./bundler";
+import { type SharedResources, type SharedResourcesOptions } from "./shared-resources";
+import type { Sandbox } from "./sandbox";
+export type { BundleResult } from "./bundler";
+export type { TypecheckResult } from "./typechecker";
+export type { SharedResources, TypesCache } from "./shared-resources";
+export type { PackageManifest, InstallResult } from "./packages";
+export { installPackage, uninstallPackage, listPackages, getPackageManifest } from "./packages";
+export { InMemoryTypesCache } from "./shared-resources";
+export { loadModule, loadExport, loadDefault, getExportNames, hasExport, createModuleUrl, revokeModuleUrl, ModuleLoadError, ExportNotFoundError, } from "./loader";
+/**
+ * Options for creating a sandbox via the manager
+ */
+export interface ManagedSandboxOptions {
+    /**
+     * Unique identifier for this sandbox.
+     *
+     * Also used as the IndexedDB database name if `fsOptions.dbName` is not provided
+     * and `inMemory` is false. If both are provided, `fsOptions.dbName` takes precedence.
+     *
+     * @default Auto-generated as "sandbox-1", "sandbox-2", etc.
+     */
+    id?: string;
+    /**
+     * Options for the IndexedDB filesystem.
+     *
+     * Note: `fsOptions.dbName` takes precedence over `id` for the database name.
+     * If neither is provided, the auto-generated `id` is used.
+     */
+    fsOptions?: IndexedDbFsOptions;
+    /**
+     * Initial files to populate the filesystem with
+     */
+    initialFiles?: Record<string, string>;
+    /**
+     * Path to tsconfig.json in the virtual filesystem.
+     * Default: "/tsconfig.json"
+     */
+    tsconfigPath?: string;
+    /**
+     * Callback invoked when a build succeeds.
+     * Receives the bundle result with the compiled code.
+     */
+    onBuild?: (result: BundleResult) => void | Promise<void>;
+    /**
+     * Additional custom commands to add to the bash environment
+     */
+    customCommands?: ReturnType<typeof defineCommand>[];
+    /**
+     * If true, use in-memory filesystem only (no IndexedDB persistence).
+     * Default: true
+     */
+    inMemory?: boolean;
+    /**
+     * Module IDs that should be resolved from the host's SharedModuleRegistry
+     * instead of esm.sh CDN. Overrides manager-level sharedModules for this sandbox.
+     *
+     * @see SandboxOptions.sharedModules for full documentation
+     */
+    sharedModules?: string[];
+}
+/**
+ * A sandbox instance managed by the SandboxManager.
+ *
+ * Extends the base Sandbox interface with an `id` property for
+ * identification within the manager. This ensures ManagedSandbox
+ * has full feature parity with Sandbox.
+ */
+export interface ManagedSandbox extends Sandbox {
+    /**
+     * Unique identifier for this sandbox within the manager.
+     */
+    id: string;
+}
+/**
+ * Statistics about the sandbox manager
+ */
+export interface SandboxManagerStats {
+    /**
+     * Whether shared resources have been initialized
+     */
+    initialized: boolean;
+    /**
+     * Number of currently active sandboxes
+     */
+    activeSandboxes: number;
+    /**
+     * Number of TypeScript lib files loaded
+     */
+    libFilesCount: number;
+    /**
+     * IDs of active sandboxes
+     */
+    sandboxIds: string[];
+}
+/**
+ * Options for creating a SandboxManager
+ */
+export interface SandboxManagerOptions extends SharedResourcesOptions {
+    /**
+     * TypeScript libs to load. Defaults to browser libs (ES2020 + DOM).
+     */
+    libs?: string[];
+    /**
+     * Default shared modules for all sandboxes created by this manager.
+     * Individual sandboxes can override with their own sharedModules option.
+     *
+     * Module IDs that should be resolved from the host's SharedModuleRegistry
+     * instead of esm.sh CDN. The host must have registered these modules
+     * using `registerSharedModules()` before loading dynamic code.
+     *
+     * @example
+     * ```ts
+     * const manager = await createSandboxManager({
+     *   sharedModules: ['react', 'react-dom/client'],
+     * });
+     * ```
+     */
+    sharedModules?: string[];
+}
+/**
+ * Manager for creating and managing multiple sandboxes with shared resources.
+ */
+export declare class SandboxManager {
+    private resources;
+    private sandboxes;
+    private initialized;
+    private initPromise;
+    private nextId;
+    private options;
+    constructor(options?: SandboxManagerOptions);
+    /**
+     * Initialize shared resources (libs and bundler).
+     * Called automatically on first sandbox creation, but can be called
+     * explicitly to pre-warm.
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Create a new managed sandbox.
+     * Shares TypeScript libs and bundler with all other sandboxes.
+     */
+    createSandbox(options?: ManagedSandboxOptions): Promise<ManagedSandbox>;
+    /**
+     * Get a sandbox by ID
+     */
+    getSandbox(id: string): ManagedSandbox | undefined;
+    /**
+     * Get all active sandboxes
+     */
+    getAllSandboxes(): ManagedSandbox[];
+    /**
+     * Close a specific sandbox
+     */
+    closeSandbox(id: string): boolean;
+    /**
+     * Close all sandboxes and release resources
+     */
+    destroyAll(): void;
+    /**
+     * Save all sandboxes that have unsaved changes.
+     *
+     * @returns Map of sandbox ID to save result (true if saved, false if nothing to save)
+     *
+     * @example
+     * ```ts
+     * const results = await manager.saveAll();
+     * for (const [id, saved] of results) {
+     *   console.log(`${id}: ${saved ? 'saved' : 'no changes'}`);
+     * }
+     * ```
+     */
+    saveAll(): Promise<Map<string, boolean>>;
+    /**
+     * Get IDs of sandboxes with unsaved changes.
+     *
+     * @example
+     * ```ts
+     * const dirtyIds = manager.getDirtySandboxes();
+     * if (dirtyIds.length > 0) {
+     *   console.log('Unsaved sandboxes:', dirtyIds.join(', '));
+     * }
+     * ```
+     */
+    getDirtySandboxes(): string[];
+    /**
+     * Get statistics about the manager
+     */
+    getStats(): SandboxManagerStats;
+    /**
+     * Get the shared resources (for advanced use cases)
+     */
+    getResources(): SharedResources | null;
+    /**
+     * Get the shared lib files (for advanced use cases)
+     * @deprecated Use getResources().libFiles instead
+     */
+    getLibFiles(): Map<string, string>;
+}
+/**
+ * Create a new SandboxManager instance.
+ *
+ * @example
+ * ```ts
+ * const manager = await createSandboxManager();
+ *
+ * // Create multiple sandboxes concurrently
+ * const [sandbox1, sandbox2] = await Promise.all([
+ *   manager.createSandbox({ id: "agent-1", initialFiles: { ... } }),
+ *   manager.createSandbox({ id: "agent-2", initialFiles: { ... } }),
+ * ]);
+ *
+ * // Run operations in parallel
+ * const [result1, result2] = await Promise.all([
+ *   sandbox1.bash.exec("build"),
+ *   sandbox2.bash.exec("build"),
+ * ]);
+ *
+ * // Clean up
+ * manager.destroyAll();
+ * ```
+ */
+export declare function createSandboxManager(options?: SandboxManagerOptions): Promise<SandboxManager>;
+//# sourceMappingURL=sandbox-manager.d.ts.map

package/dist/sandbox-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../src/sandbox-manager.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.d.ts

@@ -0,0 +1,193 @@
+import { Bash, defineCommand } from "just-bash/browser";
+import { IndexedDbFs, type IndexedDbFsOptions } from "./fs";
+import { type BundleResult } from "./bundler";
+import { type SharedResources } from "./shared-resources";
+export type { BundleResult } from "./bundler";
+export type { TypecheckResult } from "./typechecker";
+export type { SharedResources, TypesCache } from "./shared-resources";
+export type { PackageManifest, InstallResult } from "./packages";
+export type { RunContext, RunOptions, RunResult } from "./commands";
+export { installPackage, uninstallPackage, listPackages, getPackageManifest } from "./packages";
+export { InMemoryTypesCache } from "./shared-resources";
+export { loadModule, loadExport, loadDefault, getExportNames, hasExport, createModuleUrl, revokeModuleUrl, ModuleLoadError, ExportNotFoundError, } from "./loader";
+/**
+ * Options for creating a sandbox environment
+ */
+export interface SandboxOptions {
+    /**
+     * Options for the IndexedDB filesystem
+     */
+    fsOptions?: IndexedDbFsOptions;
+    /**
+     * Path to tsconfig.json in the virtual filesystem.
+     * Default: "/tsconfig.json"
+     */
+    tsconfigPath?: string;
+    /**
+     * Shared resources (lib files, bundler).
+     * If not provided, uses the default singleton resources.
+     *
+     * Provide this to share resources across multiple sandboxes,
+     * or to use custom TypeScript libs.
+     */
+    resources?: SharedResources;
+    /**
+     * Callback invoked when a build succeeds.
+     * Receives the bundle result with the compiled code.
+     * Use this to dynamically import the bundle or halt the agent.
+     */
+    onBuild?: (result: BundleResult) => void | Promise<void>;
+    /**
+     * Additional custom commands to add to the bash environment
+     */
+    customCommands?: ReturnType<typeof defineCommand>[];
+    /**
+     * Module IDs that should be resolved from the host's SharedModuleRegistry
+     * instead of esm.sh CDN. The host must have registered these modules
+     * using `registerSharedModules()` before loading dynamic code.
+     *
+     * This solves the "multiple React instances" problem by allowing dynamic
+     * components to share the same React instance as the host application.
+     *
+     * @example
+     * ```ts
+     * // Host setup
+     * import * as React from 'react';
+     * import * as ReactDOM from 'react-dom/client';
+     * import { registerSharedModules } from 'sandlot';
+     *
+     * registerSharedModules({
+     *   'react': React,
+     *   'react-dom/client': ReactDOM,
+     * });
+     *
+     * // Create sandbox with shared modules
+     * const sandbox = await createInMemorySandbox({
+     *   sharedModules: ['react', 'react-dom/client'],
+     * });
+     * ```
+     */
+    sharedModules?: string[];
+}
+/**
+ * The sandbox environment containing the filesystem and bash shell
+ */
+export interface Sandbox {
+    /**
+     * The virtual filesystem (IndexedDB-backed)
+     */
+    fs: IndexedDbFs;
+    /**
+     * The just-bash shell environment
+     */
+    bash: Bash;
+    /**
+     * Check if there are unsaved changes in the filesystem.
+     *
+     * @example
+     * ```ts
+     * await sandbox.bash.exec('echo "hello" > /test.txt');
+     * console.log(sandbox.isDirty()); // true
+     * await sandbox.save();
+     * console.log(sandbox.isDirty()); // false
+     * ```
+     */
+    isDirty(): boolean;
+    /**
+     * Save the filesystem to IndexedDB.
+     *
+     * @returns true if saved, false if nothing to save or in-memory only
+     */
+    save(): Promise<boolean>;
+    /**
+     * Close all resources (filesystem, etc.)
+     */
+    close(): void;
+    /**
+     * Subscribe to build events. Called whenever a build succeeds.
+     * Returns an unsubscribe function.
+     *
+     * Use this to capture the bundle result when build succeeds.
+     * The callback receives the BundleResult with the compiled code.
+     *
+     * @example
+     * ```ts
+     * let bundle: BundleResult | null = null;
+     *
+     * const sandbox = await createInMemorySandbox({
+     *   onBuild: (result) => {
+     *     bundle = result;
+     *     console.log('Built:', result.code.length, 'bytes');
+     *   },
+     * });
+     *
+     * // ... agent writes files and calls build ...
+     *
+     * // After successful build, bundle is available
+     * console.log(bundle?.code);
+     * ```
+     */
+    onBuild(callback: (result: BundleResult) => void | Promise<void>): () => void;
+}
+/**
+ * Create an in-browser agent sandbox with a virtual filesystem, TypeScript
+ * type checking, and bundling capabilities.
+ *
+ * The sandbox provides a just-bash shell with custom commands:
+ * - `tsc [entry]` - Type check the project
+ * - `build [entry] [options]` - Build the project (runs typecheck first)
+ *
+ * Build options:
+ * - `--output, -o <path>` - Output path (default: /dist/bundle.js)
+ * - `--format, -f <esm|iife|cjs>` - Output format (default: esm)
+ * - `--minify, -m` - Enable minification
+ * - `--skip-typecheck, -s` - Skip type checking
+ *
+ * @example
+ * ```ts
+ * let bundleResult: BundleResult | null = null;
+ *
+ * const sandbox = await createSandbox({
+ *   fsOptions: {
+ *     dbName: "my-project",
+ *     initialFiles: {
+ *       "/src/index.ts": "export const hello = 'world';",
+ *       "/tsconfig.json": JSON.stringify({
+ *         compilerOptions: { target: "ES2020", strict: true }
+ *       }),
+ *     },
+ *   },
+ *   onBuild: (result) => {
+ *     bundleResult = result;
+ *     // Could also: dynamically import, halt agent, etc.
+ *   },
+ * });
+ *
+ * // Use bash commands
+ * await sandbox.bash.exec('echo "console.log(1);" > /src/index.ts');
+ *
+ * // Type check
+ * const tscResult = await sandbox.bash.exec("tsc");
+ * console.log(tscResult.stdout);
+ *
+ * // Build (includes typecheck, triggers onBuild callback)
+ * const buildResult = await sandbox.bash.exec("build");
+ * console.log(buildResult.stdout);
+ * console.log(bundleResult?.code); // The compiled bundle
+ *
+ * // Save to IndexedDB
+ * await sandbox.save();
+ *
+ * // Clean up
+ * sandbox.close();
+ * ```
+ */
+export declare function createSandbox(options?: SandboxOptions): Promise<Sandbox>;
+/**
+ * Create an in-memory sandbox (no IndexedDB persistence).
+ * Useful for testing or temporary workspaces.
+ */
+export declare function createInMemorySandbox(options?: Omit<SandboxOptions, "fsOptions"> & {
+    initialFiles?: Record<string, string>;
+}): Promise<Sandbox>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,MAAM,CAAC;AAC5D,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG/E,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACjE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAuDlB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAE/B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;OAEG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,EAAE,CAAC;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,EAAE,EAAE,WAAW,CAAC;IAEhB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IAEX;;;;;;;;;;OAUG;IACH,OAAO,IAAI,OAAO,CAAC;IAEnB;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;CAC/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgElF;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,GACL,OAAO,CAAC,OAAO,CAAC,CA8DlB"}

package/dist/shared-modules.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Shared Module Registry for Sandlot
+ *
+ * Allows host applications to register their module instances (like React)
+ * so that dynamically bundled code can use the same instances instead of
+ * loading separate copies from esm.sh CDN.
+ *
+ * This solves the "multiple React instances" problem where hooks fail
+ * because the host and dynamic code use different React copies.
+ *
+ * @example
+ * ```ts
+ * // Host application setup
+ * import * as React from 'react';
+ * import * as ReactDOM from 'react-dom/client';
+ * import { registerSharedModules } from 'sandlot';
+ *
+ * registerSharedModules({
+ *   'react': React,
+ *   'react-dom/client': ReactDOM,
+ * });
+ *
+ * // Now create sandbox with sharedModules option
+ * const sandbox = await createInMemorySandbox({
+ *   sharedModules: ['react', 'react-dom/client'],
+ * });
+ * ```
+ */
+/**
+ * Registry for sharing host modules with dynamic bundles.
+ * Modules registered here will be used instead of esm.sh CDN
+ * when the sandbox is configured with matching sharedModules.
+ */
+export declare class SharedModuleRegistry {
+    private modules;
+    constructor();
+    /**
+     * Register a module to be shared with dynamic bundles
+     *
+     * @param moduleId - The import specifier (e.g., 'react', 'react-dom/client')
+     * @param module - The module's exports object
+     * @returns this for chaining
+     */
+    register(moduleId: string, module: unknown): this;
+    /**
+     * Register multiple modules at once
+     *
+     * @param modules - Object mapping module IDs to their exports
+     * @returns this for chaining
+     */
+    registerAll(modules: Record<string, unknown>): this;
+    /**
+     * Unregister a previously registered module
+     *
+     * @param moduleId - The import specifier to remove
+     * @returns true if the module was registered and removed
+     */
+    unregister(moduleId: string): boolean;
+    /**
+     * Get a registered module (used by dynamic bundles at runtime)
+     *
+     * @param moduleId - The import specifier
+     * @returns The registered module exports
+     * @throws Error if the module is not registered
+     */
+    get(moduleId: string): unknown;
+    /**
+     * Check if a module is registered
+     *
+     * @param moduleId - The import specifier to check
+     */
+    has(moduleId: string): boolean;
+    /**
+     * Get list of all registered module IDs
+     */
+    list(): string[];
+    /**
+     * Clear all registrations
+     */
+    clear(): void;
+    /**
+     * Get the number of registered modules
+     */
+    get size(): number;
+}
+/**
+ * Get the default shared module registry.
+ * Creates it if it doesn't exist.
+ */
+export declare function getSharedModuleRegistry(): SharedModuleRegistry;
+/**
+ * Check if a shared module registry exists on globalThis
+ */
+export declare function hasSharedModuleRegistry(): boolean;
+/**
+ * Convenience function to register modules with the default registry.
+ *
+ * @param modules - Object mapping module IDs to their exports
+ *
+ * @example
+ * ```ts
+ * import * as React from 'react';
+ * import * as ReactDOM from 'react-dom/client';
+ * import { registerSharedModules } from 'sandlot';
+ *
+ * registerSharedModules({
+ *   'react': React,
+ *   'react-dom/client': ReactDOM,
+ * });
+ * ```
+ */
+export declare function registerSharedModules(modules: Record<string, unknown>): void;
+/**
+ * Convenience function to unregister a module from the default registry.
+ *
+ * @param moduleId - The import specifier to remove
+ * @returns true if the module was registered and removed
+ */
+export declare function unregisterSharedModule(moduleId: string): boolean;
+/**
+ * Clear all shared modules from the default registry.
+ */
+export declare function clearSharedModules(): void;
+/**
+ * Generate the runtime code that dynamic bundles use to access shared modules.
+ * This is injected into bundles when they import from shared modules.
+ */
+export declare function getSharedModuleRuntimeCode(moduleId: string): string;
+//# sourceMappingURL=shared-modules.d.ts.map

package/dist/shared-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-modules.d.ts","sourceRoot":"","sources":["../src/shared-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH;;;;GAIG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAA8B;;IAO7C;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAKjD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOnD;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;OAMG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAa9B;;;;OAIG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;IAIhB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAKD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAK9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAanE"}

package/dist/shared-resources.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared resources for sandbox environments.
+ *
+ * Provides centralized management of expensive shared resources:
+ * - TypeScript lib files (~5MB) - loaded once, shared across all sandboxes
+ * - esbuild WASM (~10MB) - singleton bundler initialization
+ * - Types cache - avoids redundant network fetches when multiple sandboxes
+ *   install the same packages
+ *
+ * This module consolidates what was previously scattered across
+ * sandbox.ts and sandbox-manager.ts into a single source of truth.
+ */
+import { type TypesCache } from "./packages";
+export type { TypesCache } from "./packages";
+export { InMemoryTypesCache } from "./packages";
+/**
+ * Shared resources that can be reused across multiple sandboxes
+ */
+export interface SharedResources {
+    /**
+     * Pre-loaded TypeScript lib files for type checking
+     */
+    libFiles: Map<string, string>;
+    /**
+     * Promise that resolves when the bundler is ready
+     */
+    bundlerReady: Promise<void>;
+    /**
+     * Cache for package type definitions.
+     * Avoids redundant network fetches when multiple sandboxes
+     * install the same packages.
+     */
+    typesCache: TypesCache;
+}
+/**
+ * Options for creating shared resources
+ */
+export interface SharedResourcesOptions {
+    /**
+     * TypeScript libs to load. Defaults to browser libs (ES2020 + DOM).
+     */
+    libs?: string[];
+    /**
+     * If true, skip fetching TypeScript libs.
+     * libFiles will be an empty Map.
+     * Default: false
+     */
+    skipLibs?: boolean;
+    /**
+     * If true, skip pre-initializing the bundler.
+     * bundlerReady will resolve immediately.
+     * Default: false
+     */
+    skipBundler?: boolean;
+}
+/**
+ * Create a new SharedResources instance.
+ *
+ * Use this when you want to manage resource lifecycle explicitly,
+ * or when you need custom libs configuration.
+ *
+ * @example
+ * ```ts
+ * // Create resources with custom libs
+ * const resources = await createSharedResources({
+ *   libs: ['es2022', 'dom', 'webworker'],
+ * });
+ *
+ * // Pass to sandbox creation
+ * const sandbox = await createSandbox({
+ *   resources,
+ *   fsOptions: { ... },
+ * });
+ * ```
+ */
+export declare function createSharedResources(options?: SharedResourcesOptions): Promise<SharedResources>;
+/**
+ * Get the default shared resources singleton.
+ *
+ * Loads resources once and returns the same instance for all callers.
+ * This is the recommended way to get shared resources for most use cases.
+ *
+ * @example
+ * ```ts
+ * // Get default resources (creates on first call)
+ * const resources = await getDefaultResources();
+ *
+ * // Create multiple sandboxes sharing the same resources
+ * const sandbox1 = await createSandbox({ resources, ... });
+ * const sandbox2 = await createSandbox({ resources, ... });
+ * ```
+ */
+export declare function getDefaultResources(): Promise<SharedResources>;
+/**
+ * Clear the default resources singleton (for testing).
+ *
+ * Note: This doesn't unload the bundler WASM - that stays in memory
+ * until page reload. This only clears the cached lib files reference.
+ */
+export declare function clearDefaultResources(): void;
+/**
+ * Check if the default resources have been initialized.
+ */
+export declare function hasDefaultResources(): boolean;
+//# sourceMappingURL=shared-resources.d.ts.map

package/dist/shared-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-resources.d.ts","sourceRoot":"","sources":["../src/shared-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAGjE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE9B;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAapE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C"}