@webtypen/webframez-react 0.0.49 → 0.0.50

package/README.md

@@ -491,3 +491,64 @@ Watch mode for package development:
 ```bash
 npm run build:watch
 ```
+
+## Persistent navigation in consuming applications
+
+Use the host router's Link component for URLs. Keep the Suite renderer mounted
+across paths inside one authorized project; do not add `key={path}` or conditionally
+unmount it while reloading project context. Revalidate/reset the context when the
+project changes, and continue enforcing authorization on every server request.
+Only the page content resets for a new screen. The renderer retains its layout and
+prior page while a same-project request is pending, with stale interactions disabled.
+
+For webframez-react, configure the DOM link adapter at the host boundary:
+
+```tsx
+import React from "react";
+import { Link } from "@webtypen/webframez-react/navigation";
+
+const SuiteLink = React.forwardRef<HTMLAnchorElement,
+  React.AnchorHTMLAttributes<HTMLAnchorElement>
+>(function SuiteLink({ href, ...props }, ref) {
+  return <Link {...props} ref={ref} to={href || "#"} basename="" />;
+});
+
+// Inside an already authorized project context; paths are fully qualified.
+<NativeDesignProvider
+  key={projectId}
+  suite={{ endpoint: "/manager", navigation: {
+    pathname, linkComponent: SuiteLink,
+    onNavigate: to => router.push(to),
+  } }}
+>
+  <WebframezSuiteRenderer />
+</NativeDesignProvider>
+```
+
+Screen definitions remain JSON-serializable: links use `to`/`path`; React Link
+components belong in the consuming application's adapter, never in server schemas.
+See `AGENTS.md` for the navigation invariants and regression-test requirements.
+
+
+## Core router basename
+
+With the updated Core router, set `application.router.basename` in the Core
+configuration. `initWebframezReact(Route).renderReact("/", options)` inherits it;
+no duplicate `basePath`, `assetsPrefix`, `rscPath`, `clientScriptUrl`, or
+`Head.basename` is needed. Nested render routes and `Route.group` prefixes are
+included in the runtime mount while build target names and directories stay
+stable. Explicit external asset URLs remain unchanged. Without Core, the Node
+handler still supports `basePath` and explicit transport URLs.
+
+For API calls, form actions, raw links and redirects in shared/client code:
+
+```ts
+import { appPath, appRelativePath, getBasename } from "@webtypen/webframez-react/paths";
+fetch(appPath("/api/items"));
+```
+
+These browser-safe helpers bundle Core's URL logic and read the runtime mount;
+no server dependencies are included. `Link` and `Redirect` inherit it
+implicitly. Server requests use an async-local context, and HTML rendering and
+client navigation receive the same basename through the Flight head and HTML
+shell. External URLs and already-prefixed URLs are preserved.

package/defaults/webpack.client.cjs

@@ -1,9 +1,12 @@
 const fs = require("fs");
 const path = require("path");
-const ReactFlightWebpackPlugin = require("react-server-dom-webpack/plugin");
+const { createRequire } = require("node:module");
 const { fileURLToPath, pathToFileURL } = require("url");
 
 const projectRoot = process.cwd();
+const projectRequire = createRequire(path.join(projectRoot, "package.json"));
+const ReactFlightWebpackPlugin = projectRequire("react-server-dom-webpack/plugin");
+const reactDomRequire = createRequire(projectRequire.resolve("react-dom/package.json"));
 const frameworkDistDir = path.resolve(__dirname, "..", "dist");
 const clientEntry = process.env.WEBFRAMEZ_REACT_CLIENT_ENTRY
   ? path.resolve(projectRoot, process.env.WEBFRAMEZ_REACT_CLIENT_ENTRY)
