@base44/app-plugin-commerce 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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/SKILL.md

@@ -22,10 +22,12 @@ the file that mentioned them.
 
 ## Installing right now?
 
-Read **[`install/01-install.md`](./install/01-install.md)** and follow it. It
-routes you to `install/02-storefront.md` when you start the UI and
-`install/03-data.md` when you seed the catalog — in that order, at those
-moments. Read nothing else up front.
+Read all three stages **in one turn** — [`install/01-install.md`](./install/01-install.md),
+[`install/02-storefront.md`](./install/02-storefront.md),
+[`install/03-data.md`](./install/03-data.md) — then work them in that order:
+install, then the storefront UI, then the catalog. Every install runs all three,
+so fetching them one at a time defers nothing you will not read anyway and costs
+a model round trip per file. Read nothing *else* up front.
 
 ## Four things to hold from the start
 
@@ -109,12 +111,14 @@ const { products, has_next } = res.data.data;
 
 ## Where to look for what
 
-Open a file when its work starts — not while planning.
+Open a file when its work starts — not while planning. The exception is the
+three `install/` stages: an install reads all of them, so they come as one
+batch (above).
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 5K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 34K |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`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 |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
@@ -132,10 +136,13 @@ Open a file when its work starts — not while planning.
 | [`docs/api-admin.md`](./docs/api-admin.md) | changing admin pages, automating admin functions, the full seed contract | 24K |
 
 **The read budget.** Content you pull into context is re-read on every later
-call, so a file opened while planning costs many times what it costs opened at
-the moment it is used. Open one reference when its task starts, take what you
-need, and when a stage's checklist passes, record its carry-forward lines and
-treat the file as gone.
+call, so a file you *might* not need costs many times more when opened while
+planning than at the moment it is used. That is the rule for `references/` and
+`docs/`: open one when its task starts, take what you need, and when a stage's
+checklist passes, record its carry-forward lines and treat the file as gone.
+Deferring is worth a round trip only when it might save the read entirely — so
+it is the wrong instinct for the three install stages, which every install
+reads. Batch those.
 
 **The install stages are self-contained.** Every request and response shape they
 build against is written out in them — `install/02-storefront.md` carries a table

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

@@ -7,7 +7,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 URLs are back → 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,6 +24,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 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,

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

@@ -116,7 +116,7 @@ import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPri
 
 A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design and not an order to render in. An even grid of identical cards, each carrying the same name/price/stars trio, is where a generated store lands by default and almost never where this catalog belongs: give the grid a rhythm (a hero piece spanning two columns, an editorial break between rows, a denser tile for a large catalog), and lead each card with the one or two fields *these* products are judged on — carat weight, focal length, edition size, ABV — read off `productSpecs(row)`, not the fields every store shows.
 
-⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it.
+⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it. ⚑ **A ribbon link inside a card that is itself a link nests `<a>` in `<a>`** — invalid HTML, and React warns. In the grid, either render the ribbons as plain labels, or link the card's image and title instead of wrapping the whole card; keep the links on the product page.
 
 **Rails** (featured row, "new in") are the same hook with a filter (`{ featured: true, per_page: 4 }`) — `featured` is the merchant's own flag, so the rail stays curated store data instead of hardcoded slugs. ⚑ Any filter may legitimately match nothing — render *nothing* then, never a heading over an empty row.