sandlot 0.1.0

package/dist/loader.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Module loader utilities for Sandlot bundles.
+ *
+ * Takes a BundleResult and turns it into usable JavaScript exports.
+ * No external dependencies - just the basics for loading compiled code.
+ *
+ * @example
+ * ```ts
+ * // Capture the bundle via onBuild callback
+ * let buildResult: BundleResult | null = null;
+ * const unsubscribe = sandbox.onBuild((result) => {
+ *   buildResult = result;
+ * });
+ *
+ * const cmd = await sandbox.bash.exec("build /src/index.ts");
+ * if (cmd.exitCode === 0 && buildResult) {
+ *   // Load all exports
+ *   const module = await loadModule<{ add: (a: number, b: number) => number }>(buildResult);
+ *   console.log(module.add(1, 2)); // 3
+ *
+ *   // Load a specific export
+ *   const add = await loadExport<(a: number, b: number) => number>(buildResult, "add");
+ *   console.log(add(1, 2)); // 3
+ * }
+ * unsubscribe();
+ * ```
+ */
+import type { BundleResult } from "./bundler";
+/**
+ * Error thrown when loading a module fails
+ */
+export declare class ModuleLoadError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Error thrown when an expected export is not found
+ */
+export declare class ExportNotFoundError extends Error {
+    readonly exportName: string;
+    readonly availableExports: string[];
+    constructor(exportName: string, availableExports: string[]);
+}
+/**
+ * Create a blob URL for a bundle that can be dynamically imported.
+ * Remember to call `revokeModuleUrl()` when done to free memory.
+ *
+ * @param result - The bundle result from a successful build
+ * @returns A blob URL that can be passed to `import()`
+ *
+ * @example
+ * ```ts
+ * const url = createModuleUrl(buildResult);
+ * try {
+ *   const module = await import(url);
+ *   console.log(module.default);
+ * } finally {
+ *   revokeModuleUrl(url);
+ * }
+ * ```
+ */
+export declare function createModuleUrl(result: BundleResult): string;
+/**
+ * Revoke a blob URL created by `createModuleUrl()`.
+ * This frees the memory associated with the blob.
+ *
+ * @param url - The blob URL to revoke
+ */
+export declare function revokeModuleUrl(url: string): void;
+/**
+ * Load all exports from a bundle result.
+ *
+ * @typeParam T - The expected shape of the module's exports
+ * @param result - The bundle result from a successful build
+ * @returns A promise that resolves to the module's exports
+ * @throws {ModuleLoadError} If the module fails to load
+ *
+ * @example
+ * ```ts
+ * interface MyModule {
+ *   add: (a: number, b: number) => number;
+ *   multiply: (a: number, b: number) => number;
+ * }
+ *
+ * const module = await loadModule<MyModule>(buildResult);
+ * console.log(module.add(2, 3)); // 5
+ * console.log(module.multiply(2, 3)); // 6
+ * ```
+ */
+export declare function loadModule<T = Record<string, unknown>>(result: BundleResult): Promise<T>;
+/**
+ * Load a specific named export from a bundle result.
+ *
+ * @typeParam T - The expected type of the export
+ * @param result - The bundle result from a successful build
+ * @param exportName - The name of the export to retrieve (use "default" for default export)
+ * @returns A promise that resolves to the export's value
+ * @throws {ModuleLoadError} If the module fails to load
+ * @throws {ExportNotFoundError} If the export doesn't exist
+ *
+ * @example
+ * ```ts
+ * // Load a named export
+ * const add = await loadExport<(a: number, b: number) => number>(
+ *   buildResult,
+ *   "add"
+ * );
+ * console.log(add(2, 3)); // 5
+ *
+ * // Load the default export
+ * const Calculator = await loadExport<typeof Calculator>(
+ *   buildResult,
+ *   "default"
+ * );
+ * ```
+ */
+export declare function loadExport<T = unknown>(result: BundleResult, exportName?: string): Promise<T>;
+/**
+ * Load the default export from a bundle result.
+ * Convenience wrapper around `loadExport(result, "default")`.
+ *
+ * @typeParam T - The expected type of the default export
+ * @param result - The bundle result from a successful build
+ * @returns A promise that resolves to the default export
+ * @throws {ModuleLoadError} If the module fails to load
+ * @throws {ExportNotFoundError} If there is no default export
+ *
+ * @example
+ * ```ts
+ * // For a module that does: export default function add(a, b) { return a + b; }
+ * const add = await loadDefault<(a: number, b: number) => number>(buildResult);
+ * console.log(add(2, 3)); // 5
+ * ```
+ */
+export declare function loadDefault<T = unknown>(result: BundleResult): Promise<T>;
+/**
+ * Get a list of export names from a bundle result.
+ * Useful for introspection or debugging.
+ *
+ * @param result - The bundle result from a successful build
+ * @returns A promise that resolves to an array of export names
+ *
+ * @example
+ * ```ts
+ * const exports = await getExportNames(buildResult);
+ * console.log(exports); // ["add", "multiply", "default"]
+ * ```
+ */
+export declare function getExportNames(result: BundleResult): Promise<string[]>;
+/**
+ * Check if a bundle has a specific export.
+ *
+ * @param result - The bundle result from a successful build
+ * @param exportName - The name of the export to check for
+ * @returns A promise that resolves to true if the export exists
+ *
+ * @example
+ * ```ts
+ * if (await hasExport(buildResult, "add")) {
+ *   const add = await loadExport(buildResult, "add");
+ * }
+ * ```
+ */
+export declare function hasExport(result: BundleResult, exportName: string): Promise<boolean>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI7C;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,gBAAgB,EAAE,MAAM,EAAE;gBAD1B,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EAAE;CAQ7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAG5D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,MAAM,EAAE,YAAY,EACpB,UAAU,GAAE,MAAkB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/packages.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Package management for sandbox environments.
+ *
+ * Provides npm-like package installation using esm.sh CDN:
+ * - Fetches TypeScript type definitions for editor/typecheck support
+ * - Stores installed versions in package.json
+ * - Resolves bare imports to CDN URLs at bundle time
+ * - Supports @types/* packages (fetches package content as types)
+ * - Supports subpath exports (react-dom/client, react/jsx-runtime)
+ *
+ * @example
+ * ```ts
+ * // Install a package
+ * const result = await installPackage(fs, "react");
+ * // result: { name: "react", version: "18.2.0", typesInstalled: true }
+ *
+ * // Get installed packages
+ * const manifest = await getPackageManifest(fs);
+ * // manifest.dependencies: { "react": "18.2.0" }
+ *
+ * // Resolve import to CDN URL
+ * const url = resolveToEsmUrl("react", "18.2.0");
+ * // url: "https://esm.sh/react@18.2.0"
+ * ```
+ */
+import type { IFileSystem } from "just-bash/browser";
+/**
+ * Package manifest (subset of package.json)
+ */
+export interface PackageManifest {
+    dependencies: Record<string, string>;
+}
+/**
+ * Cache for storing fetched type definitions.
+ * Used to avoid redundant network fetches when multiple sandboxes
+ * install the same packages.
+ */
+export interface TypesCache {
+    /**
+     * Get cached type definitions for a package version.
+     * Returns null if not cached.
+     */
+    get(name: string, version: string): Map<string, string> | null;
+    /**
+     * Store type definitions in the cache.
+     */
+    set(name: string, version: string, types: Map<string, string>): void;
+    /**
+     * Check if a package version is cached.
+     */
+    has(name: string, version: string): boolean;
+    /**
+     * Remove a package version from the cache.
+     */
+    delete(name: string, version: string): boolean;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+}
+/**
+ * In-memory implementation of TypesCache.
+ * Suitable for sharing across multiple sandboxes within a session.
+ */
+export declare class InMemoryTypesCache implements TypesCache {
+    private cache;
+    private key;
+    get(name: string, version: string): Map<string, string> | null;
+    set(name: string, version: string, types: Map<string, string>): void;
+    has(name: string, version: string): boolean;
+    delete(name: string, version: string): boolean;
+    clear(): void;
+    /**
+     * Get the number of cached packages (for diagnostics).
+     */
+    get size(): number;
+}
+/**
+ * Result of installing a package
+ */
+export interface InstallResult {
+    /** Package name */
+    name: string;
+    /** Resolved version */
+    version: string;
+    /** Whether type definitions were installed */
+    typesInstalled: boolean;
+    /** Number of type definition files installed */
+    typeFilesCount: number;
+    /** Error message if types failed (but package still usable) */
+    typesError?: string;
+    /** Whether types were loaded from cache */
+    fromCache?: boolean;
+}
+/**
+ * Options for installing a package
+ */
+export interface InstallOptions {
+    /**
+     * Cache to use for storing/retrieving type definitions.
+     * When provided, avoids redundant network fetches for packages
+     * that have already been installed in other sandboxes.
+     */
+    cache?: TypesCache;
+}
+/**
+ * Parse package specifier into name and version
+ * Examples:
+ *   "react" -> { name: "react", version: undefined }
+ *   "react@18" -> { name: "react", version: "18" }
+ *   "@tanstack/react-query@5" -> { name: "@tanstack/react-query", version: "5" }
+ */
+export declare function parsePackageSpec(spec: string): {
+    name: string;
+    version?: string;
+};
+/**
+ * Read the package manifest from the filesystem
+ */
+export declare function getPackageManifest(fs: IFileSystem): Promise<PackageManifest>;
+/**
+ * Install a package from npm via esm.sh
+ *
+ * This fetches type definitions and stores them in the virtual filesystem,
+ * then updates package.json with the installed version.
+ *
+ * Special handling:
+ * - @types/* packages: Fetches package content directly as types
+ * - Known packages (react, react-dom): Auto-fetches subpath types
+ *
+ * @param fs - The virtual filesystem
+ * @param packageSpec - Package name with optional version (e.g., "react", "lodash@4")
+ * @returns Install result with version and type info
+ *
+ * @example
+ * ```ts
+ * // Install latest version
+ * await installPackage(fs, "react");
+ *
+ * // Install specific version
+ * await installPackage(fs, "lodash@4.17.21");
+ *
+ * // Install scoped package
+ * await installPackage(fs, "@tanstack/react-query@5");
+ *
+ * // Install @types package
+ * await installPackage(fs, "@types/lodash");
+ * ```
+ */
+export declare function installPackage(fs: IFileSystem, packageSpec: string, options?: InstallOptions): Promise<InstallResult>;
+/**
+ * Uninstall a package
+ *
+ * Removes the package from package.json and deletes type definitions.
+ */
+export declare function uninstallPackage(fs: IFileSystem, packageName: string): Promise<boolean>;
+/**
+ * Resolve a bare import to an esm.sh URL
+ *
+ * @param importPath - The import path (e.g., "react", "lodash/debounce")
+ * @param installedPackages - Map of package name to version
+ * @returns The CDN URL, or null if package not installed
+ *
+ * @example
+ * ```ts
+ * const packages = { "react": "18.2.0", "lodash-es": "4.17.21" };
+ *
+ * resolveToEsmUrl("react", packages);
+ * // "https://esm.sh/react@18.2.0"
+ *
+ * resolveToEsmUrl("lodash-es/debounce", packages);
+ * // "https://esm.sh/lodash-es@4.17.21/debounce"
+ *
+ * resolveToEsmUrl("unknown", packages);
+ * // null
+ * ```
+ */
+export declare function resolveToEsmUrl(importPath: string, installedPackages: Record<string, string>): string | null;
+/**
+ * Parse an import path into package name and subpath
+ *
+ * @example
+ * parseImportPath("react") // { packageName: "react", subpath: undefined }
+ * parseImportPath("lodash/debounce") // { packageName: "lodash", subpath: "debounce" }
+ * parseImportPath("@tanstack/react-query") // { packageName: "@tanstack/react-query", subpath: undefined }
+ * parseImportPath("@tanstack/react-query/devtools") // { packageName: "@tanstack/react-query", subpath: "devtools" }
+ */
+export declare function parseImportPath(importPath: string): {
+    packageName: string;
+    subpath?: string;
+};
+/**
+ * List all installed packages
+ */
+export declare function listPackages(fs: IFileSystem): Promise<Array<{
+    name: string;
+    version: string;
+}>>;
+//# sourceMappingURL=packages.d.ts.map

