@base44/app-plugin-commerce 0.6.7 → 0.7.0

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` — the platform discovers an app's pages by reading the literal `<Route>` JSX in that file, so the screens the store owner should reach from the builder 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 picker's section for them 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "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

@@ -117,7 +117,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 | 35K |
 | [`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,13 +1,14 @@
 ---
 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."
-  - "Interleave: start image generation first → mount admin + build the storefront → seed with the image_url the generate_image result already returned (never poll, never write a function to fetch URLs) → payments last."
+  - "Interleave: start image generation first → mount admin + build the storefront while images render → seed when the real image_url values are back (never the /__generating__/ placeholder) → payments last."
   - "Entities are dotted + bracket-syntax only (`base44.entities[\"commerce.X\"]`); the map is ../docs/entities.md — never scan base44/entities/."
 ---
 
@@ -24,13 +25,9 @@ carry_forward:
 Image generation is the slowest step and nothing depends on it until seed time; the storefront doesn't wait on live data either.
 
 1. **Start image generation first** — every product image, before anything else.
-   ⚑ **The result already carries the real `image_url`** alongside a `placeholder_url`
-   — use `image_url` and move on. Nothing is pending, there is nothing to poll, and a
-   backend function calling `Core.GenerateImage` to "fetch the real URLs" is pure waste:
-   you already have them. If a `/__generating__/…` value does reach a file or a seed
-   payload, the platform swaps it for the real URL after the turn (in files *and* entity
-   records) — so a placeholder that renders broken in a mid-build preview is expected and
-   must not be "fixed".
+   ⚑ The tool hands back a `/__generating__/…` placeholder immediately and the real
+   `image_url` only when it finishes. Never write the placeholder into a file or a
+   seed payload: it resolves to nothing and ships a broken image.
 2. **Mount the admin (below) and build the storefront** while images render. Every
    request and response shape the pages build against is written out in
    [`./02-storefront.md`](./02-storefront.md), so they are written from the docs,
@@ -41,21 +38,36 @@ 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 picker 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.** An array, a spread or a `.map()` discovers *zero* routes. The splat is what keeps the picker to six real pages instead of 26: discovery ignores `path="*"`, so the editors (`orders/:id`), the settings tabs and the 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`).
+- **Link the admin from the storefront header** — else the merchant's only way in is typing the URL. Resolve the user once (`base44.auth.me()`; rejection/no session = not an admin, never blocking the page) and show a plainly visible "Store manager" link to `/store-admin` when `role === "admin"`, 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. It is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)); a different path must be set in Settings → General (`general.order_received_path`).
 
 ## Admin-role enforcement — do not weaken
 
@@ -69,7 +81,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

@@ -48,7 +48,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; screens per ./01-install.md */}
   </Routes>
 </BrowserRouter>
 
@@ -71,8 +71,6 @@ function StoreLayout() {
 
 The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row`, a heading scale, a price style — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.**
 
-⚑ **Two `@apply` forms Tailwind rejects, and each breaks the whole build.** **Any** `/opacity` on a bracketed value is not a class — `text-[var(--ink)]/40` and `border-[#1B2422]/8` fail alike — so write plain CSS: `border-color: color-mix(in srgb, var(--ink) 40%, transparent)`. Translucent brand colours are the commonest thing a `.panel`/`.field` class wants, so reach for `color-mix` first. And `@apply group` is invalid; `group` is a marker for the element's `className`. Either is a postcss error that fails Vite, so *every* page renders blank — which reads as a broken import and sends you into `src/commerce/`. **Nothing rendering? Read `index.css` first.**
-
 The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show. It is the half of a store's identity a kit cannot ship.
 
 **Concentrate identity; don't diffuse it.** The classes carry the look everywhere; on top of them, spend bespoke markup on **one or two signature moments per page** — the hero, the one product-page module that shows what these products are judged on — and render everything else as conventions in the classes. **The product page stays the storefront's richest surface**, and that richness is semantic: what the controls and rows *show*, which costs words rather than chrome. One navigation affordance per control (thumbnails *or* arrows, never both plus dots); checkout, bag and order-received are convention surfaces.

package/src/commerce/admin/README.md

@@ -25,12 +25,21 @@ 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
+   the platform discovers pages from, so the screens the store owner should be
+   able to open from the builder 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 +84,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 the store owner should be able to open from the builder as literal
+ * `<Route>` JSX under it, and hand everything deeper to `<AdminRoutes />` on a
+ * splat. The platform discovers an app's pages by reading that file, so a screen
+ * declared anywhere else is unreachable from the page picker — and a splat is
+ * ignored by discovery, which is what keeps the editors and settings tabs out of
+ * it 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

@@ -91,7 +91,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 the builder's page
+ * picker should list — the picker 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>