@@ -266,7 +269,8 @@ module.exports = {
       "react-dom": path.resolve(projectRoot, "node_modules", "react-dom"),
       "react/jsx-runtime": path.resolve(projectRoot, "node_modules", "react", "jsx-runtime.js"),
       "react/jsx-dev-runtime": path.resolve(projectRoot, "node_modules", "react", "jsx-dev-runtime.js"),
-      scheduler: path.resolve(projectRoot, "node_modules", "scheduler"),
+      // Resolve React DOM's own scheduler, including pnpm's isolated layout.
+      scheduler: path.dirname(reactDomRequire.resolve("scheduler/package.json")),
     },
   },
   watchOptions: {

package/dist/http.cjs

@@ -29,9 +29,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/http.ts
 var http_exports = {};
 __export(http_exports, {
-  createNodeRequestHandler: () => createNodeRequestHandler
+  createNodeRequestHandler: () => createNodeRequestHandler,
+  disposeReactHtmlRenderer: () => disposeReactHtmlRenderer,
+  renderReactToHtml: () => renderReactToHtml
 });
 module.exports = __toCommonJS(http_exports);
+var import_node_async_hooks = require("node:async_hooks");
 var import_node_fs2 = __toESM(require("node:fs"), 1);
 var import_node_path3 = __toESM(require("node:path"), 1);
 var import_node_url = require("node:url");
@@ -341,8 +344,7 @@ var FORCED_PACKAGE_REQUESTS = [
   "react-server-dom-webpack",
   "react-server-dom-webpack/server",
   "react-server-dom-webpack/client",
-  "react-server-dom-webpack/client.node",
-  "scheduler"
+  "react-server-dom-webpack/client.node"
 ];
 var forcedPackageResolutionInstalled = false;
 function normalizePathname(pathname) {
@@ -993,6 +995,7 @@ const rootParent = {
   path: process.cwd(),
   paths: Module._nodeModulePaths(process.cwd()),
 };
+// Transitive dependencies (e.g. scheduler) must resolve from their importer.
 const forcedPackageRequests = [
   "@webtypen/webframez-core",
   "@webtypen/webframez-react",
@@ -1007,7 +1010,6 @@ const forcedPackageRequests = [
   "react-server-dom-webpack/server",
   "react-server-dom-webpack/client",
   "react-server-dom-webpack/client.node",
-  "scheduler"
 ];
 
 function shouldForcePackageResolution(request) {
@@ -1199,13 +1201,17 @@ async function renderHtmlFromFlightData(flightData, moduleMap) {
       ? payload.head.basename
       : "";
 
-  const previousBasename = globalThis.__RSC_BASENAME;
-  globalThis.__RSC_BASENAME = basename;
-  try {
-    return await renderHtml(model);
-  } finally {
-    globalThis.__RSC_BASENAME = previousBasename;
-  }
+  const routingContext = globalThis.__WEBFRAMEZ_ROUTING_CONTEXT__ ??=
+    new (require("node:async_hooks").AsyncLocalStorage)();
+  return routingContext.run(basename, async () => {
+    const previousBasename = globalThis.__RSC_BASENAME;
+    globalThis.__RSC_BASENAME = basename;
+    try {
+      return await renderHtml(model);
+    } finally {
+      globalThis.__RSC_BASENAME = previousBasename;
+    }
+  });
 }
 
 process.on("message", async (message) => {
@@ -1441,24 +1447,10 @@ ${stderrBuffer.trim()}` : "";
     }
   };
 }
+var routingRuntime = globalThis;
+var basenameContext = routingRuntime.__WEBFRAMEZ_ROUTING_CONTEXT__ ??= new import_node_async_hooks.AsyncLocalStorage();
 function withRequestBasename(basename, fn) {
-  const target = globalThis;
-  const previous = target.__RSC_BASENAME;
-  target.__RSC_BASENAME = basename;
-  const finish = () => {
-    target.__RSC_BASENAME = previous;
-  };
-  try {
-    const result = fn();
-    if (result && typeof result.then === "function") {
-      return result.finally(finish);
-    }
-    finish();
-    return result;
-  } catch (error) {
-    finish();
-    throw error;
-  }
+  return basenameContext.run(basename, fn);
 }
 function parseCookies(rawCookieHeader) {
   const raw = Array.isArray(rawCookieHeader) ? rawCookieHeader.join("; ") : rawCookieHeader ?? "";
@@ -1493,12 +1485,27 @@ function normalizeClientManifest(manifest, options) {
     }
   };
   for (const [key, value] of Object.entries(manifest)) {
+    const hashIndex = key.indexOf("#");
+    const moduleKey = hashIndex < 0 ? key : key.slice(0, hashIndex);
+    const exportSuffix = hashIndex < 0 ? "" : key.slice(hashIndex);
+    if (!import_node_path3.default.isAbsolute(moduleKey) && !moduleKey.includes(":") && !moduleKey.startsWith("file://")) {
+      const runtimePath = import_node_path3.default.resolve(options.cwd, moduleKey);
+      const allowedRoots = [options.distRootDir, ...candidateNodeModulesDirs];
+      const insideArtifact = allowedRoots.some((root) => {
+        const relative = import_node_path3.default.relative(import_node_path3.default.resolve(root), runtimePath);
+        return relative !== "" && relative !== ".." && !relative.startsWith(`..${import_node_path3.default.sep}`) && !import_node_path3.default.isAbsolute(relative);
+      });
+      if (insideArtifact) {
+        addAlias(`${runtimePath}${exportSuffix}`, value);
+        addAlias(`${(0, import_node_url.pathToFileURL)(runtimePath).href}${exportSuffix}`, value);
+      }
+    }
     if (!key.startsWith("file://")) {
       continue;
     }
     let absolutePath = "";
     try {
-      absolutePath = (0, import_node_url.fileURLToPath)(key);
+      absolutePath = (0, import_node_url.fileURLToPath)(moduleKey);
     } catch {
       continue;
     }
@@ -1509,13 +1516,13 @@ function normalizeClientManifest(manifest, options) {
     }
     const relativeModulePath = absolutePath.slice(markerIndex + marker.length);
     const relativeModulePathPosix = relativeModulePath.split(import_node_path3.default.sep).join("/");
-    addAlias(`./node_modules/${relativeModulePathPosix}`, value);
-    addAlias(`node_modules/${relativeModulePathPosix}`, value);
-    addAlias(absolutePath, value);
+    addAlias(`./node_modules/${relativeModulePathPosix}${exportSuffix}`, value);
+    addAlias(`node_modules/${relativeModulePathPosix}${exportSuffix}`, value);
+    addAlias(`${absolutePath}${exportSuffix}`, value);
     for (const nodeModulesDir of candidateNodeModulesDirs) {
       const aliasPath = import_node_path3.default.join(nodeModulesDir, relativeModulePath);
-      addAlias(aliasPath, value);
-      addAlias((0, import_node_url.pathToFileURL)(aliasPath).href, value);
+      addAlias(`${aliasPath}${exportSuffix}`, value);
+      addAlias(`${(0, import_node_url.pathToFileURL)(aliasPath).href}${exportSuffix}`, value);
     }
   }
   return normalized;
@@ -1660,10 +1667,10 @@ function createNodeRequestHandler(options) {
   const manifestPath = import_node_path3.default.resolve(
     options.manifestPath ?? import_node_path3.default.join(distRootDir, "react-client-manifest.json")
   );
-  const assetsPrefix = options.assetsPrefix ?? "/assets/";
-  const rscPath = options.rscPath ?? "/rsc";
-  const clientScriptUrl = options.clientScriptUrl ?? "/assets/client.js";
   const basePath = normalizeBasePath(options.basePath);
+  const assetsPrefix = options.assetsPrefix ?? `${basePath}/assets/`;
+  const rscPath = options.rscPath ?? `${basePath}/rsc`;
+  const clientScriptUrl = options.clientScriptUrl ?? `${basePath}/assets/client.js`;
   const nodeEnv = process.env.NODE_ENV || "";
   const runningInWatchMode = Array.isArray(process.execArgv) && process.execArgv.includes("--watch");
   const liveReloadEnabled = options.liveReloadPath !== false && (nodeEnv === "development" || runningInWatchMode);
@@ -1682,7 +1689,7 @@ function createNodeRequestHandler(options) {
   process.once("exit", disposeInitialHtmlWorker);
   process.once("SIGINT", disposeInitialHtmlWorker);
   process.once("SIGTERM", disposeInitialHtmlWorker);
-  return async function handleRequest(req, res) {
+  const handleRequest = async (req, res) => {
     if (!req.url) {
       res.statusCode = 400;
       res.end("Bad request");
@@ -1746,6 +1753,7 @@ function createNodeRequestHandler(options) {
           request: requestContext
         })
       );
+      resolved2.head = { ...resolved2.head, basename: resolved2.head.basename ?? basePath };
       attachResolvedContextToCoreRequest(req, resolved2.context);
       const payload = {
         model: resolved2.model,
@@ -1821,6 +1829,7 @@ function createNodeRequestHandler(options) {
         )
       })
     );
+    resolved.head = { ...resolved.head, basename: resolved.head.basename ?? basePath };
     attachResolvedContextToCoreRequest(req, resolved.context);
     const initialPayload = {
       model: resolved.model,
@@ -1906,8 +1915,30 @@ function createNodeRequestHandler(options) {
       }
     );
   };
+  return (req, res) => withRequestBasename(basePath, () => handleRequest(req, res));
+}
+var standaloneHtmlWorker;
+async function renderReactToHtml(element) {
+  if (!standaloneHtmlWorker) {
+    standaloneHtmlWorker = createInitialHtmlWorker(process.cwd());
+    process.once("exit", disposeReactHtmlRenderer);
+  }
+  const flightData = await renderRSCToString({ model: element }, {
+    moduleMap: {},
+    onError: (error) => {
+      console.error("[webframez-react] HTML render failed", error);
+    }
+  });
+  return standaloneHtmlWorker.renderFromFlightData({ flightData, moduleMap: {} });
+}
+function disposeReactHtmlRenderer() {
+  process.removeListener("exit", disposeReactHtmlRenderer);
+  standaloneHtmlWorker?.dispose();
+  standaloneHtmlWorker = void 0;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createNodeRequestHandler
+  createNodeRequestHandler,
+  disposeReactHtmlRenderer,
+  renderReactToHtml
 });

package/dist/http.d.ts

@@ -27,3 +27,6 @@ export interface CreateNodeHandlerOptions
 export function createNodeRequestHandler(
   options: CreateNodeHandlerOptions
 ): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export function renderReactToHtml(element: unknown): Promise<string>;
+export function disposeReactHtmlRenderer(): void;

package/dist/http.js

@@ -7,6 +7,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/http.ts
+import { AsyncLocalStorage } from "node:async_hooks";
 import fs2 from "node:fs";
 import path3 from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -321,8 +322,7 @@ var FORCED_PACKAGE_REQUESTS = [
   "react-server-dom-webpack",
   "react-server-dom-webpack/server",
   "react-server-dom-webpack/client",
-  "react-server-dom-webpack/client.node",
-  "scheduler"
+  "react-server-dom-webpack/client.node"
 ];
 var forcedPackageResolutionInstalled = false;
 function normalizePathname(pathname) {
@@ -973,6 +973,7 @@ const rootParent = {
   path: process.cwd(),
   paths: Module._nodeModulePaths(process.cwd()),
 };
+// Transitive dependencies (e.g. scheduler) must resolve from their importer.
 const forcedPackageRequests = [
   "@webtypen/webframez-core",
   "@webtypen/webframez-react",
@@ -987,7 +988,6 @@ const forcedPackageRequests = [
   "react-server-dom-webpack/server",
   "react-server-dom-webpack/client",
   "react-server-dom-webpack/client.node",
-  "scheduler"
 ];
 
 function shouldForcePackageResolution(request) {
@@ -1179,13 +1179,17 @@ async function renderHtmlFromFlightData(flightData, moduleMap) {
       ? payload.head.basename
       : "";
 
-  const previousBasename = globalThis.__RSC_BASENAME;
-  globalThis.__RSC_BASENAME = basename;
-  try {
-    return await renderHtml(model);
-  } finally {
-    globalThis.__RSC_BASENAME = previousBasename;
-  }
+  const routingContext = globalThis.__WEBFRAMEZ_ROUTING_CONTEXT__ ??=
+    new (require("node:async_hooks").AsyncLocalStorage)();
+  return routingContext.run(basename, async () => {
+    const previousBasename = globalThis.__RSC_BASENAME;
+    globalThis.__RSC_BASENAME = basename;
+    try {
+      return await renderHtml(model);
+    } finally {
+      globalThis.__RSC_BASENAME = previousBasename;
+    }
+  });
 }
 
 process.on("message", async (message) => {
@@ -1421,24 +1425,10 @@ ${stderrBuffer.trim()}` : "";
     }
   };
 }
+var routingRuntime = globalThis;
+var basenameContext = routingRuntime.__WEBFRAMEZ_ROUTING_CONTEXT__ ??= new AsyncLocalStorage();
 function withRequestBasename(basename, fn) {
-  const target = globalThis;
-  const previous = target.__RSC_BASENAME;
-  target.__RSC_BASENAME = basename;
-  const finish = () => {
-    target.__RSC_BASENAME = previous;
-  };
-  try {
-    const result = fn();
-    if (result && typeof result.then === "function") {
-      return result.finally(finish);
-    }
-    finish();
-    return result;
-  } catch (error) {
-    finish();
-    throw error;
-  }
+  return basenameContext.run(basename, fn);
 }
 function parseCookies(rawCookieHeader) {
   const raw = Array.isArray(rawCookieHeader) ? rawCookieHeader.join("; ") : rawCookieHeader ?? "";
@@ -1473,12 +1463,27 @@ function normalizeClientManifest(manifest, options) {
     }
   };
   for (const [key, value] of Object.entries(manifest)) {
+    const hashIndex = key.indexOf("#");
+    const moduleKey = hashIndex < 0 ? key : key.slice(0, hashIndex);
+    const exportSuffix = hashIndex < 0 ? "" : key.slice(hashIndex);
+    if (!path3.isAbsolute(moduleKey) && !moduleKey.includes(":") && !moduleKey.startsWith("file://")) {
+      const runtimePath = path3.resolve(options.cwd, moduleKey);
+      const allowedRoots = [options.distRootDir, ...candidateNodeModulesDirs];
+      const insideArtifact = allowedRoots.some((root) => {
+        const relative = path3.relative(path3.resolve(root), runtimePath);
+        return relative !== "" && relative !== ".." && !relative.startsWith(`..${path3.sep}`) && !path3.isAbsolute(relative);
+      });
+      if (insideArtifact) {
+        addAlias(`${runtimePath}${exportSuffix}`, value);
+        addAlias(`${pathToFileURL(runtimePath).href}${exportSuffix}`, value);
+      }
+    }
     if (!key.startsWith("file://")) {
       continue;
     }
     let absolutePath = "";
     try {
-      absolutePath = fileURLToPath(key);
+      absolutePath = fileURLToPath(moduleKey);
     } catch {
       continue;
     }
@@ -1489,13 +1494,13 @@ function normalizeClientManifest(manifest, options) {
     }
     const relativeModulePath = absolutePath.slice(markerIndex + marker.length);
     const relativeModulePathPosix = relativeModulePath.split(path3.sep).join("/");
-    addAlias(`./node_modules/${relativeModulePathPosix}`, value);
-    addAlias(`node_modules/${relativeModulePathPosix}`, value);
-    addAlias(absolutePath, value);
+    addAlias(`./node_modules/${relativeModulePathPosix}${exportSuffix}`, value);
+    addAlias(`node_modules/${relativeModulePathPosix}${exportSuffix}`, value);
+    addAlias(`${absolutePath}${exportSuffix}`, value);
     for (const nodeModulesDir of candidateNodeModulesDirs) {
       const aliasPath = path3.join(nodeModulesDir, relativeModulePath);
-      addAlias(aliasPath, value);
-      addAlias(pathToFileURL(aliasPath).href, value);
+      addAlias(`${aliasPath}${exportSuffix}`, value);
+      addAlias(`${pathToFileURL(aliasPath).href}${exportSuffix}`, value);
     }
   }
   return normalized;
@@ -1640,10 +1645,10 @@ function createNodeRequestHandler(options) {
   const manifestPath = path3.resolve(
     options.manifestPath ?? path3.join(distRootDir, "react-client-manifest.json")
   );
-  const assetsPrefix = options.assetsPrefix ?? "/assets/";
-  const rscPath = options.rscPath ?? "/rsc";
-  const clientScriptUrl = options.clientScriptUrl ?? "/assets/client.js";
   const basePath = normalizeBasePath(options.basePath);
+  const assetsPrefix = options.assetsPrefix ?? `${basePath}/assets/`;
+  const rscPath = options.rscPath ?? `${basePath}/rsc`;
+  const clientScriptUrl = options.clientScriptUrl ?? `${basePath}/assets/client.js`;
   const nodeEnv = process.env.NODE_ENV || "";
   const runningInWatchMode = Array.isArray(process.execArgv) && process.execArgv.includes("--watch");
   const liveReloadEnabled = options.liveReloadPath !== false && (nodeEnv === "development" || runningInWatchMode);
@@ -1662,7 +1667,7 @@ function createNodeRequestHandler(options) {
   process.once("exit", disposeInitialHtmlWorker);
   process.once("SIGINT", disposeInitialHtmlWorker);
   process.once("SIGTERM", disposeInitialHtmlWorker);
-  return async function handleRequest(req, res) {
+  const handleRequest = async (req, res) => {
     if (!req.url) {
       res.statusCode = 400;
       res.end("Bad request");
@@ -1726,6 +1731,7 @@ function createNodeRequestHandler(options) {
           request: requestContext
         })
       );
+      resolved2.head = { ...resolved2.head, basename: resolved2.head.basename ?? basePath };
       attachResolvedContextToCoreRequest(req, resolved2.context);
       const payload = {
         model: resolved2.model,
@@ -1801,6 +1807,7 @@ function createNodeRequestHandler(options) {
         )
       })
     );
+    resolved.head = { ...resolved.head, basename: resolved.head.basename ?? basePath };
     attachResolvedContextToCoreRequest(req, resolved.context);
     const initialPayload = {
       model: resolved.model,
@@ -1886,7 +1893,29 @@ function createNodeRequestHandler(options) {
       }
     );
   };
+  return (req, res) => withRequestBasename(basePath, () => handleRequest(req, res));
+}
+var standaloneHtmlWorker;
+async function renderReactToHtml(element) {
+  if (!standaloneHtmlWorker) {
+    standaloneHtmlWorker = createInitialHtmlWorker(process.cwd());
+    process.once("exit", disposeReactHtmlRenderer);
+  }
+  const flightData = await renderRSCToString({ model: element }, {
+    moduleMap: {},
+    onError: (error) => {
+      console.error("[webframez-react] HTML render failed", error);
+    }
+  });
+  return standaloneHtmlWorker.renderFromFlightData({ flightData, moduleMap: {} });
+}
+function disposeReactHtmlRenderer() {
+  process.removeListener("exit", disposeReactHtmlRenderer);
+  standaloneHtmlWorker?.dispose();
+  standaloneHtmlWorker = void 0;
 }
 export {
-  createNodeRequestHandler
+  createNodeRequestHandler,
+  disposeReactHtmlRenderer,
+  renderReactToHtml
 };