znode-plugin 0.1.7 → 0.1.8

package/README.md

@@ -217,9 +217,113 @@ export default function setup(host: IBrowserHost): IBrowserPlugin {
 }
 ```
 
-**Slots:** `layout.header`, `layout.footer`, `header.search`, `product.card`, `product.image`, `product.variants`,
-`product.addToCart`, `product.layout`, `product.basicInfo`, `productList.layout`, `addToCart.notification`, `login.form`,
-`checkout.address`, `checkout.shippingOptions`. Server slots (in `server.tsx`): `layout.root`, `login.layout`, `login.page`.
+**Which slots are there?** Ask the store you are linked to; the list is read from its source, so it is always current:
+
+```bash
+npx znode slot list            # every slot
+npx znode slots product        # only the ones matching "product"
+```
+
+```
+  Slot                Side     Hands over  Store component   Eject             In this package
+  ------------------  -------  ----------  ----------------  ----------------  ---------------
+  product.basicInfo   browser  yes         ProductBasicInfo  ProductBasicInfo  yes
+  product.card        browser  yes         ProductCard       ProductCard
+  product.layout      browser  no          ProductBasicInfo  -
+  layout.root         server   yes         app/layout        -                 yes
+  ...
+```
+
+- **Side**: `browser` slots go in `src/browser.tsx` (`slots`), `server` slots in `src/server.tsx` (`serverSlots`).
+- **Hands over**: `yes` = your component gets the store's rendering as `children` (keep, wrap or replace it); `no` = it
+  adds or lays out (e.g. `product.layout` moves the store's parts into your structure).
+- **Eject**: the store component you can copy into your package (next section). **In this package**: you already fill it.
+
+### Take over a whole store component (eject)
+
+When a slot is not enough and you want to change the component itself (its markup, its logic), copy it into your
+package. The store then renders your copy in its place; everything else stays the store's.
+
+```bash
+npx znode eject ProductBasicInfo      # or by its slot: npx znode eject product.basicInfo
+```
+
+It copies the store's file to `src/components/ProductBasicInfo.tsx` (imports turned into the store's `@znode/...`
+aliases), registers it in `src/browser.tsx` under its slot, and prints any npm package the copy needs
+(`npm install zustand@4.5.5`). Edit the copy, then `npm run build` and `npm run dev`. The copy is yours: store fixes to
+the component no longer reach it, so compare it with the store's file after a store upgrade. `npx znode eject` with no
+name lists what can be ejected.
+
+**The component has no slot yet?** `eject` offers to create one in the **base store** (the store you linked), then ejects:
+
+```
+$ npx znode eject ProductDetailsPage
+ProductDetailsPage has no slot yet, so it cannot be ejected.
+Create a slot for ProductDetailsPage in the base store now? [y/N] y
+Slot name (area.name) [product.detailsPage]: product.details
+creating slot "product.details" around ProductDetailsPage (packages/base-components/src/...) ...
+ejected ProductDetailsPage -> src/components/ProductDetailsPage.tsx
+registered "product.details": EjectedProductDetailsPage in src/browser.tsx
+```
+
+Creating a slot edits the base store's **source** (a `Runtime<Component>` wrapper in
+`packages/extensions/src/slots/RuntimeCreatedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the
+slot added to the store's slot list and docs). It never touches `.next` and commits nothing. Before the store renders
+your copy: review the diff in the store repo (`git diff`), commit it there through the store's own flow (it changes base
+components, so it is reviewed like any base change), and rebuild / restart the webstore.
+
+- In a script or CI (no questions): `npx znode eject ProductDetailsPage --slot product.details`.
+- Only the slot, no copy: `npx znode create-slot ProductDetailsPage product.details`; add `--dry-run` first to see
+  exactly which store files and lines it would change, without writing anything.
+- A server **component** inside base-components cannot get a slot (a browser slot is filled in the browser): it refuses
+  an `async` component or one that imports `server-only` / `next/headers` / `fs`, and says to use a client component it
+  renders instead, e.g. `ProductDetails` is a server component, so take over `ProductBasicInfo` or `ProductDetailsPage`.
+
+### 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>`):
+
+```
+$ 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]:
+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
+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):
+
+```tsx
+<NextIntlClientProvider messages={...}>
+  <RuntimeServerSlot name="forgotPassword.page">
+    <ForgotPassword />
+  </RuntimeServerSlot>
+</NextIntlClientProvider>
+```
+
+In your package you get a server component to build the page in. `children` is the store's page content:
+
+```tsx
+// src/server/pages/ForgotPasswordPage.tsx
+export async function ForgotPasswordPage(props: { children?: ReactNode }, context: IServerSlotContext) {
+  return (
+    <div className="my-forgot-page">
+      <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>
+  );
+}
+```
+
+- 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`).
+- Only the slot: `npx znode create-slot ForgotPasswordPage forgotPassword.page` (`--dry-run` to preview).
 
 ### Add a page-builder widget
 
