@marsengine/mars-client 1.0.0 → 1.1.0

package/package.json

@@ -1,20 +1,30 @@
 {
     "name": "@marsengine/mars-client",
-    "version": "1.0.0",
-    "description": "Public Client for MARS Engine (WebContainer Replacement)",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "version": "1.1.0",
+    "description": "React-friendly client for MARS Engine",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
     "scripts": {
-        "build": "tsc"
+        "build": "tsup src/index.ts --format esm --dts --clean",
+        "dev": "tsup src/index.ts --format esm --dts --watch",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@marsengine/engine": "file:../engine"
     },
-    "keywords": [
-        "mars",
-        "webcontainer",
-        "client"
-    ],
-    "author": "MARS Team",
-    "license": "MIT",
     "devDependencies": {
+        "react": "^18.2.0",
+        "tsup": "^8.0.1",
         "typescript": "^5.3.3"
+    },
+    "peerDependencies": {
+        "react": ">=18.0.0"
     }
 }

package/src/index.ts

@@ -1,77 +1,87 @@
+import { useState, useEffect, useCallback } from 'react';
+import { MarsEngine, type IMarsEngine } from '@marsengine/engine';
+
 /**
- * MARS Messenger (Public API)
- * This is the lightweight "Messenger" library that customers install.
- * It contains NO engine logic, only a bridge to the hosted runtime.
+ * Hook to use MARS Engine in a React component
  */
