@base44/app-plugin-commerce 0.8.4 → 0.9.1

package/skills/commerce/references/catalog-rendering.md

@@ -1,7 +1,7 @@
 ---
 stage: reference
 read_when: "You are asking which fields a card or a product page can actually show, or hit a variant edge case (unavailable combinations, attributes with no variations, price ranges, linkable selections)."
-skip_when: "The listing and product page render correctly from useProductList / useProduct and the render-model helpers — the quick start in ../install/02-storefront.md covers the happy path."
+skip_when: "The listing and product page render correctly from useProductList / useProduct and the render-model helpers — the quick start in ../installation/install.md covers the happy path."
 forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
 carry_forward:
   - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
@@ -95,7 +95,7 @@ Both lists are inventories of what the data supports — **not a layout and not
 
 **Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `useStorefront().submitReview`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
 
-**Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` plus an inferred `type` — `"numeric"` / `"duration"` (with `number` and `unit` split out), `"location"`, `"list"` (with `items`), `"text"` — so the rendering branch is already made for you: a weight can be a figure, a composition bars, a provenance a place. ⚑ **Never `.map()` the whole list into one grey label/value table**; design the two or three rows this catalog is judged on and let the rest fall through to a plain row. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey table ([`../install/02-storefront.md`](../install/02-storefront.md)); §5's rules govern selector *behaviour*, never its form.
+**Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` plus an inferred `type` — `"numeric"` / `"duration"` (with `number` and `unit` split out), `"location"`, `"list"` (with `items`), `"text"` — so the rendering branch is already made for you: a weight can be a figure, a composition bars, a provenance a place. ⚑ **Never `.map()` the whole list into one grey label/value table**; design the two or three rows this catalog is judged on and let the rest fall through to a plain row. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey table ([`../installation/install.md`](../installation/install.md)); §5's rules govern selector *behaviour*, never its form.
 
 ## 4. Ribbons — in **both** views
 

package/skills/commerce/references/guest-access-security.md

@@ -18,7 +18,7 @@ carry_forward:
 - The storefront catalog function strips the paywalled fields (`downloads`, `download_limit`, `download_expiry`) from every product/variation it returns. Downloadable files are reached only through `commerce/storefront-account` `get-download`, which enforces ownership, download limits, expiry and short-lived signed URLs — keep that the only path to a `file_url`.
 - `cart_token` and `order_key` are **bearer credentials** — possession grants access to that cart/order. Always serve over HTTPS; don't log them; treat them like secrets.
 - Carts and orders have admin-only RLS; customers never touch those entities directly — all access is mediated by `commerce/storefront-*` functions using the service role after verifying the caller.
-- The admin side has three enforcement layers; never weaken them ([`../install/01-install.md`](../install/01-install.md)).
+- The admin side has three enforcement layers; never weaken them ([`../installation/install.md`](../installation/install.md)).
 
 ## Rules for anything you add
 

package/skills/commerce/references/online-payments.md

@@ -1,7 +1,7 @@
 ---
 stage: reference
 read_when: "The store opted into card payments and you are wiring the provider NOW."
-skip_when: "The store takes offline payments (the default) — nothing here applies; the decision itself lives in ../install/03-data.md."
+skip_when: "The store takes offline payments (the default) — nothing here applies; the decision itself lives in ../installation/install.md."
 forget_when: "A test payment reaches /order-received as paid, or the provider file is copied and the `card` gateway is enabled."
 carry_forward:
   - "Wiring a provider = replace shared/commerce/card-payment.ts WHOLE (copy the shipped card-payment.<provider>.ts over it) — a partial edit breaks every commerce function's deploy with duplicate exports."