package/dist/packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../src/packages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgBrD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAE/D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAErE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5C;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/C;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,KAAK,CAA0C;IAEvD,OAAO,CAAC,GAAG;IAIX,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAI9D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIpE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAI3C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAI9C,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,cAAc,EAAE,OAAO,CAAC;IACxB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAiBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CA2BjF;AAqVD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAalF;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,WAAW,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CAiGxB;AAoGD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACxC,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAsBA;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,WAAW,GACd,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAMnD"}

package/dist/react.d.ts

@@ -0,0 +1,159 @@
+/**
+ * React-specific helpers for Sandlot
+ *
+ * These helpers simplify working with dynamically loaded React components,
+ * particularly when using the render function pattern for isolation.
+ *
+ * @example
+ * ```tsx
+ * import { DynamicMount } from 'sandlot/react';
+ *
+ * function App() {
+ *   const [module, setModule] = useState(null);
+ *
+ *   return (
+ *     <DynamicMount
+ *       module={module}
+ *       props={{ name: "World" }}
+ *       fallback={<div>Loading...</div>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+import { type ReactElement, type RefObject, type CSSProperties } from "react";
+/**
+ * Interface for dynamic modules that use the render function pattern.
+ * Dynamic components should export a `render` function that mounts
+ * the component into a container and returns a cleanup function.
+ */
+export interface DynamicRenderModule<P = Record<string, unknown>> {
+    /**
+     * Mount the component into a container element
+     *
+     * @param container - The DOM element to render into
+     * @param props - Props to pass to the component
+     * @returns A cleanup function to unmount the component
+     */
+    render: (container: HTMLElement, props?: P) => (() => void) | void;
+}
+/**
+ * Props for the DynamicMount component
+ */
+export interface DynamicMountProps<P = Record<string, unknown>> {
+    /** The loaded dynamic module with a render function */
+    module: DynamicRenderModule<P> | null | undefined;
+    /** Props to pass to the dynamic component */
+    props?: P;
+    /** Optional className for the container div */
+    className?: string;
+    /** Optional style for the container div */
+    style?: CSSProperties;
+    /** Optional id for the container div */
+    id?: string;
+    /** Content to render while module is loading (null/undefined) */
+    fallback?: ReactElement | null;
+    /** Called when the dynamic component mounts */
+    onMount?: () => void;
+    /** Called when the dynamic component unmounts */
+    onUnmount?: () => void;
+    /** Called if rendering fails */
+    onError?: (error: Error) => void;
+}
+/**
+ * Component that mounts a dynamic module's render function into a container.
+ * Handles cleanup automatically when the module changes or unmounts.
+ *
+ * This is the recommended way to render dynamically loaded components
+ * that use the render function pattern for React instance isolation.
+ *
+ * @example
+ * ```tsx
+ * import { DynamicMount } from 'sandlot/react';
+ * import { loadModule } from 'sandlot';
+ *
+ * function App() {
+ *   const [module, setModule] = useState(null);
+ *
+ *   const loadComponent = async (buildResult: BundleResult) => {
+ *     const mod = await loadModule(buildResult);
+ *     setModule(mod);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={loadComponent}>Load</button>
+ *       <DynamicMount
+ *         module={module}
+ *         props={{ count: 5 }}
+ *         fallback={<div>Click to load...</div>}
+ *         className="dynamic-container"
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function DynamicMount<P = Record<string, unknown>>({ module, props, className, style, id, fallback, onMount, onUnmount, onError, }: DynamicMountProps<P>): ReactElement | null;
+/**
+ * Result returned by useDynamicComponent hook
+ */
+export interface UseDynamicComponentResult {
+    /** Ref to attach to the container element */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Whether the component is currently mounted */
+    isMounted: boolean;
+    /** Any error that occurred during mounting */
+    error: Error | null;
+    /** Manually trigger a re-render with new props */
+    update: (props?: Record<string, unknown>) => void;
+    /** Manually unmount the component */
+    unmount: () => void;
+}
+/**
+ * Hook for mounting dynamic modules with more control than DynamicMount.
+ * Provides access to mount state and manual control over mounting/unmounting.
+ *
+ * @param module - The dynamic module to mount
+ * @param props - Props to pass to the component
+ * @returns Object with containerRef, state, and control functions
+ *
+ * @example
+ * ```tsx
+ * import { useDynamicComponent } from 'sandlot/react';
+ *
+ * function App() {
+ *   const { containerRef, isMounted, error, unmount } = useDynamicComponent(
+ *     module,
+ *     { initialCount: 0 }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <div ref={containerRef} />
+ *       {isMounted && <button onClick={unmount}>Remove</button>}
+ *       {error && <div>Error: {error.message}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDynamicComponent<P = Record<string, unknown>>(module: DynamicRenderModule<P> | null | undefined, props?: P): UseDynamicComponentResult;
+/**
+ * Code template for a React component's render function.
+ * This is the pattern dynamic components should follow when using
+ * the render function pattern for React instance isolation.
+ *
+ * Dynamic components import React from esm.sh and use their own
+ * ReactDOM.createRoot to mount, avoiding conflicts with the host's React.
+ */
+export declare const REACT_RENDER_TEMPLATE: string;
+/**
+ * Generate render function code for a given component name.
+ * Useful for code generation tools or agents.
+ *
+ * @param componentName - The name of the component to wrap
+ * @param hasProps - Whether the component accepts props
+ */
+export declare function generateRenderFunction(componentName: string, hasProps?: boolean): string;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,OAAO,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,uDAAuD;IACvD,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,6CAA6C;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,gCAAgC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACxD,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,EACL,EAAE,EACF,QAAe,EACf,OAAO,EACP,SAAS,EACT,OAAO,GACR,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,IAAI,CA4D5C;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,6CAA6C;IAC7C,YAAY,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC/C,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kDAAkD;IAClD,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAClD,qCAAqC;IACrC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,KAAK,CAAC,EAAE,CAAC,GACR,yBAAyB,CA8C3B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAe1B,CAAC;AAET;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,MAAM,EACrB,QAAQ,UAAO,GACd,MAAM,CAoBR"}

