znode-plugin 0.1.8 → 0.1.10

package/README.md

@@ -282,47 +282,58 @@ components, so it is reviewed like any base change), and rebuild / restart the w
 ### Take over a whole store page
 
 A store **page** (a route, `apps/webstore/src/app/**/page.tsx`) runs on the server, so it gets a **server slot** around
-its content. Use the page's component name (its `export default function <Name>`):
+the whole route, and `eject` gives you a **copy of the route**, as it does for a component. Use the page's name (its
+`export default function <Name>`):
 
 ```
 $ npx znode eject ForgotPasswordPage
 ForgotPasswordPage has no slot yet, so it cannot be ejected.
 Create a slot for ForgotPasswordPage in the base store now? [y/N] y
-Slot name (area.name) [forgotPassword.page]:
+Slot name (area.name) [forgotPassword.page]: forgotPassword.page
 creating slot "forgotPassword.page" around ForgotPasswordPage (apps/webstore/src/app/[locale]/forgot-password/page.tsx) ...
-ejected ForgotPasswordPage (server slot "forgotPassword.page") -> src/server/pages/ForgotPasswordPage.tsx
+added "storeServer" to "permissions" in znode-package.json (its server part imports store modules)
+ejected ForgotPasswordPage (a copy of apps/webstore/src/app/[locale]/forgot-password/page.tsx, server slot "forgotPassword.page") -> src/server/pages/ForgotPasswordPage.tsx
 registered "forgotPassword.page": EjectedForgotPasswordPage in src/server.tsx (serverSlots)
 ```
 
-In the store, the page's content is wrapped (inside its `NextIntlClientProvider`, so the page's texts still reach it):
+In the store, the route's function becomes `<Name>Base` and its default export is wrapped (the server version of
+`withRuntimeWrapper`; with no package for the slot the store's page renders as it is):
 
 ```tsx
-<NextIntlClientProvider messages={...}>
-  <RuntimeServerSlot name="forgotPassword.page">
-    <ForgotPassword />
-  </RuntimeServerSlot>
-</NextIntlClientProvider>
+async function ForgotPasswordPageBase() { … unchanged … }
+export default withRuntimeServerPage("forgotPassword.page", ForgotPasswordPageBase);
 ```
 
-In your package you get a server component to build the page in. `children` is the store's page content:
+In your package you get the route itself, to change as you like:
 
 ```tsx
-// src/server/pages/ForgotPasswordPage.tsx
-export async function ForgotPasswordPage(props: { children?: ReactNode }, context: IServerSlotContext) {
+// src/server/pages/ForgotPasswordPage.tsx (a copy of the store's route)
+import { ForgotPassword } from "@znode/base-components/components/forgot-password";
+import { NextIntlClientProvider } from "next-intl";
+import { getResourceMessages } from "@znode/utils/server";
+
+export async function ForgotPasswordPage() {
+  const userPasswordMessages = await getResourceMessages("UserPassword");
+  const commonMessages = await getResourceMessages("Common");
   return (
-    <div className="my-forgot-page">
+    <NextIntlClientProvider messages={{ ...userPasswordMessages, ...commonMessages }}>
       <h1>Reset your password</h1>
-      <aside>Help text, images, data fetched here (async is fine)</aside>
-      {props.children /* the store's form; leave it out to render a page of your own */}
-    </div>
+      <ForgotPassword />
+    </NextIntlClientProvider>
   );
 }
 ```
 
-- It is not a copy of the route: the route's server code (agents, `getResourceMessages`, data) stays the store's. Your
-  component runs on the server only (async, no hooks): put interactive parts in a browser slot, e.g. change the form
-  itself with `npx znode eject ForgotPassword` (slot `account.forgotPassword`).
-- A page that already has a server slot (`login.page`, `layout.root`) is ejected straight away (`npx znode eject LoginPage`).
+- **props**: the route's own (`params`, `searchParams`) and `children` (the store's page, if you want to keep it);
+  **context** (second argument): `store`, `settings`. It runs on the server only (async, no hooks).
+- **Store imports in a server part** come from the store's **server registry**, an allow-list the store generates
+  (`packages/extensions/store-server-module-registry.json`): agents (`@znode/agents/*`), the texts and store context
+  (`getResourceMessages`, `fetchMessages`, `getPortalHeader`), the server logger, and client components and modules.
+  Session, cookie, token, cache and API-client internals are not in it: the build stops on them and says so.
+  The package needs the permission `"storeServer"` (eject adds it); a sandboxed package cannot have it.
+- The route's `generateMetadata` (page title) stays the store's.
+- To change only the form, eject the client component instead: `npx znode eject ForgotPassword`.
+- A page whose slot is **inside** the page (`login.page`, `layout.root`) gives a starter that renders `children`, not a copy.
 - Only the slot: `npx znode create-slot ForgotPasswordPage forgotPassword.page` (`--dry-run` to preview).
 
 ### Add a page-builder widget

package/lib/next-imports.mjs