@@ -293,8 +397,8 @@ Run them with `npm run <name>` inside a project (the scripts call `znode … .`)
 | | `npx znode create <theme\|plugin\|widget\|content> <name>` | a minimal starter of another kind |
 | | `npx znode slot list [<filter>] [--json]` | every slot the linked store renders, read from its source: browser or server side, whether it hands over what the store renders there (children: keep, wrap or replace it) or only adds / lays out, the store component it is around, what `eject` can copy into it, and whether this package already fills it. `npx znode slots` is the same; a filter matches slot or component names (`npx znode slots product`) |
 | | `npx znode eject` | list the store components a package can take over (each has a slot that hands the component over) |
-| | `npx znode create-slot <Component> <area.name> [--dry-run] [--file <store file>]` | create a slot around a store component that has none, in the **base store's source** (the linked store, not the theme, never `.next`): a `Runtime<Component>` wrapper in `packages/extensions/src/slots/RuntimeCreatedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the slot added to the store's slot list and docs, the module registry regenerated. Refuses server components (`async`, server-only imports): a slot is filled in the browser. Nothing is committed: review the diff in the store, commit it there, rebuild the webstore, then `npx znode eject <Component>`. `create slot` (with a space) works too; `add-slot` (0.1.6) still works |
-| | `npx znode eject <Name> [--force]` | `<Name>` is the component or its slot (`ProductBasicInfo` or `product.basicInfo`). Copy the store's component into `src/components/<Name>.tsx` (imports turned into store aliases, runtime wrapper removed) and register it in `src/browser.tsx` under its slot; prints any npm package the copy needs. The copy is yours: store fixes no longer reach it |
+| | `npx znode create-slot <Component> <area.name> [--dry-run] [--file <store file>]` | create a slot around a store component that has none, in the **base store's source** (the linked store, not the theme, never `.next`): a `Runtime<Component>` wrapper in `packages/extensions/src/slots/RuntimeCreatedSlots.tsx`, the component's export wrapped with `withRuntimeWrapper`, the slot added to the store's slot list and docs, the module registry regenerated. Refuses server components inside base-components (`async`, server-only imports): a browser slot is filled in the browser. For a **route page** (`<Component>` is its `export default function`, e.g. `ForgotPasswordPage`) it puts a **server slot** (`<RuntimeServerSlot>`) around the page's content instead, filled in `src/server.tsx` (`serverSlots`). Nothing is committed: review the diff in the store, commit it there, rebuild the webstore, then `npx znode eject <Component>`. `create slot` (with a space) works too; `add-slot` (0.1.6) still works |
+| | `npx znode eject <Name> [--force] [--slot <area.name>] [--yes]` | `<Name>` is the component or its slot (`ProductBasicInfo` or `product.basicInfo`). Copy the store's component into `src/components/<Name>.tsx` (imports turned into store aliases, runtime wrapper removed) and register it in `src/browser.tsx` under its slot; prints any npm package the copy needs. The copy is yours: store fixes no longer reach it. **No slot yet?** It asks whether to create one in the base store and for its name (suggested from the component, e.g. `ProductDetailsPage` → `product.detailsPage`), does what `create-slot` does, then ejects. `--slot <area.name>` creates it without asking (for scripts / CI); `--yes` skips the confirm only |
 
 The plugin folder is taken from: the command's argument, else the `RUNTIME_PLUGINS_DIR` environment variable, else
 `znode.local.json`.
