# Guide — Priced options, size runs & logo upload (v0.4.0)

This is the how-to for the three features added in **Shoe Customizer 0.4.0**: paid **option
groups**, a **size-run** quantity grid, and customer **logo upload** with live placement. Part 1
is for the store admin building a shoe; part 2 is what the customer sees on the storefront.

---

## Part 1 — Building it (store admin)

Everything is under **WP Admin → Shoe Customizer → (a shoe)**. No code, no asset surgery.

### Paid option groups

Add-ons that change the price beyond the base colour path — *Lace colour +$10*, *Premium sole
+$25*, *Add initials +$8*, and so on.

In the **Options** card, **+ Add option group**. Each group has:

- **Label** — the heading the customer sees (e.g. "Lace colour").
- **Type** — how it's shown:
  - **Swatch** — colour dots. Give each option a **colour** and a **target zone**; picking it
    re-tints that zone live (same engine as the base palette, so a paid colourway just overrides
    that zone's colour).
  - **Buttons (radio)** — labelled buttons, pick one.
  - **Dropdown (select)** — a `<select>`; good for long lists.
  - **Text** — a free-text field (e.g. initials to embroider). The first option row sets the
    price for adding text; the customer's typed value rides along on the order.
- **Required** — the customer must choose before they can add to cart.
- **Options** (nested) — **+ Add option** per choice: **label**, **+A$ price** (the delta added
  to the unit price), and for swatches the **target zone** + **colour**.

**Show only when…** (visibility rule): one rule per group — *show this group only when
[another group] = [a specific option]*. Example: only show "Embroidery thread colour" once
"Add initials" is chosen. Save the shoe once so the dependency group's options have ids, then
pick them in the rule selects. (Single rule per group for now.)

Prices are **never taken from the browser** — the server re-reads every delta from the database
when the item is added to cart, so a tampered page can't change the price.

### Size run

The **Size run** card is one size per line (e.g. `US 6 … US 13`). Seeded US 6–13 by default;
edit freely. On the storefront this becomes a **quantity-per-size grid**; the **total pairs is
the order line quantity**, with a minimum of **2 pairs** (`SC_MOQ`). Clear the box to remove the
size grid from a shoe.

### Logo print area

A logo needs a **print area** — the rectangle it's allowed to live in on a zone (e.g. the side
panel). On a zone row, **🖼 Logo area** opens a drawer; drag a rectangle over the shoe photo and
**Save**. A green ✓ marks zones that have one. **Clear** removes it. Any zone with a print area
becomes a logo target on the storefront.

### Re-sync zones from seed

For a seeded shoe (af1, samba, dunk, advantage, court), the sidebar has **Re-sync zones from
seed**. It refreshes the base image and zone/layer slices from the bundled seed **without**
touching your price, product mapping, palette, options, size run or print areas — zones are
matched by code so ids (and the option → zone links) survive. Use it when the seed artwork is
corrected (e.g. the Dunk laces/lace-guard split).

---

## Part 2 — What the customer does (storefront)

On a product page carrying `[shoe_customizer slug="…"]`:

1. **Colour the zones** with the swatch dots (unchanged from before).
2. **Choose paid options.** Each group shows under the colours; the running **unit price**
   updates as they pick, with `(+A$…)` shown on each priced choice. Required groups are marked
   with a red `*`.
3. **Upload a logo** (optional): **Upload logo** → a PNG or JPG up to **5 MB**. It appears inside
   the print area; **drag it to move**, **drag the corner handle to resize** (or use the **Size**
   slider). A dashed outline shows the allowed area; the logo can't be dragged outside it. Only
   PNG/JPG are accepted and every upload is re-encoded server-side (no SVG, no embedded scripts).
4. **Enter the size run:** a quantity box per size. The footer shows **total pairs** live and
   turns red until the **2-pair minimum** is met.
5. **Add to cart.** The cart, checkout, order and admin all show the design (zone colours, each
   chosen option, the size breakdown, and "logo uploaded"), with the customer's mockup image as
   the line thumbnail.

The server re-validates the whole design on add-to-cart — real option ids, real sizes, a logo
that's genuinely one of ours, the size total, and any required choices — and recomputes the
price from the database. The browser only supplies intent and a preview image.