+export function useMarsEngine() {
+    const [engine, setEngine] = useState<IMarsEngine | null>(null);
+    const [isBooting, setIsBooting] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
 
-export class MarsEngineMessenger {
-    private iframe: HTMLIFrameElement | null = null;
-    private channel: MessageChannel;
-    private port: MessagePort | null = null;
-
-    constructor(private runtimeUrl: string = 'https://runtime.mars.ai') {
-        this.channel = new MessageChannel();
-    }
-
-    /**
-     * Boot the engine by creating a hidden iframe to the hosted runtime.
-     */
-    async boot(): Promise<void> {
-        return new Promise((resolve, reject) => {
-            this.iframe = document.createElement('iframe');
-            this.iframe.src = this.runtimeUrl;
-            this.iframe.style.display = 'none';
-            this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+    const boot = useCallback(async (options = {}) => {
+        setIsBooting(true);
+        setError(null);
+        try {
+            const instance = await MarsEngine.boot(options);
+            setEngine(instance);
+            return instance;
+        } catch (err: any) {
+            setError(err);
+            throw err;
+        } finally {
+            setIsBooting(false);
+        }
+    }, []);
 
-            this.iframe.onload = () => {
-                // Handshake: Send our MessagePort to the hosted runtime
-                this.iframe!.contentWindow!.postMessage(
-                    { type: 'MARS_HANDSHAKE' },
-                    this.runtimeUrl,
-                    [this.channel.port2]
-                );
+    return { engine, isBooting, error, boot };
+}
 
-                this.port = this.channel.port1;
-                this.port.onmessage = (event) => {
-                    if (event.data.type === 'MARS_READY') resolve();
-                };
-            };
+/**
+ * Messenger for remote control of MARS Engine
+ * Useful for iframe-to-iframe communication
+ */
+export class MarsMessenger {
+    private engine: IMarsEngine;
 
-            this.iframe.onerror = reject;
-            document.body.appendChild(this.iframe);
-        });
+    constructor(engine: IMarsEngine) {
+        this.engine = engine;
+        this.setupListeners();
     }
 
-    /**
-     * Proxy call to the hosted engine.
-     */
-    async call(method: string, args: any[]): Promise<any> {
-        if (!this.port) throw new Error('Engine not booted');
-
-        const requestId = Math.random().toString(36).substring(7);
-        this.port.postMessage({ type: 'MARS_CALL', requestId, method, args });
+    private setupListeners() {
+        window.addEventListener('message', async (event) => {
+            const { type, payload, id } = event.data;
+            if (!type || !type.startsWith('MARS_')) return;
 
-        return new Promise((resolve) => {
-            const handler = (event: MessageEvent) => {
-                if (event.data.requestId === requestId) {
-                    this.port!.removeEventListener('message', handler);
-                    resolve(event.data.result);
+            try {
+                let result;
+                switch (type) {
+                    case 'MARS_MOUNT':
+                        result = await this.engine.mount(payload.tree, payload.target);
+                        break;
+                    case 'MARS_SPAWN':
+                        const process = await this.engine.spawn(payload.command, payload.args, payload.options);
+                        // Handle process streaming back to caller
+                        this.handleProcess(process, id);
+                        return;
+                    case 'MARS_WRITE_FILE':
+                        result = await this.engine.fs.writeFile(payload.path, payload.contents);
+                        break;
+                    case 'MARS_READ_FILE':
+                        result = await this.engine.fs.readFile(payload.path, payload.encoding);
+                        break;
                 }
-            };
-            this.port!.addEventListener('message', handler);
-            this.port!.start();
+
+                window.parent.postMessage({ id, result }, '*');
+            } catch (err: any) {
+                window.parent.postMessage({ id, error: err.message }, '*');
+            }
         });
     }
 
-    // Public API Proxies
-    async spawn(command: string, args: string[]) {
-        return this.call('spawn', [command, args]);
-    }
+    private handleProcess(process: any, id: string) {
+        process.output.pipeTo(new WritableStream({
+            write(chunk) {
+                window.parent.postMessage({ id, type: 'STDOUT', chunk }, '*');
+            }
+        }));
 
-    get fs() {
-        return {
-            writeFile: (path: string, content: any) => this.call('fs.writeFile', [path, content]),
-            readFile: (path: string) => this.call('fs.readFile', [path]),
-        };
+        process.exit.then((code: number) => {
+            window.parent.postMessage({ id, type: 'EXIT', code }, '*');
+        });
     }
 }
+
+export { MarsEngine };
+export type { IMarsEngine };

package/tsconfig.json

@@ -1,10 +1,30 @@
 {
     "compilerOptions": {
-        "target": "ES2020",
-        "module": "CommonJS",
-        "declaration": true,
-        "outDir": "./dist",
-        "strict": true
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": [
+            "DOM",
+            "DOM.Iterable",
+            "ESNext"
+        ],
+        "allowJs": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "strict": true,
+        "forceConsistentCasingInFileNames": true,
+        "noFallthroughCasesInSwitch": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+        "jsx": "react-jsx",
+        "baseUrl": ".",
+        "paths": {
+            "@marsengine/engine": [
+                "../engine/src/index.ts"
+            ]
+        }
     },
     "include": [
         "src"

package/README.md

@@ -1,61 +0,0 @@
-# @yakreentechnologies/mars-client
-
-The official client for the **MARS Engine** - The Enterprise-Grade WebContainer Replacement.
-
-This lightweight library allows you to connect to a hosted MARS Engine runtime and control a full Node.js environment directly from the browser.
-
-## Features
-
-*   🚀 **Zero-Copy I/O**: Blazing fast communication with the engine.
-*   🔒 **Secure Sandbox**: Runs code in a hidden, isolated iframe.
-*   📦 **Drop-in Replacement**: API compatible with WebContainer.
-*   ⚡ **Vibe Coding Ready**: Optimized for AI-driven development.
-
-## Installation
-
-```bash
-npm install @marsengine/mars-client
-```
-
-## Usage
-
-### 1. Boot the Engine
-
-```typescript
-import { MarsEngineMessenger } from '@marsengine/mars-client';
-
-// Initialize the engine (pointing to your hosted runtime)
-const engine = new MarsEngineMessenger('https://engine.yourdomain.com');
-
-await engine.boot();
-console.log('MARS Engine is ready! 🚀');
-```
-
-### 2. Run a Command
-
-```typescript
-// Run 'npm install' inside the browser
-const process = await engine.spawn('npm', ['install']);
-
-// Stream the output to your terminal
-process.output.pipeTo(new WritableStream({
-  write(chunk) {
-    console.log(chunk);
-  }
-}));
-
-await process.exit;
-```
-
-### 3. Write a File
-
-```typescript
-await engine.fs.writeFile('/src/App.tsx', `
-  import React from 'react';
-  export default () => <h1>Hello from MARS! 🪐</h1>;
-`);
-```
-
-## License
-
-MIT

package/dist/index.d.ts

@@ -1,25 +0,0 @@
-/**
- * MARS Messenger (Public API)
- * This is the lightweight "Messenger" library that customers install.
- * It contains NO engine logic, only a bridge to the hosted runtime.
- */
-export declare class MarsEngineMessenger {
-    private runtimeUrl;
-    private iframe;
-    private channel;
-    private port;
-    constructor(runtimeUrl?: string);
-    /**
-     * Boot the engine by creating a hidden iframe to the hosted runtime.
-     */
-    boot(): Promise<void>;
-    /**
-     * Proxy call to the hosted engine.
-     */
-    call(method: string, args: any[]): Promise<any>;
-    spawn(command: string, args: string[]): Promise<any>;
-    get fs(): {
-        writeFile: (path: string, content: any) => Promise<any>;
-        readFile: (path: string) => Promise<any>;
-    };
-}

package/dist/index.js

@@ -1,68 +0,0 @@
-"use strict";
-/**
- * MARS Messenger (Public API)
- * This is the lightweight "Messenger" library that customers install.
- * It contains NO engine logic, only a bridge to the hosted runtime.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarsEngineMessenger = void 0;
-class MarsEngineMessenger {
-    constructor(runtimeUrl = 'https://runtime.mars.ai') {
-        this.runtimeUrl = runtimeUrl;
-        this.iframe = null;
-        this.port = null;
-        this.channel = new MessageChannel();
-    }
-    /**
-     * Boot the engine by creating a hidden iframe to the hosted runtime.
-     */
-    async boot() {
-        return new Promise((resolve, reject) => {
-            this.iframe = document.createElement('iframe');
-            this.iframe.src = this.runtimeUrl;
-            this.iframe.style.display = 'none';
-            this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
-            this.iframe.onload = () => {
-                // Handshake: Send our MessagePort to the hosted runtime
-                this.iframe.contentWindow.postMessage({ type: 'MARS_HANDSHAKE' }, this.runtimeUrl, [this.channel.port2]);
-                this.port = this.channel.port1;
-                this.port.onmessage = (event) => {
-                    if (event.data.type === 'MARS_READY')
-                        resolve();
-                };
-            };
-            this.iframe.onerror = reject;
-            document.body.appendChild(this.iframe);
-        });
-    }
-    /**
-     * Proxy call to the hosted engine.
-     */
-    async call(method, args) {
-        if (!this.port)
-            throw new Error('Engine not booted');
-        const requestId = Math.random().toString(36).substring(7);
-        this.port.postMessage({ type: 'MARS_CALL', requestId, method, args });
-        return new Promise((resolve) => {
-            const handler = (event) => {
-                if (event.data.requestId === requestId) {
-                    this.port.removeEventListener('message', handler);
-                    resolve(event.data.result);
-                }
-            };
-            this.port.addEventListener('message', handler);
-            this.port.start();
-        });
-    }
-    // Public API Proxies
-    async spawn(command, args) {
-        return this.call('spawn', [command, args]);
-    }
-    get fs() {
-        return {
-            writeFile: (path, content) => this.call('fs.writeFile', [path, content]),
-            readFile: (path) => this.call('fs.readFile', [path]),
-        };
-    }
-}
-exports.MarsEngineMessenger = MarsEngineMessenger;