npm - @vertz/ui-server - Versions diffs - 0.2.47 → 0.2.49 - Mend

@vertz/ui-server 0.2.47 → 0.2.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/bun-dev-server.d.ts +35 -0
package/dist/bun-dev-server.js +58 -0
package/dist/bun-plugin/state-inspector.d.ts +59 -0
package/dist/bun-plugin/state-inspector.js +270 -0
package/dist/index.d.ts +24 -0
package/dist/index.js +23 -7
package/dist/node-handler.d.ts +22 -0
package/dist/node-handler.js +2 -2
package/dist/shared/{chunk-kzycr5v0.js → chunk-1hjzk64k.js} +31 -10
package/dist/shared/{chunk-ck3n699k.js → chunk-91eg6dps.js} +34 -7
package/dist/shared/{chunk-tm5aeq94.js → chunk-j9z9r179.js} +38 -4
package/dist/ssr/index.d.ts +22 -0
package/dist/ssr/index.js +2 -2
package/package.json +9 -5

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

@@ -1,3 +1,32 @@
+interface QuerySnapshot {
+	data: SerializedValue;
+	loading: boolean;
+	revalidating: boolean;
+	error: SerializedValue;
+	idle: boolean;
+	key?: string;
+}
+interface InstanceSnapshot {
+	index: number;
+	key?: string;
+	signals: Record<string, SerializedValue>;
+	queries: Record<string, QuerySnapshot>;
+}
+interface ComponentSnapshot {
+	name: string;
+	moduleId: string;
+	instanceCount: number;
+	instances: InstanceSnapshot[];
+}
+interface StateSnapshot {
+	components: ComponentSnapshot[];
+	totalInstances: number;
+	connectedClients: number;
+	timestamp: string;
+	message?: string;
+	truncated?: boolean;
+}
+type SerializedValue = string | number | boolean | null | object;
 import { AccessSet } from "@vertz/ui/auth";
 interface SessionData {
 	user: {
@@ -198,6 +227,12 @@ interface BunDevServer {
 	clearErrorForFileChange(): void;
 	/** Set the last changed file path (for testing). */
 	setLastChangedFile(file: string): void;
+	/**
+	* Request a state inspection from connected browser clients.
+	* Broadcasts an `inspect-state` command and waits for the first
+	* `state-snapshot` response. Returns the snapshot JSON or an error.
+	*/
+	inspectState(filter?: string): Promise<StateSnapshot>;
 }
 interface HMRAssets {
 	/** Discovered `/_bun/client/<hash>.js` URL, or null if not found */

package/dist/bun-dev-server.js CHANGED Viewed

@@ -3632,6 +3632,7 @@ function createBunDevServer(options) {
   let ssrFallback = false;
   const wsClients = new Set;
   let currentError = null;
+  const pendingInspections = new Map;
   const sourceMapResolver = createSourceMapResolver(projectRoot);
   let clearGraceUntil = 0;
   let runtimeDebounceTimer = null;
@@ -4098,6 +4099,10 @@ function createBunDevServer(options) {
     const frInitPath = resolve(devDir, "fast-refresh-init.ts");
     writeFileSync3(frInitPath, `import '@vertz/ui-server/fast-refresh-runtime';
 if (import.meta.hot) import.meta.hot.accept();
+`);
+    const siInitPath = resolve(devDir, "state-inspector-init.ts");
+    writeFileSync3(siInitPath, `import '@vertz/ui-server/state-inspector';
+if (import.meta.hot) import.meta.hot.accept();
 `);
     const hmrShellHtml = `<!doctype html>
 <html lang="en"><head>
@@ -4105,6 +4110,7 @@ if (import.meta.hot) import.meta.hot.accept();
   <title>HMR Shell</title>
 </head><body>
   <script type="module" src="./fast-refresh-init.ts"></script>
+  <script type="module" src="./state-inspector-init.ts"></script>
   <script type="module" src="${clientSrc}"></script>
 </body></html>`;
     const hmrShellPath = resolve(devDir, "hmr-shell.html");
@@ -4431,6 +4437,13 @@ data: {}
               devServer.restart();
             } else if (data.type === "ping") {
               ws.sendText(JSON.stringify({ type: "pong" }));
+            } else if (data.type === "state-snapshot" && data.requestId) {
+              const pending = pendingInspections.get(data.requestId);
+              if (pending) {
+                clearTimeout(pending.timer);
+                pendingInspections.delete(data.requestId);
+                pending.resolve(data.snapshot);
+              }
             } else if (data.type === "resolve-stack" && data.stack) {
               const selfFetch = async (url) => {
                 const absUrl = url.startsWith("http") ? url : `http://${host}:${server?.port}${url}`;
@@ -4803,8 +4816,53 @@ data: {}
     setLastChangedFile(file) {
       lastChangedFile = file;
     },
+    async inspectState(filter) {
+      if (wsClients.size === 0) {
+        return {
+          components: [],
+          totalInstances: 0,
+          connectedClients: 0,
+          timestamp: new Date().toISOString(),
+          message: "No browser clients connected. Open the app in a browser first."
+        };
+      }
+      const requestId = crypto.randomUUID();
+      const TIMEOUT_MS = 5000;
+      return new Promise((resolve2) => {
+        const timer = setTimeout(() => {
+          pendingInspections.delete(requestId);
+          resolve2({
+            components: [],
+            totalInstances: 0,
+            connectedClients: wsClients.size,
+            timestamp: new Date().toISOString(),
+            message: "State inspection timed out after 5 seconds."
+          });
+        }, TIMEOUT_MS);
+        pendingInspections.set(requestId, { resolve: resolve2, timer });
+        const cmd = JSON.stringify({
+          type: "inspect-state",
+          requestId,
+          ...filter ? { filter } : {}
+        });
+        for (const client of wsClients) {
+          client.sendText(cmd);
+        }
+      });
+    },
     async stop() {
       stopped = true;
+      for (const [, { resolve: res, timer }] of pendingInspections) {
+        clearTimeout(timer);
+        res({
+          components: [],
+          totalInstances: 0,
+          connectedClients: 0,
+          timestamp: new Date().toISOString(),
+          message: "Server stopped."
+        });
+      }
+      pendingInspections.clear();
       if (refreshTimeout) {
         clearTimeout(refreshTimeout);
         refreshTimeout = null;

package/dist/bun-plugin/state-inspector.d.ts ADDED Viewed

@@ -0,0 +1,59 @@
+interface QuerySnapshot {
+	data: SerializedValue;
+	loading: boolean;
+	revalidating: boolean;
+	error: SerializedValue;
+	idle: boolean;
+	key?: string;
+}
+interface InstanceSnapshot {
+	index: number;
+	key?: string;
+	signals: Record<string, SerializedValue>;
+	queries: Record<string, QuerySnapshot>;
+}
+interface ComponentSnapshot {
+	name: string;
+	moduleId: string;
+	instanceCount: number;
+	instances: InstanceSnapshot[];
+}
+interface StateSnapshot {
+	components: ComponentSnapshot[];
+	totalInstances: number;
+	connectedClients: number;
+	timestamp: string;
+	message?: string;
+	truncated?: boolean;
+}
+type SerializedValue = string | number | boolean | null | object;
+/**
+* Serialize any JavaScript value to a JSON-safe representation.
+* Handles functions, DOM nodes, circular references, Date, Map, Set,
+* Error, Promise, Symbol, WeakRef, ArrayBuffer, and depth limiting.
+*/
+declare function safeSerialize(value: unknown, maxDepth?: number, seen?: WeakSet<object>): SerializedValue;
+/**
+* Walk the Fast Refresh registry and collect a state snapshot.
+* Optionally filter by component function name (case-sensitive).
+*/
+declare function collectStateSnapshot(filter?: string): StateSnapshot;
+/**
+* Handle incoming `inspect-state` WebSocket messages.
+* Collects a state snapshot and sends it back with the matching requestId.
+*/
+declare function handleInspectMessage(event: MessageEvent, ws: WebSocket): void;
+/**
+* Set up the state inspector's WebSocket listener.
+*
+* Uses `addEventListener` instead of replacing `onmessage` to coexist with
+* the error overlay handler. Polls for `__vertz_overlay._ws` reference changes
+* so that reconnections (which create a new WebSocket instance) are re-hooked.
+*
+* NOTE: When multiple browser tabs are connected, the server broadcasts
+* inspect-state to all. The first response wins — other tabs' responses are
+* dropped. This is acceptable for v0.1.x; a future improvement could merge
+* responses from multiple tabs.
+*/
+declare function setupStateInspector(): void;
+export { setupStateInspector, safeSerialize, handleInspectMessage, collectStateSnapshot, StateSnapshot, QuerySnapshot, InstanceSnapshot, ComponentSnapshot };

package/dist/bun-plugin/state-inspector.js ADDED Viewed

@@ -0,0 +1,270 @@
+// @bun
+import"../shared/chunk-pshsm7ck.js";
+// src/bun-plugin/state-inspector.ts
+var REGISTRY_KEY = Symbol.for("vertz:fast-refresh:registry");
+var MAX_RESPONSE_SIZE = 2 * 1024 * 1024;
+var DEFAULT_MAX_DEPTH = 4;
+var QUERY_SIGNAL_NAMES = ["data", "loading", "revalidating", "error", "idle"];
+function safeSerialize(value, maxDepth = DEFAULT_MAX_DEPTH, seen = new WeakSet) {
+  if (value === null)
+    return null;
+  if (value === undefined)
+    return null;
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "number") {
+    if (Number.isNaN(value))
+      return "[NaN]";
+    if (!Number.isFinite(value))
+      return value > 0 ? "[Infinity]" : "[-Infinity]";
+    return value;
+  }
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "bigint")
+    return value.toString();
+  if (typeof value === "symbol") {
+    const desc = value.description;
+    return desc ? `[Symbol: ${desc}]` : "[Symbol]";
+  }
+  if (typeof value === "function") {
+    const name = value.name;
+    return name && name !== "anonymous" ? `[Function: ${name}]` : "[Function]";
+  }
+  const obj = value;
+  if (seen.has(obj))
+    return "[Circular]";
+  if (obj instanceof Date)
+    return obj.toISOString();
+  if (obj instanceof Error) {
+    return { name: obj.name, message: obj.message };
+  }
+  if (obj instanceof Promise)
+    return "[Promise]";
+  if (obj instanceof Map)
+    return `[Map: ${obj.size} entries]`;
+  if (obj instanceof Set)
+    return `[Set: ${obj.size} items]`;
+  if (obj instanceof WeakMap)
+    return "[WeakMap]";
+  if (obj instanceof WeakSet)
+    return "[WeakSet]";
+  if (typeof WeakRef !== "undefined" && obj instanceof WeakRef)
+    return "[WeakRef]";
+  if (obj instanceof ArrayBuffer)
+    return `[ArrayBuffer: ${obj.byteLength} bytes]`;
+  if (ArrayBuffer.isView(obj) && "byteLength" in obj) {
+    return `[ArrayBuffer: ${obj.byteLength} bytes]`;
+  }
+  if (typeof HTMLElement !== "undefined" && obj instanceof HTMLElement) {
+    return `[HTMLElement: ${obj.tagName}]`;
+  }
+  if (typeof Node !== "undefined" && obj instanceof Node) {
+    return `[Node: ${obj.nodeName}]`;
+  }
+  if (maxDepth <= 0) {
+    if (Array.isArray(obj))
+      return `[Array: ${obj.length} items]`;
+    return `[Object: ${Object.keys(obj).length} keys]`;
+  }
+  seen.add(obj);
+  if (Array.isArray(obj)) {
+    const result2 = obj.map((item) => safeSerialize(item, maxDepth - 1, seen));
+    seen.delete(obj);
+    return result2;
+  }
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    result[key] = safeSerialize(obj[key], maxDepth - 1, seen);
+  }
+  seen.delete(obj);
+  return result;
+}
+function peekSafe(sig) {
+  try {
+    return sig.peek();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return `[Error: ${msg}]`;
+  }
+}
+function collectStateSnapshot(filter) {
+  const registry = globalThis[REGISTRY_KEY];
+  if (!registry || registry.size === 0) {
+    return emptySnapshot(filter ? `${filter} is not in the component registry. Check the name spelling or ensure the file has been loaded.` : undefined);
+  }
+  const components = [];
+  let totalInstances = 0;
+  let foundInRegistry = false;
+  for (const [moduleId, moduleMap] of registry) {
+    for (const [name, record] of moduleMap) {
+      if (filter && name !== filter)
+        continue;
+      if (filter)
+        foundInRegistry = true;
+      const instances = [];
+      for (let i = 0;i < record.instances.length; i++) {
+        const inst = record.instances[i];
+        if (!inst.element?.isConnected)
+          continue;
+        const signals = {};
+        const queries = {};
+        const queryGroups = new Map;
+        const standaloneSignals = [];
+        for (const sig of inst.signals) {
+          const group = sig._queryGroup;
+          if (group) {
+            if (!queryGroups.has(group))
+              queryGroups.set(group, []);
+            queryGroups.get(group).push(sig);
+          } else {
+            standaloneSignals.push(sig);
+          }
+        }
+        let positionalIdx = 0;
+        for (const sig of standaloneSignals) {
+          const key = sig._hmrKey ?? `signal_${positionalIdx++}`;
+          signals[key] = safeSerialize(peekSafe(sig));
+        }
+        for (const [groupKey, groupSignals] of queryGroups) {
+          queries[groupKey] = buildQuerySnapshot(groupSignals, groupKey);
+        }
+        instances.push({ index: i, signals, queries });
+        totalInstances++;
+      }
+      if (instances.length > 0) {
+        components.push({ name, moduleId, instanceCount: instances.length, instances });
+      } else if (filter && foundInRegistry) {}
+    }
+  }
+  let message;
+  if (filter && components.length === 0) {
+    if (foundInRegistry) {
+      let moduleId = "";
+      for (const [mid, moduleMap] of registry) {
+        if (moduleMap.has(filter)) {
+          moduleId = mid;
+          break;
+        }
+      }
+      message = `${filter} is registered (in ${moduleId}) but has 0 mounted instances on the current page. Navigate to a page that renders it.`;
+    } else {
+      message = `${filter} is not in the component registry. Check the name spelling or ensure the file has been loaded.`;
+    }
+  }
+  const snapshot = {
+    components,
+    totalInstances,
+    connectedClients: 0,
+    timestamp: new Date().toISOString(),
+    ...message ? { message } : {}
+  };
+  const jsonStr = JSON.stringify(snapshot);
+  if (jsonStr.length > MAX_RESPONSE_SIZE) {
+    return truncateSnapshot(snapshot);
+  }
+  return snapshot;
+}
+function emptySnapshot(message) {
+  return {
+    components: [],
+    totalInstances: 0,
+    connectedClients: 0,
+    timestamp: new Date().toISOString(),
+    ...message ? { message } : {}
+  };
+}
+function buildQuerySnapshot(signals, groupKey) {
+  const named = new Map;
+  const unnamed = [];
+  for (const sig of signals) {
+    const val = peekSafe(sig);
+    if (sig._hmrKey && QUERY_SIGNAL_NAMES.includes(sig._hmrKey)) {
+      named.set(sig._hmrKey, val);
+    } else {
+      unnamed.push(val);
+    }
+  }
+  return {
+    data: safeSerialize(named.get("data") ?? unnamed[0] ?? null),
+    loading: Boolean(named.get("loading") ?? unnamed[1] ?? false),
+    revalidating: Boolean(named.get("revalidating") ?? unnamed[2] ?? false),
+    error: safeSerialize(named.get("error") ?? unnamed[3] ?? null),
+    idle: Boolean(named.get("idle") ?? unnamed[4] ?? false),
+    key: groupKey
+  };
+}
+function handleInspectMessage(event, ws) {
+  if (typeof event.data !== "string")
+    return;
+  try {
+    const msg = JSON.parse(event.data);
+    if (msg.type === "inspect-state") {
+      const snapshot = collectStateSnapshot(msg.filter ?? undefined);
+      ws.send(JSON.stringify({
+        type: "state-snapshot",
+        requestId: msg.requestId,
+        snapshot
+      }));
+    }
+  } catch {}
+}
+function setupStateInspector() {
+  if (typeof window === "undefined")
+    return;
+  let currentWs = null;
+  const MAX_INIT_RETRIES = 10;
+  let initRetries = 0;
+  function hookWs(ws) {
+    if (ws === currentWs)
+      return;
+    currentWs = ws;
+    ws.addEventListener("message", (event) => {
+      handleInspectMessage(event, ws);
+    });
+  }
+  function poll() {
+    const overlay = window.__vertz_overlay;
+    if (!overlay) {
+      if (initRetries++ < MAX_INIT_RETRIES) {
+        setTimeout(poll, 500);
+      }
+      return;
+    }
+    const checkWs = () => {
+      if (overlay._ws && overlay._ws !== currentWs) {
+        hookWs(overlay._ws);
+      }
+    };
+    checkWs();
+    setInterval(checkWs, 2000);
+  }
+  poll();
+}
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", setupStateInspector);
+  } else {
+    setupStateInspector();
+  }
+}
+function truncateSnapshot(snapshot) {
+  const truncated = {
+    ...snapshot,
+    truncated: true,
+    components: snapshot.components.map((comp) => ({
+      ...comp,
+      instances: comp.instances.slice(0, 3),
+      instanceCount: comp.instanceCount
+    }))
+  };
+  truncated.totalInstances = truncated.components.reduce((sum, c) => sum + c.instances.length, 0);
+  return truncated;
+}
+export {
+  setupStateInspector,
+  safeSerialize,
+  handleInspectMessage,
+  collectStateSnapshot
+};

package/dist/index.d.ts CHANGED Viewed

@@ -536,6 +536,28 @@ interface SSRHandlerOptions {
 	* (JSON files, third-party APIs, custom DB clients).
 	*/
 	aotDataResolver?: AotDataResolver;
+	/**
+	* Derive attributes to set on the `<html>` tag from the incoming request.
+	*
+	* Useful for setting `data-theme`, `dir`, `lang`, or other attributes that
+	* must be on `<html>` to avoid FOUC. The callback runs before SSR rendering
+	* so the attributes are available in the first byte of the response.
+	*
+	* If the template already has an attribute with the same name, the callback's
+	* value overrides it. Values are HTML-escaped automatically. Keys must be
+	* valid HTML attribute names (`/^[a-zA-Z][a-zA-Z0-9-]*$/`).
+	*
+	* Return `undefined`, `null`, or `{}` to skip injection.
+	*
+	* @example
+	* ```ts
+	* htmlAttributes: (request) => ({
+	*   'data-theme': getThemeCookie(request) ?? 'dark',
+	*   dir: getDirection(request),
+	* })
+	* ```
+	*/
+	htmlAttributes?: (request: Request) => Record<string, string> | null | undefined;
 }
 declare function createSSRHandler(options: SSRHandlerOptions): (request: Request) => Promise<Response>;
 type NodeHandlerOptions = SSRHandlerOptions;
@@ -741,6 +763,8 @@ interface AotBarrelResult {
 	* Write each entry as `<tempDir>/<filename>.ts` alongside the barrel.
 	*/
 	files: Record<string, string>;
+	/** Function names skipped due to residual JSX in compiled output. */
+	skippedFns: string[];
 }
 /**
 * Generate a barrel module that re-exports __ssr_* functions from compiled files.

package/dist/index.js CHANGED Viewed

@@ -1,10 +1,10 @@
 import {
   createSSRHandler,
   loadAotManifest
-} from "./shared/chunk-ck3n699k.js";
+} from "./shared/chunk-91eg6dps.js";
 import {
   createNodeHandler
-} from "./shared/chunk-kzycr5v0.js";
+} from "./shared/chunk-1hjzk64k.js";
 import {
   clearRouteCssCache,
   collectStreamChunks,
@@ -34,7 +34,7 @@ import {
   ssrStreamNavQueries,
   streamToString,
   toPrefetchSession
-} from "./shared/chunk-tm5aeq94.js";
+} from "./shared/chunk-j9z9r179.js";
 import {
   clearGlobalSSRTimeout,
   createSSRAdapter,
@@ -171578,26 +171578,39 @@ function generateAotBarrel(compiledFiles, routeMap, appEntry) {
     "import { __esc, __esc_attr, __ssr_spread, __ssr_style_object } from '@vertz/ui-server';"
   ];
   const files = {};
+  const skippedFns = [];
   let fileIndex = 0;
   for (const [filePath, fns] of fileToFns) {
     const moduleName = basename(filePath, ".tsx").replace(/[^a-zA-Z0-9_-]/g, "_");
     const tempFileName = `__aot_${fileIndex}_${moduleName}`;
     const moduleRef = `./${tempFileName}.ts`;
-    lines.push(`export { ${fns.sort().join(", ")} } from '${moduleRef}';`);
     const compiled = compiledFiles[filePath];
     if (compiled) {
       const helperImport = `import { __esc, __esc_attr, __ssr_spread, __ssr_style_object } from '@vertz/ui-server';
 ` + `import type { SSRAotContext } from '@vertz/ui-server';
 `;
-      const extracted = extractSsrFunctions(compiled.code, fns);
-      files[`${tempFileName}.ts`] = helperImport + extracted;
+      const cleanFns = [];
+      for (const fn of fns) {
+        const fnCode = extractSsrFunctions(compiled.code, [fn]);
+        if (hasResidualJsx(fnCode)) {
+          skippedFns.push(fn);
+        } else {
+          cleanFns.push(fn);
+        }
+      }
+      if (cleanFns.length > 0) {
+        const extracted = extractSsrFunctions(compiled.code, cleanFns);
+        lines.push(`export { ${cleanFns.sort().join(", ")} } from '${moduleRef}';`);
+        files[`${tempFileName}.ts`] = helperImport + extracted;
+      }
     }
     fileIndex++;
   }
   return {
     barrelSource: lines.join(`
 `),
-    files
+    files,
+    skippedFns
   };
 }
 function extractSsrFunctions(code, fnNames) {
@@ -171624,6 +171637,9 @@ function extractSsrFunctions(code, fnNames) {
   return extracted.join(`
 `);
 }
+function hasResidualJsx(code) {
+  return /<[A-Za-z]\w*\s+[\w-]+=\{/.test(code);
+}
 function findAppComponent(components) {
   for (const [name, comp] of Object.entries(components)) {
     if (comp.tier === "runtime-fallback")

package/dist/node-handler.d.ts CHANGED Viewed

@@ -261,6 +261,28 @@ interface SSRHandlerOptions {
 	* (JSON files, third-party APIs, custom DB clients).
 	*/
 	aotDataResolver?: AotDataResolver;
+	/**
+	* Derive attributes to set on the `<html>` tag from the incoming request.
+	*
+	* Useful for setting `data-theme`, `dir`, `lang`, or other attributes that
+	* must be on `<html>` to avoid FOUC. The callback runs before SSR rendering
+	* so the attributes are available in the first byte of the response.
+	*
+	* If the template already has an attribute with the same name, the callback's
+	* value overrides it. Values are HTML-escaped automatically. Keys must be
+	* valid HTML attribute names (`/^[a-zA-Z][a-zA-Z0-9-]*$/`).
+	*
+	* Return `undefined`, `null`, or `{}` to skip injection.
+	*
+	* @example
+	* ```ts
+	* htmlAttributes: (request) => ({
+	*   'data-theme': getThemeCookie(request) ?? 'dark',
+	*   dir: getDirection(request),
+	* })
+	* ```
+	*/
+	htmlAttributes?: (request: Request) => Record<string, string> | null | undefined;
 }
 type NodeHandlerOptions = SSRHandlerOptions;
 declare function createNodeHandler(options: NodeHandlerOptions): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/node-handler.js CHANGED Viewed

@@ -1,7 +1,7 @@
 import {
   createNodeHandler
-} from "./shared/chunk-kzycr5v0.js";
-import"./shared/chunk-tm5aeq94.js";
+} from "./shared/chunk-1hjzk64k.js";
+import"./shared/chunk-j9z9r179.js";
 import"./shared/chunk-szvdd1qq.js";
 import"./shared/chunk-bt1px3c4.js";
 export {

package/dist/shared/{chunk-kzycr5v0.js → chunk-1hjzk64k.js} RENAMED Viewed

@@ -1,5 +1,6 @@
 import {
   escapeAttr,
+  injectHtmlAttributes,
   injectIntoTemplate,
   precomputeHandlerState,
   resolveRouteModulepreload,
@@ -10,7 +11,7 @@ import {
   ssrRenderSinglePass,
   ssrStreamNavQueries,
   toPrefetchSession
-} from "./chunk-tm5aeq94.js";
+} from "./chunk-j9z9r179.js";
 // src/node-handler.ts
 function createNodeHandler(options) {
@@ -25,7 +26,8 @@ function createNodeHandler(options) {
     manifest,
     progressiveHTML,
     aotManifest,
-    aotDataResolver
+    aotDataResolver,
+    htmlAttributes
   } = options;
   const { template, linkHeader, modulepreloadTags, splitResult } = precomputeHandlerState(options);
   const useProgressive = progressiveHTML && splitResult && !(manifest?.routeEntries && Object.keys(manifest.routeEntries).length > 0);
@@ -38,20 +40,37 @@ function createNodeHandler(options) {
           await handleNavRequest(req, res, module, pathname, ssrTimeout);
           return;
         }
-        let sessionScript = "";
-        let ssrAuth;
-        if (sessionResolver) {
+        let webRequest;
+        if (sessionResolver || htmlAttributes) {
           const fullUrl = `http://${req.headers.host ?? "localhost"}${url}`;
-          const webRequest = new Request(fullUrl, {
+          webRequest = new Request(fullUrl, {
             method: req.method ?? "GET",
             headers: req.headers
           });
+        }
+        let sessionScript = "";
+        let ssrAuth;
+        if (sessionResolver && webRequest) {
           const result2 = await resolveSession(webRequest, sessionResolver, nonce);
           sessionScript = result2.sessionScript;
           ssrAuth = result2.ssrAuth;
         }
+        let requestTemplate = template;
+        let requestHeadTemplate = splitResult?.headTemplate;
+        if (htmlAttributes && webRequest) {
+          const attrs = htmlAttributes(webRequest);
+          if (attrs && Object.keys(attrs).length > 0) {
+            requestTemplate = injectHtmlAttributes(template, attrs);
+            if (requestHeadTemplate) {
+              requestHeadTemplate = injectHtmlAttributes(requestHeadTemplate, attrs);
+            }
+          }
+        }
         if (useProgressive) {
-          await handleProgressiveRequest(req, res, module, splitResult, url, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest);
+          await handleProgressiveRequest(req, res, module, {
+            headTemplate: requestHeadTemplate ?? splitResult.headTemplate,
+            tailTemplate: splitResult.tailTemplate
+          }, url, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest);
           return;
         }
         const prefetchSession = ssrAuth ? toPrefetchSession(ssrAuth) : undefined;
@@ -79,7 +98,7 @@ function createNodeHandler(options) {
         const allHeadTags = [result.headTags, resolvedModulepreloadTags].filter(Boolean).join(`
 `);
         const html = injectIntoTemplate({
-          template,
+          template: requestTemplate,
           appHtml: result.html,
           appCss: result.css,
           ssrData: result.ssrData,
@@ -94,7 +113,8 @@ function createNodeHandler(options) {
           headers.Link = linkHeader;
         if (cacheControl)
           headers["Cache-Control"] = cacheControl;
-        res.writeHead(200, headers);
+        const status = result.matchedRoutePatterns?.length ? 200 : 404;
+        res.writeHead(status, headers);
         res.end(html);
       } catch (err) {
         console.error("[SSR] Render failed:", err instanceof Error ? err.message : err);
@@ -153,7 +173,8 @@ async function handleProgressiveRequest(req, res, module, split, url, ssrTimeout
     headers.Link = linkHeader;
   if (cacheControl)
     headers["Cache-Control"] = cacheControl;
-  res.writeHead(200, headers);
+  const status = result.matchedRoutePatterns?.length ? 200 : 404;
+  res.writeHead(status, headers);
   res.write(headChunk);
   let clientDisconnected = false;
   req.on("close", () => {

package/dist/shared/{chunk-ck3n699k.js → chunk-91eg6dps.js} RENAMED Viewed

@@ -1,6 +1,7 @@
 import {
   encodeChunk,
   escapeAttr,
+  injectHtmlAttributes,
   injectIntoTemplate,
   precomputeHandlerState,
   resolveRouteModulepreload,
@@ -11,7 +12,7 @@ import {
   ssrRenderSinglePass,
   ssrStreamNavQueries,
   toPrefetchSession
-} from "./chunk-tm5aeq94.js";
+} from "./chunk-j9z9r179.js";
 // src/aot-manifest-loader.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -108,7 +109,7 @@ function buildProgressiveResponse(options) {
     "Content-Type": "text/html; charset=utf-8",
     ...headers
   };
-  return new Response(stream, { status: 200, headers: responseHeaders });
+  return new Response(stream, { status: options.status ?? 200, headers: responseHeaders });
 }
 // src/ssr-handler.ts
@@ -124,7 +125,8 @@ function createSSRHandler(options) {
     manifest,
     progressiveHTML,
     aotManifest,
-    aotDataResolver
+    aotDataResolver,
+    htmlAttributes
   } = options;
   const { template, linkHeader, modulepreloadTags, splitResult } = precomputeHandlerState(options);
   return async (request) => {
@@ -141,11 +143,33 @@ function createSSRHandler(options) {
       ssrAuth = result.ssrAuth;
     }
     const cookies = request.headers.get("Cookie") ?? undefined;
+    let requestTemplate = template;
+    let requestHeadTemplate = splitResult?.headTemplate;
+    if (htmlAttributes) {
+      try {
+        const attrs = htmlAttributes(request);
+        if (attrs && Object.keys(attrs).length > 0) {
+          requestTemplate = injectHtmlAttributes(template, attrs);
+          if (requestHeadTemplate) {
+            requestHeadTemplate = injectHtmlAttributes(requestHeadTemplate, attrs);
+          }
+        }
+      } catch (err) {
+        console.error("[SSR] htmlAttributes failed:", err instanceof Error ? err.message : err);
+        return new Response("Internal Server Error", {
+          status: 500,
+          headers: { "Content-Type": "text/plain" }
+        });
+      }
+    }
     const useProgressive = progressiveHTML && splitResult && !(manifest?.routeEntries && Object.keys(manifest.routeEntries).length > 0);
     if (useProgressive) {
-      return handleProgressiveHTMLRequest(module, splitResult, pathname + url.search, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest, cookies);
+      return handleProgressiveHTMLRequest(module, {
+        headTemplate: requestHeadTemplate ?? splitResult.headTemplate,
+        tailTemplate: splitResult.tailTemplate
+      }, pathname + url.search, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest, cookies);
     }
-    return handleHTMLRequest(module, template, pathname + url.search, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest, aotManifest, aotDataResolver, cookies);
+    return handleHTMLRequest(module, requestTemplate, pathname + url.search, ssrTimeout, nonce, fallbackMetrics, linkHeader, modulepreloadTags, routeChunkManifest, cacheControl, sessionScript, ssrAuth, manifest, aotManifest, aotDataResolver, cookies);
   };
 }
 async function handleNavRequest(module, url, ssrTimeout) {
@@ -219,13 +243,15 @@ async function handleProgressiveHTMLRequest(module, split, url, ssrTimeout, nonc
       headers.Link = linkHeader;
     if (cacheControl)
       headers["Cache-Control"] = cacheControl;
+    const status = result.matchedRoutePatterns?.length ? 200 : 404;
     return buildProgressiveResponse({
       headChunk,
       renderStream: result.renderStream,
       tailChunk: split.tailTemplate,
       ssrData: result.ssrData,
       nonce,
-      headers
+      headers,
+      status
     });
   } catch (err) {
     console.error("[SSR] Render failed:", err instanceof Error ? err.message : err);
@@ -278,7 +304,8 @@ async function handleHTMLRequest(module, template, url, ssrTimeout, nonce, fallb
       headers.Link = linkHeader;
     if (cacheControl)
       headers["Cache-Control"] = cacheControl;
-    return new Response(html, { status: 200, headers });
+    const status = result.matchedRoutePatterns?.length ? 200 : 404;
+    return new Response(html, { status, headers });
   } catch (err) {
     console.error("[SSR] Render failed:", err instanceof Error ? err.message : err);
     return new Response("Internal Server Error", {

package/dist/shared/{chunk-tm5aeq94.js → chunk-j9z9r179.js} RENAMED Viewed

@@ -1050,9 +1050,10 @@ async function ssrRenderAot(module, url, options) {
   try {
     setGlobalSSRTimeout(ssrTimeout);
     const holes = createHoles(aotEntry.holes, module, normalizedUrl, queryCache, options.ssrAuth);
+    const resolveKey = (key) => key.includes("${") ? resolveParamQueryKeys([key], match.params, searchParams)[0] : key;
     const ctx = {
       holes,
-      getData: (key) => queryCache.get(key),
+      getData: (key) => queryCache.get(resolveKey(key)),
       session: options.prefetchSession,
       params: match.params,
       searchParams
@@ -1075,7 +1076,7 @@ async function ssrRenderAot(module, url, options) {
         appHoles.RouterView = () => html;
         const appCtx = {
           holes: appHoles,
-          getData: (key) => queryCache.get(key),
+          getData: (key) => queryCache.get(resolveKey(key)),
           session: options.prefetchSession,
           params: match.params,
           searchParams
@@ -1158,7 +1159,7 @@ function resolveParamQueryKeys(queryKeys, params, searchParams) {
       return value || defaultVal;
     }
     return value ?? "";
-  }).replace(/\$\{(\w+)\}/g, (_, paramName) => params[paramName] ?? ""));
+  }).replace(/\$\{(\w+)\}/g, (_, paramName) => params[paramName] ?? searchParams?.get(paramName) ?? ""));
 }
 function extractSearchParams(url) {
   const qIdx = url.indexOf("?");
@@ -1461,6 +1462,39 @@ async function resolveSession(request, sessionResolver, nonce) {
 }
 // src/template-inject.ts
+var VALID_ATTR_KEY = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+function injectHtmlAttributes(template, attrs) {
+  const entries = Object.entries(attrs);
+  if (entries.length === 0)
+    return template;
+  for (const [key] of entries) {
+    if (!VALID_ATTR_KEY.test(key)) {
+      throw new Error(`Invalid HTML attribute key: "${key}"`);
+    }
+  }
+  const htmlTagMatch = template.match(/<html(\s[^>]*)?>|<html>/i);
+  if (!htmlTagMatch || htmlTagMatch.index == null)
+    return template;
+  const existingAttrsStr = htmlTagMatch[1] ?? "";
+  const existingAttrs = parseHtmlTagAttrs(existingAttrsStr);
+  const merged = { ...existingAttrs };
+  for (const [key, value] of entries) {
+    merged[key] = escapeAttr(value);
+  }
+  const attrStr = Object.entries(merged).map(([k, v]) => v === "" && !(k in attrs) ? ` ${k}` : ` ${k}="${v}"`).join("");
+  const originalTag = htmlTagMatch[0].match(/^<([a-zA-Z]+)/i)[1];
+  const tagEnd = htmlTagMatch.index + htmlTagMatch[0].length;
+  return template.slice(0, htmlTagMatch.index) + `<${originalTag}${attrStr}>` + template.slice(tagEnd);
+}
+function parseHtmlTagAttrs(attrStr) {
+  const attrs = {};
+  const re = /([a-zA-Z][a-zA-Z0-9-]*)(?:\s*=\s*"([^"]*)"|(?:\s*=\s*'([^']*)'))?/g;
+  let m;
+  while ((m = re.exec(attrStr)) !== null) {
+    attrs[m[1]] = m[2] ?? m[3] ?? "";
+  }
+  return attrs;
+}
 function injectIntoTemplate(options) {
   const { template, appHtml, appCss, ssrData, nonce, headTags, sessionScript } = options;
   let html;
@@ -1523,4 +1557,4 @@ function replaceAppDivContent(template, appHtml) {
   return template.slice(0, contentStart) + appHtml + template.slice(i);
 }
-export { escapeHtml, escapeAttr, serializeToHtml, toPrefetchSession, evaluateAccessRule, reconstructDescriptors, compileThemeCached, createRequestContext, matchUrlToPatterns, resetSlotCounter, createSlotPlaceholder, encodeChunk, streamToString, collectStreamChunks, createTemplateChunk, renderToStream, safeSerialize, getStreamingRuntimeScript, createSSRDataChunk, ssrRenderSinglePass, ssrRenderProgressive, ssrStreamNavQueries, createHoles, ssrRenderAot, isAotDebugEnabled, clearRouteCssCache, getAccessSetForSSR, createAccessSetScript, createSessionScript, resolveRouteModulepreload, precomputeHandlerState, resolveSession, injectIntoTemplate };
+export { escapeHtml, escapeAttr, serializeToHtml, toPrefetchSession, evaluateAccessRule, reconstructDescriptors, compileThemeCached, createRequestContext, matchUrlToPatterns, resetSlotCounter, createSlotPlaceholder, encodeChunk, streamToString, collectStreamChunks, createTemplateChunk, renderToStream, safeSerialize, getStreamingRuntimeScript, createSSRDataChunk, ssrRenderSinglePass, ssrRenderProgressive, ssrStreamNavQueries, createHoles, ssrRenderAot, isAotDebugEnabled, clearRouteCssCache, getAccessSetForSSR, createAccessSetScript, createSessionScript, resolveRouteModulepreload, precomputeHandlerState, resolveSession, injectHtmlAttributes, injectIntoTemplate };

package/dist/ssr/index.d.ts CHANGED Viewed

@@ -395,6 +395,28 @@ interface SSRHandlerOptions {
 	* (JSON files, third-party APIs, custom DB clients).
 	*/
 	aotDataResolver?: AotDataResolver;
+	/**
+	* Derive attributes to set on the `<html>` tag from the incoming request.
+	*
+	* Useful for setting `data-theme`, `dir`, `lang`, or other attributes that
+	* must be on `<html>` to avoid FOUC. The callback runs before SSR rendering
+	* so the attributes are available in the first byte of the response.
+	*
+	* If the template already has an attribute with the same name, the callback's
+	* value overrides it. Values are HTML-escaped automatically. Keys must be
+	* valid HTML attribute names (`/^[a-zA-Z][a-zA-Z0-9-]*$/`).
+	*
+	* Return `undefined`, `null`, or `{}` to skip injection.
+	*
+	* @example
+	* ```ts
+	* htmlAttributes: (request) => ({
+	*   'data-theme': getThemeCookie(request) ?? 'dark',
+	*   dir: getDirection(request),
+	* })
+	* ```
+	*/
+	htmlAttributes?: (request: Request) => Record<string, string> | null | undefined;
 }
 declare function createSSRHandler(options: SSRHandlerOptions): (request: Request) => Promise<Response>;
 interface InjectIntoTemplateOptions {

package/dist/ssr/index.js CHANGED Viewed

@@ -1,12 +1,12 @@
 import {
   createSSRHandler,
   loadAotManifest
-} from "../shared/chunk-ck3n699k.js";
+} from "../shared/chunk-91eg6dps.js";
 import {
   injectIntoTemplate,
   ssrRenderSinglePass,
   ssrStreamNavQueries
-} from "../shared/chunk-tm5aeq94.js";
+} from "../shared/chunk-j9z9r179.js";
 import"../shared/chunk-szvdd1qq.js";
 import"../shared/chunk-bt1px3c4.js";
 // src/prerender.ts

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/ui-server",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "description": "Vertz UI server-side rendering runtime",
   "license": "MIT",
   "repository": {
@@ -39,6 +39,10 @@
       "import": "./dist/bun-plugin/fast-refresh-runtime.js",
       "types": "./dist/bun-plugin/fast-refresh-runtime.d.ts"
     },
+    "./state-inspector": {
+      "import": "./dist/bun-plugin/state-inspector.js",
+      "types": "./dist/bun-plugin/state-inspector.d.ts"
+    },
     "./bun-dev-server": {
       "import": "./dist/bun-dev-server.js",
       "types": "./dist/bun-dev-server.d.ts"
@@ -57,7 +61,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "bunup",
+    "build": "vtzx bunup",
     "test": "bun test --timeout 60000 src/",
     "test:integration": "bun test src/__tests__/bun-dev-server.integration.local.ts",
     "test:e2e": "bunx playwright test",
@@ -67,15 +71,15 @@
     "@ampproject/remapping": "^2.3.0",
     "@capsizecss/unpack": "^4.0.0",
     "@jridgewell/trace-mapping": "^0.3.31",
-    "@vertz/core": "^0.2.46",
-    "@vertz/ui": "^0.2.46",
+    "@vertz/core": "^0.2.48",
+    "@vertz/ui": "^0.2.48",
     "magic-string": "^0.30.0",
     "sharp": "^0.34.5"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.3",
     "@playwright/test": "^1.58.2",
-    "@vertz/codegen": "^0.2.46",
+    "@vertz/codegen": "^0.2.48",
     "bun-types": "^1.3.10",
     "bunup": "^0.16.31",
     "happy-dom": "^20.8.3",