@@ -372,6 +476,10 @@ folder after an upgrade; delete them by hand if you need the space.
 | `installed …` but still no change | the package went to another plugin folder than the running webstore reads: compare `znode.local.json` with the webstore's `RUNTIME_PLUGINS_DIR` (`apps/webstore/.env.local` or `.env`) |
 | `MISSING_MESSAGE` for your label | put browser labels under a namespace the page sends, e.g. `Common` |
 | Theme shows for you but not shoppers | expected: enable it in `plugins.json` (step 7) |
+| `<Name> cannot be ejected` | run it in a terminal and answer `y` to create the slot, or `npx znode eject <Name> --slot <area.name>`; `npx znode slot list` shows what exists |
+| `<Name> is an async server component` | a component inside base-components cannot get a slot: eject a client component it renders instead, or the route page it is on (`npx znode eject <Name>Page`) |
+| `no <Name> found` | use the component's name, or for a page its `export default function <Name>` (e.g. `ForgotPasswordPage`, not the URL); `npx znode slot list` shows what exists |
+| Ejected / new slot but the store still shows its own | the slot was created in the store's source: commit it there and rebuild / restart the webstore; check `npx znode slot list` shows it with **In this package** `yes` |
 
 ---
 

package/lib/znode-package.mjs

@@ -17,7 +17,8 @@
 //   znode link-store <storeRepoDir> [dir]       the store's real types: writes tsconfig.store.json (see README)
 //   znode eject   [<Name>] [--force]            in a package folder: list the store components that can be ejected, or
 //                                                copy one into src/components/ and register it in its slot
-//                                                (<Name> is the component or its slot name)
+//                                                (<Name> is the component or its slot name); no slot yet: it asks
+//                                                to create one in the base store first (--slot <area.name> / --yes)
 //   znode create-slot <Component> <area.name> [--dry-run] [--file <f>]   a slot around a store component, written into
 //                                                the linked store's source (base developers; review and commit there)
 //   znode slot list [<filter>] [--json]          every slot the linked store renders, what it hands over, what can be
@@ -771,7 +772,86 @@ function storeAlias(store, absolute) {
   return best ? best.alias + target.slice(best.prefix.length) : null;
 }
 
-function eject(name, force) {
+// a question on the terminal (only asked when stdin is a terminal); one line reader for the whole run, so answers
+// typed (or piped) ahead are kept for the next question
+let answers = null;
+async function ask(question) {
+  if (!answers) {
+    const { createInterface } = await import("node:readline");
+    answers = createInterface({ input: process.stdin })[Symbol.asyncIterator]();
+  }
+  process.stdout.write(question);
+  const { value, done } = await answers.next();
+  if (done) fail("no answer (input closed)");
+  return value.trim();
+}
+
+// a slot name suggested for a component: ForgotPasswordPage -> forgotPassword.page (a page), AddToCart -> add.toCart
+const suggestSlot = (name) => {
+  const words = name.match(/[A-Z][a-z0-9]*/g) || [name];
+  if (words.length > 1 && /^(Page|Layout)$/.test(words[words.length - 1]))
+    return `${words[0].toLowerCase()}${words.slice(1, -1).join("")}.${words[words.length - 1].toLowerCase()}`;
+  const [first, ...rest] = words;
+  return rest.length ? `${first.toLowerCase()}.${rest[0].toLowerCase()}${rest.slice(1).join("")}` : `${first.toLowerCase()}.main`;
+};
+
+// 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) {
+  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`);
+  const route = s.components[0] || name;
+  const text =
+    `import type { ReactNode } from "react";\n` +
+    `import type { IServerSlotContext } from "znode-plugin/types/extension-api";\n\n` +
+    `// Ejected with \`znode eject ${name}\` (${new Date().toISOString().slice(0, 10)}): the store's page ${route}, through its server slot\n` +
+    `// "${s.name}" (src/server.tsx serverSlots). It runs on the store's server only: it may be async and fetch data, its\n` +
+    `// output is in the page's HTML, and it has no hooks or browser code (put interactive parts in a browser slot).\n` +
+    `// children is the store's page content (${s.files[0]}): keep it, wrap it, or leave it out and render your own page.\n` +
+    `export async function ${name}(props: { children?: ReactNode }, context: IServerSlotContext) {\n` +
+    `  void context; // context.store.code, context.settings (this package's settings)\n` +
+    `  return (\n` +
+    `    <div data-page="${s.name}">\n` +
+    `      {props.children}\n` +
+    `    </div>\n` +
+    `  );\n` +
+    `}\n`;
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, text);
+  console.log(`ejected ${name} (server slot "${s.name}") -> ${path.relative(project, out)}`);
+
+  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)`);
+      }
+    }
+  }
+  console.log(`\nNext: edit ${path.relative(project, out)}, then npm run build and npm run dev and open the page.`);
+}
+
+async function eject(name, force, { slot: slotArg, yes } = {}) {
   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);
@@ -780,16 +860,59 @@ function eject(name, force) {
   if (!name || name === "--list") {
     console.log("Store components a package can eject (the slot that takes your copy):\n");
     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("/")}`);
