@commercelayer/agent-cli 0.1.13 → 0.2.0

package/README.md

@@ -6,7 +6,8 @@ It is a separate tool from [`@commercelayer/cli`](https://www.npmjs.com/package/
 npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11r init
 ```
 ## How it works
-- **The repo is the store.** `.commercelayer/store.yml` holds the desired state (name, markets, storefront, policies, and the products of a small store) and is committed; a large catalog goes in `.commercelayer/products/` as `.yml` or `.csv` files. `plan` shows what `apply` would change; `apply` makes the store match the files.
+- **The repo is the store.** `.commercelayer/store.yml` holds the desired state (name, markets, theme, policies, and the products of a small store) and is committed; a large catalog goes in `.commercelayer/products/` as `.yml` or `.csv` files, images in `.commercelayer/img/`. `plan` shows what `apply` would change; `apply` makes the store match the files.
+- **The website comes with the store.** Every store has a hosted theme at its preview URL, set by a few `theme:` settings and the product data: `apply` is all it takes. A custom storefront (your own web app) is opt-in: `storefront init`, `publish` and `check`.
 - **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
 - **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
 - **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it. The keys of a catalog source go in the same file.
@@ -14,12 +15,12 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | Command | Does |
 | --- | --- |
 | `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`. Reuses the store if they exist. |
-| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, and the store's name and policies. |
-| `apply [--allow-delete] [--full]` | Make the store match the files. Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused; While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
+| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, images, and the store's name, policies and theme. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
+| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused; While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
 | `catalog pull` | Read the products from the catalog source in `store.yml` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
-| `storefront init [--force]` | Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. `img/`: product images (`image_url: img/<file>`); products with no image get a neutral tile. Refuses to overwrite without the flag; with it, rewrites the three files. |
-| `storefront publish` | Upload the folder at `storefront.path` (default `storefront`) to the store host, leaving out dotfiles. Lists products whose `image_url` points at a file that is not in the folder (`missing_images`). |
-| `storefront check` | Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
+| `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image get a neutral tile. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
+| `storefront publish` | Custom storefronts only. Upload the folder at `storefront.path` (default `storefront`) to the store host, where it replaces the hosted theme, leaving out dotfiles. `/img/` on the store host is always the store's images, so files under the folder's `img/` are not served: publish lists them as `not_served`. |
+| `storefront check` | Custom storefronts only. Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
 | `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
 | `orders show <id or number>` | One order. |
@@ -49,11 +50,14 @@ products:
   - sku: COFFEE-ETH-250
     name: Ethiopia Yirgacheffe, 250 g
     description: Washed, floral, bright.
-    image_url: https://example.com/eth.jpg
+    image_url: img/eth.jpg   # .commercelayer/img/eth.jpg, or an https:// URL
     prices: { EUR: 14.50, USD: 16.00 }
-storefront:
-  # The web app in this repo that sells the products, relative to the repo root.
-  path: storefront
+theme:
+  # The hosted website. Every setting is optional.
+  color: "#2f5d50"     # the accent: buttons, links, the hero band; text on it is black or white by contrast
+  logo: img/logo.svg   # or an https:// URL; default: the name as a wordmark
+  hero: img/hero.jpg   # the home page's wide image; default: a band in the accent
+  tagline: Small-batch coffee, roasted in Milan   # at most 120 characters; default: "Ships to <countries>"
 policies:
   # Pages shopping agents show buyers before they pay. Without them the store
   # serves default sandbox pages at <preview_url>/policies/<name>.
@@ -85,7 +89,14 @@ catalog:
 - `merchant`: a Google Merchant Center product feed URL, RSS 2.0 (XML, `g:` namespace) or TSV. `id` is the sku, `title` the name, `description`, `image_link` the image, `price` (`14.50 EUR`) the price in its currency, `product_type` the category. An id listed once per currency is one product with several prices. Other attributes, `sale_price` included, are ignored.
 Error codes: `no_catalog_source`, `invalid_catalog`, `missing_credentials`, `catalog_unreachable`, `catalog_unauthorized`, `catalog_not_found`, `catalog_not_csv`, `catalog_error`, `empty_catalog`, plus `invalid_product` and `missing_price`.
 
-Error codes: `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
+### The website
+The theme renders the home page (logo, hero with name and tagline, products by top-level category), a page per category at `/categories/<slug>/...` and per product at `/products/<sku>`, with the market from `?market=<code>`, cart and checkout. Images written `img/<file>` (`theme.logo`, `theme.hero`, a product's `image_url`) are files in `.commercelayer/img/`, served at `<preview_url>/img/<file>`: paths of letters, digits, `.`, `_`, `-` and `/`, a lowercase `png`, `jpg`, `jpeg`, `webp`, `gif`, `avif` or `svg` extension, at most 5 MB each. `apply` uploads the new and changed ones (by SHA-256) before anything else, and the store host drops the ones nothing references any more.
+
+One rule for images: `img/<file>` anywhere in `store.yml` (product `image_url`, `theme.logo`, `theme.hero`) is `.commercelayer/img/<file>`, uploaded by `apply`, served at `/img/<file>`, whatever is in front.
+
+A custom storefront replaces the theme: `storefront.path` in `store.yml` names its folder, `storefront init` writes a drop-in.js scaffold, `storefront publish` uploads it, `storefront check` checks it. Its pages link product images at `/img/`; its own files (fonts, icons, styles) go in `assets/`, not `img/`.
+
+Error codes: `invalid_theme`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
 | What | Where |

package/dist/api/client.js

@@ -31,6 +31,7 @@ export function createApi(auth) {
         createSandbox: (name) => request('POST', '/sandboxes', { name }),
         getStore: () => request('GET', org()),
         applyStore: (body) => request('PUT', `${org()}/resources`, body),
+        uploadAssets: (files) => request('PUT', `${org()}/assets`, { files }),
         publishStorefront: (path, files) => request('PUT', `${org()}/storefront`, { path, files }),
         listOrders: () => request('GET', `${org()}/orders`),
         getOrder: (id) => request('GET', `${org()}/orders/${encodeURIComponent(id)}`),

package/dist/api/stub/management.js

@@ -1,13 +1,13 @@
 // The management API at api.commercelayer.ai: sandboxes, resources, storefront
 // uploads, orders, claims. The CLI's only private API; the store hosts speak UCP.
 import crypto from 'node:crypto';
-import { canonical } from '../../store.js';
+import { canonical, IMAGE_PATH } from '../../store.js';
 import { generateKey } from '../../ucp/signing.js';
 import { publicOrders, readDb, SANDBOX_DOMAIN, writeDb } from './db.js';
 import { bearer, error, json, readJson } from './http.js';
 function publicState(r) {
-    const { token: _token, ucp: _ucp, pending: _pending, ...state } = r;
-    return { ...state, name: r.name ?? null, policies: r.policies ?? null, apply: r.apply ?? null, orders: publicOrders(r) };
+    const { token: _token, ucp: _ucp, pending: _pending, asset_files: _files, ...state } = r;
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, assets: r.assets ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
 }
 /** Like Commerce Layer refusing a sku in an import. Only the stub does this, so tests can exercise apply_failed. */
 const REFUSED = /^REFUSED-/;
@@ -98,7 +98,7 @@ export function handleManagement(req) {
         writeDb(db);
         if (record.apply?.status === 'in_progress')
             return error(409, 'apply_in_progress', 'Another apply is still running.', 'Run `c11r status` to follow it, then apply again.');
-        const { applied, hash, name, policies, allow_delete, full } = readJson(req);
+        const { applied, hash, name, policies, theme, assets, allow_delete, full } = readJson(req);
         const before = record.applied?.products ?? {};
         const removed = Object.keys(before).filter((sku) => !(sku in applied.products));
         if (removed.length && !allow_delete)
@@ -107,6 +107,17 @@ export function handleManagement(req) {
         // import job (SKUs, prices, then cleanups for removals) when any changed.
         record.name = name;
         record.policies = policies ?? {};
+        if (theme !== undefined)
+            record.theme = theme;
+        // Images not in the list are no longer used: dropped now. No list (older CLIs): nothing is dropped.
+        if (assets) {
+            for (const p of Object.keys(record.assets ?? {})) {
+                if (!assets.includes(p)) {
+                    delete record.assets[p];
+                    delete record.asset_files[p];
+                }
+            }
+        }
         const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || canonical(before[sku]) !== canonical(applied.products[sku]));
         if (changed.length === 0 && removed.length === 0) {
             record.applied = applied;
@@ -129,6 +140,30 @@ export function handleManagement(req) {
         writeDb(db);
         return json(202, publicState(record));
     }
+    if (req.method === 'PUT' && rest === '/assets') {
+        const { files } = readJson(req);
+        let total = 0;
+        for (const f of files ?? []) {
+            if (!IMAGE_PATH.test(f.path) || f.path.includes('..') || f.path.includes('//'))
+                return error(422, 'invalid_asset', `${f.path} is not an image path the store host serves.`, 'Use img/<file> with letters, digits, . _ - and /, and an image extension.');
+            const bytes = Buffer.from(f.content_base64, 'base64');
+            if (crypto.createHash('sha256').update(bytes).digest('hex') !== f.sha256)
+                return error(422, 'asset_mismatch', `${f.path} does not hash to the sha256 sent.`, 'Run `c11r apply` again.');
+            if (bytes.length > 5 * 1024 * 1024)
+                return error(413, 'asset_too_large', `${f.path} is larger than 5 MB.`, 'Make the image smaller and apply again.');
+            total += bytes.length;
+        }
+        if (total > 25 * 1024 * 1024)
+            return error(413, 'upload_too_large', 'The upload is larger than 25 MB.', 'This is a bug in the CLI: it batches uploads. Tell the human, with this output.');
+        record.assets ??= {};
+        record.asset_files ??= {};
+        for (const f of files ?? []) {
+            record.assets[f.path] = f.sha256;
+            record.asset_files[f.path] = f.content_base64;
+        }
+        writeDb(db);
+        return json(200, { assets: record.assets });
+    }
     if (req.method === 'PUT' && rest === '/storefront') {
         const { path: dir, files } = readJson(req);
         if (!files?.some((f) => f.path === 'index.html')) {

package/dist/api/stub/theme.js

@@ -0,0 +1,63 @@
+// A stand-in for the hosted theme the store Worker renders on every store without a
+// custom storefront: the same settings in the same places (accent, logo or wordmark,
+// hero image or band, tagline), the products by top-level category, a page per product
+// at /products/<sku>. Prices come from what is applied; "Buy" opens the cart permalink.
+const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/** Black or white, whichever reads better on the accent. */
+function onAccent(hex) {
+    const h = hex.length === 4 ? hex.slice(1).replace(/./g, (c) => c + c) : hex.slice(1);
+    const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.179 ? '#000000' : '#ffffff';
+}
+export function renderTheme(r, path, search) {
+    const products = Object.values(r.applied?.products ?? {});
+    const markets = Object.values(r.applied?.markets ?? {});
+    const theme = r.theme ?? {};
+    const color = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(theme.color ?? '') ? theme.color : '#2f5d50';
+    const name = r.name ?? r.org;
+    const market = markets.find((m) => m.code === search.get('market')) ?? markets[0];
+    const keep = market && market !== markets[0] ? `?market=${encodeURIComponent(market.code)}` : '';
+    const price = (p) => (market && p.prices[market.currency] !== undefined ? `${market.currency} ${p.prices[market.currency].toFixed(2)}` : '');
+    const tagline = theme.tagline ?? `Ships to ${markets.flatMap((m) => m.countries).join(', ')}`;
+    const logo = theme.logo ? `<img class="logo" src="/${esc(theme.logo.replace(/^\//, ''))}" alt="${esc(name)}">` : `<span class="wordmark">${esc(name)}</span>`;
+    const img = (url) => (/^https?:/.test(url) ? url : `/${url}`);
+    const card = (p) => `<article class="product"><a href="/products/${encodeURIComponent(p.sku)}${keep}">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<h3>${esc(p.name)}</h3></a><p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></article>`;
+    let title = name;
+    let body;
+    const m = path.match(/^\/products\/([^/]+)$/);
+    if (path === '/') {
+        const groups = new Map();
+        for (const p of products) {
+            const top = p.category?.split(' > ')[0] ?? 'Other';
+            groups.set(top, [...(groups.get(top) ?? []), p]);
+        }
+        const hero = theme.hero ? `<section class="hero" style="background-image:url('${esc(img(theme.hero))}')">` : '<section class="hero band">';
+        body = `${hero}<h1>${esc(name)}</h1><p class="tagline">${esc(tagline)}</p></section><main>${[...groups].map(([k, ps]) => `<section><h2>${esc(k)}</h2><div class="grid">${ps.map(card).join('')}</div></section>`).join('')}</main>`;
+    }
+    else if (m) {
+        const p = r.applied?.products[decodeURIComponent(m[1])];
+        if (!p)
+            return null;
+        title = `${p.name} · ${name}`;
+        body = `<main class="product-page">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<div>${p.category ? `<p class="category">${esc(p.category)}</p>` : ''}<h1>${esc(p.name)}</h1>${p.description ? `<p>${esc(p.description)}</p>` : ''}<p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></div></main>`;
+    }
+    else
+        return null;
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<meta name="description" content="${esc(tagline)}">
+<!-- c11r stub: a stand-in for the hosted theme. -->
+<style>:root{--accent:${color};--on-accent:${onAccent(color)}}body{margin:0;font-family:system-ui,sans-serif;color:#16181d}header{display:flex;justify-content:space-between;padding:16px 24px}.logo{max-height:40px}.hero{padding:64px 24px;background-size:cover}.band{background:var(--accent);color:var(--on-accent)}.grid{display:grid;gap:24px;grid-template-columns:repeat(auto-fill,minmax(220px,1fr))}.buy{background:var(--accent);color:var(--on-accent);padding:8px 14px}main{padding:24px}</style>
+</head>
+<body>
+<header><a href="/${keep}">${logo}</a><nav>${markets.map((x) => `<a href="?market=${encodeURIComponent(x.code)}">${esc(x.name)}</a>`).join(' ')}</nav></header>
+${body}
+</body>
+</html>
+`;
+    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: html };
+}

package/dist/api/stub/ucp.js

@@ -8,6 +8,7 @@ import { contentDigest, signHeaders } from '../../ucp/signing.js';
 import { strip } from './db.js';
 import { json } from './http.js';
 import * as shop from './shopping.js';
+import { renderTheme } from './theme.js';
 const SCOPES = ['dev.ucp.shopping.order:read', 'dev.ucp.shopping.order:manage'];
 const OUR_CAPABILITIES = [...SHOPPING_CAPABILITIES, 'dev.ucp.common.ask', ...Object.keys(EXTENSIONS), 'dev.ucp.common.identity_linking', 'dev.ucp.shopping.permalink'];
 // ---------- profile
@@ -301,9 +302,21 @@ function handlePermalink(req, r, origin, path) {
         target = `${origin}/carts/${cartId}`;
     return { status: 303, headers: { location: target, ...safe }, body: '' };
 }
-const MIME = { html: 'text/html; charset=utf-8', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', ico: 'image/x-icon', txt: 'text/plain' };
-function serveStorefront(r, path) {
+const MIME = { html: 'text/html; charset=utf-8', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', avif: 'image/avif', ico: 'image/x-icon', txt: 'text/plain' };
+function serveStorefront(r, path, search) {
     const files = r.ucp.files;
+    // A custom storefront (an uploaded index.html) serves every path; otherwise the theme renders its routes.
+    if (files['index.html'] === undefined) {
+        const page = renderTheme(r, path, search);
+        if (page)
+            return page;
+    }
+    // /img/ is the store's images (uploaded by apply), whatever is in front of them.
+    const asset = r.asset_files?.[path.replace(/^\//, '')];
+    if (asset !== undefined) {
+        const ext = path.split('.').pop() ?? '';
+        return { status: 200, headers: { 'content-type': MIME[ext] ?? 'application/octet-stream' }, body: Buffer.from(asset, 'base64').toString('binary') };
+    }
     const candidates = [path.replace(/^\//, ''), `${path.replace(/^\/|\/$/g, '')}/index.html`.replace(/^\//, ''), ...(path === '/' ? ['index.html'] : [])];
     for (const c of candidates) {
         if (files[c] !== undefined) {
@@ -311,8 +324,6 @@ function serveStorefront(r, path) {
             return { status: 200, headers: { 'content-type': MIME[ext] ?? 'application/octet-stream' }, body: Buffer.from(files[c], 'base64').toString(ext in MIME && !MIME[ext].startsWith('image') ? 'utf8' : 'binary') };
         }
     }
-    if (Object.keys(files).length === 0)
-        return html(200, r.org, '<p>Nothing published yet. Run <code>c11r storefront publish</code>.</p>');
     return html(404, 'Not found', `<p>No ${path} in this storefront.</p>`);
 }
 // ---------- the host
@@ -342,7 +353,7 @@ export function handleUcp(req, r) {
             return html(404, 'Not found', `<p>No ${kind} ${m[2]}.</p>`);
         return html(200, `${kind === 'order' ? `Order ${found.label}` : `Your ${kind}`}`, `<p>${kind === 'order' ? 'Thank you. ' : ''}${found.line_items.length} line item(s), ${found.currency} ${(found.totals.at(-1).amount / 100).toFixed(2)}.</p>`);
     }
-    return serveStorefront(r, path);
+    return serveStorefront(r, path, req.url.searchParams);
 }
 /** Lets the service read the bearer token for order authorization. */
 export function bearerOf(req) {

package/dist/assets.js

@@ -0,0 +1,100 @@
+// The store's image files: logo, hero and product images written img/<file> live in
+// .commercelayer/img/ and are served by the store host at <preview_url>/img/<file>,
+// in front of the theme or a custom storefront alike.
+// apply uploads the new and changed ones (by sha256) before the resources, and the
+// resources PUT lists the ones still used, so the API drops the rest. plan and status
+// report the same changes, the referenced files that are missing, and files nothing uses.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { paths } from './files.js';
+import { fail } from './output.js';
+import { isLocalImage } from './store.js';
+export const imgDir = path.join(paths.dir, 'img');
+/** The API's limits: a file, and the decoded bytes of one upload. */
+const MAX_FILE = 5 * 1024 * 1024;
+const MAX_BATCH = 20 * 1024 * 1024;
+/** Every img/<file> the store references: theme logo and hero, product images. */
+export function referencedImages(store) {
+    const refs = new Map();
+    const add = (url, by) => {
+        if (url && isLocalImage(url))
+            refs.set(url, [...(refs.get(url) ?? []), by]);
+    };
+    add(store.theme?.logo, 'theme.logo');
+    add(store.theme?.hero, 'theme.hero');
+    for (const p of store.products)
+        add(p.image_url, p.sku);
+    return refs;
+}
+function filesUnder(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs
+        .readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((e) => e.isFile())
+        .map((e) => path.relative(dir, path.join(e.parentPath, e.name)).split(path.sep).join('/'))
+        .filter((rel) => !rel.split('/').some((part) => part.startsWith('.')));
+}
+const sha256 = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+export function planAssets(state, store) {
+    const refs = referencedImages(store);
+    const missing = [];
+    const local = new Map();
+    for (const [ref, by] of refs) {
+        const file = path.join(paths.dir, ref);
+        if (fs.existsSync(file)) {
+            if (fs.statSync(file).size > MAX_FILE)
+                fail('asset_too_large', `${file} is larger than 5 MB.`, 'Make the image smaller (a product photo needs about 2000 px on the long side), keep the name, and run the command again.');
+            local.set(ref, { file, sha256: sha256(file) });
+        }
+        else
+            missing.push(`${by.join(', ')}: ${ref}`);
+    }
+    const unused = filesUnder(imgDir)
+        .map((rel) => `img/${rel}`)
+        .filter((p) => !refs.has(p));
+    const supported = state.assets !== undefined;
+    const served = state.assets ?? {};
+    const changes = [];
+    const upload = [];
+    if (supported) {
+        for (const [p, l] of [...local].sort(([a], [b]) => (a < b ? -1 : 1))) {
+            if (served[p] === l.sha256)
+                continue;
+            changes.push({ action: p in served ? 'update' : 'create', type: 'asset', id: p });
+            upload.push({ path: p, ...l });
+        }
+        for (const p of Object.keys(served).sort())
+            if (!local.has(p))
+                changes.push({ action: 'delete', type: 'asset', id: p });
+    }
+    return { supported, changes, missing, unused, keep: [...local.keys()].sort(), upload };
+}
+/** Upload the new and changed files, in requests under the API's size cap. */
+export async function uploadAssets(api, plan) {
+    let batch = [];
+    let bytes = 0;
+    const flush = async () => {
+        if (batch.length)
+            await api.uploadAssets(batch);
+        batch = [];
+        bytes = 0;
+    };
+    for (const u of plan.upload) {
+        const content = fs.readFileSync(u.file);
+        if (bytes + content.length > MAX_BATCH)
+            await flush();
+        batch.push({ path: u.path, sha256: u.sha256, content_base64: content.toString('base64') });
+        bytes += content.length;
+    }
+    await flush();
+    return plan.upload.length;
+}
+/** The fields plan and status add for images: only when there is something to say. */
+export function imageNotes(plan) {
+    return {
+        missing_images: plan.missing.length ? plan.missing : undefined,
+        unused_images: plan.unused.length ? plan.unused : undefined,
+    };
+}

package/dist/commands.js

@@ -6,8 +6,9 @@ import path from 'node:path';
 import { createApi } from './api/client.js';
 import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCredentials } from './files.js';
 import { CliError, fail, progress } from './output.js';
-import { diff, hashStore, isLocalImage, loadStore, storefrontPath, template, toApplied } from './store.js';
+import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontFiles } from './storefront.js';
+import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
 import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
@@ -18,12 +19,12 @@ import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
 export const HELP = {
     init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
-    plan: 'Show what apply would create, update or delete: markets, products and the store\'s name and policies, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
-    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
+    plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
+    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
     'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant, url, table }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category and one price column per market currency, in lowercase (eur, usd). Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV.',
-    'storefront init': 'Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js, plus img/ for product images. Refuses to overwrite unless --force is given.',
-    'storefront check': 'Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
-    'storefront publish': 'Upload the storefront folder (store.yml storefront.path, default storefront) to the sandbox preview URL.',
+    'storefront init': 'Custom storefronts only: the hosted theme needs none of this (set theme: in store.yml and apply). Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js. Product images are the store\'s, at /img/ (.commercelayer/img/, uploaded by apply); the site\'s own files go in storefront/assets/. Refuses to overwrite unless --force is given.',
+    'storefront check': 'Custom storefronts only. Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
+    'storefront publish': 'Custom storefronts only: upload the storefront folder (store.yml storefront.path, default storefront) to the preview URL, where it replaces the hosted theme.',
     'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline.',
     'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
     'orders show': 'Show one order: c11r orders show <id or number>.',
@@ -75,15 +76,22 @@ export async function init(values) {
         expires_at: sandbox.expires_at,
         preview_url: sandbox.preview_url,
         files,
-        next: 'Describe the store in .commercelayer/store.yml (products there or in .commercelayer/products/*.yml|csv), then run c11r plan.',
+        next: 'Describe the store in .commercelayer/store.yml (products there or in .commercelayer/products/*.yml|csv, the theme under theme:, images in .commercelayer/img/), then run c11r plan and c11r apply: the website is live at preview_url.',
     };
 }
 export async function plan() {
     const api = createApi(requireCredentials());
     const desired = loadStore();
     const state = await api.getStore();
-    const changes = diff(state, desired);
-    return { status: changes.length ? 'changes' : 'up_to_date', changes, deletes: changes.filter((c) => c.action === 'delete').length };
+    const assets = planAssets(state, desired);
+    const changes = [...diff(state, desired), ...assets.changes];
+    return {
+        status: changes.length ? 'changes' : 'up_to_date',
+        changes,
+        deletes: changes.filter((c) => c.action === 'delete' && c.type !== 'asset').length,
+        ...imageNotes(assets),
+        next: assets.missing.length ? 'Put the missing images in .commercelayer/img/ (img/<file> in store.yml is .commercelayer/img/<file>), or fix the references: apply refuses until they are there.' : undefined,
+    };
 }
 /** How often apply reads a running import, and when it stops waiting. Env overrides are for tests. */
 const POLL_MS = Number(process.env.C11R_APPLY_POLL_MS) || 2000;
@@ -130,12 +138,28 @@ export async function apply(flags) {
     let state = await api.getStore();
     if (state.apply?.status === 'in_progress')
         state = await follow(api, state);
-    const changes = diff(state, desired);
-    const deletes = changes.filter((c) => c.action === 'delete');
+    const assets = planAssets(state, desired);
+    const changes = [...diff(state, desired), ...assets.changes];
+    // Images nothing uses any more are dropped without asking: they are copies of files in the repo.
+    const deletes = changes.filter((c) => c.action === 'delete' && c.type !== 'asset');
     if (deletes.length && !flags.has('--allow-delete')) {
         fail('deletes_need_approval', `Apply would delete ${deletes.map((d) => `${d.type} ${d.id}`).join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
     }
-    const body = { applied: toApplied(desired), hash: hashStore(), name: desired.name, policies: desired.policies, ...(flags.has('--allow-delete') && { allow_delete: true }), ...(flags.has('--full') && { full: true }) };
+    if (assets.missing.length) {
+        fail('missing_images', `The store references images that are not in .commercelayer/img/: ${assets.missing.join('; ')}.`, 'Put the files there (img/<file> in store.yml is .commercelayer/img/<file>), or fix or remove the references, then apply again.');
+    }
+    // Images first, so the theme and products never point at a file the store host does not have yet.
+    const uploaded = assets.supported ? await uploadAssets(api, assets) : 0;
+    const body = {
+        applied: toApplied(desired),
+        hash: hashStore(),
+        name: desired.name,
+        policies: desired.policies,
+        theme: desired.theme ?? {},
+        ...(assets.supported && { assets: assets.keep }),
+        ...(flags.has('--allow-delete') && { allow_delete: true }),
+        ...(flags.has('--full') && { full: true }),
+    };
     const started = await api.applyStore(body);
     const job = started.apply?.status === 'in_progress' ? started.apply : null;
     const done = job ? await follow(api, started) : started;
@@ -152,6 +176,8 @@ export async function apply(flags) {
         markets: desired.markets.length,
         products: desired.products.length,
         payment_gateway: 'sandbox (test payments only)',
+        images_uploaded: uploaded || undefined,
+        unused_images: assets.unused.length ? assets.unused : undefined,
         apply: job && done.apply ? jobSummary(done.apply) : undefined,
     };
 }
@@ -173,17 +199,12 @@ export async function storefrontInit(flags) {
         fs.writeFileSync(file, content);
         written.push(file);
     }
-    // img/ is where product images go (image_url: img/<file>); .gitkeep keeps the empty folder in git, and publish skips dotfiles.
-    const keep = path.join(dir, 'img', '.gitkeep');
-    fs.mkdirSync(path.dirname(keep), { recursive: true });
-    if (!fs.existsSync(keep))
-        fs.writeFileSync(keep, '');
     return {
         status: 'created',
-        files: [...written, keep],
+        files: written,
         markets: desired.markets.map((m) => m.code),
         products: desired.products.length,
-        next: `Set storefront.path: ${dir} in ${paths.store}, make it the human's (restyle through the tokens at the top of styles.css; product images go in ${dir}/img/ with image_url: img/<file>; each product has a page at #/p/<sku>, built from #product-template in index.html), then run c11r storefront publish.`,
+        next: `Set storefront.path: ${dir} in ${paths.store}, make it the human's (restyle through the tokens at the top of styles.css; each product has a page at #/p/<sku>, built from #product-template in index.html; product images come from .commercelayer/img/ at /img/, and this site's own files go in ${dir}/assets/), then run c11r storefront publish.`,
     };
 }
 export async function storefrontCheckCmd() {
@@ -202,18 +223,8 @@ export async function storefrontPublish() {
         .map((e) => path.relative(dir, path.join(e.parentPath, e.name)).split(path.sep).join('/'))
         .filter((rel) => !rel.split('/').some((part) => part.startsWith('.')))
         .map((rel) => ({ path: rel, content_base64: fs.readFileSync(path.join(dir, rel)).toString('base64') }));
-    // Products whose image_url is a path in the storefront that is not there.
-    let missingImages = [];
-    try {
-        const uploaded = new Set(files.map((f) => f.path));
-        missingImages = loadStore()
-            .products.filter((p) => p.image_url && isLocalImage(p.image_url) && !uploaded.has(p.image_url.replace(/^\.?\//, '')))
-            .map((p) => `${p.sku}: ${p.image_url}`);
-    }
-    catch (e) {
-        if (!(e instanceof CliError))
-            throw e;
-    }
+    // /img/ on the store host is the store's images (.commercelayer/img/, uploaded by apply): files here under img/ are never served.
+    const shadowed = files.filter((f) => f.path.startsWith('img/')).map((f) => f.path);
     const published = await api.publishStorefront(dir, files);
     const state = await api.getStore();
     return {
@@ -222,8 +233,8 @@ export async function storefrontPublish() {
         path: dir,
         files: published.files,
         published_at: published.published_at,
-        missing_images: missingImages.length ? missingImages : undefined,
-        next: missingImages.length ? `Add the missing images under ${dir}/ (image_url is relative to it), or fix image_url, then publish again.` : undefined,
+        not_served: shadowed.length ? shadowed : undefined,
+        next: shadowed.length ? `/img/ is the store's images, from .commercelayer/img/ (uploaded by apply): move product images there and this site's own files to ${dir}/assets/.` : undefined,
     };
 }
 /** The store's origin on the web: where it speaks UCP. */
@@ -283,7 +294,8 @@ export async function status() {
     let pending = [];
     let storeError;
     try {
-        pending = diff(s, loadStore());
+        const desired = loadStore();
+        pending = [...diff(s, desired), ...planAssets(s, desired).changes];
     }
     catch (e) {
         if (!(e instanceof CliError))

package/dist/store.js

@@ -10,6 +10,7 @@ import { paths } from './files.js';
 import { productFiles, readProductFile } from './products.js';
 /** The keys a product may have. Stock is not one: inventory lives in Commerce Layer. */
 export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'category', 'prices'];
+export const THEME_KEYS = ['color', 'logo', 'hero', 'tagline'];
 export const template = (name) => `# Commerce Layer store. This file is the store: edit it, then run
 #   c11r plan    to see what will change
 #   c11r apply   to make the change
@@ -31,6 +32,7 @@ products:
   #   <name>.yml   a list of products in this same shape
   #   <name>.csv   one product per row, columns: sku, name, description, image_url,
   #                category, and one column per currency (EUR, USD, ...) with the price
+  # image_url is an https:// URL or a file in .commercelayer/img/, written img/<file>.
   # category is optional, a path from the top level: Coffee > Single origin.
   # Use the folder for anything beyond a handful of products.
   # sku is unique and stays the same when you rename a product.
@@ -51,8 +53,17 @@ catalog:
   # url: https://...
   # table: products
 
+theme:
+  # The store's website: a theme the platform renders and keeps up to date.
+  # Every setting is optional. Images live in .commercelayer/img/ and apply uploads them.
+  # color: "#2f5d50"     # the accent: buttons, links, the hero band
+  # logo: img/logo.svg   # or an https:// URL; without it the name is the logo
+  # hero: img/hero.jpg   # the home page's wide image; without it a band in the accent
+  # tagline: Small-batch coffee, roasted in Milan   # at most 120 characters
+
 storefront:
-  # The web app in this repo that sells the products, relative to the repo root.
+  # Only for a custom storefront (your own web app in this repo, published with
+  # c11r storefront publish): it replaces the theme. Its folder, from the repo root.
   # path: storefront
 
 policies:
@@ -130,9 +141,10 @@ export function loadStore() {
         if (url && !/^https?:\/\//.test(String(url)))
             fail('invalid_store', `policies.${key} is not a URL.`, 'Policy entries are full URLs starting with https://, or left out to use the default sandbox pages.');
     }
+    const theme = checkTheme(doc.theme);
     const currencies = [...new Set(markets.map((m) => m.currency))];
     const products = checkProducts(sourced, currencies);
-    return { name: doc.name, markets, products, storefront: doc.storefront, policies };
+    return { name: doc.name, markets, products, storefront: doc.storefront, policies, theme };
 }
 /** The product rules, shared by loadStore and catalog pull: errors name each product's source. */
 export function checkProducts(sourced, currencies) {
@@ -153,11 +165,8 @@ export function checkProducts(sourced, currencies) {
             const why = unknown.includes('stock') ? 'Stock is not part of the catalog: inventory is tracked live in Commerce Layer. ' : '';
             fail('invalid_product', `Product ${p.sku} in ${source} has ${unknown.length === 1 ? 'a field' : 'fields'} not in the catalog: ${unknown.join(', ')}.`, `${why}A product has ${PRODUCT_KEYS.join(', ')}. Remove the other fields.`);
         }
-        if (p.image_url !== undefined) {
-            const url = String(p.image_url);
-            const ok = isLocalImage(url) ? !url.split('/').includes('..') && url.trim() === url && url !== '' : /^https?:\/\/\S+$/.test(url);
-            if (!ok)
-                fail('invalid_product', `Product ${p.sku} in ${source} has image_url "${url}".`, 'Use a full https:// URL, or a path in the storefront folder such as img/eth.jpg (no "..").');
+        if (p.image_url !== undefined && !isImageRef(String(p.image_url))) {
+            fail('invalid_product', `Product ${p.sku} in ${source} has image_url "${p.image_url}".`, IMAGE_HINT);
         }
         if (p.category !== undefined) {
             const parts = typeof p.category === 'string' ? p.category.split('>').map((c) => c.trim()) : [''];
@@ -175,8 +184,36 @@ export function checkProducts(sourced, currencies) {
     }
     return products;
 }
-/** An image_url that is a path in the storefront (img/eth.jpg), not a URL. */
+/** An image reference that is a file in .commercelayer/img/ (img/eth.jpg), not a URL. */
 export const isLocalImage = (url) => !/^[a-z][a-z0-9+.-]*:/i.test(url) && !url.startsWith('//');
+/** The paths the store host serves images at, as the API accepts them. */
+export const IMAGE_PATH = /^img\/[A-Za-z0-9._-][A-Za-z0-9._/-]*\.(png|jpg|jpeg|webp|gif|avif|svg)$/;
+/** image_url, logo, hero: an https URL, or img/<file> for a file in .commercelayer/img/. */
+export const isImageRef = (url) => isLocalImage(url) ? IMAGE_PATH.test(url) && !url.includes('..') && !url.includes('//') : /^https?:\/\/\S+$/.test(url);
+const IMAGE_HINT = 'Use a full https:// URL, or img/<file> for a file in .commercelayer/img/ (letters, digits, . _ - and /; extension png, jpg, jpeg, webp, gif, avif or svg, in lowercase).';
+/** The theme block of store.yml, validated: the theme would ignore bad values, so say so here. */
+function checkTheme(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        fail('invalid_theme', 'theme in store.yml is not a mapping.', 'Write `theme:` with color, logo, hero and tagline under it, each optional. See the comments in store.yml.');
+    const t = raw;
+    const unknown = Object.keys(t).filter((k) => !THEME_KEYS.includes(k));
+    if (unknown.length)
+        fail('invalid_theme', `theme in store.yml has ${unknown.length === 1 ? 'a setting' : 'settings'} the theme does not have: ${unknown.join(', ')}.`, `The theme's settings are ${THEME_KEYS.join(', ')}. A custom storefront's folder goes under storefront.path.`);
+    const theme = {};
+    for (const k of THEME_KEYS)
+        if (t[k] !== undefined && t[k] !== null)
+            theme[k] = String(t[k]);
+    if (theme.color !== undefined && !/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(theme.color))
+        fail('invalid_theme', `theme.color is "${theme.color}".`, 'Use a hex colour in quotes, #rgb or #rrggbb, such as "#2f5d50".');
+    for (const k of ['logo', 'hero'])
+        if (theme[k] !== undefined && !isImageRef(theme[k]))
+            fail('invalid_theme', `theme.${k} is "${theme[k]}".`, IMAGE_HINT);
+    if (theme.tagline !== undefined && (theme.tagline.length > 120 || /[\r\n<>]/.test(theme.tagline)))
+        fail('invalid_theme', `theme.tagline is ${theme.tagline.length > 120 ? `${theme.tagline.length} characters long` : 'not plain text on one line'}.`, 'Write the tagline as one line of plain text, at most 120 characters.');
+    return theme;
+}
 export function toApplied(store) {
     return {
         markets: Object.fromEntries(store.markets.map((m) => [m.code, m])),
@@ -194,6 +231,8 @@ export function diff(state, desired) {
             changes.push({ action: 'update', type: 'store', id: 'name' });
         if (state.policies !== undefined && canonical(state.policies) !== canonical(desired.policies))
             changes.push({ action: 'update', type: 'store', id: 'policies' });
+        if (state.theme !== undefined && canonical(state.theme) !== canonical(desired.theme))
+            changes.push({ action: 'update', type: 'store', id: 'theme' });
     }
     const after = toApplied(desired);
     for (const kind of ['markets', 'products']) {

package/dist/storefront.js

@@ -2,7 +2,11 @@
 // index.html (the config block, the drop-in elements, the products grouped by
 // top-level category), styles.css (theme tokens first, then the drop-in.css
 // overrides, then the page) and app.js (market switch, category links, and a
-// product page at #/p/<sku>). The agent then makes it the human's.
+// product page at #/p/<sku>). Product images are the store's, at /img/<file> (from
+// .commercelayer/img/, uploaded by apply). The agent then makes it the human's.
+import { isLocalImage } from './store.js';
+/** img/<file> is the store's image at /img/<file> on the store host, whatever page links it. */
+const imageSrc = (url) => (isLocalImage(url) ? `/${url}` : url);
 const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 /** The scaffold's files, by path relative to the storefront folder. */
 export function storefrontFiles(store, clientId) {
@@ -13,7 +17,7 @@ function indexHtml(store, clientId) {
     const card = (p, h) => {
         const href = `#/p/${encodeURIComponent(p.sku)}`;
         return `      <article class="product" id="p-${esc(p.sku)}">
-        <a class="media" href="${esc(href)}" tabindex="-1">${p.image_url ? `<img src="${esc(p.image_url)}" alt="${esc(p.name)}">` : '<div class="placeholder" aria-hidden="true"></div>'}</a>
+        <a class="media" href="${esc(href)}" tabindex="-1">${p.image_url ? `<img src="${esc(imageSrc(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder" aria-hidden="true"></div>'}</a>
         <${h}><a href="${esc(href)}">${esc(p.name)}</a></${h}>
 ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-price code="${esc(p.sku)}"><cl-price-amount type="compare-at"></cl-price-amount> <cl-price-amount type="price"></cl-price-amount></cl-price>
         <cl-availability code="${esc(p.sku)}"><cl-availability-status type="available">In stock</cl-availability-status><cl-availability-status type="unavailable">Sold out</cl-availability-status></cl-availability>
@@ -49,7 +53,7 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
     }
     const options = store.markets.map((m) => `          <option value="${esc(m.code)}">${esc(m.name)} (${esc(m.currency)})</option>`).join('\n');
     // What the product page shows, by sku. Prices and availability come live from drop-in.js.
-    const data = Object.fromEntries(store.products.map((p) => [p.sku, { name: p.name, description: p.description, image_url: p.image_url, category: p.category }]));
+    const data = Object.fromEntries(store.products.map((p) => [p.sku, { name: p.name, description: p.description, image_url: p.image_url && imageSrc(p.image_url), category: p.category }]));
     const json = JSON.stringify(data, null, 2).replace(/</g, '\\u003c');
     return `<!doctype html>
 <html lang="en">
@@ -60,7 +64,8 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
   <!-- Commerce Layer drop-in.js: prices, availability, add to cart, the minicart (a slide-in panel, styled by minicart.css) and links to the hosted cart and checkout. -->
   <link href="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/drop-in.css" rel="stylesheet">
   <link href="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/minicart.css" rel="stylesheet">
-  <!-- After the drop-in.js stylesheets: styles.css overrides them with the same selectors. Restyle through its tokens. -->
+  <!-- After the drop-in.js stylesheets: styles.css overrides them with the same selectors. Restyle through its tokens.
+       Product images are the store's, at /img/ (.commercelayer/img/, uploaded by apply). Put this site's own files in assets/: /img/ is not served from here. -->
   <link href="styles.css" rel="stylesheet">
   <script>
     // The market comes from ?market=<code>; the first market in store.yml is the default. Keep clientId as it is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && chmod +x dist/bin.js dist/api/server.js",
+    "build": "rm -rf dist.next && tsc -p tsconfig.json --outDir dist.next && chmod +x dist.next/bin.js dist.next/api/server.js && rm -rf dist.old && { mv dist dist.old 2>/dev/null; mv dist.next dist; } && rm -rf dist.old",
     "dev": "tsx src/bin.ts",
     "stub-api": "tsx src/api/server.ts",
     "test": "npm run build && vitest run",