### Install and Run Convex Todo Demo

Source: https://github.com/macaly/almostnode/blob/main/examples/convex-todo/README.md

Installs dependencies and starts the development server for the Convex Todo browser runtime demo. This command should be run from the examples/convex-todo directory.

```bash
npm install
npm run dev
```

--------------------------------

### Project Setup

Source: https://github.com/macaly/almostnode/blob/main/README.md

Clone the repository, navigate to the project directory, and install dependencies using npm.

```bash
git clone https://github.com/macaly/almostnode.git
cd almostnode
npm install
```

--------------------------------

### Install and Use Lodash Package

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

This example demonstrates installing the 'lodash' package and then using its utility functions within a JavaScript file executed in the virtual file system.

```javascript
import { createContainer } from 'almostnode';

const { vfs, npm, runtime } = createContainer();

// Install lodash from npm
await npm.install('lodash');

// Use it in your code
vfs.writeFileSync('/app.js', `
  const _ = require('lodash');
  const data = [1, [2, [3, [4]]]];
  console.log(_.flattenDeep(data));  // [1, 2, 3, 4]
  console.log(_.chunk([1,2,3,4,5,6], 2));  // [[1,2],[3,4],[5,6]]
`);

runtime.runFile('/app.js');
```

--------------------------------

### Initialize almostnode Container

Source: https://github.com/macaly/almostnode/blob/main/docs/index.html

Use `createContainer()` to set up a virtual filesystem, runtime, and package manager. This is the fastest way to get started.

```javascript
import { createContainer } from 'almostnode';

const { vfs, runtime, npm } = createContainer();

// Write a file to the virtual filesystem
vfs.writeFileSync('/hello.js', `
  console.log('Hello from almostnode!');
`);

// Execute it
runtime.runFile('/hello.js');
```

--------------------------------

### Run HTTP or Express Server

Source: https://github.com/macaly/almostnode/blob/main/index.html

Initializes the playground environment, installs Express if needed, resets the server bridge, and starts the server. Handles console logs from the server and sets up the preview.

```typescript
async function runSimple(tabId) {
  terminal.innerHTML = '';
  iframe.src = 'about:blank';
  placeholder.classList.remove('hidden');
  previewUrl.classList.remove('visible');
  setRunning(true);
  setTabState(tabId, 'running');
  setStatus('Starting...');
  try {
    const container = createContainer();
    container.runtime.onConsole = (method, args) => {
      const msg = args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' ');
      log(msg, method === 'error' ? 'err' : 'log');
    };
    if (tabId === 'express') {
      log('Installing express from npm...', 'info');
      setStatus('Installing npm packages...');
      await container.npm.install('express', {
        onProgress: (msg) => log(msg, 'info'),
      });
      log('Express installed', 'ok');
    }
    resetServerBridge();
    const bridge = getServerBridge({
      baseUrl: window.location.origin,
      onServerReady: (port) => {
        currentBridge = bridge;
        currentPort = port;
        log('Server listening on port ' + port, 'ok');
        setStatus('Running');
        setTabState(tabId, 'running');
        loadPreview(bridge, port, '/');
      },
    });
    const code = editors[tabId].value;
    log('Executing code...', 'info');
    setStatus('Executing...');
    containe
```

--------------------------------

### Start Dev Server with Env Vars

Source: https://github.com/macaly/almostnode/blob/main/docs/CONVEX_TUTORIAL.md

Initializes and starts a development server with Convex URL set as an environment variable. It first deploys to Convex to get the URL, then configures and registers the server.

```typescript
import { getServerBridge } from 'almostnode/server-bridge';

// Deploy and get the URL
const convexUrl = await deployToConvex('dev:my-project|token...');

// Create server with env vars
const server = new NextDevServer(vfs, {
  port: 3000,
  preferAppRouter: true,
  env: {
    NEXT_PUBLIC_CONVEX_URL: convexUrl,
  },
});

// Register and start
const bridge = getServerBridge();
await bridge.initServiceWorker();
bridge.registerServer(server, 3000);
server.start();

console.log(`App running at: ${bridge.getServerUrl(3000)}`);
```

--------------------------------

### Express Server Setup and Routes

Source: https://github.com/macaly/almostnode/blob/main/examples/express-demo.html

Sets up an Express server with middleware for JSON parsing, defines routes for the home page, user API, time API, and a random number API. Includes a 404 handler and starts the server on port 3000. This is the main server logic.