@@ -15,7 +15,7 @@ The kit ships a **Credit card** checkout option (`commerce.PaymentGateway` slug
 
 What it does **not** ship is a live provider. Wiring one means **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
 
-Card payments are **off by default** and are the last thing to add, never the first — the rule, the timing and the decision table live in [`../install/03-data.md`](../install/03-data.md). Everything below assumes that decision is made.
+Card payments are **off by default** and are the last thing to add, never the first — the rule, the timing and the decision table live in [`../installation/install.md`](../installation/install.md). Everything below assumes that decision is made.
 
 ## Enabling the gateway — one seed call, at any time
 

package/skills/commerce/references/shipping-and-tax.md

@@ -1,7 +1,7 @@
 ---
 stage: reference
-read_when: "You need shipping or tax beyond the one recipe inline in ../install/03-data.md — several priced tiers, VAT, tax on shipping, or editing locations after the seed."
-skip_when: "One flat rate is enough, or the '€X region / €Y worldwide' recipe in ../install/03-data.md already expresses the requirement."
+read_when: "You need shipping or tax beyond the one recipe inline in ../installation/install.md — several priced tiers, VAT, tax on shipping, or editing locations after the seed."
+skip_when: "One flat rate is enough, or the '€X region / €Y worldwide' recipe in ../installation/install.md already expresses the requirement."
 forget_when: "The seed response came back with no `no_catchall_location` warning and checkout prices shipping for both a domestic and a foreign test address."
 carry_forward:
   - "One matched commerce.ShippingTaxLocation supplies BOTH the shipping rates and the tax for an address."
@@ -13,7 +13,7 @@ carry_forward:
 
 One entity does both jobs. A **`commerce.ShippingTaxLocation`** is *a set of regions plus everything charged there*: the shipping options offered and the tax applied. There is no zone/method/class model and no separate tax-rate table.
 
-Declaring `locations` in the `commerce/seed-store` call is **the** way to set shipping up ([`../install/03-data.md`](../install/03-data.md)); editing the entity afterwards is the day-2 route (last section).
+Declaring `locations` in the `commerce/seed-store` call is **the** way to set shipping up ([`../installation/install.md`](../installation/install.md)); editing the entity afterwards is the day-2 route (last section).
 
 ## The model
 

package/skills/commerce/references/store-settings.md

@@ -31,7 +31,7 @@ Six records, one per group: `general`, `products`, `inventory`, `tax`, `shipping
 | **`shipping`** | | |
 | `enable_shipping` | `true` | `false` = no shipping line, no rates, no address requirement anywhere. The digital-only-store switch. |
 | **`emails`** | | |
-| `store_name` | `""` (set from the seed call) | Subject/heading `{store_name}`, the `SendEmail` sender name, **and** the public shop name on `get-store-info`. Blank = Base44 sends as the app's name; semantics in [`emails.md`](./emails.md). Required on a first seed ([`../install/03-data.md`](../install/03-data.md)). |
+| `store_name` | `""` (set from the seed call) | Subject/heading `{store_name}`, the `SendEmail` sender name, **and** the public shop name on `get-store-info`. Blank = Base44 sends as the app's name; semantics in [`emails.md`](./emails.md). Required on a first seed ([`../installation/install.md`](../installation/install.md)). |
 | `admin_recipients` | `[]` | Fallback notification addresses; empty falls back to the app's `admin`-role users. |
 | `<type>.enabled` / `.subject` / `.heading` / `.recipient` | enabled, blanks | Per-type overrides at the **top level** of the group (`emails.new_order.enabled`) — [`emails.md`](./emails.md). |
 

package/src/commerce/admin/README.md

@@ -6,7 +6,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
 
 > Docs live in the commerce skill, and every path below is **relative to that
 > skill folder** (`.agents/skills/commerce/` once installed): install, mounting
-> and role setup are `install/01-install.md`; the map for everything else is
+> and role setup are `installation/install.md`; the map for everything else is
 > `SKILL.md`; the API references are `docs/api-admin.md` and
 > `docs/api-storefront.md`.
 
@@ -28,7 +28,7 @@ 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
    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`.
+   splat. The full step is the skill's `installation/install.md`.
 
    ```jsx
    import AdminApp, { AdminRoutes } from "@/commerce/admin";
@@ -50,7 +50,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
    catalog — the store counts as ready and this screen never shows; see
-   the commerce skill's install/03-data.md.
+   the commerce skill's installation/install.md.
 
 ## External touchpoints
 
@@ -85,16 +85,64 @@ npx shadcn@latest add <component>
 ```
 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
+layout/          AdminLayout, Sidebar, Topbar, ThemeToggle, 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
+context/         SettingsContext (store settings + first-run seeding), BasePathContext, ThemeContext
 hooks/           useAsync, usePagedList, useRealtime (live updates), useMoney, useDebounce
 i18n/            t() + locale; locales/ = en (default), de, es, fr, ja, pt
-lib/             api (function calls), constants, format, geo-data, order/product utils
+lib/             api (function calls), constants, format, theme, geo-data, order/product utils
 components/      DataTable, SearchSelect, MoneyInput, DateRangePicker, AddressForm, …
 pages/           All admin pages (orders, products, coupons, customers, reports, settings, webhooks)
 ```
 
+## Theme: the store's, or Base44's
+
+The admin renders in the host app's theme — it styles everything with the
+shadcn semantic classes (`bg-background`, `text-muted-foreground`, `bg-primary`),
+so it picks up the store's tokens for free. That is right for most stores and
+wrong for some: a display font, a saturated brand color on every primary
+button, or a dark low-contrast surface reads as personality on a storefront and
+as noise in a back office someone works in all day.
+
+So the topbar carries a **switch with both ends named — Site ⇄ Base44** — next
+to the signed-in email. Off is *Site*, the store's own theme and the default;
+on is *Base44*, a fixed neutral palette and font stack in the shape of the
+Base44 dashboard, with the side in effect shown in full-contrast text. Both
+ends are named because a control that shows one theme cannot say whether that
+is the state you are in or the one a click would give you. The choice is per browser
+(`localStorage`, key `commerce.admin.theme`) — it is a viewing preference of
+whoever is working, not a store setting, so it is not saved to the backend and
+not shared between admins.
+
+**Only colors and fonts change.** No spacing, radii, sizes or layout, and
+nothing outside the admin: `lib/theme.js` writes shadcn tokens as inline custom
+properties on `<html>` and removes them when the admin unmounts or the switch
+goes back to *Site*.
+
+Four things worth knowing before editing `lib/theme.js`:
+
+- **It writes to `<html>`, not to an admin wrapper.** The shadcn primitives the
+  admin is built from — dropdowns, dialogs, sheets, selects, toasts — render
+  through portals into `document.body`, and a wrapper-scoped theme would leave
+  every one of them in the site's colors while the page behind them changed.
+- **It matches the app's token convention at runtime.** A Tailwind v3 shadcn app
+  stores bare triples (`0 0% 100%`) and wraps at the point of use
+  (`hsl(var(--background))`); a v4 app stores finished colors and uses the var
+  directly. Writing the wrong shape paints nothing at all, so the palette is
+  authored once as triples and emitted in whichever form the app already uses.
+- **The Base44 theme is a light theme** and suspends the app's `dark` class
+  while it is on, restoring it on the way out. Without that, `dark:` utilities
+  and native controls stay dark over light surfaces.
+- **It repaints `<body>` as well as the tokens.** Plenty of stores paint the
+  page directly — `body { background-color: var(--brand-ink); color: … }` next
+  to their tokens rather than through them. Tokens alone would then put white
+  cards and near-white inherited text on a dark page; the same rules that set
+  the font set the root's background and text color from the palette.
+
+Restyling the admin to match your store instead is the other direction, and it
+is just the tokens: change them in your app's CSS and both the storefront and
+the admin's *Site theme* follow.
+
 ## Localization
 
 Every user-visible string renders through `t()` from `i18n/`; the wording

package/src/commerce/admin/context/ThemeContext.jsx

@@ -0,0 +1,62 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+} from "react";
+import {
+  BASE44_THEME,
+  SITE_THEME,
+  applyAdminTheme,
+  readStoredTheme,
+  storeTheme,
+} from "../lib/theme";
+
+/**
+ * Which theme the admin renders in — the host app's ("site") or the built-in
+ * Base44 palette and fonts ("base44"). See `lib/theme.js` for what each one
+ * changes; the picker is `layout/ThemeToggle.jsx`.
+ *
+ * The default value keeps `useAdminTheme()` safe for anything rendered outside
+ * the provider (a hand-mounted Topbar, a test): the toggle then reports the
+ * site theme and does nothing, rather than throwing.
+ */
+const ThemeCtx = createContext({ theme: SITE_THEME, setTheme: () => {}, toggle: () => {} });
+
+export function useAdminTheme() {
+  return useContext(ThemeCtx);
+}
+
+// Before paint where there is a DOM: a stored Base44 theme applied in a passive
+// effect would show one frame of the site theme on every admin load — the exact
+// flash of loud colors the toggle is there to avoid.
+const useThemeEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
+
+export function AdminThemeProvider({ children }) {
+  const [theme, setThemeState] = useState(readStoredTheme);
+
+  // Applies to <html> (portals, see lib/theme.js) and clears on unmount, so
+  // leaving the admin for the storefront restores the site's own theme.
+  useThemeEffect(() => {
+    applyAdminTheme(theme);
+    return () => applyAdminTheme(SITE_THEME);
+  }, [theme]);
+
+  const setTheme = useCallback((next) => {
+    const value = next === BASE44_THEME ? BASE44_THEME : SITE_THEME;
+    setThemeState(value);
+    storeTheme(value);
+  }, []);
+
+  const toggle = useCallback(() => {
+    setThemeState((current) => {
+      const next = current === BASE44_THEME ? SITE_THEME : BASE44_THEME;
+      storeTheme(next);
+      return next;
+    });
+  }, []);
+
+  return <ThemeCtx.Provider value={{ theme, setTheme, toggle }}>{children}</ThemeCtx.Provider>;
+}

package/src/commerce/admin/i18n/locales/de.js

@@ -94,6 +94,11 @@ export default {
   "auth.sign_out": "Abmelden",
   "auth.signed_in_as": "Angemeldet als {email}",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "Neutrale Base44-Farben und -Schriften statt des Website-Designs verwenden",
+  "theme.site": "Website",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "Stadt",
   "address.company": "Firma",

package/src/commerce/admin/i18n/locales/en.js

@@ -98,6 +98,11 @@ export default {
   "auth.sign_out": "Sign out",
   "auth.signed_in_as": "Signed in as {email}",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "Use neutral Base44 dashboard colors and fonts instead of the store's theme",
+  "theme.site": "Site",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "City",
   "address.company": "Company",

package/src/commerce/admin/i18n/locales/es.js

@@ -94,6 +94,11 @@ export default {
   "auth.sign_out": "Cerrar sesión",
   "auth.signed_in_as": "Sesión iniciada como {email}",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "Usar los colores y las fuentes neutros de Base44 en lugar del tema del sitio",
+  "theme.site": "Sitio",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "Ciudad",
   "address.company": "Empresa",

package/src/commerce/admin/i18n/locales/fr.js

@@ -94,6 +94,11 @@ export default {
   "auth.sign_out": "Se déconnecter",
   "auth.signed_in_as": "Connecté en tant que {email}",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "Utiliser les couleurs et polices neutres de Base44 au lieu du thème du site",
+  "theme.site": "Site",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "Ville",
   "address.company": "Société",

package/src/commerce/admin/i18n/locales/ja.js

@@ -94,6 +94,11 @@ export default {
   "auth.sign_out": "サインアウト",
   "auth.signed_in_as": "{email} でサインイン中",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "サイトのテーマではなく Base44 の中立的な配色とフォントを使用します",
+  "theme.site": "サイト",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "市区町村",
   "address.company": "会社名",

package/src/commerce/admin/i18n/locales/pt.js

@@ -94,6 +94,11 @@ export default {
   "auth.sign_out": "Terminar sessão",
   "auth.signed_in_as": "Sessão iniciada como {email}",
 
+  // ── theme toggle ────────────────────────────────────────────────
+  "theme.base44": "Base44",
+  "theme.hint": "Usar as cores e tipos de letra neutros do Base44 em vez do tema do site",
+  "theme.site": "Site",
+
   // ── address form ────────────────────────────────────────────────
   "address.city": "Cidade",
   "address.company": "Empresa",

package/src/commerce/admin/index.jsx

@@ -6,6 +6,7 @@ import AdminLayout from "./layout/AdminLayout";
 import AdminRoutes from "./routes";
 import { SettingsProvider } from "./context/SettingsContext";
 import { BasePathProvider } from "./context/BasePathContext";
+import { AdminThemeProvider } from "./context/ThemeContext";
 
 export { default as AdminRoutes } from "./routes";
 
@@ -37,6 +38,10 @@ export { default as AdminRoutes } from "./routes";
  *
  * Requires an authenticated user with role "admin" (enforced by AuthGuard,
  * and independently by entity RLS + requireAdmin() in backend functions).
+ *
+ * AdminThemeProvider is outermost so the topbar's site/Base44 theme choice also
+ * covers the screens rendered before the admin proper — sign-in, access-denied,
+ * first-run setup — and the toasts, which portal out of the layout.
  */
 export default function AdminApp({ basePath = "/store-admin" }) {
   // Installs from before the routes moved into App.jsx mount the whole admin
@@ -46,13 +51,15 @@ export default function AdminApp({ basePath = "/store-admin" }) {
   // 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>{outlet ?? <AdminRoutes />}</AdminLayout>
-        </SettingsProvider>
-      </AuthGuard>
-    </BasePathProvider>
+    <AdminThemeProvider>
+      <BasePathProvider value={basePath}>
+        <Toaster richColors position="top-right" />
+        <AuthGuard>
+          <SettingsProvider>
+            <AdminLayout>{outlet ?? <AdminRoutes />}</AdminLayout>
+          </SettingsProvider>
+        </AuthGuard>
+      </BasePathProvider>
+    </AdminThemeProvider>
   );
 }

package/src/commerce/admin/layout/AuthGuard.jsx

@@ -25,7 +25,7 @@ const AUTH_CHECK_TIMEOUT_MS = 8000;
 
 /**
  * Blocks the admin UI unless the caller is an authenticated user with
- * role === "admin". Do NOT weaken this check — see the commerce skill's install/01-install.md.
+ * role === "admin". Do NOT weaken this check — see the commerce skill's installation/install.md.
  * (Server-side RLS + requireAdmin() in functions enforce this independently.)
  *
  * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants

package/src/commerce/admin/layout/ThemeToggle.jsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { Switch } from "@/components/ui/switch";
+import { Palette } from "lucide-react";
+import { useAdminTheme } from "../context/ThemeContext";
+import { BASE44_THEME, SITE_THEME } from "../lib/theme";
+import { t } from "../i18n";
+
+/**
+ * Topbar switch between the host site's theme and the built-in Base44 one
+ * (colors and fonts only — `lib/theme.js`).
+ *
+ * Both ends are named — Site ⇄ Base44, off being Site — because a control that
+ * shows one theme cannot say whether that is the state you are in or the one a
+ * click would give you. The side in effect is the one in full-contrast text.
+ * The words are labels, not buttons: one control, one tab stop.
+ */
+export default function ThemeToggle() {
+  const { theme, setTheme } = useAdminTheme();
+  const isBase44 = theme === BASE44_THEME;
+  const side = (active) =>
+    `hidden text-sm sm:inline ${active ? "font-medium text-foreground" : "text-muted-foreground"}`;
+
+  return (
+    <div className="flex shrink-0 items-center gap-2" title={t("theme.hint")}>
+      <Palette className="h-4 w-4 shrink-0 text-muted-foreground" />
+      <span className={side(!isBase44)}>{t("theme.site")}</span>
+      <Switch
+        checked={isBase44}
+        onCheckedChange={(on) => setTheme(on ? BASE44_THEME : SITE_THEME)}
+        aria-label={t("theme.hint")}
+      />
+      <span className={side(isBase44)}>{t("theme.base44")}</span>
+    </div>
+  );
+}

package/src/commerce/admin/layout/Topbar.jsx

@@ -14,6 +14,7 @@ import { base44 } from "../lib/api";
 import { t } from "../i18n";
 import { useAuth } from "./AuthGuard";
 import { useBasePath, useAdminHref } from "../context/BasePathContext";
+import ThemeToggle from "./ThemeToggle";
 import { ADMIN_ROUTES } from "../routes";
 
 /** Match an internal path (no leading slash) against ADMIN_ROUTES patterns. */
@@ -44,7 +45,7 @@ function useBreadcrumbs() {
   return crumbs;
 }
 
-/** Top bar: mobile menu button, breadcrumbs, user menu. */
+/** Top bar: mobile menu button, breadcrumbs, theme toggle, user menu. */
 export default function Topbar({ onMenuClick }) {
   const user = useAuth();
   const href = useAdminHref();
@@ -72,6 +73,7 @@ export default function Topbar({ onMenuClick }) {
           </React.Fragment>
         ))}
       </nav>
+      <ThemeToggle />
       <DropdownMenu>
         <DropdownMenuTrigger asChild>
           <Button variant="ghost" size="sm" className="gap-2">

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

@@ -0,0 +1,212 @@
+/**
+ * The admin's two color/typography themes, applied as CSS custom properties.
+ *
+ *   "site"    — inherit the host app's shadcn tokens (default; nothing applied)
+ *   "base44"  — a fixed, neutral palette and font stack that reads like the
+ *               Base44 dashboard, for stores whose site theme makes the back
+ *               office hard to work in (display fonts, saturated brand colors,
+ *               low-contrast surfaces)
+ *
+ * Only colors and fonts change: no spacing, radii, sizes or layout. The admin
+ * screens keep using semantic classes (`bg-background`, `text-muted-foreground`,
+ * `bg-primary`), so both themes go through the same tokens and no screen needs
+ * to know which one is on.
+ *
+ * Framework-free on purpose — `context/ThemeContext.jsx` is the React wrapper.
+ */
+
+/** Persisted per browser: which theme the admin last chose. */
+export const THEME_STORAGE_KEY = "commerce.admin.theme";
+
+/** Set on <html> while a non-default theme is active; the scoped rules key off it. */
+export const THEME_ATTR = "data-commerce-admin-theme";
+
+export const SITE_THEME = "site";
+export const BASE44_THEME = "base44";
+
+/**
+ * Base44-dashboard palette as shadcn token → HSL triple ("H S% L%").
+ *
+ * Triples, not finished colors, because that is the format shadcn itself
+ * authors in and a triple can always be wrapped for the apps that need a
+ * complete color. Values are a warm near-neutral: white surfaces, near-black
+ * primary, low-chroma grays — the light theme the dashboard ships. There is
+ * deliberately no dark variant; `applyAdminTheme()` suspends the app's `dark`
+ * class instead of guessing at one.
+ */
+const BASE44_TOKENS = {
+  background: "0 0% 100%",
+  foreground: "60 3% 10%",
+  card: "0 0% 100%",
+  "card-foreground": "60 3% 10%",
+  popover: "0 0% 100%",
+  "popover-foreground": "60 3% 10%",
+  primary: "60 3% 10%",
+  "primary-foreground": "40 20% 98%",
+  secondary: "45 14% 96%",
+  "secondary-foreground": "60 3% 10%",
+  muted: "45 14% 96%",
+  "muted-foreground": "50 4% 44%",
+  accent: "45 14% 93%",
+  "accent-foreground": "60 3% 10%",
+  destructive: "0 72% 45%",
+  "destructive-foreground": "0 0% 98%",
+  border: "45 10% 91%",
+  input: "45 10% 88%",
+  ring: "60 3% 10%",
+};
+
+const BASE44_FONT_SANS =
+  'Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif';
+const BASE44_FONT_MONO =
+  'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+
+/** Tokens read to learn the host app's format; the first one defined decides. */
+const PROBE_TOKENS = ["--background", "--foreground", "--primary", "--card"];
+
+/** A bare shadcn triple: "0 0% 100%", "222.2 47.4% 11.2%". */
+const HSL_TRIPLE = /^-?[\d.]+(deg)?\s+[\d.]+%\s+[\d.]+%$/;
+
+/**
+ * Whether this app's tokens hold *finished* colors rather than bare triples.
+ *
+ * shadcn ships both conventions and the CSS that consumes them differs: a
+ * Tailwind v3 app stores `0 0% 100%` and wraps at the point of use
+ * (`hsl(var(--background))`), a v4 app stores `oklch(1 0 0)` and uses the var
+ * directly (`var(--background)`). Writing the wrong shape paints nothing at
+ * all — every surface silently loses its background — so read what the app
+ * already has instead of assuming. Unreadable or undefined tokens fall back to
+ * triples: that is the convention this admin was written against.
+ */
+function tokensAreColors() {
+  if (typeof window === "undefined" || !window.getComputedStyle) return false;
+  const style = window.getComputedStyle(document.documentElement);
+  for (const token of PROBE_TOKENS) {
+    const value = style.getPropertyValue(token).trim();
+    if (value) return !HSL_TRIPLE.test(value);
+  }
+  return false;
+}
+
+/** The style element carrying the rules tokens can't express; created on first use. */
+let scopedStyleEl = null;
+
+/** Custom properties this module set on <html>, so cleanup removes only those. */
+let appliedProps = [];
+
+/** True when we removed the app's `dark` class and owe it a restore. */
+let suspendedDark = false;
+
+/**
+ * The two things a token override cannot reach.
+ *
+ * **Fonts**, which are not tokens in shadcn at all — a store's face arrives as
+ * `body { font-family }` or a Tailwind utility, and both are outranked by these
+ * rules: they are anchored on `<html>` and injected unlayered, so they beat
+ * anything an app declares inside `@layer base`. `.font-mono` and friends are
+ * listed separately so order IDs, coupon codes and the bot's code spans stay
+ * monospaced instead of inheriting the sans stack.
+ *
+ * **The page's own background and text color**, for the common case of a store
+ * that paints `<body>` directly (`background-color: var(--brand-ink)`) next to
+ * its tokens rather than through them. The tokens then say "white surfaces" and
+ * the body still says "near-black, near-white text": the admin's translucent
+ * page layer (`bg-muted/30`) renders muddy over it, and every element that
+ * inherits its color instead of naming one — breadcrumbs, table cells, card
+ * body text — comes out near-white on a white card. Repainting the root from
+ * the same palette is what keeps the theme whole.
+ */
+function applyScopedRules(scope) {
+  if (!scopedStyleEl) {
+    scopedStyleEl = document.createElement("style");
+    scopedStyleEl.setAttribute("data-commerce-admin-theme", "");
+    document.head.appendChild(scopedStyleEl);
+  }
+  scopedStyleEl.textContent = `
+${scope}, ${scope} body {
+  background-color: hsl(${BASE44_TOKENS.background});
+  color: hsl(${BASE44_TOKENS.foreground});
+  font-family: ${BASE44_FONT_SANS};
+}
+${scope} h1, ${scope} h2, ${scope} h3, ${scope} h4, ${scope} h5, ${scope} h6 { font-family: ${BASE44_FONT_SANS}; }
+${scope} .font-mono, ${scope} code, ${scope} kbd, ${scope} pre, ${scope} samp { font-family: ${BASE44_FONT_MONO}; }
+`.trim();
+}
+
+/** Undo everything `applyAdminTheme` set, leaving the app's own theme untouched. */
+function clearAdminTheme() {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  appliedProps.forEach((prop) => root.style.removeProperty(prop));
+  appliedProps = [];
+  root.style.removeProperty("color-scheme");
+  root.removeAttribute(THEME_ATTR);
+  if (scopedStyleEl) {
+    scopedStyleEl.remove();
+    scopedStyleEl = null;
+  }
+  if (suspendedDark) {
+    root.classList.add("dark");
+    suspendedDark = false;
+  }
+}
+
+/**
+ * Apply `theme` to the document, replacing whatever this module applied before.
+ * `SITE_THEME` (or anything unknown) just clears back to the app's own theme.
+ *
+ * Everything lands on `<html>`, not on an admin wrapper, for two reasons: the
+ * shadcn primitives the admin builds on — dropdowns, dialogs, sheets, selects,
+ * toasts — render through portals into `document.body` and would otherwise keep
+ * the site theme while the page behind them changed; and inline properties on
+ * the root outrank every stylesheet rule, including `.dark`. The admin is a
+ * full-page shell, so nothing else is on screen to be affected — but the caller
+ * owns the lifetime and must clear on unmount (`ThemeContext` does).
+ */
+export function applyAdminTheme(theme) {
+  if (typeof document === "undefined") return;
+  clearAdminTheme();
+  if (theme !== BASE44_THEME) return;
+
+  const root = document.documentElement;
+  const asColor = tokensAreColors();
+  Object.entries(BASE44_TOKENS).forEach(([name, triple]) => {
+    const prop = `--${name}`;
+    root.style.setProperty(prop, asColor ? `hsl(${triple})` : triple);
+    appliedProps.push(prop);
+  });
+  // Tailwind v4 resolves `font-sans`/`font-mono` through these; harmless in v3.
+  root.style.setProperty("--font-sans", BASE44_FONT_SANS);
+  root.style.setProperty("--font-mono", BASE44_FONT_MONO);
+  appliedProps.push("--font-sans", "--font-mono");
+
+  // This palette is a light one. Leaving a `dark` class in place would keep the
+  // app's `dark:` utilities and native controls dark over light surfaces, so
+  // the class steps aside while the theme is on and comes back when it is off.
+  if (root.classList.contains("dark")) {
+    root.classList.remove("dark");
+    suspendedDark = true;
+  }
+  root.style.setProperty("color-scheme", "light");
+
+  root.setAttribute(THEME_ATTR, BASE44_THEME);
+  applyScopedRules(`html[${THEME_ATTR}="${BASE44_THEME}"]`);
+}
+
+/** The stored choice, or the site theme when nothing is stored or storage is blocked. */
+export function readStoredTheme() {
+  try {
+    return localStorage.getItem(THEME_STORAGE_KEY) === BASE44_THEME ? BASE44_THEME : SITE_THEME;
+  } catch {
+    return SITE_THEME;
+  }
+}
+
+/** Remember the choice for next time; a blocked localStorage is not worth failing over. */
+export function storeTheme(theme) {
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    /* private mode / storage disabled — the theme still applies for this session */
+  }
+}