@base44/app-plugin-commerce 0.8.2 → 0.8.4

package/README.md

@@ -85,12 +85,18 @@ From your existing Base44 app:
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
    See [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) for the exact shadcn component list.
-5. **Mount the admin router** in your app:
+5. **Mount the admin** as a layout route in your app's `src/App.jsx` — Base44 discovers an app's pages by reading the literal `<Route>` JSX in that file, so the screens that should be listed as pages are declared there and the rest run off a splat handled by the kit's own router:
    ```jsx
-   import AdminApp from "@/commerce/admin";
+   import AdminApp, { AdminRoutes } from "@/commerce/admin";
    // inside your <Routes>:
-   <Route path="/store-admin/*" element={<AdminApp />} />
+   <Route path="/store-admin" element={<AdminApp />}>
+     <Route index element={<Dashboard />} />
+     <Route path="orders" element={<OrdersList />} />
+     {/* …products, customers, coupons, reports… */}
+     <Route path="*" element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
+   </Route>
    ```
+   Name the section they group under in `base44/ui.jsonc` (app-owned — edit in place): `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
 7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, the payment gateway rows (`offline` enabled, `card` off — enable it only with a provider wired) and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Worked example: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); the full payload contract: [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md). Shipping zones are part of the same call — `locations` takes `continents: ["EU"]` and `rest_of_world: true`, so "€20 in Europe, €100 worldwide" is six lines.
 

package/base44/functions/commerce/admin-refunds/entry.ts

@@ -5,6 +5,9 @@
  * Actions: create | delete
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
 import { refundCardOrder } from "../../../shared/commerce/payments.ts";
 import { round2 } from "../../../shared/commerce/money.ts";
@@ -64,6 +67,7 @@ async function create(sr: any, payload: any, actor: string): Promise<any> {
   let gatewayRefund: Awaited<ReturnType<typeof refundCardOrder>> = null;
   if (payload.refund_payment) {
     gatewayRefund = await refundCardOrder(sr, order, {
+      secrets,
       amount,
       reason: payload.reason,
     });

package/base44/functions/commerce/payment-webhook/entry.ts

@@ -27,6 +27,9 @@
  * 400 `webhook_not_implemented`.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { confirmCardPayment } from "../../../shared/commerce/payments.ts";
@@ -41,7 +44,7 @@ Deno.serve(async (req: Request) => {
   try {
     const payload = await req.text();
 
-    const event = await parseWebhook(req, payload);
+    const event = await parseWebhook(req, payload, secrets);
     // Not about one of this store's orders — acknowledge so the provider
     // doesn't retry.
     if (!event || !event.order_id) {
@@ -62,6 +65,7 @@ Deno.serve(async (req: Request) => {
 
     const settings = await getSettings(sr);
     const result = await confirmCardPayment(sr, order, {
+      secrets,
       reference: event.reference,
       trustedPaid: event.paid,
       settings,

package/base44/functions/commerce/payments/entry.ts

@@ -25,6 +25,9 @@
  * order without a key. Entity access is service-role throughout.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, getCallerUser, isAdmin } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { serializeOrderForCustomer } from "../../../shared/commerce/orders.ts";
@@ -112,6 +115,7 @@ Deno.serve(async (req: Request) => {
           returnPath: settings.general?.order_received_path,
         });
         const link = await startCardPayment(sr, order, {
+      secrets,
           successUrl,
           cancelUrl,
           customerEmail: order.billing?.email || undefined,
@@ -134,6 +138,7 @@ Deno.serve(async (req: Request) => {
         const order = await authorizeOrder(sr, payload, admin);
         const settings = await getSettings(sr);
         const result = await confirmCardPayment(sr, order, {
+      secrets,
           settings,
           actor: admin ? (user?.email ?? "admin") : "customer-return",
         });
@@ -154,6 +159,7 @@ Deno.serve(async (req: Request) => {
               returnPath: settings.general?.order_received_path,
             });
             paymentLink = await startCardPayment(sr, result.order, {
+      secrets,
               successUrl,
               cancelUrl,
               customerEmail: result.order.billing?.email || undefined,
@@ -195,6 +201,7 @@ Deno.serve(async (req: Request) => {
         const order = await authorizeOrder(sr, payload, admin);
         const settings = await getSettings(sr);
         const result = await confirmCardPayment(sr, order, {
+      secrets,
           settings,
           actor: admin ? (user?.email ?? "admin") : "customer-return",
         });

package/base44/functions/commerce/storefront-checkout/entry.ts

@@ -12,6 +12,9 @@
  * Checkout is open to guests; order_key possession is the guest bearer credential.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, getCallerUser, ownsEmail } from "../../../shared/commerce/auth.ts";
 import { getSetting, getSettings } from "../../../shared/commerce/settings.ts";
 import { calculateTotals } from "../../../shared/commerce/totals.ts";
@@ -290,6 +293,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
       returnPath: settings.general?.order_received_path,
     });
     const link = await startCardPayment(sr, order, {
+      secrets,
       successUrl,
       cancelUrl,
       customerEmail: billing.email,
@@ -357,6 +361,7 @@ async function confirmPayment(sr: any, payload: any): Promise<any> {
 
   const settings = await getSettings(sr);
   const result = await confirmCardPayment(sr, order, {
+      secrets,
     settings,
     actor: "customer-return",
   });

package/base44/shared/commerce/card-payment.stripe.ts

@@ -41,6 +41,17 @@
  */
 import { HttpError } from "./auth.ts";
 
+/**
+ * The app's secret store, handed in per call by the function layer:
+ * `import { secrets } from "base44:runtime"` there, never in this file —
+ * that specifier resolves only in the Deno function runtime, and `shared/` is
+ * reachable by the client bundler, so importing it here fails the storefront's
+ * build. `Deno.env` would leak the same runtime assumption.
+ */
+export interface SecretStore {
+  get(name: string): unknown;
+}
+
 /** Stripe's REST API, called directly — no SDK to bundle in the function. */
 const STRIPE_API = "https://api.stripe.com/v1";
 /** Pinned, so a Stripe API release can never change the shapes read below. */
@@ -61,14 +72,9 @@ export interface CardPaymentPage {
  * store that has the file but not yet the secret answers a clean 503 at
  * checkout instead of failing to boot every commerce function that imports it.
  */
-const secret = (name: string): string => {
-  // Deno.env, never `secrets` from "base44:runtime": that specifier resolves
-  // only in the Deno function runtime, and this file lives under shared/ where
-  // a client bundler can reach it — the static import fails the Vite build of
-  // the whole storefront. Base44 publishes app secrets into the function
-  // environment, so Deno.env.get reads the same values.
+const secret = (secrets: SecretStore, name: string): string => {
   try {
-    return String(Deno.env.get(name) ?? "");
+    return String(secrets?.get(name) ?? "");
   } catch {
     return "";
   }
@@ -81,9 +87,9 @@ const secret = (name: string): string => {
  */
 const STRIPE_KEY_SECRETS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
 
-const stripeKey = (): string => {
+const stripeKey = (secrets: SecretStore): string => {
   for (const name of STRIPE_KEY_SECRETS) {
-    const value = secret(name);
+    const value = secret(secrets, name);
     if (value) return value;
   }
   // The client is told only that cards are unavailable — which secret is
@@ -104,7 +110,7 @@ const stripeKey = (): string => {
  * as `base44_app_id`, which is how the platform attributes a Stripe payment
  * back to this app — send it on every call that creates money movement.
  */
-const base44AppId = (): string => secret("BASE44_APP_ID");
+const base44AppId = (secrets: SecretStore): string => secret(secrets, "BASE44_APP_ID");
 
 /**
  * One Stripe REST call. A body makes it a POST (form-encoded, with an
@@ -113,9 +119,9 @@ const base44AppId = (): string => secret("BASE44_APP_ID");
  * Stripe's own error text stays in the log: it describes backend configuration
  * (keys, account state, API parameters), so the caller gets a flat message.
  */
-async function stripeCall(path: string, body?: URLSearchParams): Promise<any> {
+async function stripeCall(secrets: SecretStore, path: string, body?: URLSearchParams): Promise<any> {
   const headers: Record<string, string> = {
-    "Authorization": `Bearer ${stripeKey()}`,
+    "Authorization": `Bearer ${stripeKey(secrets)}`,
     "Stripe-Version": STRIPE_VERSION,
   };
   if (body) {
@@ -156,7 +162,7 @@ export async function createCardPayment(
     order_id: String(order.id),
     order_key: String(order.order_key),
   };
-  const appId = base44AppId();
+  const appId = base44AppId(opts.secrets);
   if (appId) metadata.base44_app_id = appId;
 
   const params = new URLSearchParams();
@@ -174,7 +180,7 @@ export async function createCardPayment(
     params.set(`payment_intent_data[metadata][${key}]`, value);
   }
 
-  const session = await stripeCall("/checkout/sessions", params);
+  const session = await stripeCall(opts.secrets, "/checkout/sessions", params);
   if (!session?.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
   return { url: session.url, reference: String(session.id) };
 }
@@ -184,8 +190,8 @@ export async function createCardPayment(
  * caller. Runs on the customer-return page, the webhook's unverified path and
  * the admin's "Check payment" button.
  */
-export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
-  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(reference)}`);
+export async function checkCardPaymentPaid(_sr: any, order: any, reference: string, secrets: SecretStore): Promise<boolean> {
+  const session = await stripeCall(secrets, `/checkout/sessions/${encodeURIComponent(reference)}`);
   // The payment must be for THIS order — stops a reference to some other
   // (genuinely paid) session being replayed against a different order.
   return session?.payment_status === "paid" && session?.metadata?.order_id === String(order.id);
@@ -200,20 +206,21 @@ export async function refundCardPayment(_sr: any, _order: any, opts: {
   amount: number;
   currency: string;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string }> {
   // The stored reference is the Checkout Session; the refundable object is the
   // payment intent behind it, which only exists once the session was paid.
-  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(opts.reference)}`);
+  const session = await stripeCall(opts.secrets, `/checkout/sessions/${encodeURIComponent(opts.reference)}`);
   if (!session?.payment_intent) {
     throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
   }
   const params = new URLSearchParams();
   params.set("payment_intent", String(session.payment_intent));
   params.set("amount", String(minorUnits(opts.amount, opts.currency)));
-  const appId = base44AppId();
+  const appId = base44AppId(opts.secrets);
   if (appId) params.set("metadata[base44_app_id]", appId);
 
-  const refund = await stripeCall("/refunds", params);
+  const refund = await stripeCall(opts.secrets, "/refunds", params);
   return { refund_id: String(refund.id) };
 }
 
@@ -246,7 +253,7 @@ export interface CardWebhookEvent {
  * null for anything that isn't a payment event for one of this store's orders;
  * the premade function answers 200 so Stripe stops retrying.
  */
-export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
+export async function parseWebhook(_req: Request, payload: string, secrets: SecretStore): Promise<CardWebhookEvent | null> {
   let event: any;
   try { event = JSON.parse(payload); } catch { return null; }
   const metadata = event?.data?.object?.metadata;

package/base44/shared/commerce/card-payment.ts

@@ -34,16 +34,25 @@
  * Until implemented, the Credit Card checkout option answers
  * 503 `no_card_payment_provider`.
  *
- * Credentials belong in Base44 secrets, read with `Deno.env.get("...")` —
- * never in an entity, never in the code, never from the client. Do NOT import
- * `secrets` from `base44:runtime` here: that specifier resolves only in the
- * Deno function runtime, and a static import of it in this shared file fails
- * the client bundle of the whole storefront. When one is missing, log which one and answer the caller with the
+ * Credentials belong in Base44 secrets — but this file never reaches for them
+ * itself. Every function below is handed a `SecretStore` by the function that
+ * called it, the one layer that may `import { secrets } from "base44:runtime"`.
+ * Neither that import nor `Deno.env` belongs here: `shared/` is reachable by
+ * the client bundler, so either one fails the storefront's build and pins this
+ * file to a single runtime. Never an entity, never the code, never the client. When one is missing, log which one and answer the caller with the
  * flat 503 below: the storefront must not learn the names of the app's
  * secrets.
  */
 import { HttpError } from "./auth.ts";
 
+/**
+ * The app's secret store, handed in per call by the function layer:
+ * `import { secrets } from "base44:runtime"` there, never here.
+ */
+export interface SecretStore {
+  get(name: string): unknown;
+}
+
 /** A hosted payment page for one order. */
 export interface CardPaymentPage {
   /** Where the customer goes to pay. */
@@ -67,7 +76,7 @@ export interface CardPaymentPage {
 export async function createCardPayment(
   _sr: any,
   _order: any,
-  _opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+  _opts: { successUrl: string; cancelUrl: string; customerEmail?: string; secrets: SecretStore },
 ): Promise<CardPaymentPage> {
   throw new HttpError(
     503,
@@ -82,7 +91,7 @@ export async function createCardPayment(
  * a claim from the client. Called by the customer-return page, the webhook's
  * unsigned path, and the admin's "Check payment" button.
  */
-export async function checkCardPaymentPaid(_sr: any, _order: any, _reference: string): Promise<boolean> {
+export async function checkCardPaymentPaid(_sr: any, _order: any, _reference: string, _secrets: SecretStore): Promise<boolean> {
   return false;
 }
 
@@ -97,6 +106,7 @@ export async function refundCardPayment(_sr: any, _order: any, _opts: {
   amount: number;
   currency: string;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string }> {
   throw new HttpError(
     501,
@@ -140,7 +150,7 @@ export interface CardWebhookEvent {
  * aren't about a payment for one of this store's orders (answered 200 so the
  * provider doesn't retry).
  */
-export async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
+export async function parseWebhook(_req: Request, _payload: string, _secrets: SecretStore): Promise<CardWebhookEvent | null> {
   throw new HttpError(
     400,
     "This store's payment webhook is not implemented.",

package/base44/shared/commerce/payments.ts

@@ -19,7 +19,7 @@
 import { HttpError } from "./auth.ts";
 import { round2 } from "./money.ts";
 import { transitionOrder } from "./orders.ts";
-import { checkCardPaymentPaid, createCardPayment, refundCardPayment } from "./card-payment.ts";
+import { checkCardPaymentPaid, createCardPayment, refundCardPayment, type SecretStore } from "./card-payment.ts";
 
 /** The one `commerce.PaymentGateway` slug that pays online; all others are manual. */
 export const CARD_GATEWAY_SLUG = "card";
@@ -182,6 +182,8 @@ export async function startCardPayment(sr: any, order: any, opts: {
   successUrl: string;
   cancelUrl: string;
   customerEmail?: string;
+  // Handed down from the function entry — shared/ may not read secrets itself.
+  secrets: SecretStore;
 }): Promise<{ url: string; reference: string }> {
   if (isOrderPaid(order)) {
     throw new HttpError(409, "This order is already paid.", "already_paid");
@@ -210,12 +212,13 @@ export async function confirmCardPayment(sr: any, order: any, opts: {
   settings?: Record<string, any>;
   actor?: string;
   trustedPaid?: boolean;
-} = {}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
+  secrets: SecretStore;
+}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
   if (isOrderPaid(order)) return { paid: true, already_confirmed: true, order };
 
   const reference = opts.reference || orderMeta(order, REFERENCE_META_KEY) || String(order?.transaction_id ?? "");
   const paid = opts.trustedPaid === true ||
-    (reference ? await checkCardPaymentPaid(sr, order, reference) : false);
+    (reference ? await checkCardPaymentPaid(sr, order, reference, opts.secrets) : false);
   if (!paid) return { paid: false, already_confirmed: false, order };
 
   if (reference) {
@@ -242,10 +245,12 @@ export async function confirmCardPayment(sr: any, order: any, opts: {
 export async function refundCardOrder(sr: any, order: any, opts: {
   amount: number;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string } | null> {
   const reference = order?.transaction_id || orderMeta(order, REFERENCE_META_KEY);
   if (!isCardGateway(order?.payment_method) || !reference) return null;
   return await refundCardPayment(sr, order, {
+    secrets: opts.secrets,
     reference,
     amount: round2(opts.amount),
     currency: String(order.currency || "USD"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -217,8 +217,10 @@
     "\n" +
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
     "     Base44 template — check package.json and npm i only what is truly missing\n" +
-    '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
+    '  2. Mount the admin in src/App.jsx: <Route path="/store-admin" element={<AdminApp />}>\n' +
+    "     with the main screens as literal child <Route>s (that file is what the platform\n" +
+    '     discovers pages from) and <Route path="*" element={<AdminRoutes />} /> for the\n' +
+    "     rest, plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
     "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
     "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"

package/skills/commerce/SKILL.md

@@ -122,7 +122,7 @@ batch (above).
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 8K |
 | [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 38K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |

package/skills/commerce/install/01-install.md

@@ -1,9 +1,10 @@
 ---
 stage: install/01
 read_when: "The commerce kit's files were just copied into the app, or you are installing it now."
-skip_when: "The admin already mounts at /store-admin/* behind the shipped AuthGuard and / routes somewhere real."
+skip_when: "src/App.jsx already declares the admin's screens as literal <Route> JSX under a /store-admin layout route, and / routes somewhere real."
 forget_when: "The checklist at the bottom of this file passes (admin mounts, / routes somewhere real, /order-received exists)."
 carry_forward:
+  - "The admin's six picker-visible routes are literal <Route> JSX in src/App.jsx (the platform discovers pages by reading that file — an array or a .map() discovers nothing); the rest run off its <Route path=\"*\" element={<AdminRoutes />} />."
   - "Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them."
   - "/order-received must exist as a route: every payment link returns there, and confirming is what marks an order paid."
   - "The storefront header shows a visible \"Store manager\" link to /store-admin when the signed-in user's role is admin, and nothing for everyone else."
@@ -41,18 +42,33 @@ Image generation is the slowest step and nothing depends on it until seed time;
 
 The only dependency edges are *image URLs → seed payload* and *seed done → real products on the pages*.
 
-## Mount the admin router
+## Mount the admin
 
-```jsx
-import AdminApp from "@/commerce/admin";
-import { Navigate } from "react-router-dom";
+The admin mounts as a **layout route in the app's own `src/App.jsx`**: the six screens the store owner opens from the builder are declared there as literal `<Route>` JSX, and everything deeper goes to `<AdminRoutes />` on a splat. The platform discovers an app's pages by reading that file — a screen declared anywhere else is unreachable from the page picker.
 
-<Route path="/store-admin/*" element={<AdminApp />} />
+```jsx
+import AdminApp, { AdminRoutes } from "@/commerce/admin";
+import Dashboard from "@/commerce/admin/pages/Dashboard";   // …and orders/OrdersList,
+// products/ProductsList, customers/CustomersList, coupons/CouponsList, reports/Reports
+
+{/* Literal JSX — the platform reads this file, it never runs it. Do not refactor into a map. */}
+<Route path="/store-admin" element={<AdminApp />}>
+  <Route index            element={<Dashboard />} />
+  <Route path="orders"    element={<OrdersList />} />
+  <Route path="products"  element={<ProductsList />} />
+  <Route path="customers" element={<CustomersList />} />
+  <Route path="coupons"   element={<CouponsList />} />
+  <Route path="reports"   element={<Reports />} />
+  <Route path="*"         element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
+</Route>
 <Route path="/" element={<Navigate to="/store-admin" replace />} />   {/* until a storefront exists */}
 <Route path="/order-received" element={<OrderReceived />} />          {/* mandatory — see below */}
 ```
 
-- **The `/*` splat is required** — without it every nested admin link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` (prefix without the splat).
+- **Those seven lines, as they are.** The splat is what keeps the app's listed pages to six instead of 26: `path="*"` is skipped, so the editors, settings tabs and webhook screens stay navigable without appearing there, and `<AdminRoutes />` still serves the admin's own 404.
+- **Don't add `settings` to the list** — it is a tabbed layout around a nested route, so it only renders correctly from the splat.
+- **Elsewhere than `/store-admin`**: change the layout route's path and pass the prefix — `<AdminApp basePath="/backoffice" />`; the children are unchanged.
+- **Name the group** in `base44/ui.jsonc` — app-owned, so edit it in place, keep any other keys, never recreate a deleted one: `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
 - **Give `/` something** — a blank app has no `/` route, and "page not found" at the app's own URL reads like a broken install.
 - **Link the admin from the storefront header** — otherwise the merchant has no way in but typing the URL. Resolve the signed-in user once (`base44.auth.me()`, rejection/no session = not an admin, never blocking the page) and render a plainly visible "Store manager" link to `/store-admin` in the header when `role === "admin"` — and nothing at all for everyone else.
 - **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General (`general.order_received_path`).
@@ -69,7 +85,7 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 ## Done — forget this file
 
-- [ ] `/store-admin/*` mounted with the splat, behind the shipped `AuthGuard`; the three enforcement layers untouched.
+- [ ] The `/store-admin` layout route is in `src/App.jsx` with its six literal `<Route>` screens and the `path="*"` → `<AdminRoutes />` splat; `base44/ui.jsonc` names the section; the three enforcement layers untouched.
 - [ ] `/` routes somewhere real; `/order-received` is a route.
 - [ ] The storefront header shows a visible `/store-admin` link to signed-in admins, and to nobody else.
 - [ ] Anonymous function invocation is allowed in the app's settings.

package/skills/commerce/install/02-storefront.md

@@ -50,7 +50,7 @@ import AdminApp from "@/commerce/admin";
       <Route path="/product/:slug" element={<ProductPage />} />
       {/* /bag, /checkout, and /order-received — which is mandatory */}
     </Route>
-    <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
+    <Route path="/store-admin" element={<AdminApp />}>…</Route>   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
 

package/src/commerce/admin/README.md

@@ -25,12 +25,20 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
 
-4. Mount the app in your router:
+4. Mount it as a layout route in the app's own `src/App.jsx` — that is the file
+   Base44 discovers an app's pages from, so the screens that should be listed as
+   pages are declared there literally, and the rest go to `<AdminRoutes />` on a
+   splat. The full step is the skill's `install/01-install.md`.
 
    ```jsx
-   import AdminApp from "@/commerce/admin";
-
-   <Route path="/store-admin/*" element={<AdminApp />} />
+   import AdminApp, { AdminRoutes } from "@/commerce/admin";
+
+   <Route path="/store-admin" element={<AdminApp />}>
+     <Route index element={<Dashboard />} />
+     <Route path="orders" element={<OrdersList />} />
+     {/* …products, customers, coupons, reports… */}
+     <Route path="*" element={<AdminRoutes />} />
+   </Route>
    // mounted elsewhere? → <AdminApp basePath="/backoffice" />
    ```
 
@@ -75,8 +83,8 @@ npx shadcn@latest add <component>
 ## Layout of this folder
 
 ```
-index.jsx        AdminApp: providers → auth guard → layout → routes
-routes.jsx       Route table + <AdminRoutes/>
+index.jsx        AdminApp: providers → auth guard → layout → <Outlet/>
+routes.jsx       Route table + <AdminRoutes/> (the splat handler App.jsx delegates to)
 layout/          AdminLayout, Sidebar, Topbar, AuthGuard (admin-role gate), AccessDenied
 bot/             StoreAdminBot (chat panel over the commerce/StoreAdmin agent), Markdown (GFM renderer)
 context/         SettingsContext (store settings + first-run seeding), BasePathContext

package/src/commerce/admin/index.jsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { useOutlet } from "react-router-dom";
 import { Toaster } from "sonner";
 import AuthGuard from "./layout/AuthGuard";
 import AdminLayout from "./layout/AdminLayout";
@@ -6,27 +7,50 @@ import AdminRoutes from "./routes";
 import { SettingsProvider } from "./context/SettingsContext";
 import { BasePathProvider } from "./context/BasePathContext";
 
+export { default as AdminRoutes } from "./routes";
+
 /**
  * The store admin application.
  *
- * Mount inside your app's router:
- *   <Route path="/store-admin/*" element={<AdminApp />} />
+ * Mount it as a *layout route* in the app's own `src/App.jsx`: declare the few
+ * screens that should be listed among the app's pages there, as literal `<Route>`
+ * JSX, and hand everything deeper to `<AdminRoutes />` on a splat. Base44
+ * discovers an app's pages by reading that file rather than running it, so a
+ * route declared anywhere else is reachable by URL but never listed — and a
+ * splat is skipped by discovery, which is what keeps the editors and the
+ * settings tabs off the list while leaving them navigable.
+ *
+ *   <Route path="/store-admin" element={<AdminApp />}>
+ *     <Route index element={<Dashboard />} />
+ *     <Route path="orders" element={<OrdersList />} />
+ *     …
+ *     <Route path="*" element={<AdminRoutes />} />
+ *   </Route>
  *
  * If mounted somewhere other than /store-admin, pass the prefix:
- *   <Route path="/backoffice/*" element={<AdminApp basePath="/backoffice" />} />
+ *   <Route path="/backoffice" element={<AdminApp basePath="/backoffice" />}>
+ *
+ * The providers belong here, above the outlet, and must not be repeated per
+ * route: SettingsProvider fetches commerce.StoreSettings on mount, so wrapping
+ * each route would cost a round trip and a remounted sidebar on every admin
+ * navigation.
  *
  * Requires an authenticated user with role "admin" (enforced by AuthGuard,
  * and independently by entity RLS + requireAdmin() in backend functions).
  */
 export default function AdminApp({ basePath = "/store-admin" }) {
+  // Installs from before the routes moved into App.jsx mount the whole admin
+  // behind one splat route (`<Route path="/store-admin/*" element={<AdminApp />} />`)
+  // and declare no children, so nothing ever fills the outlet. Fall back to the
+  // kit's own router there rather than drawing an empty page area under the
+  // sidebar; those apps keep working until an agent rewrites their App.jsx.
+  const outlet = useOutlet();
   return (
     <BasePathProvider value={basePath}>
       <Toaster richColors position="top-right" />
       <AuthGuard>
         <SettingsProvider>
-          <AdminLayout>
-            <AdminRoutes />
-          </AdminLayout>
+          <AdminLayout>{outlet ?? <AdminRoutes />}</AdminLayout>
         </SettingsProvider>
       </AuthGuard>
     </BasePathProvider>

package/src/commerce/admin/lib/paths.js

@@ -1,8 +1,9 @@
 /**
  * Mount-path handling for the admin app.
  *
- * The admin is mounted with a splat route — `<Route path="/store-admin/*">` — and both
- * halves of that pattern leak into places they shouldn't: the `basePath` prop
+ * Installs from before the routes moved into App.jsx mount the admin with a splat
+ * route — `<Route path="/store-admin/*">` — and both halves of that pattern leak
+ * into places they shouldn't: the `basePath` prop
  * gets the pattern pasted in verbatim, and the literal URL `/store-admin/*` gets
  * opened (pattern copied into the address bar, or a nav link built from the
  * route table). Neither is a real page, so both are normalized here rather than

package/src/commerce/admin/routes.jsx

@@ -92,7 +92,20 @@ function UnmatchedRoute() {
   return isMountPatternPath(params["*"]) ? <Navigate to={href()} replace /> : <NotFound />;
 }
 
-/** All admin routes. Rendered inside AdminLayout; mount AdminApp at `/store-admin/*`. */
+/**
+ * Every admin route, matched relative to the mount point.
+ *
+ * The app's `src/App.jsx` declares the handful of screens that should be listed
+ * among the app's pages — discovery only sees literal `<Route>` JSX in that file —
+ * and sends the rest here on a splat: `<Route path="*" element={<AdminRoutes />} />`.
+ * A descendant `<Routes>` needs exactly that trailing splat to resolve against.
+ * The overlap is deliberate: a path declared in App.jsx wins there, and the same
+ * entry here keeps this table complete for anything App.jsx does not name —
+ * `orders/:id` and the settings tabs among them.
+ *
+ * With no splat and no children at all — an install predating the move into
+ * App.jsx — `index.jsx` renders this component directly instead.
+ */
 export default function AdminRoutes() {
   return (
     <Routes>