almostnode 0.1.0 → 0.2.0

package/README.md

@@ -139,6 +139,156 @@ bridge.registerServer(server, 3000);
 
 ---
 
+## Service Worker Setup
+
+almostnode uses a Service Worker to intercept HTTP requests and route them to virtual dev servers (e.g., `ViteDevServer`, `NextDevServer`).
+
+> **Note:** The service worker is only needed if you're using dev servers with URL access (e.g., `/__virtual__/3000/`). If you're only executing code with `runtime.execute()`, you don't need the service worker.
+
+### Which Setup Do I Need?
+
+| Use Case | Setup Required |
+|----------|----------------|
+| Cross-origin sandbox (recommended for untrusted code) | `generateSandboxFiles()` - includes everything |
+| Same-origin with Vite | `almostnodePlugin` from `almostnode/vite` |
+| Same-origin with Next.js | `getServiceWorkerContent` from `almostnode/next` |
+| Same-origin with other frameworks | Manual copy to public directory |
+
+---
+
+### Option 1: Cross-Origin Sandbox (Recommended)
+
+When using `createRuntime()` with a cross-origin `sandbox` URL, the service worker must be deployed **with the sandbox**, not your main app.
+
+The `generateSandboxFiles()` helper generates all required files:
+
+```typescript
+import { generateSandboxFiles } from 'almostnode';
+import fs from 'fs';
+
+const files = generateSandboxFiles();
+
+// Creates: index.html, vercel.json, __sw__.js
+fs.mkdirSync('sandbox', { recursive: true });
+for (const [filename, content] of Object.entries(files)) {
+  fs.writeFileSync(`sandbox/${filename}`, content);
+}
+
+// Deploy to a different origin:
+// cd sandbox && vercel --prod
+```
+
+**Generated files:**
+| File | Purpose |
+|------|---------|
+| `index.html` | Sandbox page that loads almostnode and registers the service worker |
+| `vercel.json` | CORS headers for cross-origin iframe embedding |
+| `__sw__.js` | Service worker for intercepting dev server requests |
+
+See [Sandbox Setup](#sandbox-setup) for full deployment instructions.
+
+---
+
+### Option 2: Same-Origin with Vite
+
+For trusted code using `dangerouslyAllowSameOrigin: true`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { almostnodePlugin } from 'almostnode/vite';
+
+export default defineConfig({
+  plugins: [almostnodePlugin()]
+});
+```
+
+The plugin serves `/__sw__.js` automatically during development.
+
+**Custom path:**
+
+```typescript
+// vite.config.ts
+almostnodePlugin({ swPath: '/custom/__sw__.js' })
+
+// Then in your app:
+await bridge.initServiceWorker({ swUrl: '/custom/__sw__.js' });
+```
+
+---
+
+### Option 3: Same-Origin with Next.js
+
+For trusted code using `dangerouslyAllowSameOrigin: true`:
+
+**App Router:**
+
+```typescript
+// app/__sw__.js/route.ts
+import { getServiceWorkerContent } from 'almostnode/next';
+
+export async function GET() {
+  return new Response(getServiceWorkerContent(), {
+    headers: {
+      'Content-Type': 'application/javascript',
+      'Cache-Control': 'no-cache',
+    },
+  });
+}
+```
+
+**Pages Router:**
+
+```typescript
+// pages/api/__sw__.ts
+import { getServiceWorkerContent } from 'almostnode/next';
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default function handler(req: NextApiRequest, res: NextApiResponse) {
+  res.setHeader('Content-Type', 'application/javascript');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.send(getServiceWorkerContent());
+}
+```
+
+**Initialize with the correct path:**
+
+```typescript
+// App Router (file-based route)
+await bridge.initServiceWorker({ swUrl: '/__sw__.js' });
+
+// Pages Router (API route)
+await bridge.initServiceWorker({ swUrl: '/api/__sw__' });
+```
+
+**Available exports from `almostnode/next`:**
+
+| Export | Description |
+|--------|-------------|
+| `getServiceWorkerContent()` | Returns the service worker file content as a string |
+| `getServiceWorkerPath()` | Returns the absolute path to the service worker file |
+
+---
+
+### Option 4: Manual Setup (Other Frameworks)
+
+Copy the service worker to your public directory:
+
+```bash
+cp node_modules/almostnode/dist/__sw__.js ./public/
+```
+
+Or programmatically:
+
+```typescript
+import { getServiceWorkerPath } from 'almostnode/next';
+import fs from 'fs';
+
+fs.copyFileSync(getServiceWorkerPath(), './public/__sw__.js');
+```
+
+---
+
 ## Comparison with WebContainers
 
 | Feature | almostnode | WebContainers |
@@ -312,12 +462,24 @@ For running untrusted code securely, deploy a cross-origin sandbox. The key requ
 
 ```typescript
 import { generateSandboxFiles } from 'almostnode';
+import fs from 'fs';
 
 const files = generateSandboxFiles();
-// Write files['index.html'] and files['vercel.json'] to a directory
+// Generates: index.html, vercel.json, __sw__.js
+
+fs.mkdirSync('sandbox', { recursive: true });
+for (const [filename, content] of Object.entries(files)) {
+  fs.writeFileSync(`sandbox/${filename}`, content);
+}
+
 // Deploy: cd sandbox && vercel --prod
 ```
 
+The generated files include:
+- `index.html` - Sandbox page with service worker registration
+- `vercel.json` - CORS headers for cross-origin iframe embedding
+- `__sw__.js` - Service worker for dev server URL access
+
 ### Manual Setup (Any Platform)
 
 The sandbox requires two things:

package/dist/index.cjs

@@ -6,8 +6,31 @@ const pako = require('pako');
 const justBash = require('just-bash');
 const resolve_exports = require('resolve.exports');
 const comlink = require('comlink');
+const fs$1 = require('fs');
+const path$1 = require('path');
+const url$2 = require('url');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } });
+  if (e) {
+    for (const k in e) {
+      if (k !== 'default') {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs$1);
+const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path$1);
+
 function createNodeError(code, syscall, path, message) {
   const errno = {
     ENOENT: -2,
@@ -9909,7 +9932,34 @@ async function createRuntime(vfs, options = {}) {
   return new AsyncRuntimeWrapper(vfs, runtimeOptions);
 }
 
-function getSandboxHtml(justNodeUrl = "https://unpkg.com/almostnode/dist/index.js") {
+const __dirname$1 = path__namespace.dirname(url$2.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))));
+function getServiceWorkerContent() {
+  try {
+    let swPath = path__namespace.join(__dirname$1, "__sw__.js");
+    if (fs__namespace.existsSync(swPath)) {
+      return fs__namespace.readFileSync(swPath, "utf-8");
+    }
+    swPath = path__namespace.join(__dirname$1, "../dist/__sw__.js");
+    if (fs__namespace.existsSync(swPath)) {
+      return fs__namespace.readFileSync(swPath, "utf-8");
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getSandboxHtml(options = {}) {
+  const opts = typeof options === "string" ? { almostnodeUrl: options } : options;
+  const almostnodeUrl = opts.almostnodeUrl ?? "https://unpkg.com/almostnode/dist/index.js";
+  const includeServiceWorker = opts.includeServiceWorker ?? true;
+  const serviceWorkerScript = includeServiceWorker ? `
+  // Register service worker for dev server support
+  if ('serviceWorker' in navigator) {
+    navigator.serviceWorker.register('/__sw__.js', { scope: '/' })
+      .then(reg => console.log('[Sandbox] Service worker registered'))
+      .catch(err => console.warn('[Sandbox] Service worker registration failed:', err));
+  }
+` : "";
   return `<!DOCTYPE html>
 <html>
 <head>
@@ -9918,7 +9968,8 @@ function getSandboxHtml(justNodeUrl = "https://unpkg.com/almostnode/dist/index.j
 </head>
 <body>
 <script type="module">
-  import { VirtualFS, Runtime } from '${justNodeUrl}';
+  import { VirtualFS, Runtime } from '${almostnodeUrl}';
+${serviceWorkerScript}
 
   let vfs = null;
   let runtime = null;
@@ -10014,11 +10065,18 @@ function getSandboxVercelConfig() {
     ]
   };
 }