-    console.log("\nznode eject <Name>   copies one into src/components/ and registers it in src/browser.tsx");
+    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("\nznode eject <Name>   copies one into src/components/ (or a page starter into src/server/pages/) and registers it");
     return;
   }
-  const c = components.find((item) => item.name.toLowerCase() === name.toLowerCase() || item.slot.toLowerCase() === name.toLowerCase());
-  if (!c)
-    fail(
-      `${name} cannot be ejected: no store component with that name or slot hands itself over to a slot.\n` +
-        `  znode eject                      lists the ones that can (component name or slot name both work)\n` +
-        `  znode create-slot ${/^[A-Z]/.test(name) ? name : "<Component>"} <area.name>   creates a slot around a store component in the base (edits the linked store's source)`
-    );
+  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()));
+  let c = find(components);
+  if (!c) {
+    const server = findServer();
+    if (server) return ejectServerSlot(project, server, force);
+  }
+  if (!c) {
+    // no slot hands this component over yet: offer to create one in the base store (what znode create-slot does), then eject
+    const isComponent = /^[A-Z]\w*$/.test(name);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const hint =
+      `  znode eject                                   lists the ones that can (component name or slot name both work)\n` +
+      `  znode eject ${isComponent ? name : "<Component>"} --slot <area.name>   creates the slot in the base store first, then ejects\n` +
+      `  znode create-slot ${isComponent ? name : "<Component>"} <area.name>     only creates the slot (edits the linked store's source)`;
+    if (!isComponent || (!interactive && !slotArg)) fail(`${name} cannot be ejected: no store component with that name or slot hands itself over to a slot.\n${hint}`);
+    console.log(`${name} has no slot yet, so it cannot be ejected.`);
+    console.log(`A slot can be created around it in the base store (${store.root}): it edits the store's source, nothing is committed.`);
+    if (!yes && !slotArg) {
+      const answer = await ask(`Create a slot for ${name} in the base store now? [y/N] `);
+      if (!/^y(es)?$/i.test(answer)) fail(`not created.\n${hint}`);
+    }
+    let slot = slotArg;
+    while (!slot) {
+      const suggested = suggestSlot(name);
+      slot = (await ask(`Slot name (area.name) [${suggested}]: `)) || suggested;
+      if (!SLOT_NAME.test(slot)) {
+        console.log(`  "${slot}" is not a slot name: area.name in camelCase, e.g. product.details`);
+        slot = "";
+      }
+    }
+    createSlot(name, slot, { fromEject: true });
+    c = find(ejectableComponents(store.root));
+    if (!c) {
+      const server = findServer();
+      if (server) {
+        console.log("");
+        return ejectServerSlot(project, server, force);
+      }
+      fail(`the slot "${slot}" was created, but ${name} is still not found as ejectable; check the store diff`);
+    }
+    console.log("");
+  }
 
   const out = path.join(project, "src", "components", `${c.name}.tsx`);
   if (fs.existsSync(out) && !force) fail(`${path.relative(project, out)} exists: delete it or run znode eject ${c.name} --force`);
