Merge branch 'main' into feature/example-ui-redesign

Author: jasonkneen

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9] - 2026-02-08
+
+### Added
+
+- **`browser` field support in module resolution:** npm packages with a `browser` field in package.json now resolve to their browser-specific entry point. Supports both string form (`"browser": "lib/browser/index.js"`) and object form (`"browser": {"./lib/node.js": "./lib/browser.js"}`). This fixes compatibility with packages like `depd`, `debug`, and others that provide browser-optimized versions.
+
+### Fixed
+
+- **Safari Express crash:** Fixed `callSite.getFileName is not a function` error when running Express in Safari. The `depd` package (an Express dependency) uses V8-specific `Error.captureStackTrace` APIs that don't exist in WebKit. By respecting depd's `"browser"` field, the no-op browser version is now loaded instead.
+- **`Error.captureStackTrace` polyfill improvements:** Added `Error.stackTraceLimit` default, `.stack` getter interception on `Error.prototype` for lazy `prepareStackTrace` evaluation, re-entrancy protection, and error logging instead of silent fallback.
+
 ## [0.2.8] - 2026-02-07
 
 ### Added

README.md

@@ -315,7 +315,7 @@ fs.copyFileSync(getServiceWorkerPath(), './public/__sw__.js');
 
 | Feature | almostnode | WebContainers |
 |---------|-----------|---------------|
-| **Bundle Size** | ~50KB | ~2MB |
+| **Bundle Size** | ~250KB gzipped | ~2MB |
 | **Startup Time** | Instant | 2-5 seconds |
 | **Execution Model** | Main thread or Web Worker (configurable) | Web Worker isolates |
 | **Shell** | `just-bash` (POSIX subset) | Full Linux kernel |

docs/api-reference.html

@@ -45,6 +45,10 @@
       <a href="./nextjs-guide.html">Next.js</a>
       <a href="./vite-guide.html">Vite</a>
     </div>
+    <div class="sidebar-group">
+      <div class="sidebar-label">Tutorials</div>
+      <a href="./tutorial-editor.html">Editor + Preview</a>
+    </div>
     <div class="sidebar-group">
       <div class="sidebar-label">Reference</div>
       <a href="./api-reference.html" class="active">API Reference</a>
@@ -305,13 +309,34 @@ <h2>NextDevServer</h2>
     <p>A virtual Next.js dev server that supports both App Router and Pages Router, CSS Modules, API routes, dynamic routes, route groups, and HMR via React Refresh.</p>
     <p>Import from <code>almostnode/next</code>.</p>
 
+    <h3>Methods</h3>
+    <table>
+      <thead><tr><th>Method</th><th>Signature</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr><td><code>start</code></td><td><code>(): void</code></td><td>Start file watching for HMR. <strong>Required</strong> before HMR updates will fire.</td></tr>
+        <tr><td><code>stop</code></td><td><code>(): void</code></td><td>Stop the server and clean up file watchers</td></tr>
+        <tr><td><code>setHMRTarget</code></td><td><code>(window: Window): void</code></td><td>Set the iframe <code>contentWindow</code> as the HMR update target. Call inside the iframe's <code>onload</code> handler.</td></tr>
+        <tr><td><code>handleRequest</code></td><td><code>(method, url, headers, body): Promise&lt;Response&gt;</code></td><td>Handle an HTTP request (used internally by the Service Worker bridge)</td></tr>
+      </tbody>
+    </table>
+
+    <h3>Events</h3>
+    <table>
+      <thead><tr><th>Event</th><th>Payload</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr><td><code>'hmr-update'</code></td><td><code>{ type: 'update' | 'full-reload', path: string, timestamp: number }</code></td><td>Fired when a VFS file changes. JS/CSS files get <code>'update'</code>, others get <code>'full-reload'</code>.</td></tr>
+        <tr><td><code>'listening'</code></td><td><code>port: number</code></td><td>Fired when <code>start()</code> is called</td></tr>
+      </tbody>
+    </table>
+
     <!-- ViteDevServer -->
     <h2>ViteDevServer</h2>
     <div class="method-sig">
       <span class="kw">new</span> <span class="fn">ViteDevServer</span>(<span class="ty">vfs</span>: VirtualFS)
     </div>
     <p>A virtual Vite dev server with React support, JSX/TSX transforms, npm module resolution, and HMR via React Refresh.</p>
     <p>Import from <code>almostnode/vite</code>.</p>
+    <p>Shares the same <code>start()</code>, <code>stop()</code>, <code>setHMRTarget()</code>, and <code>handleRequest()</code> methods as <code>NextDevServer</code>. Emits the same <code>'hmr-update'</code> event.</p>
 
     <!-- Utility -->
     <h2>Utility Functions</h2>

docs/core-concepts.html

@@ -45,6 +45,10 @@
       <a href="./nextjs-guide.html">Next.js</a>
       <a href="./vite-guide.html">Vite</a>
     </div>
+    <div class="sidebar-group">
+      <div class="sidebar-label">Tutorials</div>
+      <a href="./tutorial-editor.html">Editor + Preview</a>
+    </div>
     <div class="sidebar-group">
       <div class="sidebar-label">Reference</div>
       <a href="./api-reference.html">API Reference</a>

docs/index.html

@@ -45,6 +45,10 @@
       <a href="./nextjs-guide.html">Next.js</a>
       <a href="./vite-guide.html">Vite</a>
     </div>
