@vertz/ui-server 0.2.31 → 0.2.33

package/README.md

@@ -85,14 +85,14 @@ const html = await renderToHTML(App, {
 
 **Options:**
 
-| Option | Type | Description |
-|---|---|---|
-| `app` | `() => VNode` | App component function |
-| `url` | `string` | Request URL for SSR routing |
-| `theme` | `Theme` | Theme definition for CSS vars |
-| `styles` | `string[]` | Global CSS strings to inject |
-| `head` | `object` | Head config: `title`, `meta[]`, `links[]` |
-| `container` | `string` | Container selector (default `'#app'`) |
+| Option      | Type          | Description                               |
+| ----------- | ------------- | ----------------------------------------- |
+| `app`       | `() => VNode` | App component function                    |
+| `url`       | `string`      | Request URL for SSR routing               |
+| `theme`     | `Theme`       | Theme definition for CSS vars             |
+| `styles`    | `string[]`    | Global CSS strings to inject              |
+| `head`      | `object`      | Head config: `title`, `meta[]`, `links[]` |
+| `container` | `string`      | Container selector (default `'#app'`)     |
 
 ### `renderPage(vnode, options?)`
 
@@ -113,18 +113,18 @@ return renderPage(<App />, {
 
 **Options:**
 
-| Option | Type | Description |
-|---|---|---|
-| `status` | `number` | HTTP status code (default `200`) |
-| `title` | `string` | Page title |
-| `description` | `string` | Meta description |
-| `lang` | `string` | HTML lang attribute (default `'en'`) |
-| `favicon` | `string` | Favicon URL |
-| `og` | `object` | Open Graph: `title`, `description`, `image`, `url`, `type` |
-| `twitter` | `object` | Twitter card: `card`, `site` |
-| `scripts` | `string[]` | Script URLs for end of body |
-| `styles` | `string[]` | Stylesheet URLs for head |
-| `head` | `string` | Raw HTML escape hatch for head |
+| Option        | Type       | Description                                                |
+| ------------- | ---------- | ---------------------------------------------------------- |
+| `status`      | `number`   | HTTP status code (default `200`)                           |
+| `title`       | `string`   | Page title                                                 |
+| `description` | `string`   | Meta description                                           |
+| `lang`        | `string`   | HTML lang attribute (default `'en'`)                       |
+| `favicon`     | `string`   | Favicon URL                                                |
+| `og`          | `object`   | Open Graph: `title`, `description`, `image`, `url`, `type` |
+| `twitter`     | `object`   | Twitter card: `card`, `site`                               |
+| `scripts`     | `string[]` | Script URLs for end of body                                |
+| `styles`      | `string[]` | Stylesheet URLs for head                                   |
+| `head`        | `string`   | Raw HTML escape hatch for head                             |
 
 ### `renderToStream(tree, options?)`
 
@@ -148,6 +148,7 @@ return new Response(stream, {
 ```
 
 **Options:**
+
 - `nonce?: string` — CSP nonce for inline scripts
 
 ### `serializeToHtml(node)`
@@ -203,11 +204,11 @@ removeDomShim();
 
 **Note:** `renderToHTML` handles DOM shim setup and teardown automatically. You only need these when using lower-level rendering APIs.
 
-| Export | Description |
-|---|---|
+| Export             | Description                                  |
+| ------------------ | -------------------------------------------- |
 | `installDomShim()` | Install the minimal DOM shim on `globalThis` |
-| `removeDomShim()` | Remove the DOM shim from `globalThis` |
-| `toVNode(element)` | Convert an SSR element to a VNode |
+| `removeDomShim()`  | Remove the DOM shim from `globalThis`        |
+| `toVNode(element)` | Convert an SSR element to a VNode            |
 
 ---
 
@@ -228,6 +229,7 @@ const headHtml = renderHeadToHtml(headCollector.getEntries());
 ```
 
 **`HeadCollector` methods:**
+
 - `addTitle(text)` — Add a `<title>` tag
 - `addMeta(attrs)` — Add a `<meta>` tag
 - `addLink(attrs)` — Add a `<link>` tag
@@ -266,7 +268,9 @@ const hydratedNode = wrapWithHydrationMarkers(counterNode, {
 <div data-v-id="Counter" data-v-key="counter-0">
   <span>Count: 0</span>
   <button>+</button>
-  <script type="application/json">{"initial":0}</script>
+  <script type="application/json">
+    { "initial": 0 }
+  </script>
 </div>
 ```
 
@@ -363,24 +367,24 @@ await server.listen();
 
 **Options:**
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `entry` | `string` | (required) | Path to the SSR entry module |
-| `port` | `number` | `5173` | Port to listen on |
-| `host` | `string` | `'0.0.0.0'` | Host to bind to |
-| `viteConfig` | `InlineConfig` | `{}` | Custom Vite configuration |
-| `middleware` | `function` | — | Custom middleware before SSR handler |
-| `skipModuleInvalidation` | `boolean` | `false` | Skip invalidating modules on each request |
-| `logRequests` | `boolean` | `true` | Log requests to console |
+| Option                   | Type           | Default     | Description                               |
+| ------------------------ | -------------- | ----------- | ----------------------------------------- |
+| `entry`                  | `string`       | (required)  | Path to the SSR entry module              |
+| `port`                   | `number`       | `5173`      | Port to listen on                         |
+| `host`                   | `string`       | `'0.0.0.0'` | Host to bind to                           |
+| `viteConfig`             | `InlineConfig` | `{}`        | Custom Vite configuration                 |
+| `middleware`             | `function`     | —           | Custom middleware before SSR handler      |
+| `skipModuleInvalidation` | `boolean`      | `false`     | Skip invalidating modules on each request |
+| `logRequests`            | `boolean`      | `true`      | Log requests to console                   |
 
 **`DevServer` interface:**
 
-| Property/Method | Description |
-|---|---|
-| `listen()` | Start the server |
-| `close()` | Stop the server |
-| `vite` | The underlying `ViteDevServer` |
-| `httpServer` | The underlying `http.Server` |
+| Property/Method | Description                    |
+| --------------- | ------------------------------ |
+| `listen()`      | Start the server               |
+| `close()`       | Stop the server                |
+| `vite`          | The underlying `ViteDevServer` |
+| `httpServer`    | The underlying `http.Server`   |
 
 The entry module should export a `renderToString(url: string)` function that returns HTML.
 
@@ -390,11 +394,11 @@ The entry module should export a `renderToString(url: string)` function that ret
 
 The `@vertz/ui-server/jsx-runtime` subpath provides a server-side JSX factory that produces VNode trees compatible with `renderToStream`. During SSR, Vite's `ssrLoadModule` swaps this in automatically.
 
-| Export | Description |
-|---|---|
-| `jsx` | JSX factory for single-child elements |
-| `jsxs` | JSX factory for multi-child elements |
-| `Fragment` | Fragment component |
+| Export     | Description                           |
+| ---------- | ------------------------------------- |
+| `jsx`      | JSX factory for single-child elements |
+| `jsxs`     | JSX factory for multi-child elements  |
+| `Fragment` | Fragment component                    |
 
 ---
 
@@ -430,11 +434,11 @@ import type {
 
 ## Utilities
 
-| Export | Description |
-|---|---|
-| `streamToString(stream)` | Convert a `ReadableStream<Uint8Array>` to a string |
-| `collectStreamChunks(stream)` | Collect stream chunks as a `string[]` |
-| `encodeChunk(html)` | Encode a string to a `Uint8Array` chunk |
+| Export                        | Description                                        |
+| ----------------------------- | -------------------------------------------------- |
+| `streamToString(stream)`      | Convert a `ReadableStream<Uint8Array>` to a string |
+| `collectStreamChunks(stream)` | Collect stream chunks as a `string[]`              |
+| `encodeChunk(html)`           | Encode a string to a `Uint8Array` chunk            |
 
 ---
 

package/dist/bun-dev-server.d.ts

@@ -133,6 +133,19 @@ declare function isStaleGraphError(message: string): boolean;
 *   addEventListener("DOMContentLoaded",function(event){location.reload()})
 */
 declare function isReloadStub(text: string): boolean;
+/**
+* Determine whether the dev server should check for a stale dev bundler
+* (and potentially restart) after a file change.
+*
+* When the bundle hash changed, the dev bundler processed the update
+* successfully — HMR will deliver it. Checking for a reload stub would
+* race with Bun's internal update and produce false positives.
+*
+* When the hash did NOT change, the dev bundler may be stuck (e.g. new
+* file imported for the first time). The stale check is needed to detect
+* this and auto-restart.
+*/
+declare function shouldCheckStaleBundler(hashChanged: boolean): boolean;
 /** A resolved stack frame for terminal logging. */
 interface TerminalStackFrame {
 	functionName: string | null;
@@ -244,4 +257,4 @@ declare function clearSSRRequireCache(): number;
 * SSR is always on. HMR always works. No mode toggle needed.
 */
 declare function createBunDevServer(options: BunDevServerOptions): BunDevServer;
-export { parseHMRAssets, isStaleGraphError, isReloadStub, generateSSRPageHtml, formatTerminalRuntimeError, detectFaviconTag, createRuntimeErrorDeduplicator, createFetchInterceptor, createBunDevServer, clearSSRRequireCache, buildScriptTag, SSRPageHtmlOptions, HMRAssets, FetchInterceptorOptions, ErrorDetail, ErrorCategory, BunDevServerOptions, BunDevServer };
+export { shouldCheckStaleBundler, parseHMRAssets, isStaleGraphError, isReloadStub, generateSSRPageHtml, formatTerminalRuntimeError, detectFaviconTag, createRuntimeErrorDeduplicator, createFetchInterceptor, createBunDevServer, clearSSRRequireCache, buildScriptTag, SSRPageHtmlOptions, HMRAssets, FetchInterceptorOptions, ErrorDetail, ErrorCategory, BunDevServerOptions, BunDevServer };

package/dist/bun-dev-server.js

@@ -2556,6 +2556,9 @@ function isStaleGraphError(message) {
 function isReloadStub(text) {
   return text.trimStart().startsWith("try{location.reload()}");
 }
+function shouldCheckStaleBundler(hashChanged) {
+  return !hashChanged;
+}
 var MAX_TERMINAL_STACK_FRAMES = 5;
 function formatTerminalRuntimeError(errors, parsedStack) {
   const primary = errors[0];
@@ -2883,6 +2886,7 @@ var BUILD_ERROR_LOADER = [
   "fetch(src).then(function(r){return r.text()}).then(function(t){",
   "if(t.trimStart().startsWith('try{location.reload()}')){",
   "fetch('/__vertz_build_check').then(function(r){return r.json()}).then(function(j){",
+  `if(j.restarting){showOverlay('Restarting dev server','<p style="margin:0;color:#666;font-size:12px">Stale module graph detected. Restarting...</p>');sessionStorage.removeItem('__vertz_stub_retry');return}`,
   "if(j.errors&&j.errors.length>0){showOverlay('Build failed',formatErrors(j.errors),j)}",
   "else{var V2=window.__vertz_overlay;",
   "if(V2&&V2._autoRestart&&V2._canAutoRestart&&V2._canAutoRestart()){",
@@ -3045,6 +3049,7 @@ function createBunDevServer(options) {
       pendingRuntimeError = null;
     }
     clearGraceUntil = Date.now() + 5000;
+    autoRestartTimestamps.length = 0;
     const msg = JSON.stringify({ type: "clear" });
     for (const ws of wsClients) {
       ws.sendText(msg);
@@ -3061,6 +3066,7 @@ function createBunDevServer(options) {
       pendingRuntimeError = null;
     }
     clearGraceUntil = 0;
+    autoRestartTimestamps.length = 0;
     const msg = JSON.stringify({ type: "clear" });
     for (const ws of wsClients) {
       ws.sendText(msg);
@@ -3488,6 +3494,20 @@ if (import.meta.hot) import.meta.hot.accept();
             if (lastBuildError) {
               return Response.json({ errors: [{ message: lastBuildError }] });
             }
+            if (bundledScriptUrl && !isRestarting && canAutoRestart()) {
+              try {
+                const bundleRes = await fetch(`http://${host}:${server?.port}${bundledScriptUrl}`);
+                const bundleText = await bundleRes.text();
+                if (isReloadStub(bundleText)) {
+                  autoRestartTimestamps.push(Date.now());
+                  if (logRequests) {
+                    console.log("[Server] Build check: dev bundler stale \u2014 restarting");
+                  }
+                  devServer.restart();
+                  return Response.json({ errors: [], restarting: true });
+                }
+              } catch {}
+            }
             return Response.json({ errors: [] });
           } catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
@@ -3852,6 +3872,27 @@ data: {}
         console.warn("[Server] Could not discover HMR bundled URL:", e);
       }
     }
+    async function checkAndRestartIfBundlerStale() {
+      if (!bundledScriptUrl || !server || isRestarting)
+        return false;
+      try {
+        const bundleRes = await fetch(`http://${host}:${server.port}${bundledScriptUrl}`);
+        const bundleText = await bundleRes.text();
+        if (isReloadStub(bundleText)) {
+          if (canAutoRestart()) {
+            autoRestartTimestamps.push(Date.now());
+            if (logRequests) {
+              console.log("[Server] Dev bundler still serving reload stub after SSR recovery \u2014 restarting");
+            }
+            devServer.restart();
+            return true;
+          } else if (logRequests) {
+            console.log("[Server] Dev bundler stale but auto-restart cap reached");
+          }
+        }
+      } catch {}
+      return false;
+    }
     stopped = false;
     if (existsSync2(srcDir)) {
       srcWatcherRef = watch2(srcDir, { recursive: true }, (_event, filename) => {
@@ -3875,6 +3916,7 @@ data: {}
           await discoverHMRAssets();
           if (stopped)
             return;
+          let hashChanged = false;
           try {
             const clientRelative = rawClientSrc.replace(/^\//, "");
             const result = await Bun.build({
@@ -3906,10 +3948,12 @@ data: {}
                 if (stopped)
                   return;
                 await discoverHMRAssets();
-                if (bundledScriptUrl !== prevUrl)
+                if (bundledScriptUrl !== prevUrl) {
+                  hashChanged = true;
                   break;
+                }
               }
-              if (bundledScriptUrl && server && !isRestarting) {
+              if (!hashChanged && bundledScriptUrl && server && !isRestarting) {
                 try {
                   const bundleRes = await fetch(`http://${host}:${server.port}${bundledScriptUrl}`);
                   const bundleText = await bundleRes.text();
@@ -3927,7 +3971,6 @@ data: {}
                   }
                 } catch {}
               }
-              clearErrorForFileChange();
             }
           } catch {}
           if (stopped)
@@ -3977,8 +4020,10 @@ data: {}
               return;
             }
             if (logRequests) {
-              console.log("[Server] SSR in fallback mode \u2014 attempting re-import (best effort)");
+              console.log("[Server] SSR in fallback mode \u2014 restarting dev server");
             }
+            devServer.restart();
+            return;
           }
           const cacheCleared = clearSSRRequireCache();
           logger.log("watcher", "cache-cleared", { entries: cacheCleared });
@@ -4002,6 +4047,9 @@ data: {}
             if (logRequests) {
               console.log("[Server] SSR module refreshed");
             }
+            if (!hashChanged && await checkAndRestartIfBundlerStale())
+              return;
+            clearErrorForFileChange();
           } catch {
             logger.log("watcher", "ssr-reload", { status: "retry" });
             if (stopped)
@@ -4028,6 +4076,9 @@ data: {}
               if (logRequests) {
                 console.log("[Server] SSR module refreshed (retry)");
               }
+              if (!hashChanged && await checkAndRestartIfBundlerStale())
+                return;
+              clearErrorForFileChange();
             } catch (e2) {
               console.error("[Server] Failed to refresh SSR module:", e2);
               const errMsg = e2 instanceof Error ? e2.message : String(e2);
@@ -4138,6 +4189,7 @@ data: {}
   return devServer;
 }
 export {
+  shouldCheckStaleBundler,
   parseHMRAssets,
   isStaleGraphError,
   isReloadStub,