@immediately-run/sandpack-client 2.19.8

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

@@ -0,0 +1,63 @@
+import type { WorkerStatusUpdate } from "@codesandbox/nodebox";
+import type { BaseSandpackMessage, SandpackErrorMessage, SandpackLogLevel } from "../..";
+type SandpackStandartMessages = {
+    type: "start";
+    firstLoad?: boolean;
+} | {
+    type: "done";
+    compilatonError: boolean;
+};
+type SandpackBundlerMessages = {
+    type: "compile";
+    template?: string;
+    logLevel?: SandpackLogLevel;
+} | ({
+    type: "action";
+    action: "show-error";
+} & SandpackErrorMessage) | {
+    type: "action";
+    action: "notification";
+    notificationType: "error";
+    title: string;
+};
+type SandpackFSMessages = {
+    type: "fs/change";
+    path: string;
+    content: string;
+} | {
+    type: "fs/remove";
+    path: string;
+};
+type SandpackURLsMessages = {
+    type: "urlchange";
+    url: string;
+    back: boolean;
+    forward: boolean;
+} | {
+    type: "refresh";
+} | {
+    type: "urlback";
+} | {
+    type: "urlforward";
+};
+type SandpackShellMessages = {
+    type: "shell/restart";
+} | {
+    type: "shell/openPreview";
+} | {
+    type: "shell/progress";
+    data: WorkerStatusUpdate & {
+        command?: string;
+    };
+};
+export type SandpackNodeMessage = BaseSandpackMessage & (SandpackStandartMessages | SandpackURLsMessages | SandpackBundlerMessages | SandpackShellMessages | {
+    type: "connected";
+} | {
+    type: "stdout";
+    payload: SandpackShellStdoutData;
+} | SandpackFSMessages);
+export interface SandpackShellStdoutData {
+    data?: string;
+    type?: "out" | "err";
+}
+export {};

package/dist/clients/runtime/file-resolver-protocol.d.ts

@@ -0,0 +1,17 @@
+/**
+ * This file is a copy of the resolver from the `codesandbox-api` package.
+ * We wanted to avoid to reference codesandbox-api because of the code that runs on load in the package.
+ * The plan is to take some time and refactor codesandbox-api into what it was supposed to be in the first place,
+ * an abstraction over the actions that can be dispatched between the bundler and the iframe.
+ */
+import type { IFrameProtocol } from "./iframe-protocol";
+import type { ProtocolRequestMessage } from "../../types";
+export default class Protocol {
+    private type;
+    private handleMessage;
+    private protocol;
+    private _disposeMessageListener;
+    constructor(type: string, handleMessage: (message: ProtocolRequestMessage) => any, protocol: IFrameProtocol);
+    getTypeId(): string;
+    dispose(): void;
+}

package/dist/clients/runtime/iframe-protocol.d.ts

@@ -0,0 +1,17 @@
+import type { ListenerFunction, SandpackMessage, UnsubscribeFunction } from "../../types";
+export declare class IFrameProtocol {
+    private frameWindow;
+    private origin;
+    private globalListeners;
+    private globalListenersCount;
+    channelListeners: Record<number, ListenerFunction>;
+    private channelListenersCount;
+    readonly channelId: number;
+    constructor(iframe: HTMLIFrameElement, origin: string);
+    cleanup(): void;
+    register(port?: MessagePort, config?: Record<string, unknown>, babelPort?: MessagePort): void;
+    dispatch(message: SandpackMessage): void;
+    globalListen(listener: ListenerFunction): UnsubscribeFunction;
+    channelListen(listener: ListenerFunction): UnsubscribeFunction;
+    private eventListener;
+}

package/dist/clients/runtime/immutable-fetch-protocol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parent-side fetch + cache for immutable, exact-versioned module URLs.
+ *
+ * The bundler iframe runs at an opaque origin (sandboxed without
+ * `allow-same-origin`), so it has no persistent storage of any kind — its own
+ * Cache API is unavailable. It therefore forwards immutable-URL fetches here
+ * over the iframe protocol (`protocol-immutable-fetch`), and the parent — a
+ * real origin — serves them cache-first from a persistent Cache API cache.
+ *
+ * Security: the handler only fetches URLs matching {@link IMMUTABLE_URL_ALLOWLIST}.
+ * The iframe runs untrusted code, and an unrestricted parent-side fetch proxy
+ * would let it read arbitrary cross-origin responses with the parent's network
+ * context (a CORS bypass). The allowlist mirrors the prefixes the bundler
+ * registers via `registerImmutableUrlPrefix` (see sandpack-bundler
+ * `src/utils/fetch.ts`) — keep the two in sync.
+ */
+export interface ImmutableFetchResult {
+    status: number;
+    contentType: string;
+    /** Structured-cloned (copied) to the iframe in the protocol response. */
+    body: ArrayBuffer;
+}
+/**
+ * `protocol-immutable-fetch` handler: serve an allowlisted immutable URL,
+ * cache-first from the persistent parent-side cache.
+ *
+ * INTEGRITY-AWARE CACHING (cache-poisoning prevention). When the caller passes
+ * the expected SHA-384 (`integrity`), the cache is never allowed to serve or
+ * persist bytes that don't match it:
+ *  - verify-on-read: a cache HIT whose bytes no longer match the expected hash
+ *    (the host re-pinned the version under the cached bytes) is EVICTED and the
+ *    URL refetched, so a stale/poisoned entry self-heals instead of failing the
+ *    consumer forever.
+ *  - verify-before-cache: freshly fetched bytes are only stored when they match.
+ *    Mismatched bytes are returned (so the consumer's own check fails closed with
+ *    a clear error) but NEVER cached, so a bad upstream window can't poison the
+ *    cache. Without an `integrity` argument the URL is cached by URL as before.
+ */
+export declare function handleImmutableFetch(url: unknown, integrity?: unknown): Promise<ImmutableFetchResult>;

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