+    <div class="sidebar-group">
+      <div class="sidebar-label">Tutorials</div>
+      <a href="./tutorial-editor.html">Editor + Preview</a>
+    </div>
     <div class="sidebar-group">
       <div class="sidebar-label">Reference</div>
       <a href="./api-reference.html">API Reference</a>
@@ -133,7 +137,7 @@ <h2>Comparison with WebContainers</h2>
         <th>almostnode</th>
         <th>WebContainers</th>
       </tr>
-      <tr><td>Bundle Size</td><td>~50KB</td><td>~2MB</td></tr>
+      <tr><td>Bundle Size</td><td>~250KB gzipped</td><td>~2MB</td></tr>
       <tr><td>Startup Time</td><td>Instant</td><td>2-5 seconds</td></tr>
       <tr><td>Execution Model</td><td>Main thread or Web Worker</td><td>Web Worker isolates</td></tr>
       <tr><td>Shell</td><td><code>just-bash</code> (POSIX subset)</td><td>Full Linux kernel</td></tr>
@@ -200,6 +204,7 @@ <h2>Next Steps</h2>
       <li><a href="./security.html">Security &amp; Sandbox</a> — cross-origin isolation, security modes, and service worker setup</li>
       <li><a href="./nextjs-guide.html">Next.js Guide</a> — run a full Next.js dev server with App Router, HMR, and CSS Modules</li>
       <li><a href="./vite-guide.html">Vite Guide</a> — set up Vite with React and hot module replacement</li>
+      <li><a href="./tutorial-editor.html">Tutorial: Editor + Preview</a> — build a file editor with live Next.js preview and cross-origin sandbox</li>
       <li><a href="./api-reference.html">API Reference</a> — full method signatures for every class and function</li>
     </ul>
 

docs/nextjs-guide.html

@@ -45,6 +45,10 @@
       <a href="./nextjs-guide.html" class="active">Next.js</a>
       <a href="./vite-guide.html">Vite</a>
     </div>
+    <div class="sidebar-group">
+      <div class="sidebar-label">Tutorials</div>
+      <a href="./tutorial-editor.html">Editor + Preview</a>
+    </div>
     <div class="sidebar-group">
       <div class="sidebar-label">Reference</div>
       <a href="./api-reference.html">API Reference</a>
@@ -181,20 +185,28 @@ <h2>CSS Modules</h2>
     <p>Classes are scoped with a hash to prevent collisions between components.</p>
 
     <h2>Hot Module Replacement</h2>
-    <p>The dev server supports HMR through React Refresh. When you change a file in the VFS, the server detects it and pushes updates to the browser without a full page reload:</p>
-    <pre><code><span class="cm">// Initial page</span>
-vfs<span class="op">.</span><span class="fn">writeFileSync</span><span class="op">(</span><span class="str">'/app/page.tsx'</span><span class="op">,</span> <span class="str">`
-  export default function Home() {
-    return &lt;h1&gt;Version 1&lt;/h1&gt;;
-  }
-`</span><span class="op">);</span>
-
-<span class="cm">// Later, update the file — HMR kicks in automatically</span>
+    <p>The dev server supports HMR through React Refresh. Two things are required for HMR to work:</p>
+    <ol>
+      <li>Call <code>devServer.start()</code> — this enables file watching on the VFS</li>
+      <li>Call <code>devServer.setHMRTarget(iframe.contentWindow)</code> — this tells the server where to send updates via <code>postMessage</code></li>
+    </ol>
+    <p>Once both are set up, writing to the VFS triggers HMR automatically:</p>
+    <pre><code><span class="kw">const</span> devServer <span class="op">=</span> <span class="kw">new</span> <span class="fn">NextDevServer</span><span class="op">(</span>vfs<span class="op">,</span> <span class="op">{</span> port<span class="op">:</span> <span class="num">3000</span><span class="op">,</span> root<span class="op">:</span> <span class="str">'/'</span> <span class="op">});</span>
+devServer<span class="op">.</span><span class="fn">start</span><span class="op">();</span> <span class="cm">// Required: enables file watching for HMR</span>
+
+<span class="cm">// After bridge setup and iframe load:</span>
+devServer<span class="op">.</span><span class="fn">setHMRTarget</span><span class="op">(</span>iframe<span class="op">.</span>contentWindow<span class="op">);</span> <span class="cm">// Required: HMR delivery target</span>
+
+<span class="cm">// Now updating a file triggers HMR automatically</span>
 vfs<span class="op">.</span><span class="fn">writeFileSync</span><span class="op">(</span><span class="str">'/app/page.tsx'</span><span class="op">,</span> <span class="str">`
   export default function Home() {
     return &lt;h1&gt;Version 2&lt;/h1&gt;;
   }
 `</span><span class="op">);</span></code></pre>
+    <div class="callout">
+      <div class="callout-title">Important</div>
+      <p>Without <code>devServer.start()</code>, the server won't watch the VFS for changes and HMR updates won't fire. This is the most common cause of HMR not working.</p>
+    </div>
 
     <h2>Configuration</h2>
     <p>You can provide a <code>next.config.js</code> for path aliases and other options:</p>

docs/security.html

@@ -45,6 +45,10 @@
       <a href="./nextjs-guide.html">Next.js</a>
       <a href="./vite-guide.html">Vite</a>
     </div>
+    <div class="sidebar-group">
+      <div class="sidebar-label">Tutorials</div>
+      <a href="./tutorial-editor.html">Editor + Preview</a>
+    </div>
     <div class="sidebar-group">
       <div class="sidebar-label">Reference</div>
       <a href="./api-reference.html">API Reference</a>