@@ -130,10 +130,12 @@ function splitStoreImports(code, store) {
 
 // the stand-in for a store module: the store's module itself (loaded before the bundle), its names as rollup's
 // synthetic named exports; a name missing on the module is read from its default (an npm CommonJS package)
-function storeStandIn(key) {
+// (a server part reads the store's server set, __znodeStoreServer: next-modules.server.ts loads it before the bundle)
+function storeStandIn(key, part) {
+  const global = part === "server" ? "__znodeStoreServer" : "__znodeNextClient";
   return [
-    `const loaded = (globalThis.__znodeNextClient || {})[${JSON.stringify(key)}];`,
-    `if (!loaded) throw new Error(${JSON.stringify(`"${key}" was not loaded by the store: the package needs a store with the Generated Store Module Registry`)});`,
+    `const loaded = (globalThis.${global} || {})[${JSON.stringify(key)}];`,
+    `if (!loaded) throw new Error(${JSON.stringify(`"${key}" was not loaded by the store: the package needs a store with the Generated Store Module Registry${part === "server" ? " (server registry)" : ""}`)});`,
     `export const __store = new Proxy(loaded, { get: (module, name) => (name in module ? module[name] : module.default?.[name]) });`,
     `export default loaded.default;`,
   ].join("\n");
@@ -325,14 +327,24 @@ export function znodeNext({ part, prefix, outDir, fonts, store, storeImports = [
     resolveId(source) {
       if (MODULES[source]) return VIRTUAL + source;
       if (SHARED_PACKAGES.has(source) || source.startsWith("@znode/") || source.startsWith(STORE_FILE)) {
-        if (part === "server") this.error(`"${source}" is a store module for browser parts (src/browser.tsx), not server parts`);
         if (!store) this.error(`"${source}" is a store module: connect the store first (npm run link-store -- <store repo>), which writes tsconfig.store.json`);
-        if (!store.registry) this.error(`"${source}": the store at ${store.root} has no packages/extensions/store-module-registry.json (run node scripts/gen-store-module-registry.mjs there, or update the store)`);
+        // a server part imports from the store's server registry (an allow-list: agents, texts and store context, logger,
+        // client modules), a browser part from the client registry
+        const registry = part === "server" ? store.serverRegistry : store.registry;
+        const registryFile = part === "server" ? "store-server-module-registry.json" : "store-module-registry.json";
+        if (!registry)
+          this.error(
+            `"${source}": the store at ${store.root} has no packages/extensions/${registryFile} (run node scripts/gen-store-module-registry.mjs there, or update the store)${part === "server" ? ": a server part can import store modules only from a store with the server registry" : ""}`
+          );
         // a named import was split to the file that defines it (transform); a default or namespace import is the module
         const key = source.startsWith(STORE_FILE) ? source.slice(STORE_FILE.length) : storeKey(source, store);
         if (!key) this.error(`"${source}" is not a store module (no file for it under the store's tsconfig paths)`);
-        if (!store.registry.has(key)) {
-          this.error(`"${source}" (${key}) is not in the store's module registry: it is server-only, or the store's registry is older than this file (regenerate it: node scripts/gen-store-module-registry.mjs in the store repo)`);
+        if (!registry.has(key)) {
+          this.error(
+            part === "server"
+              ? `${source.startsWith(STORE_FILE) ? `store module ${key} (a named import's defining file)` : `"${source}" (${key})`} is not available to a package's server part: the store's server registry allows agents, texts and store context (getResourceMessages, fetchMessages, getPortalHeader), the server logger and client modules, not session, cookie, token, cache or API-client internals (or the store's registry is older: node scripts/gen-store-module-registry.mjs in the store repo)`
+              : `"${source}" (${key}) is not in the store's module registry: it is server-only, or the store's registry is older than this file (regenerate it: node scripts/gen-store-module-registry.mjs in the store repo)`
+          );
         }
         if (!storeImports.includes(key)) storeImports.push(key);
         return VIRTUAL + STORE + key;
@@ -346,12 +358,12 @@ export function znodeNext({ part, prefix, outDir, fonts, store, storeImports = [
     load(id) {
       if (!id.startsWith(VIRTUAL)) return null;
       const name = id.slice(VIRTUAL.length);
-      if (name.startsWith(STORE)) return { code: storeStandIn(name.slice(STORE.length)), syntheticNamedExports: "__store" };
+      if (name.startsWith(STORE)) return { code: storeStandIn(name.slice(STORE.length), part), syntheticNamedExports: "__store" };
       return standIn(name, part);
     },
     async transform(code, id) {
       if (id.startsWith(VIRTUAL)) return null;
-      const split = part === "browser" && store && /from\s*["']@znode\//.test(code) ? splitStoreImports(code, store) : code;
+      const split = store && /from\s*["']@znode\//.test(code) ? splitStoreImports(code, store) : code;
       const output = await transformFonts(split, id, { prefix, outDir, fonts });
       if (output === null) return split === code ? null : { code: split, map: null };
       return { code: output, map: null };

package/lib/znode-package.mjs

@@ -41,14 +41,15 @@
 //                       (attribute: the value comes from a Znode global attribute, "Code" for the store's, or
 //                        { "code": "...", "levels": ["store", "account", "user"] }; the most specific level wins)
 //   marketplace: "license", "keywords", "homepage", "compatibility": { "webstore": ">=10.0.0" },
-//   "permissions": ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"]   (what it does beyond UI;
-//                  "uploads": its routes take files, multipart/form-data up to RUNTIME_PLUGIN_UPLOAD_BYTES)
+//   "permissions": ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads", "storeServer"]   (what it does beyond UI;
+//                  "uploads": its routes take files, multipart/form-data up to RUNTIME_PLUGIN_UPLOAD_BYTES;
+//                  "storeServer": its server part imports store modules from the store's server registry)
 //   "sandbox": true   (its server part runs in a separate, permission-limited Node process: routes and overrides only)
 // }
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync, spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
+import { builtinModules, createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import vm from "node:vm";
 import { TEMPLATES } from "./templates.mjs";
@@ -79,7 +80,9 @@ const MAX_BYTES = 10 * 1024 * 1024;
 const SETTING_TYPES = ["string", "number", "boolean", "list", "json", "object", "array"];
 const ATTRIBUTE_LEVELS = ["store", "account", "user"];
 const ATTRIBUTE_CODE = /^[A-Za-z][A-Za-z0-9_]{1,99}$/;
-const PERMISSIONS = ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads"];
+// storeServer: its server part imports store modules (agents, texts and store context, logger, client components) from the
+// store's server registry, e.g. a page ejected with `znode eject <Page>`; not in a sandboxed package
+const PERMISSIONS = ["routes", "cartHooks", "overrides", "znodeApi", "externalNetwork", "uploads", "storeServer"];
 
 const fail = (message) => {
   console.error(`znode-package: ${message}`);
@@ -209,7 +212,10 @@ function linkedStore(dir) {
   const root = path.resolve(dir, compilerOptions.baseUrl);
   const registryFile = path.join(root, "packages/extensions/store-module-registry.json");
   const registry = fs.existsSync(registryFile) ? readJson(registryFile).modules : null;
-  return { root, paths: compilerOptions.paths || {}, registry };
+  // the store modules a package's server part may import (an allow-list, permission storeServer)
+  const serverRegistryFile = path.join(root, "packages/extensions/store-server-module-registry.json");
+  const serverRegistry = fs.existsSync(serverRegistryFile) ? readJson(serverRegistryFile).modules : null;
+  return { root, paths: compilerOptions.paths || {}, registry, serverRegistry };
 }
 
 function build(target) {
@@ -226,7 +232,27 @@ function build(target) {
   const fonts = [];
   // the store modules its browser part imports (Generated Store Module Registry keys), for the store to load first
   const storeImports = [];
+  // the store modules its server part imports (the store's server registry, permission storeServer)
+  const serverStoreImports = [];
   const store = linkedStore(dir);
+  // the npm packages its sources import: those the store does not share and the package does not have yet are installed
+  // at the store's version before anything compiles (--no-install: named instead); another version than the store's warns
+  if (store) {
+    const sources = [];
+    const walk = (folder) => {
+      if (!fs.existsSync(folder)) return;
+      for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+        const file = path.join(folder, entry.name);
+        if (entry.isDirectory()) walk(file);
+        else if (/\.(tsx?|jsx?|mjs)$/.test(entry.name)) sources.push(file);
+      }
+    };
+    walk(path.join(dir, "src"));
+    const specs = sources.flatMap((file) => npmImportsOf(fs.readFileSync(file, "utf8")));
+    ensureStorePackages(dir, store, specs, { install: !process.argv.includes("--no-install") });
+    const drift = versionDrift(dir, store, specs);
+    if (drift.length) console.log(`warning installed at another version than the store's: ${drift.join(", ")} (npm install --save-exact <pkg>@<store version>)`);
+  }
   // A package with its own tsconfig.json (extending the store's tsconfig.base.json) is checked against the store's real
   // types (every @znode alias, no declarations to write), then compiled file by file without type information, JSX as
   // Next.js does (react/jsx-runtime: the store's). Without one, the package compiles as before (tsc, JSX factory h).
@@ -282,6 +308,7 @@ function build(target) {
         `const storeImports = [];`,
         `const store = ${JSON.stringify(store)};`,
         `if (store?.registry) store.registry = new Set(store.registry);`,
+        `if (store?.serverRegistry) store.serverRegistry = new Set(store.serverRegistry);`,
         `export default {`,
         `  input: ${JSON.stringify(compiled)},`,
         `  output: { file: ${JSON.stringify(path.join(out, target))}, format: "es", sourcemap: true },`,
@@ -294,7 +321,8 @@ function build(target) {
     );
     execFileSync(process.execPath, [ROLLUP(), "--config", config, "--silent"], { stdio: "inherit" });
     if (fs.existsSync(fontsFile)) fonts.push(...JSON.parse(fs.readFileSync(fontsFile, "utf8")));
-    if (fs.existsSync(storeImportsFile)) storeImports.push(...JSON.parse(fs.readFileSync(storeImportsFile, "utf8")));
+    // the server part's store imports (server registry) are loaded by the store's server, the browser part's by the browser
+    if (fs.existsSync(storeImportsFile)) (part === "server" ? serverStoreImports : storeImports).push(...JSON.parse(fs.readFileSync(storeImportsFile, "utf8")));
     files[part] = target;
   }
   fs.rmSync(tmp, { recursive: true, force: true });
@@ -336,7 +364,19 @@ function build(target) {
     );
   }
   const { build: _build, styles: _styles, assets: _assets, dedupeStyles: _dedupe, ...rest } = manifest;
-  fs.writeFileSync(path.join(out, MANIFEST), JSON.stringify({ ...rest, files, ...(storeImports.length ? { storeImports: [...new Set(storeImports)].sort() } : {}) }, null, 2) + "\n");
+  fs.writeFileSync(
+    path.join(out, MANIFEST),
+    JSON.stringify(
+      {
+        ...rest,
+        files,
+        ...(storeImports.length ? { storeImports: [...new Set(storeImports)].sort() } : {}),
+        ...(serverStoreImports.length ? { serverStoreImports: [...new Set(serverStoreImports)].sort() } : {}),
+      },
+      null,
+      2
+    ) + "\n"
+  );
   console.log(`built ${manifest.kind} ${manifest.name}@${manifest.version}: ${fs.readdirSync(out).length} files`);
   return { manifest, out };
 }
@@ -487,6 +527,8 @@ function install(source, storeDir) {
     ...(manifest.widgets?.length ? { widgets: manifest.widgets } : {}),
     // the store modules its browser bundle imports: the store loads them first (Generated Store Module Registry)
     ...(Array.isArray(manifest.storeImports) && manifest.storeImports.length ? { storeImports: manifest.storeImports.map(String) } : {}),
+    // and the store modules its server bundle imports (server registry): the store's server loads them first
+    ...(Array.isArray(manifest.serverStoreImports) && manifest.serverStoreImports.length ? { serverStoreImports: manifest.serverStoreImports.map(String) } : {}),
     ...(manifest.overrides ? { overrides: manifest.overrides } : {}),
     ...(manifest.serverPages?.length ? { serverPages: manifest.serverPages } : {}),
     ...(manifest.sandbox === true ? { sandbox: true } : {}),
@@ -593,6 +635,8 @@ function check(target) {
   if (/\bznode\s*\(/.test(server)) used.add("znodeApi");
   if (/\bfetch\s*\(|\bhttps?\.request\s*\(/.test(server)) used.add("externalNetwork");
   if (/\.files\b/.test(server)) used.add("uploads");
+  if (/^\s*import\s+(?!type\b)[^;]*?from\s*["']@znode\/(?!types\/)/m.test(server)) used.add("storeServer");
+  if (used.has("storeServer") && manifest.sandbox === true) errors.push(`its server part imports store modules ("storeServer"), which a sandboxed package cannot: its routes run in their own process`);
   const declared = new Set(manifest.permissions || []);
   for (const item of used) if (!declared.has(item)) errors.push(`uses "${item}" without declaring it in "permissions"`);
   for (const item of declared) if (!used.has(item)) warnings.push(`declares "${item}" but no code uses it (the review asks why)`);
@@ -678,12 +722,134 @@ function linkStore(storeRepo, project = ".") {
   const options = config.compilerOptions || {};
   const toSlash = (value) => value.split(path.sep).join("/");
   const file = path.resolve(project, "tsconfig.store.json");
+  // the npm packages the store shares at runtime (next-intl, lodash, ...): never installed in the package (the build uses
+  // the store's copy), so their types come from the store's own node_modules, at the store's version
+  const repo = path.dirname(base);
+  const sharedPaths = {};
+  for (const pkg of storeSharedPackages(repo)) {
+    const types = path.join(repo, "node_modules", "@types", pkg.replace(/^@/, "").replace("/", "__"));
+    const dir = path.join(repo, "node_modules", pkg);
+    if (fs.existsSync(path.join(types, "package.json"))) sharedPaths[pkg] = [toSlash(types)];
+    else if (fs.existsSync(path.join(dir, "package.json"))) {
+      sharedPaths[pkg] = [toSlash(dir)];
+      sharedPaths[`${pkg}/*`] = [`${toSlash(dir)}/*`];
+    }
+  }
   const linked = {
     extends: "znode-plugin/tsconfig.json",
-    compilerOptions: { baseUrl: toSlash(path.resolve(path.dirname(base), options.baseUrl || ".")), paths: options.paths || {} },
+    compilerOptions: { baseUrl: toSlash(path.resolve(repo, options.baseUrl || ".")), paths: { ...sharedPaths, ...(options.paths || {}) } },
   };
   fs.writeFileSync(file, JSON.stringify(linked, null, 2) + "\n");
-  console.log(`linked ${file} to ${base} (${Object.keys(linked.compilerOptions.paths).length} store aliases)`);
+  const shared = Object.keys(sharedPaths).filter((key) => !key.endsWith("/*"));
+  console.log(
+    `linked ${file} to ${base} (${Object.keys(options.paths || {}).length} store aliases${shared.length ? `; types of the packages the store shares: ${shared.join(", ")}` : ""})`
+  );
+}
+
+// ---- the store's npm packages: shared at runtime, or installed in the package at the store's version -------------------
+// react, react-dom, next and @znode/* are the store's at runtime (stand-ins, never bundled); so are the store's shared
+// packages (its registry's sharedPackages: next-intl, lodash, ...). Any other npm package a package imports is bundled
+// into it, so it must be installed in the package: at the version the store has installed, so a copied store component
+// behaves as it does in the store. Installed exactly (no ^), from the npm registry, by eject and by build.
+const RUNTIME_PROVIDED = /^(react|react-dom|next|@znode)(\/|$)/;
+const DEFAULT_SHARED = ["lodash", "next-intl"];
+const packageNameOf = (spec) => (spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0]);
+
+function storeSharedPackages(root) {
+  for (const name of ["store-module-registry.json", "store-server-module-registry.json"]) {
+    const file = path.join(root, "packages/extensions", name);
+    try {
+      const list = readJson(file).sharedPackages;
+      if (Array.isArray(list) && list.length) return list.map(String);
+    } catch {
+      // no registry, or one from before sharedPackages: the default list
+    }
+  }
+  return DEFAULT_SHARED;
+}
+
+// the version the store has installed (its node_modules), else its package.json range without ^ / ~
+function storePackageVersion(root, pkg) {
+  try {
+    return readJson(path.join(root, "node_modules", pkg, "package.json")).version;
+  } catch {
+    try {
+      const manifest = readJson(path.join(root, "package.json"));
+      const range = { ...(manifest.devDependencies || {}), ...(manifest.dependencies || {}) }[pkg];
+      return range ? range.replace(/^[\^~]/, "") : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+const installedIn = (project, pkg) => fs.existsSync(path.join(project, "node_modules", pkg, "package.json"));
+
+// the npm packages code imports (bare specifiers, type-only imports included: their types are needed too)
+const npmImportsOf = (code) =>
+  [...code.matchAll(/(?:^|[^\w$.])(?:import|export)\s*(?:[^"';]*?\s+from\s*)?["']([^"'.][^"']*)["']|import\(\s*["']([^"'.][^"']*)["']\s*\)/g)]
+    .map((match) => match[1] || match[2])
+    .filter((spec) => !spec.startsWith("node:") && !builtinModules.includes(packageNameOf(spec)));
+
+/**
+ * The npm packages `specs` need in the package at `project`: the store's runtime and shared packages are left out, the
+ * others not installed yet are installed at the store's version (with their @types package when the store has one), or
+ * only named when install is false. Returns what was done, for the caller's message.
+ */
+function ensureStorePackages(project, store, specs, { install = true } = {}) {
+  const root = store.root;
+  const shared = new Set(storeSharedPackages(root));
+  const wanted = new Map();
+  const typesWanted = new Map();
+  const notInStore = new Set();
+  const sharedUsed = new Set();
+  for (const pkg of new Set(specs.map(packageNameOf))) {
+    if (RUNTIME_PROVIDED.test(pkg)) continue;
+    if (shared.has(pkg)) {
+      sharedUsed.add(pkg);
+      continue;
+    }
+    if (installedIn(project, pkg)) continue;
+    const version = storePackageVersion(root, pkg);
+    if (!version) {
+      notInStore.add(pkg);
+      continue;
+    }
+    wanted.set(pkg, `${pkg}@${version}`);
+    const typesName = `@types/${pkg.replace(/^@/, "").replace("/", "__")}`;
+    const typesVersion = fs.existsSync(path.join(root, "node_modules", typesName, "package.json")) ? storePackageVersion(root, typesName) : null;
+    if (typesVersion && !installedIn(project, typesName)) typesWanted.set(typesName, `${typesName}@${typesVersion}`);
+  }
+  const run = (args) => spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", args, { cwd: project, stdio: "inherit", shell: process.platform === "win32" });
+  let installed = [];
+  if (wanted.size) {
+    const list = [...wanted.values()];
+    if (install) {
+      console.log(`installing the store's versions: ${list.join(" ")}`);
+      const result = run(["install", "--save-exact", "--no-audit", "--no-fund", ...list]);
+      if (result.status !== 0) fail(`npm install failed: run it yourself in ${project}: npm install --save-exact ${list.join(" ")}`);
+      if (typesWanted.size) run(["install", "--save-dev", "--save-exact", "--no-audit", "--no-fund", ...typesWanted.values()]);
+      installed = [...list, ...typesWanted.values()];
+    } else {
+      console.log(`needs the store's versions (not installed: --no-install): npm install --save-exact ${list.join(" ")}`);
+      if (typesWanted.size) console.log(`  and its types: npm install --save-dev --save-exact ${[...typesWanted.values()].join(" ")}`);
+    }
+  }
+  for (const pkg of notInStore) console.log(`warning "${pkg}" is not a dependency of the store: install it yourself (npm install ${pkg})`);
+  return { installed, shared: [...sharedUsed], notInStore: [...notInStore] };
+}
+
+// packages installed in the package at another version than the store's (after a store upgrade): a warning, the store's
+// version is what its components were written against
+function versionDrift(project, store, specs) {
+  const drift = [];
+  for (const pkg of new Set(specs.map(packageNameOf))) {
+    if (RUNTIME_PROVIDED.test(pkg) || !installedIn(project, pkg)) continue;
+    const mine = readJson(path.join(project, "node_modules", pkg, "package.json")).version;
+    const theirs = fs.existsSync(path.join(store.root, "node_modules", pkg, "package.json")) ? storePackageVersion(store.root, pkg) : null;
+    if (theirs && mine !== theirs) drift.push(`${pkg} ${mine} (store: ${theirs})`);
+  }
+  return drift;
 }
 
 // ---- eject: a store component copied into the package, in place of the store's, through its slot ----------------
@@ -753,8 +919,25 @@ function ejectableComponents(root) {
   return found.sort((a, b) => a.name.localeCompare(b.name));
 }
 
-// a store file's import path as the package can import it: the store alias that maps to that file, without extension
-function storeAlias(store, absolute) {
+// a store file that re-exports `target` (export * from / export { … } from), followed through nested barrels
+function reExports(barrel, target, seen = new Set()) {
+  if (!barrel || seen.has(barrel) || !fs.existsSync(barrel)) return false;
+  seen.add(barrel);
+  const asFile = (base) =>
+    [base, `${base}.ts`, `${base}.tsx`, path.join(base, "index.ts"), path.join(base, "index.tsx")].find((file) => fs.existsSync(file) && fs.statSync(file).isFile());
+  for (const match of fs.readFileSync(barrel, "utf8").matchAll(/export\s*(?:\*|\{[^}]*\})\s*from\s*["'](\.{1,2}\/[^"']+)["']/g)) {
+    const file = asFile(path.resolve(path.dirname(barrel), match[1]));
+    if (!file) continue;
+    if (file.split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "") === target) return true;
+    if (reExports(file, target, seen)) return true;
+  }
+  return false;
+}
+
+// a store file's import path as the package can import it: the store alias that maps to that file, without extension;
+// else, for named imports (statement: the import's text up to its path), an exact alias whose barrel re-exports the file
+// (".../stores/modal" -> "@znode/base-components/stores"): export * does not carry a default, so a default import is not
+function storeAlias(store, absolute, { statement = "" } = {}) {
   const target = absolute.split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
   let best = null;
   const norm = (value) => path.resolve(store.root, value).split(path.sep).join("/").replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
@@ -769,7 +952,14 @@ function storeAlias(store, absolute) {
       if (target.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) best = { prefix, alias: alias.slice(0, -1) };
     }
   }
-  return best ? best.alias + target.slice(best.prefix.length) : null;
+  if (best) return best.alias + target.slice(best.prefix.length);
+  const namedOnly = /^import\s*(?:type\s+)?\{/.test(statement.trim()) || /^export\s/.test(statement.trim());
+  if (!namedOnly) return null;
+  for (const [alias, targets] of Object.entries(store.paths)) {
+    if (alias.endsWith("/*") || !alias.startsWith("@znode/")) continue;
+    if (targets.some((pattern) => reExports(path.resolve(store.root, pattern), target))) return alias;
+  }
+  return null;
 }
 
 // a question on the terminal (only asked when stdin is a terminal); one line reader for the whole run, so answers
@@ -798,10 +988,85 @@ const suggestSlot = (name) => {
 // eject a store page (a server slot around a route's content): not a copy of the route (its server code, agents and
 // data stay the store's), a server component of the package's own in src/server/pages/<Page>.tsx, registered under the
 // slot in src/server.tsx, that renders the store's page content (children) to start with
-function ejectServerSlot(project, s, force) {
+// A whole route (withRuntimeServerPage): a COPY of the route instead, as component eject copies a component: the route's
+// file with its function as `export async function <Page>(props, context)` (props: the route's params and searchParams,
+// children: the store's page), its imports as the store's aliases, which a server part imports from the store's server
+// registry (permission storeServer, added to znode-package.json).
+function ejectRouteCopy(project, s, store) {
+  const name = s.page;
+  const storeFile = path.join(store.root, s.files[0]);
+  let text = fs.readFileSync(storeFile, "utf8");
+  // the copy is the plain page: no wrapper (the slot is what puts it in place)
+  text = text.replace(/^import\s*\{\s*withRuntimeServerPage\s*\}\s*from\s*["'][^"']+["'];?[ \t]*\r?\n/m, "");
+  text = text.replace(/(?:^\/\/ runtime packages render the whole page instead[^\n]*\n(?:\/\/[^\n]*\n)*)?^export\s+default\s+withRuntimeServerPage\([^)]*\);?[ \t]*\r?\n?/m, "");
+  text = text.replace(new RegExp(`^(async\\s+)?function\\s+${s.base}\\s*\\(`, "m"), (whole, isAsync) => `export ${isAsync || ""}function ${name}(`);
+  // relative imports become the store's aliases (the package lives elsewhere)
+  const warnings = [];
+  text = text.replace(/((?:from|import)\s*\(?\s*["'])(\.{1,2}\/[^"']+)(["'])/g, (whole, before, spec, after, offset, source) => {
+    const alias = storeAlias(store, path.resolve(path.dirname(storeFile), spec), { statement: source.slice(source.lastIndexOf("import", offset), offset) });
+    if (!alias) {
+      warnings.push(`import ${spec}: no store alias for it; change it by hand`);
+      return whole;
+    }
+    return `${before}${alias}${after}`;
+  });
+  const header =
+    `// Ejected from the store: ${s.files[0]} (${new Date().toISOString().slice(0, 10)}), with \`znode eject ${name}\`: a copy of the\n` +
+    `// whole route. The store renders it instead of its own page through the server slot "${s.name}" (src/server.tsx\n` +
+    `// serverSlots), on the server only. props: the route's params and searchParams, and children (the store's page);\n` +
+    `// context (second argument): store, settings. Its @znode imports come from the store's server registry (permission\n` +
+    `// storeServer): agents, texts and store context, the server logger, client components. It is yours now: the store's\n` +
+    `// later changes to this page do not reach it, so compare it with ${s.files[0]} after a store upgrade.\n`;
+  text = header + text;
+
+  // what the store's server registry does not allow: named now, the build stops on it too
+  if (store.serverRegistry) {
+    const allowed = new Set(store.serverRegistry);
+    for (const m of text.matchAll(/^\s*import\s+(?!type\b)[^;]*?from\s*["'](@znode\/[^"']+)["']/gm)) {
+      if (m[1].startsWith("@znode/types/")) continue;
+      const file = (() => {
+        for (const [alias, [target]] of Object.entries(store.paths)) {
+          if (alias.endsWith("/*") && m[1].startsWith(alias.slice(0, -1))) return target.replace("*", m[1].slice(alias.length - 1));
+          if (alias === m[1]) return target;
+        }
+        return null;
+      })();
+      const key = file && file.replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+      // a barrel (utils/server's index, a component folder) is checked name by name at build time, each name from the file
+      // that defines it; only a module that is not a barrel and not allowed is named here
+      const barrel = /\/index\.tsx?$/.test(file || "") || [...allowed].some((allowedKey) => allowedKey.startsWith(`${key}/`));
+      if (key && !allowed.has(key) && !barrel) warnings.push(`${m[1]}: not in the store's server registry; the build will stop on it (use an agent or context.znode instead)`);
+    }
+  } else warnings.push("the linked store has no server registry (packages/extensions/store-server-module-registry.json): update the store, or the build stops on the copy's @znode imports");
+
+  // the permission it needs
+  const manifestFile = path.join(project, MANIFEST);
+  const manifest = readJson(manifestFile);
+  if (!(manifest.permissions || []).includes("storeServer")) {
+    manifest.permissions = [...(manifest.permissions || []), "storeServer"];
+    fs.writeFileSync(manifestFile, JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`added "storeServer" to "permissions" in ${MANIFEST} (its server part imports store modules)`);
+  }
+  return { text, warnings };
+}
+
+function ejectServerSlot(project, s, force, store, noInstall = false) {
   const name = s.page;
   const out = path.join(project, "src", "server", "pages", `${name}.tsx`);
   if (fs.existsSync(out) && !force) fail(`${path.relative(project, out)} exists: delete it or run znode eject ${name} --force`);
+  if (s.route) {
+    const { text, warnings } = ejectRouteCopy(project, s, store);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, text);
+    console.log(`ejected ${name} (a copy of ${s.files[0]}, server slot "${s.name}") -> ${path.relative(project, out)}`);
+    registerServerSlot(project, s, name);
+    const deps = ensureStorePackages(project, store, npmImportsOf(text), { install: !noInstall });
+    if (deps.installed.length) console.log(`installed (store versions): ${deps.installed.join(", ")}`);
+    if (deps.shared.length) console.log(`shared by the store (not installed; types from the linked store): ${deps.shared.join(", ")}`);
+    for (const warning of warnings) console.log(`warning ${warning}`);
+    console.log(`\nNext: edit ${path.relative(project, out)}, then npm run build (it names any store import a server part cannot use) and npm run dev.`);
+    return;
+  }
   const route = s.components[0] || name;
   const text =
     `import type { ReactNode } from "react";\n` +
@@ -822,36 +1087,41 @@ function ejectServerSlot(project, s, force) {
   fs.writeFileSync(out, text);
   console.log(`ejected ${name} (server slot "${s.name}") -> ${path.relative(project, out)}`);
 
+  registerServerSlot(project, s, name);
+  console.log(`\nNext: edit ${path.relative(project, out)}, then npm run build and npm run dev and open the page.`);
+}
+
+// src/server.tsx: import { <Page> as Ejected<Page> } from "./server/pages/<Page>.js" and serverSlots: { "<slot>": … }
+function registerServerSlot(project, s, name) {
   const server = path.join(project, "src", "server.tsx");
   const local = `Ejected${name}`;
   const importLine = `import { ${name} as ${local} } from "./server/pages/${name}.js";`;
   const entry = `"${s.name}": ${local},`;
   if (!fs.existsSync(server)) {
     console.log(`warning src/server.tsx not found: register it yourself: ${importLine}  and  serverSlots: { ${entry} }`);
-  } else {
-    let source = fs.readFileSync(server, "utf8");
-    if (new RegExp(`["']${s.name.replace(/\./g, "\\.")}["']\\s*:`).test(source)) {
-      console.log(`warning src/server.tsx already fills "${s.name}": point it at ${local} (${importLine}) yourself`);
-    } else {
-      if (/serverSlots\s*:\s*\{/.test(source)) source = source.replace(/serverSlots\s*:\s*\{/, `serverSlots: {\n    // ejected (znode eject ${name}): the store renders this around / instead of its page\n    ${entry}`);
-      else if (/apiVersion\s*:\s*\d+\s*,/.test(source)) source = source.replace(/(apiVersion\s*:\s*\d+\s*,)/, `$1\n  serverSlots: {\n    ${entry}\n  },`);
-      else {
-        console.log(`warning no "serverSlots" in src/server.tsx: add ${importLine} and serverSlots: { ${entry} }`);
-        source = null;
-      }
-      if (source) {
-        const imports = [...source.matchAll(/^import [^;]+;[ \t]*$/gm)];
-        const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
-        source = source.slice(0, at) + `\n${importLine}` + source.slice(at);
-        fs.writeFileSync(server, source);
-        console.log(`registered "${s.name}": ${local} in src/server.tsx (serverSlots)`);
-      }
-    }
+    return;
   }
-  console.log(`\nNext: edit ${path.relative(project, out)}, then npm run build and npm run dev and open the page.`);
+  let source = fs.readFileSync(server, "utf8");
+  if (new RegExp(`["']${s.name.replace(/\./g, "\\.")}["']\\s*:`).test(source)) {
+    console.log(`warning src/server.tsx already fills "${s.name}": point it at ${local} (${importLine}) yourself`);
+    return;
+  }
+  if (/serverSlots\s*:\s*\{/.test(source)) source = source.replace(/serverSlots\s*:\s*\{/, `serverSlots: {\n    // ejected (znode eject ${name}): the store renders this around / instead of its page\n    ${entry}`);
+  else if (/apiVersion\s*:\s*\d+\s*,/.test(source)) source = source.replace(/(apiVersion\s*:\s*\d+\s*,)/, `$1\n  serverSlots: {\n    ${entry}\n  },`);
+  else {
+    console.log(`warning no "serverSlots" in src/server.tsx: add ${importLine} and serverSlots: { ${entry} }`);
+    return;
+  }
+  if (!source.includes(importLine)) {
+    const imports = [...source.matchAll(/^import [^;]+;[ \t]*$/gm)];
+    const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
+    source = source.slice(0, at) + `\n${importLine}` + source.slice(at);
+  }
+  fs.writeFileSync(server, source);
+  console.log(`registered "${s.name}": ${local} in src/server.tsx (serverSlots)`);
 }
 
-async function eject(name, force, { slot: slotArg, yes } = {}) {
+async function eject(name, force, { slot: slotArg, yes, noInstall } = {}) {
   const project = path.resolve(".");
   if (!fs.existsSync(path.join(project, MANIFEST))) fail(`run znode eject in a package folder (the one with ${MANIFEST})`);
   const store = linkedStore(project);
@@ -862,20 +1132,22 @@ async function eject(name, force, { slot: slotArg, yes } = {}) {
     for (const c of components) console.log(`  ${c.name.padEnd(34)} ${c.slot.padEnd(26)} ${path.relative(store.root, c.file).split(path.sep).join("/")}`);
     const pages = storeSlots(store.root).filter((s) => s.page);
     if (pages.length) {
-      console.log("\nStore pages (server slot around the page's content; you get a server starter in src/server/pages/):\n");
-      for (const s of pages) console.log(`  ${s.page.padEnd(34)} ${s.name.padEnd(26)} ${s.files[0]}`);
+      console.log("\nStore pages (server slot: a whole route is copied, a slot inside a page gives a starter; src/server/pages/):\n");
+      for (const s of pages) console.log(`  ${s.page.padEnd(34)} ${s.name.padEnd(26)} ${s.route ? "whole route, copy " : "inside the page    "} ${s.files[0]}`);
     }
-    console.log("\nznode eject <Name>   copies one into src/components/ (or a page starter into src/server/pages/) and registers it");
+    console.log("\nznode eject <Name>   copies one into src/components/ (a page into src/server/pages/) and registers it");
     return;
   }
   const find = (list) => list.find((item) => item.name.toLowerCase() === name.toLowerCase() || item.slot.toLowerCase() === name.toLowerCase());
-  // a route page with a server slot around its content: the package gets a server starter for it (src/server.tsx)
-  const findServer = () =>
-    storeSlots(store.root).find((s) => s.page && [s.page.toLowerCase(), s.name.toLowerCase()].includes(name.toLowerCase()));
+  // a route page with a server slot: around the whole route (a copy of the route), else inside it (a starter)
+  const findServer = () => {
+    const pages = storeSlots(store.root).filter((s) => s.page && [s.page.toLowerCase(), s.name.toLowerCase()].includes(name.toLowerCase()));
+    return pages.find((s) => s.route) || pages[0];
+  };
   let c = find(components);
   if (!c) {
     const server = findServer();
-    if (server) return ejectServerSlot(project, server, force);
+    if (server) return ejectServerSlot(project, server, force, store, noInstall);
   }
   if (!c) {
     // no slot hands this component over yet: offer to create one in the base store (what znode create-slot does), then eject
@@ -907,7 +1179,7 @@ async function eject(name, force, { slot: slotArg, yes } = {}) {
       const server = findServer();
       if (server) {
         console.log("");
-        return ejectServerSlot(project, server, force);
+        return ejectServerSlot(project, server, force, store, noInstall);
       }
       fail(`the slot "${slot}" was created, but ${name} is still not found as ejectable; check the store diff`);
     }
@@ -919,15 +1191,15 @@ async function eject(name, force, { slot: slotArg, yes } = {}) {
   const warnings = [];
   let text = fs.readFileSync(c.file, "utf8");
   // relative imports become the store's aliases (the package lives elsewhere); a style file stays the store's
-  text = text.replace(/((?:from|import)\s*\(?\s*["'])(\.{1,2}\/[^"']+)(["'])/g, (whole, before, spec, after) => {
+  text = text.replace(/((?:from|import)\s*\(?\s*["'])(\.{1,2}\/[^"']+)(["'])/g, (whole, before, spec, after, offset, source) => {
     const absolute = path.resolve(path.dirname(c.file), spec);
     if (/\.(s?css)$/.test(spec)) {
       warnings.push(`style import ${spec}: kept out of the copy; the store's own stylesheet is loaded where the store renders it, add your CSS to src/styles/`);
       return `${before}${spec}${after}`;
     }
-    const alias = storeAlias(store, fs.existsSync(absolute) || /\.\w+$/.test(spec) ? absolute : absolute);
+    const alias = storeAlias(store, absolute, { statement: source.slice(source.lastIndexOf("import", offset), offset) });
     if (!alias) {
-      warnings.push(`import ${spec}: no store alias for it; change it by hand`);
+      warnings.push(`import ${spec}: no store alias for it (nor a store barrel that re-exports its names); change it by hand`);
       return whole;
     }
     return `${before}${alias}${after}`;
@@ -946,32 +1218,11 @@ async function eject(name, force, { slot: slotArg, yes } = {}) {
   fs.writeFileSync(out, text);
   console.log(`ejected ${c.name} -> ${path.relative(project, out)}`);
 
-  // npm packages the copy imports that this package does not have (react, next and the store's @znode modules come from
-  // the store): install them at the store's version, so the types match and the build finds them
-  const PROVIDED = /^(react|react-dom|next|next-intl|@znode)(\/|$)/;
-  const storePackage = (() => {
-    try {
-      return readJson(path.join(store.root, "package.json"));
-    } catch {
-      return {};
-    }
-  })();
-  const storeDeps = { ...(storePackage.devDependencies || {}), ...(storePackage.dependencies || {}) };
-  const missing = new Map();
-  for (const m of text.matchAll(/(?:from|import)\s*\(?\s*["']([^."'/][^"']*)["']/g)) {
-    const spec = m[1];
-    if (PROVIDED.test(spec)) continue;
-    const pkg = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
-    try {
-      createRequire(path.join(project, "package.json")).resolve(`${pkg}/package.json`);
-    } catch {
-      missing.set(pkg, storeDeps[pkg] ? `${pkg}@${storeDeps[pkg].replace(/^[\^~]/, "")}` : pkg);
-    }
-  }
-  if (missing.size) {
-    console.log(`\nThe copy imports npm packages this package does not have (bundled into the package when it builds):`);
-    console.log(`  npm install ${[...missing.values()].join(" ")}`);
-  }
+  // npm packages the copy imports: the store's shared ones are used from the store (types through link-store), the others
+  // are installed in this package at the store's version (bundled into the package when it builds)
+  const deps = ensureStorePackages(project, store, npmImportsOf(text), { install: !noInstall });
+  if (deps.installed.length) console.log(`installed (store versions): ${deps.installed.join(", ")}`);
+  if (deps.shared.length) console.log(`shared by the store (not installed; types from the linked store): ${deps.shared.join(", ")}`);
 
   // register the copy under the slot in src/browser.tsx
   const browser = path.join(project, "src", "browser.tsx");
@@ -1064,53 +1315,30 @@ function openTagEnd(text, start) {
   return -1;
 }
 
-// A route page gets a server slot around what it returns: <RuntimeServerSlot name="…"> … </RuntimeServerSlot>, inside a
-// NextIntlClientProvider at the top (so the slot's components, and the store's, keep the page's texts). A package fills
-// it in src/server.tsx (serverSlots): it gets the page's content as children and the store / settings as context.
+// A route page gets a server slot around the WHOLE route: its function becomes <Name>Base and the default export is
+// withRuntimeServerPage("<slot>", <Name>Base) (packages/extensions/src/with-runtime-server-page.tsx), the server version of
+// withRuntimeWrapper. A package that fills the slot (src/server.tsx serverSlots) gets the route's props (params,
+// searchParams) and the store's page as children, and renders the page instead: `znode eject <Name>` gives it a copy of
+// the route to start from. The route's data loading, texts and metadata stay the store's when no package fills it.
+const SERVER_PAGE_WRAPPER = "@znode/extensions/with-runtime-server-page";
 function routeServerSlot(file, name, slot, rel) {
   const before = fs.readFileSync(file, "utf8");
   if (/^\s*["']use client["']/.test(before)) fail(`${rel(file)} is a client page ("use client"): a server slot cannot go there; add a <RuntimeSlot> by hand`);
-  const fnAt = before.search(new RegExp(`export\\s+default\\s+(?:async\\s+)?function\\s+${name}\\s*\\(`));
-  const existing = before.slice(fnAt).match(/<RuntimeServerSlot\s+name=["']([\w.]+)["']/);
-  if (existing) fail(`${name} (${rel(file)}) already has the server slot "${existing[1]}": fill that one (npx znode slot list)`);
-  const ret = before.lastIndexOf("return (");
-  if (ret < fnAt) fail(`${name} (${rel(file)}) does not end with return (<…>): put <RuntimeServerSlot name="${slot}"> around its content by hand`);
-  const open = ret + "return ".length;
-  const close = closingParen(before, open);
-  if (close < 0) fail(`${rel(file)}: could not find the end of ${name}'s return (…): put <RuntimeServerSlot name="${slot}"> around its content by hand`);
-  let start = open + 1;
-  let end = close;
-  const providerAt = before.slice(start, end).search(/^\s*<NextIntlClientProvider\b/);
-  if (providerAt === 0) {
-    const tagStart = before.indexOf("<NextIntlClientProvider", start);
-    const tagClose = before.lastIndexOf("</NextIntlClientProvider>", close);
-    const tagEnd = openTagEnd(before, tagStart);
-    if (tagEnd > 0 && tagClose > tagEnd && before[tagEnd - 1] !== "/") {
-      start = tagEnd + 1;
-      end = tagClose;
-    }
-  }
-  const inner = before.slice(start, end);
-  const lead = inner.match(/^\s*/)[0];
-  const trail = inner.match(/\s*$/)[0];
-  const core = inner.slice(lead.length, inner.length - trail.length);
-  const indent = lead.includes("\n") ? lead.slice(lead.lastIndexOf("\n") + 1) : "";
-  const body = core
-    .split("\n")
-    .map((line, i) => (i === 0 || !line.trim() ? line : `  ${line}`))
-    .join("\n");
-  const wrapped = `${lead}<RuntimeServerSlot name="${slot}">\n${indent}  ${body}\n${indent}</RuntimeServerSlot>${trail}`;
-  let after = before.slice(0, start) + wrapped + before.slice(end);
-  // a note above the return, and the import
-  // (the text up to the return is unchanged, so its position still holds)
-  const lineStart = before.lastIndexOf("\n", ret) + 1;
-  const retIndent = before.slice(lineStart, ret);
-  after = after.slice(0, lineStart) + `${retIndent}// runtime packages: server components around the page's content (server slot ${slot}, znode create-slot)\n` + after.slice(lineStart);
-  if (!/import\s*\{[^}]*\bRuntimeServerSlot\b/.test(after)) {
-    const imports = [...after.matchAll(/^import [^;]+;[ \t]*$/gm)];
-    const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
-    after = after.slice(0, at) + `${at ? "\n" : ""}import { RuntimeServerSlot } from "@znode/extensions/RuntimeServerSlot";${at ? "" : "\n"}` + after.slice(at);
-  }
+  const wrapped = before.match(/withRuntimeServerPage\(\s*["']([\w.]+)["']/);
+  if (wrapped) fail(`${name} (${rel(file)}) already has the server slot "${wrapped[1]}" around the whole route: fill or eject that one (npx znode eject ${name})`);
+  const definition = new RegExp(`export\\s+default\\s+(async\\s+)?function\\s+${name}\\s*\\(`);
+  const match = before.match(definition);
+  if (!match) fail(`${rel(file)}: no "export default function ${name}(" to wrap`);
+  const baseName = `${name}Base`;
+  if (new RegExp(`\\b${baseName}\\b`).test(before)) fail(`${rel(file)} already has a ${baseName}: wrap it by hand`);
+  let after = before.replace(definition, `${match[1] || ""}function ${baseName}(`);
+  after =
+    after.trimEnd() +
+    `\n\n// runtime packages render the whole page instead through the server slot "${slot}" (znode create-slot; src/server.tsx\n` +
+    `// serverSlots); with none, it renders as it is\nexport default withRuntimeServerPage("${slot}", ${baseName});\n`;
+  const imports = [...after.matchAll(/^import [^;]+;[ \t]*$/gm)];
+  const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length : 0;
+  after = after.slice(0, at) + `${at ? "\n" : ""}import { withRuntimeServerPage } from "${SERVER_PAGE_WRAPPER}";${at ? "" : "\n"}` + after.slice(at);
   return { file, before, after };
 }
 
@@ -1234,7 +1462,7 @@ function createSlot(name, slot, { dryRun, file: chosen, fromEject } = {}) {
         end,
         0,
         isRoute
-          ? `//   ${slot.padEnd(20)} (server slot, src/server.tsx serverSlots) the ${where} route's content (children) (znode create-slot)`
+          ? `//   ${slot.padEnd(20)} (server slot, src/server.tsx serverSlots) the whole ${where} route (withRuntimeServerPage)  props: params, searchParams; children = the store's page (znode create-slot)`
           : `//   ${slot.padEnd(20)} the store's ${name} itself (children)  props: every prop ${name} gets (znode create-slot)`
       );
       changes.push({ file: typesFile, before, after: lines.join("\n") });
@@ -1252,7 +1480,7 @@ function createSlot(name, slot, { dryRun, file: chosen, fromEject } = {}) {
         row + 1,
         0,
         isRoute
-          ? `| \`${slot}\` (server slot) | none: \`<RuntimeServerSlot>\` written directly in \`${rel(target)}\` (znode create-slot) | the ${where} route's content (\`${name}\`) | none (context: store, settings); keep \`children\`, wrap it, or render your own page (\`znode eject ${name}\`) |`
+          ? `| \`${slot}\` (server slot) | \`withRuntimeServerPage\` (\`with-runtime-server-page.tsx\`) on the route's default export in \`${rel(target)}\` (znode create-slot) | the whole ${where} route (\`${name}\`, its children: the store's page) | the route's props (params, searchParams); context: store, settings; keep \`children\`, wrap it, or render a copy of the page (\`znode eject ${name}\`, permission storeServer) |`
           : `| \`${slot}\` | \`${wrapper}\` (\`${CREATED_SLOTS_FILE.replace("packages/extensions/src/", "")}\`) | \`${where}\` (its children: the component itself) | every ${name} prop; keep \`children\`, wrap it, or render a copy instead (\`znode eject ${name}\`) |`
       );
       changes.push({ file: docsFile, before, after: lines.join("\n") });
@@ -1350,6 +1578,16 @@ function storeSlots(root) {
         files: [relFile],
       });
     }
+    // a whole route with its server slot around it: export default withRuntimeServerPage("<slot>", <Page>Base) in a route
+    // file; `znode eject <Page>` copies the route into the package
+    const relFile = path.relative(root, file).split(path.sep).join("/");
+    if (/^apps\/[^/]+\/src\/app\//.test(relFile)) {
+      for (const m of text.matchAll(/export\s+default\s+withRuntimeServerPage\(\s*["']([\w.]+)["']\s*,\s*(\w+)\s*\)/g)) {
+        const page = m[2].replace(/Base$/, "");
+        const where = "app/" + relFile.replace(/^apps\/[^/]+\/src\/app\/(\[locale\]\/)?/, "").replace(/\.tsx$/, "");
+        slots.set(m[1], { name: m[1], side: "server", handsOver: true, wrapper: null, components: [`${page} (${where}, whole route)`], page, route: true, base: m[2], eject: page, files: [relFile] });
+      }
+    }
   }
   return [...slots.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -1426,7 +1664,11 @@ if (command === "eject") {
   // eject <Name> [--force] [--slot <area.name>] [--yes]: --slot / --yes create a missing slot without asking
   const slotAt = args.indexOf("--slot");
   const name = args.find((arg, index) => index > 0 && !arg.startsWith("-") && !(slotAt >= 0 && index === slotAt + 1));
-  await eject(name, args.includes("--force"), { slot: slotAt >= 0 ? args[slotAt + 1] : undefined, yes: args.includes("--yes") || args.includes("-y") });
+  await eject(name, args.includes("--force"), {
+    slot: slotAt >= 0 ? args[slotAt + 1] : undefined,
+    yes: args.includes("--yes") || args.includes("-y"),
+    noInstall: args.includes("--no-install"),
+  });
   process.exit(0);
 }
 if (command === "link-store") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "znode-plugin",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
   "license": "UNLICENSED",
   "type": "module",