@immediately-run/sandpack-client 2.19.8

package/README.md

@@ -0,0 +1,26 @@
+<img style="width:100%" src="https://user-images.githubusercontent.com/4838076/143581035-ebee5ba2-9cb1-4fe8-a05b-2f44bd69bb4b.gif" alt="Component toolkit for live running code editing experiences" />
+
+# Sandpack client 
+
+This is a small foundation package that sits on top of the bundler. It is
+framework agnostic and facilitates the handshake between your context and the bundler iframe.
+
+```js
+import { loadSandpackClient } from "@codesandbox/sandpack-client";
+
+const main = async () => {
+  const client = await loadSandpackClient("#preview", {
+    files: {
+      "/index.js": {
+        code: `console.log(require('uuid'))`,
+      },
+    },
+    entry: "/index.js",
+    dependencies: {
+      uuid: "latest",
+    },
+  });
+}
+```
+
+[Read more](https://sandpack.codesandbox.io/docs/advanced-usage/client)

package/dist/.ir-build-stamp.json

@@ -0,0 +1,6 @@
+{
+  "name": "sandpack-client",
+  "version": "2.19.8",
+  "srcHash": "0eaf0bf3d7e1b039ddf5c81d671c599261917c9d2f79e6ab678c9a255639e850",
+  "builtAt": "2026-06-29T12:49:38.087Z"
+}

package/dist/base-DBh7xJX9.mjs

@@ -0,0 +1,48 @@
+import { dequal } from 'dequal';
+
+var SandpackClient = /** @class */ (function () {
+    function SandpackClient(iframeSelector, sandboxSetup, options) {
+        if (options === void 0) { options = {}; }
+        this.status = "idle";
+        this.options = options;
+        this.sandboxSetup = sandboxSetup;
+        this.iframeSelector = iframeSelector;
+    }
+    /**
+     * Clients handles
+     */
+    SandpackClient.prototype.updateOptions = function (options) {
+        if (!dequal(this.options, options)) {
+            this.options = options;
+            this.updateSandbox();
+        }
+    };
+    SandpackClient.prototype.updateSandbox = function (_sandboxSetup, _isInitializationCompile) {
+        if (_sandboxSetup === void 0) { _sandboxSetup = this.sandboxSetup; }
+        throw Error("Method not implemented");
+    };
+    /**
+     * Notify the bundler that the given paths changed in the shared filesystem.
+     * Only the runtime client needs this (its bundler can't observe parent writes
+     * itself); other clients re-bundle via {@link updateSandbox}, so this is a
+     * no-op for them.
+     */
+    SandpackClient.prototype.notifyFilesChanged = function (_paths) {
+        // no-op by default
+    };
+    SandpackClient.prototype.destroy = function () {
+        throw Error("Method not implemented");
+    };
+    /**
+     * Bundler communication
+     */
+    SandpackClient.prototype.dispatch = function (_message) {
+        throw Error("Method not implemented");
+    };
+    SandpackClient.prototype.listen = function (_listener) {
+        throw Error("Method not implemented");
+    };
+    return SandpackClient;
+}());
+
+export { SandpackClient as S };

package/dist/base-DelKLlDk.js

@@ -0,0 +1,50 @@
+'use strict';
+
+var dequal = require('dequal');
+
+var SandpackClient = /** @class */ (function () {
+    function SandpackClient(iframeSelector, sandboxSetup, options) {
+        if (options === void 0) { options = {}; }
+        this.status = "idle";
+        this.options = options;
+        this.sandboxSetup = sandboxSetup;
+        this.iframeSelector = iframeSelector;
+    }
+    /**
+     * Clients handles
+     */
+    SandpackClient.prototype.updateOptions = function (options) {
+        if (!dequal.dequal(this.options, options)) {
+            this.options = options;
+            this.updateSandbox();
+        }
+    };
+    SandpackClient.prototype.updateSandbox = function (_sandboxSetup, _isInitializationCompile) {
+        if (_sandboxSetup === void 0) { _sandboxSetup = this.sandboxSetup; }
+        throw Error("Method not implemented");
+    };
+    /**
+     * Notify the bundler that the given paths changed in the shared filesystem.
+     * Only the runtime client needs this (its bundler can't observe parent writes
+     * itself); other clients re-bundle via {@link updateSandbox}, so this is a
+     * no-op for them.
+     */
+    SandpackClient.prototype.notifyFilesChanged = function (_paths) {
+        // no-op by default
+    };
+    SandpackClient.prototype.destroy = function () {
+        throw Error("Method not implemented");
+    };
+    /**
+     * Bundler communication
+     */
+    SandpackClient.prototype.dispatch = function (_message) {
+        throw Error("Method not implemented");
+    };
+    SandpackClient.prototype.listen = function (_listener) {
+        throw Error("Method not implemented");
+    };
+    return SandpackClient;
+}());
+
+exports.SandpackClient = SandpackClient;

package/dist/clients/base.d.ts

@@ -0,0 +1,34 @@
+import type { ClientStatus } from "..";
+import type { ClientOptions, SandboxSetup, ListenerFunction, SandpackMessage, UnsubscribeFunction } from "../types";
+export declare class SandpackClient {
+    /**
+     * Sandbox configuration: files, setup, customizations;
+     */
+    sandboxSetup: SandboxSetup;
+    options: ClientOptions;
+    /**
+     * DOM bindings
+     */
+    iframe: HTMLIFrameElement;
+    iframeSelector: string | HTMLIFrameElement;
+    status: ClientStatus;
+    constructor(iframeSelector: string | HTMLIFrameElement, sandboxSetup: SandboxSetup, options?: ClientOptions);
+    /**
+     * Clients handles
+     */
+    updateOptions(options: ClientOptions): void;
+    updateSandbox(_sandboxSetup?: SandboxSetup, _isInitializationCompile?: boolean): void;
+    /**
+     * Notify the bundler that the given paths changed in the shared filesystem.
+     * Only the runtime client needs this (its bundler can't observe parent writes
+     * itself); other clients re-bundle via {@link updateSandbox}, so this is a
+     * no-op for them.
+     */
+    notifyFilesChanged(_paths: string[]): void;
+    destroy(): void;
+    /**
+     * Bundler communication
+     */
+    dispatch(_message: SandpackMessage): void;
+    listen(_listener: ListenerFunction): UnsubscribeFunction;
+}

package/dist/clients/event-emitter.d.ts

@@ -0,0 +1,10 @@
+import type { ListenerFunction, SandpackMessage, UnsubscribeFunction } from "..";
+export declare class EventEmitter {
+    private listeners;
+    private listenersCount;
+    readonly channelId: number;
+    constructor();
+    cleanup(): void;
+    dispatch(message: SandpackMessage): void;
+    listener(listener: ListenerFunction): UnsubscribeFunction;
+}

package/dist/clients/iframe-factory.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The single chokepoint for creating **app iframes** (UI_AS_APPS_SPEC §2 / G1 /
+ * threat T1).
+ *
+ * App iframes MUST be opaque-origin: `sandbox="allow-scripts …"` WITHOUT
+ * `allow-same-origin`. With `allow-same-origin` alongside `allow-scripts` an app
+ * could remove its own sandboxing and reach the parent — the whole capability
+ * model collapses. This is the one invariant with no defense-in-depth, so
+ * creation is centralized here and the resolved attribute is asserted. Raw
+ * `document.createElement('iframe')` for app content elsewhere is forbidden (a
+ * greppable CI check), so the verifiable invariant is "every app iframe is born
+ * in this factory."
+ *
+ * Scope: the opaque-origin app iframes (the runtime + static preview clients).
+ * The node/nodebox emulator is a different execution model and is intentionally
+ * NOT routed through here.
+ */
+/** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
+export declare function assertOpaqueOrigin(iframe: HTMLIFrameElement): void;
+/** Create an opaque-origin sandboxed iframe for running untrusted app code. */
+export declare function createSandboxedIframe(doc?: Document): HTMLIFrameElement;
+/**
+ * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
+ * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
+ * this for the case where a host passes in its own iframe element.
+ */
+export declare function ensureSandboxed(iframe: HTMLIFrameElement): void;

package/dist/clients/index.d.ts

@@ -0,0 +1,4 @@
+import type { ClientOptions, SandboxSetup } from "../types";
+import type { SandpackClient as SandpackClientBase } from "./base";
+export type { SandpackClient } from "./base";
+export declare function loadSandpackClient(iframeSelector: string | HTMLIFrameElement, sandboxSetup: SandboxSetup, options?: ClientOptions): Promise<SandpackClientBase>;

package/dist/clients/node/client.utils.d.ts

@@ -0,0 +1,7 @@
+import type { ShellCommandOptions } from "@codesandbox/nodebox/build/modules/shell";
+export declare function generateRandomId(): string;
+/**
+ * Figure out which script it must run to start a server
+ */
+export declare const findStartScriptPackageJson: (packageJson: string) => [string, string[], ShellCommandOptions];
+export declare const getMessageFromError: (error: Error | string) => string;

package/dist/clients/node/iframe.utils.d.ts

@@ -0,0 +1,3 @@
+import type { ClientOptions } from "../..";
+export declare function loadPreviewIframe(iframe: HTMLIFrameElement, url: string): Promise<void>;
+export declare const setPreviewIframeProperties: (iframe: HTMLIFrameElement, options: ClientOptions) => void;

package/dist/clients/node/index.d.ts

@@ -0,0 +1,49 @@
+import type { ClientOptions, ListenerFunction, SandboxSetup, UnsubscribeFunction } from "../..";
+import { SandpackClient } from "../base";
+import type { SandpackNodeMessage } from "./types";
+export declare class SandpackNode extends SandpackClient {
+    private emitter;
+    private emulatorIframe;
+    private emulator;
+    private emulatorShellProcess;
+    private emulatorCommand;
+    private iframePreviewUrl;
+    private messageChannelId;
+    iframe: HTMLIFrameElement;
+    private _initPromise;
+    constructor(selector: string | HTMLIFrameElement, sandboxInfo: SandboxSetup, options?: ClientOptions);
+    private _init;
+    /**
+     * It initializes the emulator and provide it with files, template and script to run
+     */
+    private compile;
+    /**
+     * It creates a new shell and run the starting task
+     */
+    private createShellProcessFromTask;
+    private createPreviewURLFromId;
+    /**
+     * Nodebox needs to handle two types of iframes at the same time:
+     *
+     * 1. Runtime iframe: where the emulator process runs, which is responsible
+     *    for creating the other iframes (hidden);
+     * 2. Preview iframes: any other node process that contains a PORT (public);
+     */
+    private manageIframes;
+    private setLocationURLIntoIFrame;
+    /**
+     * Send all messages and events to tell to the
+     * consumer that the bundler is ready without any error
+     */
+    private dispatchDoneMessage;
+    private globalListeners;
+    /**
+     * PUBLIC Methods
+     */
+    restartShellProcess(): Promise<void>;
+    updateSandbox(setup: SandboxSetup): void;
+    private updateSandboxAsync;
+    dispatch(message: SandpackNodeMessage): Promise<void>;
+    listen(listener: ListenerFunction): UnsubscribeFunction;
+    destroy(): void;
+}