@@ -814,6 +937,8 @@ function eject(name, force) {
   // the copy is the plain component: no runtime wrapper (the slot is what puts it in place)
   text = text.replace(new RegExp(`^.*import\\s*\\{[^}]*\\b(?:withRuntimeWrapper|${c.wrapper})\\b[^}]*\\}\\s*from\\s*["'][^"']+["'];?\\s*\\n`, "gm"), "");
   text = text.replace(new RegExp(`withRuntimeWrapper\\(\\s*${c.wrapper}\\s*,\\s*${c.base}\\s*,\\s*"${c.name}"\\s*\\)`), c.base);
+  // and none of the store's comments about that wrapper
+  text = text.replace(/^\/\/ runtime packages render around it\b.*\n/gm, "");
   const storeFile = path.relative(store.root, c.file).split(path.sep).join("/");
   const header = `// Ejected from the store: ${storeFile} (${new Date().toISOString().slice(0, 10)}), with \`znode eject ${c.name}\`.\n// The store renders this copy instead of its own through the slot "${c.slot}" (src/browser.tsx). It is yours now: the\n// store's later changes to ${c.name} do not reach it, so compare it with the store's file after a store upgrade.\n`;
   text = text.startsWith('"use client"') || text.startsWith("'use client'") ? text.replace(/^(["']use client["'];?\s*\n)/, `$1${header}`) : header + text;
@@ -863,7 +988,7 @@ function eject(name, force) {
       warnings.push(`src/browser.tsx already fills "${c.slot}": point it at ${local} (${importLine}) yourself`);
     } else if (/slots\s*:\s*\{/.test(source)) {
       if (!source.includes(importLine)) {
-        const imports = [...source.matchAll(/^import .*;\s*$/gm)];
+        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);
       }
@@ -902,7 +1027,94 @@ function storeSourceFiles(root) {
   return files;
 }
 
-function createSlot(name, slot, { dryRun, file: chosen }) {
+// the store's route pages and layouts (apps/<app>/src/app/**/page.tsx, layout.tsx)
+function storeRoutePages(root) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules") walk(file);
+      } else if (/^(page|layout)\.tsx$/.test(entry.name)) files.push(file);
+    }
+  };
+  const apps = path.join(root, "apps");
+  if (fs.existsSync(apps)) for (const app of fs.readdirSync(apps)) if (fs.existsSync(path.join(apps, app, "src/app"))) walk(path.join(apps, app, "src/app"));
+  return files;
+}
+
+// the ")" that closes the "(" at index open (parentheses in the JSX's text are expected to be balanced)
+function closingParen(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "(") depth++;
+    else if (text[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+// the ">" that ends the JSX opening tag starting at index start (attributes in {…} may contain ">", e.g. "=>")
+function openTagEnd(text, start) {
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === "{") depth++;
+    else if (text[i] === "}") depth--;
+    else if (text[i] === ">" && depth === 0) return i;
+  }
+  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.
+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);
+  }
+  return { file, before, after };
+}
+
+function createSlot(name, slot, { dryRun, file: chosen, fromEject } = {}) {
   const usage = "usage: znode create-slot <Component> <area.name> [--dry-run] [--file <store file>]   e.g. znode create-slot ProductBasicInfo product.basicInfo";
   if (!name || !slot) fail(usage);
   if (!/^[A-Z]\w*$/.test(name)) fail(`"${name}" is not a component name (PascalCase, e.g. ProductDetails)\n${usage}`);
@@ -918,6 +1130,7 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
   const wrapperSlots = storeWrapperSlots(root);
   const taken = Object.entries(wrapperSlots).find(([, value]) => value === slot);
   if (taken) fail(`slot "${slot}" already exists (${taken[0]}); znode eject lists what it hands over`);
+  if (storeSlots(root).some((s) => s.name === slot)) fail(`slot "${slot}" already exists in the store (npx znode slot list)`);
   const wrapper = `Runtime${name}`;
   if (wrapperSlots[wrapper] || fs.readdirSync(slotsDir).some((f) => new RegExp(`export\\s+function\\s+${wrapper}\\b`).test(fs.readFileSync(path.join(slotsDir, f), "utf8"))))
     fail(`${wrapper} already exists in ${rel(slotsDir)}: ${name} already has a slot (znode eject lists it)`);
@@ -931,8 +1144,22 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
     if (named.length === 1) candidates = named;
     else fail(`${name} is defined in more than one store file; pick one with --file:\n  ${candidates.map(rel).join("\n  ")}`);
   }