-function generateSandboxFiles(justNodeUrl) {
-  return {
-    "index.html": getSandboxHtml(justNodeUrl),
+function generateSandboxFiles(options = {}) {
+  const opts = typeof options === "string" ? { almostnodeUrl: options } : options;
+  const includeServiceWorker = opts.includeServiceWorker ?? true;
+  const swContent = includeServiceWorker ? getServiceWorkerContent() : null;
+  const files = {
+    "index.html": getSandboxHtml(opts),
     "vercel.json": JSON.stringify(getSandboxVercelConfig(), null, 2)
   };
+  if (swContent) {
+    files["__sw__.js"] = swContent;
+  }
+  return files;
 }
 const SANDBOX_SETUP_INSTRUCTIONS = `
 # Setting up a almostnode Sandbox on Vercel
@@ -11006,12 +11064,15 @@ class ServerBridge extends EventEmitter {
   }
   /**
    * Initialize Service Worker communication
+   * @param options - Configuration options for the service worker
+   * @param options.swUrl - Custom URL path to the service worker file (default: '/__sw__.js')
    */
-  async initServiceWorker() {
+  async initServiceWorker(options) {
     if (!("serviceWorker" in navigator)) {
       throw new Error("Service Workers not supported");
     }
-    const registration = await navigator.serviceWorker.register("/__sw__.js", {
+    const swUrl = options?.swUrl ?? "/__sw__.js";
+    const registration = await navigator.serviceWorker.register(swUrl, {
       scope: "/"
     });
     const sw = registration.active || registration.waiting || registration.installing;
@@ -13421,8 +13482,8 @@ class NextDevServer extends DevServer {
       React.useEffect(() => {
         const handlePopState = () => {
           setCurrentPath(window.location.pathname);
-          // Re-render the page component
-          window.location.reload();
+          // Defer reload outside React's update cycle
+          setTimeout(() => window.location.reload(), 0);
         };
 
         window.addEventListener('popstate', handlePopState);