package/dist/react.js

@@ -0,0 +1,149 @@
+// src/react.tsx
+import {
+  useRef,
+  useEffect,
+  useCallback,
+  useState
+} from "react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+function DynamicMount({
+  module,
+  props,
+  className,
+  style,
+  id,
+  fallback = null,
+  onMount,
+  onUnmount,
+  onError
+}) {
+  const containerRef = useRef(null);
+  const cleanupRef = useRef(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (!module || !containerRef.current)
+      return;
+    try {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+        onUnmount?.();
+      }
+      setError(null);
+      const cleanup = module.render(containerRef.current, props);
+      cleanupRef.current = cleanup ?? null;
+      onMount?.();
+    } catch (err) {
+      const error2 = err instanceof Error ? err : new Error(String(err));
+      setError(error2);
+      onError?.(error2);
+    }
+    return () => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+        onUnmount?.();
+      }
+    };
+  }, [module, props, onMount, onUnmount, onError]);
+  if (!module) {
+    return fallback;
+  }
+  if (error) {
+    return /* @__PURE__ */ jsxDEV("div", {
+      style: {
+        color: "red",
+        padding: "8px",
+        border: "1px solid red",
+        borderRadius: "4px"
+      },
+      children: [
+        "Failed to render dynamic component: ",
+        error.message
+      ]
+    }, undefined, true, undefined, this);
+  }
+  return /* @__PURE__ */ jsxDEV("div", {
+    ref: containerRef,
+    className,
+    style,
+    id
+  }, undefined, false, undefined, this);
+}
+function useDynamicComponent(module, props) {
+  const containerRef = useRef(null);
+  const cleanupRef = useRef(null);
+  const propsRef = useRef(props);
+  const [isMounted, setIsMounted] = useState(false);
+  const [error, setError] = useState(null);
+  propsRef.current = props;
+  const unmount = useCallback(() => {
+    if (cleanupRef.current) {
+      cleanupRef.current();
+      cleanupRef.current = null;
+    }
+    setIsMounted(false);
+  }, []);
+  const update = useCallback((newProps) => {
+    if (!module || !containerRef.current)
+      return;
+    try {
+      unmount();
+      setError(null);
+      const cleanup = module.render(containerRef.current, newProps ?? propsRef.current);
+      cleanupRef.current = cleanup ?? null;
+      setIsMounted(true);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }, [module, unmount]);
+  useEffect(() => {
+    if (module && containerRef.current) {
+      update(props);
+    }
+    return unmount;
+  }, [module, props, update, unmount]);
+  return { containerRef, isMounted, error, update, unmount };
+}
+var REACT_RENDER_TEMPLATE = `
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+// Your component here
+function MyComponent(props) {
+  return <div>Hello {props.name}</div>;
+}
+
+// Export a render function that mounts using esm.sh's ReactDOM
+export function render(container, props) {
+  const root = createRoot(container);
+  root.render(<MyComponent {...props} />);
+  return () => root.unmount();
+}
+`.trim();
+function generateRenderFunction(componentName, hasProps = true) {
+  if (hasProps) {
+    return `
+// Export a render function that mounts using esm.sh's ReactDOM
+export function render(container: HTMLElement, props?: Parameters<typeof ${componentName}>[0]) {
+  const root = createRoot(container);
+  root.render(<${componentName} {...props} />);
+  return () => root.unmount();
+}
+`.trim();
+  }
+  return `
+// Export a render function that mounts using esm.sh's ReactDOM
+export function render(container: HTMLElement) {
+  const root = createRoot(container);
+  root.render(<${componentName} />);
+  return () => root.unmount();
+}
+`.trim();
+}
+export {
+  useDynamicComponent,
+  generateRenderFunction,
+  REACT_RENDER_TEMPLATE,
+  DynamicMount
+};