```javascript
const express = require('express');
const app = express();

// Middleware to parse JSON
app.use(express.json());

// Home route
app.get('/', (req, res) => {
  console.log('GET /');
  res.send(`
 <!DOCTYPE html>
 <html>
 <head>
 <style>
 body { font-family: system-ui, sans-serif; padding: 2rem; background: #0c0c0c; min-height: 100vh; margin: 0; display: flex; align-items: center; justify-content: center; color: #c0c0c0; }
 .card { border: 1px solid #2a2a2a; padding: 2rem; max-width: 480px; }
 h1 { color: #00ff88; margin-top: 0; }
 a { color: #00ff88; font-weight: bold; }
 code { background: #1a1a1a; padding: 2px 6px; border: 1px solid #2a2a2a; }
 </style>
 </head>
 <body>
 <div class="card">
 <h1>Express Agent Runtime</h1>
 <p>This Express server is running inside an isolated browser runtime.</p>
 <p>Routes:</p>
 <p><a href="/api/users">/api/users</a> — list all users</p>
 <p><a href="/api/time">/api/time</a> — current time</p>
 </div>
 </body>
 </html>
 `);
});

// API routes
app.get('/api/users', (req, res) => {
  console.log('GET /api/users');
  res.json([
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
    { id: 3, name: 'Charlie', email: 'charlie@example.com' }
  ]);
});

app.get('/api/time', (req, res) => {
  console.log('GET /api/time');
  res.json({ timestamp: Date.now(), iso: new Date().toISOString(), readable: new Date().toLocaleString() });
});

app.get('/api/random', (req, res) => {
  console.log('GET /api/random');
  res.json({ number: Math.random(), dice: Math.floor(Math.random() * 6) + 1 });
});

// 404 handler
app.use((req, res) => {
  res.status(404).json({ error: 'Not Found', path: req.path });
});

// Start server
app.listen(3000, () => {
  console.log('Express server running on port 3000');
});

```

--------------------------------

### Install a Package with PackageManager

Source: https://github.com/macaly/almostnode/blob/main/docs/api-reference.html

Demonstrates installing a specific npm package using the `install` method of the PackageManager. Options for saving to package.json are available.

```javascript
`install`

`(packageSpec: string, options?: InstallOptions): Promise<InstallResult>`
```

--------------------------------

### Register and Start Development Server

Source: https://github.com/macaly/almostnode/blob/main/docs/tutorial-editor.html

Register the development server on a specific port and then start it to enable file watching for HMR.

```javascript
bridge.registerServer(devServer, 3000);

devServer.start();
```

--------------------------------

### Install Packages from package.json

Source: https://github.com/macaly/almostnode/blob/main/docs/api-reference.html

Shows how to install all dependencies listed in a package.json file using the `installFromPackageJson` method of the PackageManager.

```javascript
`installFromPackageJson`

`(options?: InstallOptions): Promise<InstallResult>`
```

--------------------------------

### List Installed Packages

Source: https://github.com/macaly/almostnode/blob/main/docs/api-reference.html

Demonstrates retrieving a record of installed packages and their versions using the `list` method of the PackageManager.

```javascript
`list`

`(): Record<string, string>`
```

--------------------------------

### Execute the Default Start Script

Source: https://github.com/macaly/almostnode/blob/main/examples/npm-scripts-demo.html

Executes the 'start' script defined in package.json, typically used to launch a development server or application.

```bash
npm start
```

--------------------------------

### Install and run CLI tools

Source: https://github.com/macaly/almostnode/blob/main/README.md

Install npm packages that include CLI tools, such as Vitest, and run them directly. The tools are automatically available in the PATH after installation.

```typescript
// Install a package that includes a CLI tool
await container.npm.install('vitest');

// Run it directly — bin stubs are created in /node_modules/.bin/
const result = await container.run('vitest run');
console.log(result.stdout); // Test results
```

--------------------------------

### Install Package Function

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Handles the installation of a specified package using the package manager, updates the UI, creates a demo page, and loads the file. Includes error handling and progress logging.

```javascript
async function installPackage(packageSpec) { if (!vfs || !packageManager) { log('VFS or PackageManager not initialized', 'error'); return; } const packageName = packageSpec.split('@')[0]; installBtn.disabled = true; installBtn.textContent = 'Installing...'; try { log(`Installing ${packageSpec}...`); const result = await packageManager.install(packageSpec, { onProgress: (message) => log(message), }); for (const name of result.added) installedPackages.add(name); updateInstalledList(); const { pagePath, routePath } = createPackageDemoPage(packageName); log(`Created demo: ${pagePath}`, 'hmr'); const tabs = useAppRouter ? appRouterTabs : pagesRouterTabs; if (!tabs.find(t => t.file === pagePath)) { tabs.push({ file: pagePath, label: `${packageName}-demo.jsx` }); updateFileTabs(); } loadFile(pagePath); log(`Installed ${packageSpec}`, 'hmr'); log(`Navigate to ${routePath} to see the demo.`); } catch (error) { log(`Failed: ${error.message}`, 'error'); console.error(error); } finally { installBtn.disabled = false; installBtn.textContent = 'Install'; } }
```

--------------------------------

### Run Development Server

Source: https://github.com/macaly/almostnode/blob/main/docs/AI_CHATBOT_TUTORIAL.md

Starts the development server for the Next.js application. Open your browser to the specified local address to view the demo.

```bash
npm run dev
```

--------------------------------

### Install Dependencies from package.json

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

Use `container.npm.installFromPackageJson()` to install all dependencies listed in an existing `package.json` file.

```javascript
container.npm.installFromPackageJson()
```

--------------------------------

### Initial Sandbox Messages

Source: https://github.com/macaly/almostnode/blob/main/examples/sandbox-next-demo.html

Logs initial informational messages to the console when the sandbox demo is loaded, guiding the user on how to start.

```javascript
logToConsole('Sandbox demo loaded', 'info');
logToConsole('Click Connect to Sandbox to start', 'info');
```

--------------------------------

### Install Package

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Installs a specified package using the package manager. This function is triggered by user input and updates the UI to reflect the installation.

```javascript
function installPackage(pkg) {
  log(`Installing ${pkg}...`);
  packageManager.install([pkg]).then(() => {
    installedPackages.add(pkg);
    updateInstalledList();
    log(`Installed ${pkg}`);
  }).catch(e => {
    log(`Failed to install ${pkg}: ${e.message}`, 'error');
    console.error(e);
  });
}
```

--------------------------------

### Setting up a Vite Development Server with VirtualFS

Source: https://github.com/macaly/almostnode/blob/main/README.md

Initialize a VirtualFS and configure a ViteDevServer for a frontend application. This example creates a basic React app structure.

```typescript
import { VirtualFS, ViteDevServer, getServerBridge } from 'almostnode';

const vfs = new VirtualFS();

// Create a React app
vfs.writeFileSync('/index.html', "
  <!DOCTYPE html>
  <html>
    <body>
      <div id=\"root\"><\/div>
      <script type=\"module\" src=\"/src/main.jsx\"><\/script>
    </body>
  </html>");

vfs.mkdirSync('/src', { recursive: true });
vfs.writeFileSync('/src/main.jsx', "
  import React from 'react';
  import ReactDOM from 'react-dom/client';

  function App() {
    return <h1>Hello Vite!</h1>;
  }

  ReactDOM.createRoot(document.getElementById('root')).render(<App />);
");

// Start Vite dev server
const server = new ViteDevServer(vfs, { port: 5173 });
```

--------------------------------

### Package Manager Installation

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

Illustrates how to install npm packages into the virtual filesystem using the PackageManager, including single packages, specific versions, and dependencies from package.json.

```typescript
import { VirtualFS, PackageManager } from 'almostnode';

const vfs = new VirtualFS();
const npm = new PackageManager(vfs);

// Install a single package
await npm.install('lodash');

// Install a specific version
await npm.install('react@18.2.0');

// Install all deps from package.json
vfs.writeFileSync('/package.json', JSON.stringify({
  dependencies: { express: '^4.18.0' }
}));
await npm.installFromPackageJson();

// List installed packages
console.log(npm.list()); // { express: '4.18.2', ... }
```

--------------------------------

### Initialize Playground Environment

Source: https://github.com/macaly/almostnode/blob/main/index.html

Imports necessary modules and gets references to DOM elements for the playground UI. This setup is required before interacting with any playground features.

```typescript
import { createContainer, VirtualFS, NextDevServer, getServerBridge, resetServerBridge } from '/src/index.ts';

const terminal = document.getElementById('pg-terminal');
const iframe = document.getElementById('pg-iframe');
const placeholder = document.getElementById('pg-placeholder');
const previewUrl = document.getElementById('pg-preview-url');
const statusEl = document.getElementById('pg-status');
const tabs = document.querySelectorAll('.pg-tab');
const panels = {
  http: document.getElementById('pg-code-http'),
  express: document.getElementById('pg-code-express'),
  nextjs: document.getElementById('pg-code-nextjs'),
};

let activeTab = 'http';
let running = false;
let currentBridge = null;
let currentPort = null;

const editors = {
  http: document.getElementById('pg-editor-http'),
  express: document.getElementById('pg-editor-express'),
  nextjs: document.getElementById('pg-editor-nextjs'),
};
```

--------------------------------

### Next.js Dev Server Setup

Source: https://github.com/macaly/almostnode/blob/main/docs/nextjs-guide.html

Initializes the VirtualFS, NextDevServer, and ServerBridge. Registers the server and points an iframe to the dev server URL. Ensure the service worker is initialized before registering the server.

```javascript
import { VirtualFS } from 'almostnode';
import { NextDevServer } from 'almostnode/next';
import { getServerBridge } from 'almostnode';

const vfs = new VirtualFS();
const server = new NextDevServer(vfs);
const bridge = getServerBridge();

// Initialize the service worker
await bridge.initServiceWorker();

// Register the server on a port
bridge.registerServer(server, 3000);

// Point an iframe to the dev server
iframe.src = bridge.getServerUrl(3000);
```

--------------------------------

### Install npm Packages

Source: https://github.com/macaly/almostnode/blob/main/docs/vite-guide.html

Installs 'react' and 'react-dom' packages into the VirtualFS using the PackageManager, enabling them to be imported in the Vite app.

```javascript
import { VirtualFS, PackageManager } from 'almostnode';

const vfs = new VirtualFS();
const npm = new PackageManager(vfs);

// Install React
await npm.install('react');
await npm.install('react-dom');

// Now your Vite app can import them
// import React from 'react';
```

--------------------------------

### Running the Sandbox and Development Server

Source: https://github.com/macaly/almostnode/blob/main/examples/sandbox-next-demo.html

Commands to start the sandbox on port 3002 and the development server on port 5173. Ensure both are running before connecting.

```bash
npm run sandbox
npm run dev
```

--------------------------------

### Next.js Demo Initialization and Setup

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Imports necessary functions for Next.js demos and sets up event listeners for various UI elements. It also initializes the virtual file system and runtime environment.

```javascript
import { initNextDemo, initNextAppRouterDemo, startNextDevServer, VirtualFS, Runtime, PackageManager, createRuntime } from '../src/next-demo.ts'; // CORS Proxy helpers function setCorsProxy(url) { if (url) localStorage.setItem('\_	rumpet_corsProxyUrl', url); else localStorage.removeItem('\_	rumpet_corsProxyUrl'); } function getCorsProxy() { return localStorage.getItem('\_	rumpet_corsProxyUrl') || null; } const outputEl = document.getElementById('output'); const editorEl = document.getElementById('editor'); const statusDot = document.getElementById('status-dot'); const statusText = document.getElementById('status-text'); const saveBtn = document.getElementById('save-btn'); const clearBtn = document.getElementById('clear-btn'); const runBtn = document.getElementById('run-btn'); const refreshBtn = document.getElementById('refresh-btn'); const fileTabsEl = document.getElementById('file-tabs'); const previewFrame = document.getElementById('preview-frame'); const previewPlaceholder = document.getElementById('preview-placeholder'); const hmrIndicator = document.getElementById('hmr-indicator'); const pagesRouterBtn = document.getElementById('pages-router-btn'); const appRouterBtn = document.getElementById('app-router-btn'); const urlInput = document.getElementById('url-input'); const urlGoBtn = document.getElementById('url-go-btn'); const packageInput = document.getElementById('package-input'); const installBtn = document.getElementById('install-btn'); const installedList = document.getElementById('installed-list'); const proxyInput = document.getElementById('proxy-input'); const setProxyBtn = document.getElementById('set-proxy-btn'); const clearProxyBtn = document.getElementById('clear-proxy-btn'); const proxyStatus = document.getElementById('proxy-status'); const workerToggle = document.getElementById('worker-toggle'); const workerStatus = document.getElementById('worker-status'); let vfs = null; let runtime = null; let devServer = null; let devServerUrl = null; let currentFile = '/pages/index.jsx'; let previewActive = false; let useAppRouter = false; let useWorker = false; let packageManager = null; let installedPackages = new Set(['react', 'react-dom']); function updateWorkerStatus() { if (useWorker) { workerStatus.textContent = 'On'; workerStatus.classList.add('on'); } else { workerStatus.textContent = 'Off'; workerStatus.classList.remove('on'); } } const pagesRouterTabs = [ { file: '/pages/index.jsx', label: 'index.jsx' }, { file: '/pages/about.jsx', label: 'about.jsx' }, { file: '/pages/users/[id].jsx', label: '[id].jsx' }, { file: '/pages/typescript/index.tsx', label: 'typescript.tsx' }, { file: '/pages/external-api.jsx', label: 'external-api.jsx' }, { file: '/pages/api/hello.js', label: 'api/hello.js' }, { file: '/styles/globals.css', label: 'globals.css' }, ]; const appRouterTabs = [ { file: '/app/page.jsx', label: 'page.jsx' }, { file: '/app/layout.jsx', label: 'layout.jsx' }, { file: '/app/about/page.jsx', label: 'about/page.jsx' }, { file: '/app/typescript/page.tsx', label: 'typescript.tsx' }, { file: '/app/dashboard/page.jsx', label: 'dashboard/page.jsx' }, { file: '/app/users/[id]/page.jsx', label: 'users/[id].jsx' }, { file: '/app/globals.css', label: 'globals.css' }, ]; function log(message, className = '') { const line = document.createElement('div'); line.textContent = `[${new Date().toLocaleTimeString()}] ${message}`; if (className) line.className = className; outputEl.appendChild(line); outputEl.scrollTop = outputEl.scrollHeight; } function setStatus(status, text) { statusDot.className = 'status-dot ' + status; statusText.textContent = text; } function showHmrIndicator() { hmrIndicator.classList.add('show'); setTimeout(() => hmrIndicator.classList.remove('show'), 2000); } function updateInstalledList() { installedList.textContent = Array.from(installedPackages).join(', ') || 'none'; }
```

--------------------------------

### Install and Run npm Packages

Source: https://github.com/macaly/almostnode/blob/main/docs/index.html

Install real npm packages at runtime using the package manager. The package manager fetches, resolves, and extracts packages from the npm registry in the browser.

```javascript
import { createContainer } from 'almostnode';

const { vfs, npm, runtime } = createContainer();

// Install Express from npm
await npm.install('express');

vfs.writeFileSync('/app.js', `
  const express = require('express');
  const app = express();

  app.get('/', (req, res) => {
    res.json({ message: 'Express in the browser!' });
  });

  app.listen(3000);
`);

runtime.runFile('/app.js');
```

--------------------------------

### Start Next.js Development Server

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Starts the Next.js development server, logs its URL, and sets up an HMR update listener. This is crucial for enabling live reloading and hot module replacement.

```javascript
async function doStartPreview() {
  try {
    runBtn.disabled = true;
    setStatus('', 'Starting dev server...');
    const result = await startNextDevServer(vfs, { port: 3001, log });
    devServer = result.server;
    devServerUrl = result.url;
    log(`Dev server: ${devServerUrl}`);
    devServer.on('hmr-update', (update) => {
      log(`HMR: ${update.path}`, 'hmr');
      showHmrIndicator();
    });
    await startPreview();
    setStatus('running', 'Dev server running');
  } catch (e) {
    setStatus('error', 'Preview failed');
    log(`Error: ${e.message}`, 'error');
    console.error(e);
    runBtn.disabled = false;
  }
}
```

--------------------------------

### Install Specific Package Version

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

Install a specific version of a package by appending the version number to the package name with an '@' symbol.

```javascript
await npm.install('dayjs@1.11.10');
```

--------------------------------

### Express Application in Browser

Source: https://github.com/macaly/almostnode/blob/main/index.html

Shows how to set up an Express application using the 'express' module, installed via npm and running client-side. Includes a root route and an API route.

```javascript
const express = require('express');
const app = express();
app.get('/', (req, res) => {
  res.send(` <body style="font-family:system-ui;padding:2rem;background:#f8f9fa">
 <h1>Express in the browser</h1>
 <p>Installed from npm, running client-side.</p>
 <a href="/api/hello">Try the API →</a>
 </body> `);
});
app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello from Express!', runtime: 'almostnode' });
});
app.listen(3000);
```

--------------------------------

### Start Next.js Development Server

Source: https://github.com/macaly/almostnode/blob/main/examples/next-features-test.html

Initializes and starts a Next.js development server using an in-memory file system (VFS). Includes service worker initialization and registers the server with a bridge for HMR.

```javascript
async function doStartPreview() { try { runBtn.disabled = true; statusText.textContent = 'Starting dev server...'; const server = new NextDevServer(vfs, { port: 3002, root: '/' }); devServer = server; window.__TEST_SERVER = server; const bridge = getServerBridge(); try { await bridge.initServiceWorker(); log('Service Worker ready'); } catch (error) { log('SW init failed: ' + error); } const httpServer = { listening: true, address: () => ({ port: 3002, address: '0.0.0.0', family: 'IPv4' }), async handleRequest(method, url, headers, body) { const bodyBuffer = body ? (typeof body === 'string' ? Buffer.from(body) : body) : undefined; return server.handleRequest(method, url, headers, bodyBuffer); }, }; bridge.registerServer(httpServer, 3002); server.start(); devServerUrl = bridge.getServerUrl(3002) + '/'; window.__TEST_URL = devServerUrl; log('Dev server URL: ' + devServerUrl); previewFrame.style.display = 'block'; previewFrame.onload = () => { if (devServer && previewFrame.contentWindow) { devServer.setHMRTarget(previewFrame.contentWindow); } }; previewFrame.src = devServerUrl; statusText.textContent = 'Dev server running'; log('Dev server running on port 3002'); } catch (e) { statusText.textContent = 'Error: ' + e.message; log('Error: ' + e.message); console.error(e); runBtn.disabled = false; } }
```

--------------------------------

### Start Development Server and Preview

Source: https://github.com/macaly/almostnode/blob/main/examples/editor-tutorial.html

This asynchronous function orchestrates the startup of the Next.js dev server and the preview environment. It handles UI updates for status indicators and enables the save button upon successful startup.

```javascript
async function startPreview() {
  startBtn.disabled = true;
  statusDot.className = 'status-dot starting';
  statusText.textContent = 'Starting...';
  log('Starting Next.js dev server...');
  try {
    // ... (server creation and HMR setup code) ...
    saveBtn.disabled = false;
    statusDot.className = 'status-dot running';
    statusText.textContent = 'Running';
    log('Preview started! Edit a file and save to see HMR.');
  } catch (e) {
    statusDot.className = 'status-dot';
    statusText.textContent = 'Error';
    log('Failed to start: ' + e.message, 'error');
    console.error(e);
    startBtn.disabled = false;
  }
}
```

--------------------------------

### Start Preview Frame

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Starts the preview frame, making it visible and setting its source to the development server URL. It also configures the HMR target if the dev server is available.

```javascript
async function startPreview() {
  previewPlaceholder.style.display = 'none';
  previewFrame.style.display = 'block';
  previewActive = true;
  if (devServerUrl) {
    previewFrame.onload = () => {
      if (devServer && previewFrame.contentWindow) {
        devServer.setHMRTarget(previewFrame.contentWindow);
        log('HMR target connected', 'hmr');
      }
    };
    previewFrame.src = devServerUrl;
    urlInput.value = '/';
  }
  log('Preview started');
  log('Edit and save to trigger HMR', 'hmr');
}
```

--------------------------------

### Complete AlmostNode Editor Example

Source: https://github.com/macaly/almostnode/blob/main/docs/tutorial-editor.html

This full-page script integrates VirtualFS, NextDevServer, and a server bridge to create a live-editing environment. It includes file management, an editor, and a preview iframe with HMR.

```javascript
<script type="module">
import { VirtualFS } from 'almostnode';
import { NextDevServer } from 'almostnode/next';
import { getServerBridge } from 'almostnode';

// ── State ──
let vfs, devServer, serverUrl;
let currentFile = '/app/page.tsx';

const editor = document.getElementById('editor');
const iframe = document.getElementById('preview-frame');

const files = [
  { path: '/app/page.tsx', label: 'page.tsx' },
  { path: '/app/layout.tsx', label: 'layout.tsx' },
  { path: '/app/about/page.tsx', label: 'about/page.tsx' },
];

// ── 1. Set up VFS with project files ──
vfs = new VirtualFS();
vfs.mkdirSync('/app/about', { recursive: true });

vfs.writeFileSync('/app/layout.tsx', "
  export default function RootLayout({ children }) {
    return <html><body>{children}</body></html>;
  }
");

vfs.writeFileSync('/app/page.tsx', "
  'use client';
  import { useState } from 'react';
  export default function Home() {
    const [count, setCount] = useState(0);
    return <div><h1>Hello!</h1><p>{count}</p>
      <button onClick={() => setCount(c => c+1)}>+</button></div>;
  }
");

vfs.writeFileSync('/app/about/page.tsx', "
  export default function About() {
    return <h1>About</h1>;
  }
");

// ── 2. Load file into editor ──
function loadFile(path) {
  editor.value = vfs.readFileSync(path, 'utf8');
  currentFile = path;
}

// ── 3. Save file (triggers HMR automatically) ──
function saveFile() {
  vfs.writeFileSync(currentFile, editor.value);
}

editor.addEventListener('keydown', (e) => {
  if ((e.ctrlKey || e.metaKey) && e.key === 's') {
    e.preventDefault();
    saveFile();
  }
});

// ── 4. Start dev server and preview ──
async function start() {
  devServer = new NextDevServer(vfs, { port: 3000, root: '/' });
  devServer.start(); // Enable file watching for HMR

  const bridge = getServerBridge();
  await bridge.initServiceWorker();
  bridge.registerServer(devServer, 3000);

  serverUrl = bridge.getServerUrl(3000) + '/';

  devServer.on('hmr-update', (u) => console.log('HMR:', u.path));

  iframe.onload = () => {
    if (iframe.contentWindow)
      devServer.setHMRTarget(iframe.contentWindow);
  };
  iframe.src = serverUrl;
}

loadFile(currentFile);
document.getElementById('start-btn').addEventListener('click', start);
</script>
```

--------------------------------

### PackageManager for npm Installs

Source: https://github.com/macaly/almostnode/blob/main/docs/CONVEX_TUTORIAL.md

Shows how to use the PackageManager to install npm packages into the virtual filesystem, including single packages and multiple packages.

```typescript
import { PackageManager } from 'almostnode';

const npm = new PackageManager(vfs, { cwd: '/project' });

// Install a package
await npm.install('convex', {
  onProgress: (msg) => console.log(msg),
});

// Install multiple packages
await npm.install(['react', 'react-dom']);

```

--------------------------------

### Initialize PackageManager

Source: https://github.com/macaly/almostnode/blob/main/docs/api-reference.html

Shows the instantiation of the PackageManager to install npm packages into a virtual filesystem. It fetches from the npm registry and resolves dependencies.

```javascript
new PackageManager(vfs: VirtualFS, options?: { cwd?: string })
```

--------------------------------

### Run Next.js Dev Server

Source: https://github.com/macaly/almostnode/blob/main/README.md

Set up a virtual file system with Next.js pages and start the Next.js development server. The server can be accessed via a virtual URL.

```typescript
import { VirtualFS, NextDevServer, getServerBridge } from 'almostnode';

const vfs = new VirtualFS();

// Create a Next.js page
vfs.mkdirSync('/pages', { recursive: true });
vfs.writeFileSync('/pages/index.jsx', "
  import { useState } from 'react';

  export default function Home() {
    const [count, setCount] = useState(0);
    return (
      <div>
        <h1>Count: {count}</h1>
        <button onClick={() => setCount(c => c + 1)}>+</button>
      </div>
    );
  }
");

// Start the dev server
const server = new NextDevServer(vfs, { port: 3000 });
const bridge = getServerBridge();
await bridge.initServiceWorker();
bridge.registerServer(server, 3000);

// Access at: /__virtual__/3000/
```

--------------------------------

### Install npm Package Programmatically

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

Install a single npm package using `container.npm.install()`. This method provides typed results and supports progress callbacks and options like `save` or `saveDev`.

```javascript
container.npm.install('pkg')
```

--------------------------------

### Load File and Render Tabs

Source: https://github.com/macaly/almostnode/blob/main/examples/editor-tutorial.html

This snippet includes event listeners for file tab clicks to load files and initial setup functions to render tabs and load the default file. It also logs a message indicating the initial state.

```javascript
fileTabs.addEventListener('click', (e) => {
  if (e.target.classList.contains('file-tab')) {
    loadFile(e.target.dataset.path);
  }
});
startBtn.addEventListener('click', startPreview);
saveBtn.addEventListener('click', saveFile);
setupFiles();
renderTabs();
loadFile(currentFile);
log('Files loaded. Click "Start Preview" to launch.');
```

--------------------------------

### HTML Scaffolding for Editor and Preview

Source: https://github.com/macaly/almostnode/blob/main/docs/tutorial-editor.html

Sets up the basic two-column layout for the editor and preview panels. Includes elements for file tabs, a textarea for editing, and buttons for starting the preview and saving. This structure serves as the foundation for the interactive editor.

```html
<div class="container">
  <!-- Left: Editor -->
  <div class="editor-panel">
    <div id="file-tabs"></div>
    <textarea id="editor"></textarea>
    <button id="start-btn">Start Preview</button>
    <button id="save-btn">Save</button>
  </div>

  <!-- Right: Preview -->
  <div class="preview-panel">
    <iframe id="preview-frame"></iframe>
  </div>
</div>
```

--------------------------------

### Generate Sandbox Files for Deployment

Source: https://github.com/macaly/almostnode/blob/main/docs/security.html

Use this utility to quickly create the necessary files for deploying the cross-origin sandbox, for example, to Vercel. It generates an HTML page, Vercel configuration, and a service worker.

```javascript
import { generateSandboxFiles } from 'almostnode';
import fs from 'fs';

const files = generateSandboxFiles();

fs.mkdirSync('sandbox', { recursive: true });
for (const [filename, content] of Object.entries(files)) {
  fs.writeFileSync(`sandbox/${filename}`, content);
}

// Deploy: cd sandbox && vercel --prod
```

--------------------------------

### Manual Service Worker Setup

Source: https://github.com/macaly/almostnode/blob/main/README.md

Copies the service worker file to the public directory, either via bash command or programmatically using Node.js fs module.

```bash
cp node_modules/almostnode/dist/__sw__.js ./public/
```

```typescript
import { getServiceWorkerPath } from 'almostnode/next';
import fs from 'fs';

fs.copyFileSync(getServiceWorkerPath(), './public/__sw__.js');
```

--------------------------------

### Minimal Next.js App with almostnode

Source: https://github.com/macaly/almostnode/blob/main/docs/CONVEX_TUTORIAL.md

Sets up a virtual filesystem, writes project files, and starts a Next.js development server. It then registers the server with a bridge and logs the application URL.

```typescript
import { VirtualFS, Runtime, NextDevServer, PackageManager } from 'almostnode';
import { getServerBridge } from 'almostnode/server-bridge';

// 1. Create virtual filesystem
const vfs = new VirtualFS();

// 2. Write project files
vfs.writeFileSync('/package.json', JSON.stringify({ name: 'my-app' }));
vfs.mkdirSync('/app', { recursive: true });
vfs.writeFileSync('/app/page.tsx', "
  export default function Home() {
    return <h1>Hello from almostnode!</h1>;
  }
");

// 3. Create and start the dev server
const server = new NextDevServer(vfs, {
  port: 3000,
  preferAppRouter: true,
});

// 4. Register with the server bridge (enables Service Worker routing)
const bridge = getServerBridge();
await bridge.initServiceWorker();
bridge.registerServer(server, 3000);
server.start();

// 5. Navigate to the app
const url = bridge.getServerUrl(3000);
console.log(`App running at: ${url}`);

```

--------------------------------

### Initialize VirtualFS and Project Files

Source: https://github.com/macaly/almostnode/blob/main/examples/editor-tutorial.html

Sets up the VirtualFS with a basic Next.js project structure and files. This includes package.json, layout.tsx, page.tsx, about/page.tsx, and globals.css.

```typescript
import { VirtualFS } from '../src/index.ts';
import { NextDevServer } from '../src/frameworks/next-dev-server.ts';
import { getServerBridge } from '../src/server-bridge.ts';

// ── State ──
let vfs, devServer, devServerUrl;
let currentFile = '/app/page.tsx';

// ── DOM refs ──
const editor = document.getElementById('editor');
const fileTabs = document.getElementById('file-tabs');
const startBtn = document.getElementById('start-btn');
const saveBtn = document.getElementById('save-btn');
const refreshBtn = document.getElementById('refresh-btn');
const statusDot = document.getElementById('status-dot');
const statusText = document.getElementById('status-text');
const previewFrame = document.getElementById('preview-frame');
const placeholder = document.getElementById('preview-placeholder');
const hmrToast = document.getElementById('hmr-toast');
const consoleEl = document.getElementById('console');

// ── Files we can edit ──
const files = [
  { path: '/app/page.tsx', label: 'page.tsx' },
  { path: '/app/layout.tsx', label: 'layout.tsx' },
  { path: '/app/about/page.tsx', label: 'about/page.tsx' },
  { path: '/app/globals.css', label: 'globals.css' },
];

// ── Logging ──
function log(msg, cls = '') {
  const line = document.createElement('div');
  line.textContent = `[${new Date().toLocaleTimeString()}] ${msg}`;
  if (cls) line.className = cls;
  consoleEl.appendChild(line);
  consoleEl.scrollTop = consoleEl.scrollHeight;
}

function showHmrToast() {
  hmrToast.classList.add('show');
  setTimeout(() => hmrToast.classList.remove('show'), 2000);
}

// ── Step 1: Create VFS with project files ──
function setupFiles() {
  vfs = new VirtualFS();
  vfs.writeFileSync('/package.json', JSON.stringify({
    name: 'editor-tutorial',
    version: '1.0.0',
    dependencies: {
      next: '^14.0.0',
      react: '^18.2.0',
      'react-dom': '^18.2.0'
    },
  }, null, 2));
  vfs.mkdirSync('/app', { recursive: true });
  vfs.mkdirSync('/app/about', { recursive: true });
  vfs.writeFileSync('/app/layout.tsx', `export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </head>
      <body style={{ margin: 0, fontFamily: 'system-ui, sans-serif', background: '#fafafa' }}>
        <nav style={{ background: '#111', color: '#fff', padding: '12px 24px', display: 'flex', gap: '16px', alignItems: 'center' }}>
          <strong>My App</strong>
          <a href="/" style={{ color: '#aaa', textDecoration: 'none' }}>Home</a>
          <a href="/about" style={{ color: '#aaa', textDecoration: 'none' }}>About</a>
        </nav>
        <main style={{ maxWidth: 720, margin: '0 auto', padding: '32px 24px' }}>
          {children}
        </main>
      </body>
    </html>
  );
}
`);
  vfs.writeFileSync('/app/page.tsx', `'use client';
import { useState } from 'react';

export default function Home() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1 style={{ fontSize: '2rem', marginBottom: 8 }}>Welcome!</h1>
      <p style={{ color: '#666', marginBottom: 24 }}>
        This is a Next.js app running entirely in the browser. Edit this file and press Ctrl/Cmd+S to see HMR in action.
      </p>
      <div style={{ background: '#fff', borderRadius: 12, padding: 24, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
        <p style={{ fontSize: '3rem', textAlign: 'center', margin: '8px 0' }}>{count}</p>
        <div style={{ display: 'flex', gap: 8, justifyContent: 'center' }}>
          <button onClick={() => setCount(c => c - 1)} style={{ padding: '8px 20px', borderRadius: 6, border: '1px solid #ddd', background: '#fff', cursor: 'pointer', fontSize: 16 }}>-</button>
          <button onClick={() => setCount(c => c + 1)} style={{ padding: '8px 20px', borderRadius: 6, border: 'none', background: '#22c55e', color: '#fff', cursor: 'pointer', fontSize: 16 }}>+</button>
        </div>
      </div>
    </div>
  );
}
`);
  vfs.writeFileSync('/app/about/page.tsx', `export default function About() {
  return (
    <div>
      <h1 style={{ fontSize: '2rem', marginBottom: 8 }}>About</h1>
      <p style={{ color: '#666', lineHeight: 1.7 }}>
        This demo shows how to build a file editor with a live Next.js preview using almostnode. The preview runs in an iframe and updates via HMR when you save a file.
      </p>
      <div style={{ marginTop: 24, padding: 16, background: '#e8f5e9', borderRadius: 8 }}>
        <strong>Tip:</strong> For production use, run the preview iframe on a different origin (e.g., a subdomain) to isolate untrusted code from your app's cookies, localStorage, and DOM.
      </div>
    </div>
  );
}
`);
  vfs.writeFileSync('/app/globals.css', `* { box-sizing: border-box; }
body { margin: 0; font-family: system-ui, -apple-system, sans-serif; background: #fafafa; color: #222; }
a { color: #22c55e; }
a:hover { text-decoration: underline; }
`);
}

// ── Step 2: Render file tabs ──
function renderTabs() {
  fileTabs.innerHTML = files.map(f => `<button class="file-tab${f.path === currentFile ? ' active' : ''}" data-path="${f.path}">${f.label}</button>` ).join('');
}

function loadFile(path) {
  try {
    editor.value = vfs.readFileSync(path, 'utf8');
    currentFile = path;
    renderTabs();
  } catch (e) {
    log('Error loading ' +

```

--------------------------------

### Create Runtime with Same-Origin Main Thread

Source: https://github.com/macaly/almostnode/blob/main/docs/security.html

Runs code directly on the main thread. This is the simplest setup but provides no isolation, so it should only be used with fully trusted code.

```javascript
const runtime = await createRuntime(vfs, {
  dangerouslyAllowSameOrigin: true,
});
```

--------------------------------

### Generic Package Demo Component

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Generates a placeholder React component for any other package, indicating it has been installed and showing how to import it via esm.sh. This is a fallback for unhandled packages.

```javascript
'use client'; import React from 'react'; // import ${jsName} from 'https://esm.sh/${packageName}?dev'; export default function ${jsName.charAt(0).toUpperCase() + jsName.slice(1)}Demo() { return ( <div style={{padding:'2rem',maxWidth:'600px',margin:'0 auto'}}> <h1>${packageName} Demo</h1> <p>The <code>${packageName}</code> package has been installed.</p> <p>Import via esm.sh:</p> <code>import ${jsName} from 'https://esm.sh/${packageName}?dev';</code> </div> ); }
```

--------------------------------

### Navigate to Path in Preview

Source: https://github.com/macaly/almostnode/blob/main/examples/next-demo.html

Navigates the preview frame to a specified path. It ensures the path starts with a '/' and constructs the full URL for the preview frame's source.

```javascript
function navigateToPath(path) {
  if (!previewActive || !devServerUrl) {
    log('Preview not running.', 'error');
    return;
  }
  if (!path.startsWith('/')) path = '/' + path;
  const fullUrl = devServerUrl + path.substring(1);
  previewFrame.onload = () => {
    if (devServer && previewFrame.contentWindow)
      devServer.setHMRTarget(previewFrame.contentWindow);
  };
  log(`Navigating to: ${path}`);
  previewFrame.src = fullUrl;
  urlInput.value = path;
}
```

--------------------------------

### Running Development Servers

Source: https://github.com/macaly/almostnode/blob/main/README.md

Instructions for running the main application and the sandbox on different ports for local development.

```bash
# Terminal 1: Main app on port 5173
npm run dev

# Terminal 2: Sandbox on port 3002
npm run sandbox
```

--------------------------------

### App Router Route Handler

Source: https://github.com/macaly/almostnode/blob/main/docs/nextjs-guide.html

Define an API endpoint using the App Router's route handler. This example sets up a GET request handler.

```typescript
export async function GET(request) {
  return Response.json({ message: 'Hello!' });
}
```

--------------------------------

### Install Scoped Packages

Source: https://github.com/macaly/almostnode/blob/main/docs/core-concepts.html

Scoped packages, identified by the '@' prefix, can also be installed using the `npm.install` method.

```javascript
await npm.install('@hono/node-server');
```

--------------------------------

### Install almostnode Package

Source: https://github.com/macaly/almostnode/blob/main/README.md

Install the almostnode package using npm. This is the first step to using almostnode in your project.

```bash
npm install almostnode
```

--------------------------------

### Container Initialization Options

Source: https://github.com/macaly/almostnode/blob/main/README.md

Shows how to create a new container with custom options for working directory, environment variables, and console logging.

```typescript
interface ContainerOptions {
  cwd?: string;           // Working directory (default: '/')
  env?: Record<string, string>;  // Environment variables
  onConsole?: (method: string, args: any[]) => void;  // Console hook
}

const container = createContainer({
  cwd: '/app',
  env: { NODE_ENV: 'development' },
  onConsole: (method, args) => console.log(`[${method}]`, ...args),
});
```

--------------------------------

### Install Convex Package with npm

Source: https://github.com/macaly/almostnode/blob/main/docs/CONVEX_TUTORIAL.md

Installs the Convex package using npm within the project directory. Includes progress logging.

```typescript
const npm = new PackageManager(vfs, { cwd: '/project' });

await npm.install('convex', {
  onProgress: (msg) => console.log(`[npm] ${msg}`),
});
```

--------------------------------

### PackageManager

Source: https://github.com/macaly/almostnode/blob/main/docs/CONVEX_TUTORIAL.md

Installs npm packages into the virtual filesystem. It supports installing single packages or multiple packages and provides progress updates.

```APIDOC
## Class: PackageManager

### Description
Install npm packages into the virtual filesystem.

### Methods
- `install(packages: string | string[], options?: object)`: Installs one or more npm packages. The `onProgress` option can be used to track installation progress.
  - `onProgress(msg: string)`: Callback function to receive installation progress messages.
```