@base44/app-plugin-commerce 0.7.0 → 0.7.1

package/README.md

@@ -85,7 +85,7 @@ 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** 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:
+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, { AdminRoutes } from "@/commerce/admin";
    // inside your <Routes>:
@@ -96,7 +96,7 @@ From your existing Base44 app:
      <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" }] }`
+   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/package.json

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

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

@@ -8,7 +8,7 @@ carry_forward:
   - "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 while images render → seed when the real image_url values are back (never the /__generating__/ placeholder) → payments last."
+  - "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."
   - "Entities are dotted + bracket-syntax only (`base44.entities[\"commerce.X\"]`); the map is ../docs/entities.md — never scan base44/entities/."
 ---
 
@@ -25,9 +25,13 @@ 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 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.
+   ⚑ **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".
 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,
@@ -47,7 +51,7 @@ 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. */}
+{/* 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 />} />
@@ -61,13 +65,13 @@ import Dashboard from "@/commerce/admin/pages/Dashboard";   // …and orders/Ord
 <Route path="/order-received" element={<OrderReceived />} />          {/* mandatory — see below */}
 ```
 
-- **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.
+- **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** — 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`).
+- **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`).
 
 ## Admin-role enforcement — do not weaken
 

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 />}>…</Route>  {/* own chrome; screens per ./01-install.md */}
+    <Route path="/store-admin" element={<AdminApp />}>…</Route>   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
 
@@ -71,6 +71,8 @@ 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

@@ -26,10 +26,9 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    ```
 
 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`.
+   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, { AdminRoutes } from "@/commerce/admin";

package/src/commerce/admin/index.jsx

@@ -12,13 +12,13 @@ export { default as AdminRoutes } from "./routes";
 /**
  * The store admin application.
  *
- * 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.
+ * 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 />} />

package/src/commerce/admin/routes.jsx

@@ -94,8 +94,8 @@ function UnmatchedRoute() {
 /**
  * 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 —
+ * 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