-  if (!candidates.length) fail(`no ${name} component found in packages/base-components/src or packages/page-builder/src (only .tsx components can get a slot)`);
+  if (!candidates.length) {
+    // not a component: a route page (apps/<app>/src/app/**/page.tsx or layout.tsx) whose default export is <name>
+    const pages = storeRoutePages(root).filter((f) => new RegExp(`export\\s+default\\s+(?:async\\s+)?function\\s+${name}\\s*\\(`).test(fs.readFileSync(f, "utf8")));
+    if (pages.length > 1) fail(`${name} is the default export of more than one route; pick one with --file:\n  ${pages.map(rel).join("\n  ")}`);
+    if (!pages.length)
+      fail(
+        `no ${name} found: not a component in packages/base-components/src or packages/page-builder/src, and not the default export of a route page (apps/*/src/app/**/page.tsx or layout.tsx).\n` +
+          `  npx znode slot list shows the slots there are; a page's component name is its "export default function <Name>"`
+      );
+    candidates = pages;
+  }
   const target = candidates[0];
+  const isRoute = /^apps\/[^/]+\/src\/app\//.test(rel(target));
+  let changes;
+  if (isRoute) changes = [routeServerSlot(target, name, slot, rel)];
+  else {
   let source = fs.readFileSync(target, "utf8");
   const def = source.match(DEFINES);
   if (!def) fail(`${rel(target)} does not define ${name} as a function or const component`);
@@ -986,11 +1213,13 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
     `export function ${wrapper}({ children, ...props }: Readonly<Record<string, unknown> & { children?: ReactNode }>) {\n` +
     `  return (\n    <RuntimeSlot name="${slot}" props={props}>\n      {children}\n    </RuntimeSlot>\n  );\n}\n`;
 
-  const changes = [
+  changes = [
     { file: target, before: fs.readFileSync(target, "utf8"), after: source },
     { file: addedFile, before: addedBefore, after: added },
   ];
+  }
   const warnings = [];
+  const where = rel(target).replace(/^packages\/[\w-]+\/src\//, "").replace(/^apps\/[^/]+\/src\/app\/(\[locale\]\/)?/, "app/").replace(/\.tsx$/, "");
 
   // the slot list in the SDK types of the store (packages/extensions/src/types.ts), when it has one
   const typesFile = path.join(root, "packages/extensions/src/types.ts");
@@ -1001,7 +1230,13 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
     if (start >= 0) {
       let end = start + 1;
       while (end < lines.length && /^\s*\/\/\s{3,}/.test(lines[end])) end++;
-      lines.splice(end, 0, `//   ${slot.padEnd(20)} the store's ${name} itself (children)  props: every prop ${name} gets (znode create-slot)`);
+      lines.splice(
+        end,
+        0,
+        isRoute
+          ? `//   ${slot.padEnd(20)} (server slot, src/server.tsx serverSlots) the ${where} route's content (children) (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") });
     } else warnings.push(`${rel(typesFile)}: no "// Slots (" comment found; add "${slot}" to the slot list yourself`);
   }
@@ -1013,7 +1248,13 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
     let row = lines.findIndex((line) => line.startsWith("| `product.card`"));
     if (row >= 0) {
       while (row + 1 < lines.length && lines[row + 1].startsWith("|")) row++;
-      lines.splice(row + 1, 0, `| \`${slot}\` | \`${wrapper}\` (\`${CREATED_SLOTS_FILE.replace("packages/extensions/src/", "")}\`) | \`${rel(target).replace(/^packages\/[\w-]+\/src\//, "").replace(/\.tsx$/, "")}\` (its children: the component itself) | every ${name} prop; keep \`children\`, wrap it, or render a copy instead (\`znode eject ${name}\`) |`);
+      lines.splice(
+        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}\` | \`${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") });
     } else warnings.push(`${rel(docsFile)}: slot table not found; add a "${slot}" row yourself`);
   }
@@ -1035,11 +1276,18 @@ function createSlot(name, slot, { dryRun, file: chosen }) {
   const registry = path.join(root, "scripts/gen-store-module-registry.mjs");
   if (fs.existsSync(registry)) spawnSync(process.execPath, [registry], { cwd: root, stdio: "inherit" });
   for (const warning of warnings) console.log(`warning ${warning}`);
+  if (fromEject) {
+    console.log(
+      `\nSlot "${slot}" created in the base store's source (nothing committed, .next untouched). Before the store renders it:\n` +
+        `  review the diff in ${root} (git diff), commit it through the store's own flow, rebuild / restart the webstore.`
+    );
+    return;
+  }
   console.log(
     `\nDone (the store's source only: nothing committed, .next untouched). Next:\n` +
       `  1. review the diff in ${root} (git diff) and commit it through the store's own flow (hooks, review: it edits base components)\n` +
       `  2. rebuild / restart the webstore so it renders the slot\n` +
-      `  3. here: npx znode eject ${name}   (or fill "${slot}" in src/browser.tsx with a component of your own)`
+      `  3. here: npx znode eject ${name}   (or fill "${slot}" in ${isRoute ? "src/server.tsx serverSlots" : "src/browser.tsx slots"} with a component of your own)`
   );
 }
 