@@ -0,0 +1,76 @@
+import type { SandpackFS } from "../../fs/SandpackFS";
+import type { BundlerState, ClientOptions, ListenerFunction, SandboxSetup, SandpackError, UnsubscribeFunction } from "../../types";
+import { SandpackClient } from "../base";
+import Protocol from "./file-resolver-protocol";
+import { IFrameProtocol } from "./iframe-protocol";
+import { type SandpackRuntimeMessage } from "./types";
+export declare class SandpackRuntime extends SandpackClient {
+    fileResolverProtocol?: Protocol;
+    immutableFetchProtocol?: Protocol;
+    bundlerURL: string;
+    bundlerState?: BundlerState;
+    errors: SandpackError[];
+    selector: string;
+    element: Element;
+    unsubscribeGlobalListener: UnsubscribeFunction;
+    unsubscribeChannelListener: UnsubscribeFunction;
+    unsubscribeFsWatcher?: () => void;
+    iframeProtocol: IFrameProtocol;
+    fs: SandpackFS;
+    /** Parent-owned Babel transpiler worker, connected to the iframe by port. */
+    private babelWorker;
+    constructor(selector: string | HTMLIFrameElement, sandboxSetup: SandboxSetup, options?: ClientOptions);
+    private createBundlerURL;
+    /**
+     * Creates (or recreates) the parent-owned Babel transpiler worker and returns
+     * the `MessagePort` to transfer into the iframe. The iframe can no longer run
+     * its own worker — without `allow-same-origin` it has an opaque origin, and a
+     * same-origin worker script won't load there — so transpilation happens in
+     * this worker on the parent's real origin. Per-transform traffic then flows
+     * iframe<->worker directly over the entangled ports; the parent doesn't relay.
+     */
+    private createBabelWorkerPort;
+    private serviceWorkerHandshake;
+    private handleWorkerRequest;
+    setLocationURLIntoIFrame(): void;
+    destroy(): void;
+    updateOptions(options: ClientOptions): void;
+    /**
+     * Updates the local sandbox state. The bundler watches the shared filesystem
+     * itself, so there is nothing to push to the iframe here — a file mutation
+     * triggers a rebuild on the bundler side without a `compile` message. A
+     * template/environment change is handled by re-registering the client (see
+     * `useClient`'s `watchFileChanges` effect), which re-runs `computeInitConfig`.
+     */
+    updateSandbox(sandboxSetup?: SandboxSetup): void;
+    /**
+     * Computes the bundler's bootstrap config. Delivered once via the
+     * `register-frame` handshake (see the `initialized` handler) instead of a
+     * `compile` message, since the bundler now self-watches the filesystem.
+     */
+    private computeInitConfig;
+    /**
+     * Relays the set of changed file paths to the bundler so it can re-bundle.
+     * The bundler can't observe parent-side writes to the shared filesystem on
+     * its own: zenfs's `Port` backend doesn't forward watch events across the
+     * iframe boundary. This lightweight signal replaces the old per-change
+     * `compile` message — it carries only paths, not template/options/config.
+     */
+    notifyFilesChanged(paths: string[]): void;
+    dispatch(message: SandpackRuntimeMessage): void;
+    listen(listener: ListenerFunction): UnsubscribeFunction;
+    /**
+     * Get the URL of the contents of the current sandbox
+     */
+    getCodeSandboxURL(): Promise<{
+        sandboxId: string;
+        editorUrl: string;
+        embedUrl: string;
+    }>;
+    getTranspilerContext: () => Promise<Record<string, Record<string, unknown>>>;
+    getTranspiledFiles: () => Promise<Array<{
+        path: string;
+        code: string;
+    }>>;
+    private initializeElement;
+}