@macle-community/simulator-web 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @macle-community/simulator-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Standalone, lightweight, zero-Electron web simulator and developer workbench for Macle MiniPrograms (Taro React/Vue & Native MAML).
+
+[![npm version](https://img.shields.io/npm/v/@macle-community/simulator-web.svg)](https://www.npmjs.com/package/@macle-community/simulator-web)
+[![Engine](https://img.shields.io/badge/Engine-26.6.0--LG0001-blue.svg)](https://www.huawei.com)
+[![Runtime](https://img.shields.io/badge/Runtime-v100.4.2-green.svg)](https://www.huawei.com)
+[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE)
+[![Zero-Dependency](https://img.shields.io/badge/Dependencies-Zero%20(Pure%20Node.js)-orange.svg)]()
+
+---
+
+## ✨ Features
+
+- **Zero Electron Dependencies**: Runs on standard Node.js (v16+) with zero heavy binary dependencies. Compatible with Linux, macOS, Windows, Docker, and remote cloud development environments.
+- **Official Dual-Thread Engine (v26.6.0-LG0001 / v100.4.2)**: Includes official service and view runtime engines, patched with webpack chunk loading proxy traps and null-safe DOM reconciliation.
+- **Embedded Web Workbench**:
+  - **Realistic Device Frames**: Huawei Mate 60 Pro, Huawei Pura 70 Ultra, iPhone 15 Pro, iPhone 14 Pro Max, iPhone 13, iPhone 8 / SE, and iPad Pro 11".
+  - **Device Controls**: Portrait / Landscape orientation rotation, zoom scaling (50%, 75%, 100%, 125%, Fit-to-screen).
+  - **Touch Gesture Simulation**: Mouse-to-touch emulation with animated ripple cursor.
+  - **Page Selector**: Direct navigation to any page declared in `app.json`.
+- **Integrated DevTools Drawer**:
+  - **Console**: Captures logs from both the logic thread (`service.js`) and render thread (`view.js`), with level filtering and interactive JavaScript REPL.
+  - **Storage**: Real-time inspection, editing, and deletion of `ma.getStorage` and `localStorage` keys.
+  - **Network**: Monitor and inspect `ma.request` calls, latency, payloads, and HTTP statuses.
+  - **App Info**: Project metadata, registered routes, window settings, and compiler versions.
+- **Live Reload & Watcher**: Automatic file watching and hot-reloading via Server-Sent Events (SSE).
+- **Mobile Device Preview via QR Code**: Auto-detects local LAN IP and generates a mobile-ready QR code for instant testing on physical phones/tablets.
+- **Universal Compilation**: Compiles native MAML miniapps via `@macle/compiler` or serves pre-compiled Taro output bundles.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation via NPM
+
+```bash
+# Global CLI installation
+npm install -g @macle-community/simulator-web
+
+# Or run directly via npx
+npx @macle-community/simulator-web -s ./dist
+```
+
+### 2. Run from Source / Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/natiDotnet/macle-simulator-web.git
+cd macle-simulator-web
+
+# Run the web simulator
+node bin/macle-web-simulator.js -s ../sample-project/dist
+```
+
+### 3. CLI Options
+
+```bash
+macle-simulator-web [options]
+
+Options:
+  -s, --source <path>     Path to compiled (dist) or source Macle project [default: auto-detected]
+  -p, --port <port>       Port to run the simulator server [default: 30001]
+  -H, --host <host>       Host interface to bind [default: 0.0.0.0]
+  -w, --watch             Watch files and auto-recompile / live-reload on changes
+  -o, --open              Automatically open simulator in default browser
+  -v, --version           Show version information
+  -h, --help              Show help message
+```
+
+### 3. NPM Scripts
+
+```bash
+# Run with sample project
+npm run sample
+
+# Run with opendoc native miniapp
+npm run opendoc
+
+# Watch mode
+npm run dev
+```
+
+---
+
+## 📁 Project Structure
+
+```
+macle-web-simulator/
+├── bin/
+│   └── macle-web-simulator.js       # CLI executable
+├── src/
+│   ├── server.js                    # Pure Node.js HTTP server & static router
+│   ├── compiler.js                  # @macle/compiler runner
+│   ├── mock-backend.js              # /mcss/simulate/* native Macle backend APIs
+│   ├── project-parser.js            # app.json & project.config.json parser
+│   └── watcher.js                   # Live reload file watcher & SSE emitter
+├── runtime/                         # Bundled 26.6.0-LG0001 / v100.4.2 runtime
+│   ├── framework/                   # service.js & view.js
+│   └── simulator/                   # native.js, service.html, webview.js, common.css
+├── web/                             # Web simulator shell & DevTools
+│   ├── index.html                   # Workbench UI
+│   ├── simulator.css                # Sleek device frames & dark DevTools theme
+│   ├── simulator.js                 # Device dimensions, devtools, and router logic
+│   └── qrcode.js                    # Client-side QR generator
+├── package.json
+└── README.md
+```
+
+---
+
+## 🛠️ Native APIs Supported in Web Simulation
+
+- `ma.request`: Outbound HTTP request proxying through the backend server.
+- `ma.getStorage` / `ma.setStorage` / `ma.removeStorage` / `ma.clearStorage`.
+- `ma.navigateTo` / `ma.redirectTo` / `ma.navigateBack` / `ma.switchTab`.
+- `ma.setNavigationBarTitle` / `ma.setNavigationBarColor`.
+- `ma.showToast` / `ma.showModal` / `ma.showLoading` / `ma.hideLoading`.
+- `ma.getSystemInfo` / `ma.getSystemInfoSync` (responsive to device viewport changes).
+- `ma.saveFile` / `ma.removeSavedFile` / `ma.getFileInfo` / `ma.getSavedFileList`.
+
+---
+
+## 📄 License
+
+MIT © [Macle Team & natiDotnet](https://github.com/natiDotnet)

package/bin/macle-web-simulator.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Macle MiniProgram Standalone Web Simulator CLI
+ * Pure Node.js - Zero Electron Dependencies
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { exec } = require('child_process');
+const { MacleWebSimulatorServer } = require('../src/server');
+
+const args = process.argv.slice(2);
+
+function printHelp() {
+  console.log(`
+Macle MiniProgram Standalone Web Simulator
+Version: 1.0.0 (Engine: 26.6.0-LG0001 / Runtime: v100.4.2)
+
+Usage:
+  macle-web-simulator [options]
+
+Options:
+  -s, --source <path>     Path to compiled or source Macle project (e.g. sample-project/dist)
+  -p, --port <port>       Port to run the simulator server (default: 30001)
+  -H, --host <host>       Host to bind server (default: 0.0.0.0)
+  -w, --watch             Watch files and auto-recompile / live-reload on changes
+  -o, --open              Automatically open simulator in default browser
+  -v, --version           Show version information
+  -h, --help              Show this help message
+
+Examples:
+  npx macle-web-simulator -s ./sample-project/dist
+  macle-web-simulator -s ./opendoc/miniapp --watch --open
+  macle-web-simulator -p 30005
+`);
+  process.exit(0);
+}
+
+if (args.includes('-h') || args.includes('--help')) {
+  printHelp();
+}
+
+if (args.includes('-v') || args.includes('--version')) {
+  console.log('macle-web-simulator v1.0.0');
+  console.log('Macle Engine: 26.6.0-LG0001');
+  console.log('Framework Runtime: v100.4.2');
+  process.exit(0);
+}
+
+function getArgValue(shortFlag, longFlag, defaultValue) {
+  const shortIdx = args.indexOf(shortFlag);
+  if (shortIdx !== -1 && args[shortIdx + 1]) return args[shortIdx + 1];
+  const longIdx = args.indexOf(longFlag);
+  if (longIdx !== -1 && args[longIdx + 1]) return args[longIdx + 1];
+  return defaultValue;
+}
+
+const source = getArgValue('-s', '--source', null);
+const portStr = getArgValue('-p', '--port', '30001');
+const host = getArgValue('-H', '--host', '0.0.0.0');
+const watch = args.includes('-w') || args.includes('--watch');
+const shouldOpen = args.includes('-o') || args.includes('--open');
+
+const port = parseInt(portStr, 10) || 30001;
+
+async function run() {
+  try {
+    const simulator = new MacleWebSimulatorServer({
+      source,
+      port,
+      host,
+      watch
+    });
+
+    await simulator.init();
+    const { localUrl } = await simulator.start();
+
+    if (shouldOpen) {
+      openBrowser(localUrl);
+    }
+
+    process.on('SIGINT', () => {
+      console.log('\n[Simulator] Stopping web simulator server...');
+      simulator.close();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', () => {
+      simulator.close();
+      process.exit(0);
+    });
+  } catch (err) {
+    console.error('[Simulator] Fatal error starting web simulator:', err);
+    process.exit(1);
+  }
+}
+
+function openBrowser(url) {
+  const start = process.platform === 'darwin' ? 'open' :
+                process.platform === 'win32' ? 'start' : 'xdg-open';
+  exec(`${start} ${url}`, (err) => {
+    if (err) {
+      console.warn('[Simulator] Could not auto-open browser:', err.message);
+    }
+  });
+}
+
+run();

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@macle-community/simulator-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Standalone, zero-electron Web Simulator for Macle MiniPrograms (Taro & Native MAML)",
+  "main": "src/server.js",
+  "bin": {
+    "macle-simulator-web": "bin/macle-web-simulator.js",
+    "macle-web-simulator": "bin/macle-web-simulator.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/macle-web-simulator.js",
+    "dev": "node bin/macle-web-simulator.js --watch",
+    "sample": "node bin/macle-web-simulator.js -s ../sample-project/dist",
+    "opendoc": "node bin/macle-web-simulator.js -s ../opendoc/miniapp",
+    "test": "node bin/macle-web-simulator.js --help"
+  },
+  "keywords": [
+    "macle",
+    "miniprogram",
+    "simulator",
+    "web-simulator",
+    "devtools",
+    "taro",
+    "maml",
+    "huawei"
+  ],
+  "author": "t.tsegaye <t.tsegaye@appdiv.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natiDotnet/macle-simulator-web.git"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "license": "MIT"
+}