@@ -1074,10 +1322,9 @@ function storeSlots(root) {
     for (const m of text.matchAll(/<Runtime(Server)?Slot\s+name=["']([\w.]+)["']/g)) {
       const name = m[2];
       const tag = m[1] ? "RuntimeServerSlot" : "RuntimeSlot";
-      const rest = text.slice(m.index + m[0].length, m.index + 2000);
-      const close = rest.indexOf(`</${tag}>`);
-      const next = rest.search(/<Runtime(Server)?Slot\s/);
-      const wraps = close >= 0 && (next < 0 || close < next);
+      // it wraps something unless its tag closes itself (<RuntimeSlot name="…" … />)
+      const tagEnd = openTagEnd(text, m.index);
+      const wraps = tagEnd > 0 && text[tagEnd - 1] !== "/" && text.indexOf(`</${tag}>`, tagEnd) > 0;
       const wrapper = wrappers.filter((w) => w.index < m.index).pop()?.[1];
       const relFile = path.relative(root, file).split(path.sep).join("/");
       const existing = slots.get(name);
@@ -1090,13 +1337,16 @@ function storeSlots(root) {
         ? "app/" + relFile.replace(/^apps\/[^/]+\/src\/app\/(\[locale\]\/)?/, "").replace(/\.tsx$/, "")
         : path.basename(file, ".tsx");
       const around = wrapper ? [...new Set(components[wrapper] || [])] : [where];
+      // a server slot written in a route page wraps that page's content: eject gives the package a starter for it
+      const page = !wrapper && m[1] && wraps && /^apps\//.test(relFile) ? (text.match(/export\s+default\s+(?:async\s+)?function\s+(\w+)/) || [])[1] || null : null;
       slots.set(name, {
         name,
         side: m[1] ? "server" : "browser",
         handsOver: wraps,
         wrapper: wrapper || null,
-        components: around,
-        eject: wrapper && handover[wrapper] === name ? around[0] || null : null,
+        components: page ? [`${page} (${where})`] : around,
+        page,
+        eject: wrapper && handover[wrapper] === name ? around[0] || null : page,
         files: [relFile],
       });
     }
@@ -1173,7 +1423,10 @@ if (command === "create") {
   process.exit(0);
 }
 if (command === "eject") {
-  eject(args.find((arg, index) => index > 0 && !arg.startsWith("--")), args.includes("--force"));
+  // 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") });
   process.exit(0);
 }
 if (command === "link-store") {

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "znode-plugin",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Build, check, pack and deploy Znode runtime plugins and themes: the SDK behind every create-znode-plugin project.",
   "license": "UNLICENSED",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azharuddin-mulla-amla/znode-plugin-npm-registry.git",
+    "directory": "packages/znode-plugin"
+  },
   "bin": {
     "znode": "lib/znode-package.mjs"
   },