@feeef.dev/cli 0.2.0

package/scaffolds/blank/docs/05-ANTI-PATTERNS.md

@@ -0,0 +1,80 @@
+# Anti-Patterns — Do Not Do These
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+High-signal mistakes AIs and humans make in this system.
+
+## Data shape
+
+| Anti-pattern | Correct |
+|---|---|
+| `{ props: { code, propsSchema, slots } }` | Top-level `code`, `propsSchema`, `slots`, `slotsSchema`, `slotsLayout` |
+| Omitting `props` entirely | Always include `props: {}` at minimum |
+| Using `children` on `custom` for composition | Use `slots` + `slotsSchema` |
+| Using `slots` on `grid` | Use `children` |
+| Inventing `slotsLayout` leaf ids not in `slotsSchema` | Leaves must be slot keys |
+| Regenerating `instanceId` on every edit | Keep stable ids |
+| Deleting empty section keys | Keep `components: []` |
+
+## Custom JSX
+
+| Anti-pattern | Correct |
+|---|---|
+| `import React from "react"` | Scope already has `React` |
+| `export default function …` | `function App() { … }` only |
+| Bare `useState()` in new code | `React.useState()` |
+| `color: store.decoration.primary` | `hsl(var(--primary))` |
+| Hardcoded light-only `#fff` / `#111` chrome | `hsl(var(--background))` / `hsl(var(--foreground))` — see `docs/12-DARK-LIGHT-THEME.md` |
+| Custom “dark palette” hex map beside Lithium | Use `:root` / `.dark` tokens + `useTheme()` |
+| Hardcoded `'Checkout'` / Arabic copy in custom JSX | `t('checkout.title')` + `docs/13-TEMPLATE-I18N.md` |
+| Theme strings only outside `locales/*.json` | Use theme `locales/*.json` → `data.i18n` |
+| Client-filter entire catalog for stock/price | `in_stock` / `price_min` / filterator — `docs/14-FILTERATOR.md` |
+| `product.media[0].url` | `product.media[0]` (string URL) |
+| Invent related-products API | Same `category_id` / `random` / `sold` |
+| `product.media.map(m => m.url)` | `product.media` is `string[]` |
+| `<a href="/p/x">` for in-app nav | `<Link href="/p/x">` or `RouterNav` |
+| `useSlotContext('x').routerNav.push` | Real `useRouter` / `Link` / `RouterNav` |
+| Assuming `useStore()` non-null | Always null-check |
+| TypeScript / JSX types in published `code` | Author `component.tsx`; build strips types into `code` |
+| Assuming raw `import` works inside react-live without build | Use theme `npm run build` — imports are bundled into `code` |
+| Bundling a second `react` into `code` | Mark react as external (build does this); use live scope |
+
+## Kit / tooling
+
+| Anti-pattern | Correct |
+|---|---|
+| Hand-edit `dist/data.json` as primary workflow | Edit `pages/` / `shared/`, then `npm run build` |
+| Use Node APIs inside component source | Use `utils/get-template.ts` |
+| Arbitrary filesystem preview paths | Only `feeef template dev` / CLI override |
+| Expect Shopify reference dumps to render | They are not Feeef themes |
+| Skip `npm run check` after edits | Rebuild and hard-refresh preview |
+| Commit `dist/` as source | Source is the folder tree |
+| Duplicate the same footer/navbar JSX on every page | Promote to `shared/components/<id>/` + `$ref` |
+| Copy dawn-order-form as “complete” checkout | Follow `docs/08-ORDER-FORM.md` + native `order-form.tsx` |
+| `ff.orders.send` from custom JSX | `fetch("/api/orders/create")` |
+| Free-text wilaya/city without cascade/indices | Legacy 1-based indices or new state codes + city names |
+| `useEffect(..., [cartCtx])` that calls `setShippingAddress({ state: null })` | Bootstrap **once** per `product.id`; depend on `cartReady` boolean; preserve existing state/city ([09](./09-THEME-PORTING.md)) |
+| Fake add-to-cart via `updateCurrentItem({})` + click Cart | `cart.addCurrentItemToCart()` (+ `dawn:open-cart` event) |
+| Search with only `params.q` | Prefer `params.search` (Feeef list); URL can stay `?q=` |
+| `product.media.map(m => m.url)` for hover | `media` is `string[]`; dedupe with `photoUrl` |
+| Floating label + `<option>State</option>` on empty select | Empty hidden option + always-floated select label |
+| Fake newsletter subscribe in footer | Store bio / About (`store.description`) |
+| Duplicate header/footer JSX on every page shell | `shared/` + `$ref` from day one |
+| Theme chrome without `dir="ltr"` on RTL store while matching LTR Dawn | Multilang: `dir` from `useFeeefLocale()` + `t()` ([13](./13-TEMPLATE-I18N.md)); force LTR only for LTR-only craft demos |
+
+## Registry / built-ins
+
+Prefer built-in types when they fit; otherwise `type: "custom"` with `component.jsx` / `.tsx`.
+
+## AI generation
+
+| Anti-pattern | Correct |
+|---|---|
+| Returning slots nested under `props` | Top-level siblings of `code` |
+| Empty `slots: {}` wiping existing children on edit | Omit slots fields to mean “keep existing” (backend contract) |
+| Placeholder `_customComponentDescription` left in production data | Resolve to real `code` before ship |
+| Arabic/RTL ignored for DZ merchants | Respect store language / RTL CSS |
+
+## Production
+
+Do not ship local-preview-only overrides to production hosts.

package/scaffolds/blank/docs/07-SHARED-COMPONENTS.md

@@ -0,0 +1,144 @@
+# Shared Components — Design Consistency
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Feeef has **two** reuse layers. Use the right one.
+
+```mermaid
+flowchart TB
+  subgraph authoring [Theme authoring - template-kit]
+    sharedDisk["shared/components/footer"]
+    placement["pages/.../component.json\n$ref: shared.footer"]
+    build["template:build"]
+    dataJson["dist/data.json\nfully inlined components"]
+    sharedDisk --> build
+    placement --> build
+    build --> dataJson
+  end
+
+  subgraph runtime [Merchant runtime - Lithium]
+    lib["Backend template_components\nlibrary"]
+    refNode["type: reference\nrefId + props overrides"]
+    resolve["materializeTemplateReferences"]
+    custom["type: custom in memory"]
+    lib --> resolve
+    refNode --> resolve
+    resolve --> custom
+  end
+
+  dataJson -->|"install / save to store"| storeMeta["store.metadata.templateData"]
+  storeMeta --> resolve
+```
+
+## 1. Theme shared library (compile-time) — **prefer this for kit themes**
+
+**Path:** `templates/<theme>/shared/components/<id>/`
+
+Same shape as any component (`component.json` + optional `component.jsx` + slots/children).
+
+**Placement** (thin stub — do not copy JSX):
+
+```json
+{
+  "order": 0,
+  "$ref": "shared.footer",
+  "instanceId": "contact_footer_1",
+  "title": null,
+  "props": {
+    "social_media": [{ "platform": "instagram", "url": "https://instagram.com/feeef.dz" }]
+  }
+}
+```
+
+Shorthand: `"shared": "footer"` instead of `"$ref": "shared.footer"`.
+
+### What build does
+
+1. Loads every `shared/components/<id>/` into a catalog.
+2. Expands each placement: clone shared definition → deep-merge `props` → keep placement `instanceId` / `title` / slot overrides.
+3. Writes a normal `TemplateData` blob (**no `$ref` left** in `dist/data.json`).
+
+Lithium never needs to know about `$ref` — the storefront only sees full components.
+
+### Why this exists
+
+- **One place to change design** (footer columns, navbar nav items, Dawn chrome) → every page updates on rebuild.
+- Git-friendly: edit `shared/footer/component.jsx` once.
+- Matches `defaults.json`’s historical `"$ref": "shared.navbar"` idea, but as real folders.
+
+### Dawn theme shared ids (current)
+
+| Id | Role |
+|---|---|
+| `dawn-footer` | Custom Dawn footer (JSX) |
+| `dawn-header-bar` | Custom Dawn header bar (JSX) — chrome only, not a page shell |
+| `dawn-storefront-shell` | Thin home/products page shell (`header` \| `sections` \| `footer`) |
+| `dawn-thanks-shell` | Thin `/thanks` page shell (`header` \| `body` \| `footer`) |
+| `dawn-order-form` | Legacy single-file COD (prefer field kit below) |
+| `dawn-order-offers` | Offer list tiles (`price × minQuantity`) + per-slot variant loop (`" \| "`) |
+| `dawn-order-qty` | Order form quantity |
+| `dawn-order-name` | Order form name (+ section title) |
+| `dawn-order-phone` | Order form phone (drives draft) |
+| `dawn-order-email` | Order form email |
+| `dawn-order-geo` | State + city row (slots: `stateSlot`, `citySlot`) |
+| `dawn-order-state` / `dawn-order-city` | Wilaya / commune selects |
+| `dawn-order-shipping` | Delivery type cards |
+| `dawn-order-address` / `dawn-order-note` | Street + customer note |
+| `dawn-order-actions` | Add to cart + Buy (place **last** in form content) |
+| `dawn-order-success` | Post-order success UI |
+
+**Also ship matching entries under `library/components/`** for editor drag-drop (docs/10). Keep library JSX in sync with `shared/` — library is copy-on-drop, not a live `$ref`.
+
+Order-form fields are **shared + slot-ordered** on the PDP form manager — hide via `props.hide`, reorder by changing `order` / folder siblings, add/remove by adding/removing `$ref` placements. Behavior contract: [`08-ORDER-FORM.md`](./08-ORDER-FORM.md).
+
+**Rule of thumb:** if the same UI appears on 2+ pages, it **must** live under `shared/` and be referenced — do not paste duplicate `component.jsx` / props.
+
+## 2. Backend library references (runtime)
+
+```json
+{
+  "type": "reference",
+  "refId": "cuid_of_template_components_row",
+  "refVersion": 3,
+  "instanceId": "hero_on_home",
+  "props": { "title": "Override" },
+  "slots": {}
+}
+```
+
+- Source of truth: per-store (or public) rows in `template_components`.
+- Resolved in `getTemplate()` by `materializeTemplateReferences()` → becomes `type: "custom"`.
+- Merchants reuse library blocks across stores; editing the library updates all refs (subject to versioning/policy).
+
+**Do not confuse** `refId` (backend) with `$ref: "shared.*"` (disk kit). Different planes.
+
+| | Kit `$ref` / `shared` | Runtime `type: "reference"` |
+|---|---|---|
+| When resolved | `template:build` | SSR `getTemplate` |
+| Storage | Folders on disk | DB `template_components` |
+| Audience | Theme engineers | Merchants / marketplace |
+| In `data.json` | Expanded away | Kept until SSR |
+
+## 3. Defaults.json `$ref` (legacy blank store)
+
+`(platform)` still has a top-level `"shared"` map and `"$ref": "shared.navbar"` inside page trees. New themes should use disk `shared/components` instead of a JSON shared map.
+
+## 4. Consistency checklist
+
+When adding UI to a theme:
+
+1. Search `shared/components/` — reuse if it exists.
+2. If copying a block to a second page → **promote** it to `shared/components/<id>/` first, then `$ref` from both places.
+3. Page-specific differences → **props overrides only** on the placement (URLs, labels), not a fork of the JSX.
+4. Global look (colors, corners, fonts) → root `props.json` / CSS variables — not hardcoded in every custom component.
+5. After edits: `npm run build` and spot-check every page that refs the shared id.
+
+## 5. Anti-patterns
+
+| Bad | Good |
+|---|---|
+| Copy-paste `component.jsx` onto home + products | One `shared/x` + two `$ref` stubs |
+| Fork shared by duplicating folder “footer2” | Override `props` on the placement |
+| Leave `$ref` in published `data.json` manually | Always run `template:build` |
+| Use `type: "reference"` for local theme files | Kit `$ref` for themes; `reference` for DB library |
+| Change shared + forget rebuild | `template:watch` / `template:dev` |

package/scaffolds/blank/docs/08-ORDER-FORM.md

@@ -0,0 +1,376 @@
+# Order Form Contract — AI Must Follow
+
+> Theme package copy — paths assume this theme folder is the project root.
+
+Canonical native implementation:
+
+- the native Lithium `OrderForm` — production `OrderForm`
+- `POST /api/orders/create` — **required** submit proxy
+- Types/config: order field types
+- Security: storefront order-create security checks
+- Scope API: `docs/03-CUSTOM-COMPONENTS.md`
+
+When writing a **custom** order form (`type: "custom"` / `component.jsx`), you must reproduce this contract. Styling may change; behavior must not.
+
+The shared Dawn form (`shared/components/dawn-order-form/`) is a **simplified visual reference** — it is **incomplete** vs native (no draft, no wilaya cascade, no security, calls `ff.orders.send` directly). Do **not** copy it as the behavioral source of truth.
+
+---
+
+## 0. Hard rules (fail the task if violated)
+
+1. **Submit via `POST /api/orders/create`** — never call `ff.orders.send()` from the browser in production custom forms (loses real IP / UA forwarding).
+2. **Draft + pending** — send `status: "draft"` when phone reaches exact length; send `status: "pending"` on final submit; reuse draft `id` on pending.
+3. **Legacy vs new geo** — branch on `store.configs.selectedCountry` (see §3). Wrong encoding breaks shipping + backend validation.
+4. **Security on pending only** — honeypot, min 3s dwell, in-flight lock, fake id prefix `FuHe3nf`, pixel suppression.
+5. **Cart bootstrap** — set current item + shipping method/address before reading shipping types/prices.
+6. **`React.use*` hooks** — no imports; null-check `useFeeefCart` / `useStore` / `useFeeef`.
+7. Prefer native registry `product_order_form` when design allows; custom only when UI must diverge.
+
+---
+
+## 1. Lifecycle
+
+```
+mount
+  → formLoadTime = Date.now()
+  → optional device fingerprint in metadata (if your form collects one)
+  → cart.setCurrentItem({ product, quantity })
+  → cart.setShippingMethod(product|store)
+  → load states (legacy utils OR feeef.states.list)
+
+phone digits length === getPhoneLength(country)
+  → if sendDrafts !== false AND no draft yet AND not sending
+  → POST /api/orders/create { status: "draft", id?: undefined, ... }
+  → keep draft.id in ref+state
+  → optional Lead / Purchase pixel (skip if fake)
+
+user changes city (and draft exists)
+  → optional draft update (same id, status draft)
+
+submit
+  → client validateRequiredFields
+  → security checks (pending only)
+  → POST /api/orders/create { status: "pending", id: draft?.id, ... }
+  → cart.clear()
+  → pixels (unless suppressed)
+  → success UI / redirect / payment step
+```
+
+### Phone length
+
+```ts
+const COUNTRY_PHONE_LENGTHS = { DZ: 10, TN: 10, IQ: 11, LY: 10 };
+// default 10
+```
+
+Draft fires when `phone.replace(/\D/g, "").length === requiredLength` — **not** on blur alone.
+
+Use a **ref** (`draftOrderRef`, `draftOrderSendingRef`) so rapid keypresses cannot double-send drafts. State alone is too slow.
+
+---
+
+## 2. API — `POST /api/orders/create`
+
+### Why the proxy exists
+
+[`route.ts`](../../app/api/orders/create/route.ts) sets:
+
+- `x-feeef-real-ip` from `x-forwarded-for` / `x-real-ip` / `cf-connecting-ip`
+- `x-feeef-client-user-agent` from the browser UA
+- Geo hint into `metadata.debug.country` (`x-vercel-ip-country`)
+
+Then calls server SDK `ff.orders.send(data)`.
+
+### Request body (minimum production shape)
+
+```ts
+{
+  id?: string,                    // draft id when upgrading draft → pending
+  storeId: string,
+  customerPhone: string,          // required
+  customerName?: string,
+  customerEmail?: string,
+  shippingCountry?: string,       // UPPERCASE ISO, e.g. "DZ"
+  shippingState?: string,         // legacy: "1".."58" | new: state code
+  shippingCity?: string,          // legacy: "1"..N index | new: city name
+  shippingAddress?: string,
+  shippingType: "home" | "pickup" | "store",
+  customerNote?: string,
+  status: "draft" | "pending",
+  source?: string,                // traffic source detection
+  references?: string[],          // session attribution tokens
+  customFields?: Record<string, any>,
+  items: Array<{
+    productId: string,
+    quantity: number,
+    variantPath?: string,         // "Color/Red" OR expand "A | B" → two items qty 1
+    offerCode?: string,
+    addons?: Record<string, number>, // title → qty
+  }>,
+  metadata: {
+    metaPixel?: { fbclid?, fbc?, fbp?, eventSourceUrl? },
+    deviceFingerprint?: string,
+    formLoadTime: number,         // ms epoch from mount
+    platform: "web;lithium v1.0",
+    email?: string,
+    clarity?: { userId: string },
+  }
+}
+```
+
+### Response handling
+
+| Status | Behavior |
+|---|---|
+| 200 | Order entity (`id`, totals, shipping…); treat as success |
+| 422 | Field errors `{ errors: [{ field, message }] }` — map `customFields.<id>` |
+| 403 | Security / ads-only — show i18n-friendly message |
+| 429 | Rate limit — “too many orders” |
+
+### Fake / bot responses
+
+Any order `id` starting with **`FuHe3nf`** is synthetic. **Do not** fire pixels, clear cart for “success” analytics, or treat as a real order for tracking links.
+
+Helper: `shouldSuppressOrderPixelEvents(order)` in `order-create security checksorder-pixel-suppression.ts`.
+
+---
+
+## 3. Country / state / city (the hard part)
+
+### Decide mode
+
+```ts
+const isLegacy = !store?.configs?.selectedCountry;
+```
+
+### Legacy Algeria (no `selectedCountry`)
+
+| Field | UI | Stored value sent to API |
+|---|---|---|
+| State (wilaya) | Labels from `utils/states.ts` via `getStates(shippingRates)` as `"01 - أدرار"` | **1-based index string** `"1"`…`"58"` |
+| City (commune) | Names from `getCitiesByWilayaCode(stateCode)` | **1-based index string** of the commune list |
+
+If the UI holds a **city name**, convert to index before submit:
+
+```ts
+const cities = getCitiesByWilayaCode(state);
+const idx = cities.findIndex((c) => c === cityName);
+shippingCity = idx !== -1 ? String(idx + 1) : shippingCity;
+```
+
+Filter wilayas whose shipping rate is `[null, null]` out of the select.
+
+Use Feeef states/cities APIs or legacy cascade helpers from the storefront scope.
+
+### New multi-country (`selectedCountry` set)
+
+| Field | Source | Stored value |
+|---|---|---|
+| Country | `store.configs.selectedCountry` | Uppercase ISO in `shippingCountry` |
+| State | `feeef.states.list({ countryCode })` filtered by shipping prices | **State code** |
+| City | `feeef.cities.list({ countryCode, stateCode })` on state change | **City name** (localized via `entity.locales?.[lang]`) |
+
+Show loading while cities fetch. Clear city when state changes.
+
+### Shipping types & cart
+
+```ts
+cart.setShippingMethod(product /* or store */);
+cart.updateShippingAddress({ country, state, city, type });
+cart.getAvailableShippingTypes();      // home | pickup | store with prices
+cart.getShippingPriceForType(type);
+```
+
+Terminology gotcha in rate keys:
+
+| UI `ShippingType` | Often keyed as |
+|---|---|
+| `home` | home delivery |
+| `pickup` | stopdesk / desk |
+| `store` | collect at merchant (sometimes rate key `pickup` in price data) |
+
+Hide shipping selector when ≤1 available type or `config.shipping.visible === false`.
+
+Bootstrap helper: `lib/bootstrap-product-cart-shipping.ts` — use if you skip native `OrderForm`.
+
+**Do not re-run bootstrap on every cart update.** `useFeeefCart()` often returns a new `cartCtx` object whenever shipping/address changes. If your effect depends on `cartCtx` and calls `setShippingAddress({ state: null, city: null })`, the form will reset on every keystroke / wilaya change. Pattern: bootstrap **once per `product.id`** (ref + `cartReady` boolean), and **preserve** existing `state` / `city` / `type`. Full write-up: [`09-THEME-PORTING.md`](./09-THEME-PORTING.md) §4.
+
+---
+
+## 4. Client validation (mirror native defaults)
+
+Defaults from native parsers:
+
+| Field | Visible | Required |
+|---|---|---|
+| phone | yes | yes |
+| name | yes | yes |
+| state | yes | yes |
+| city | yes | yes |
+| address | no | no |
+| email | no | no |
+| notes | no | no |
+
+Rules:
+
+- Phone digit length must equal `getPhoneLength(country)`.
+- If `fields.phone.validate === true` **and** country is DZ: `validatePhoneNumber(tryFixPhoneNumber(phone))` from `feeef` SDK. Prefer **off** for non-DZ.
+- Email regex if required: `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`.
+- If `product.variant.required` and no `variantPath` → block.
+- If `requireOffer` and offers exist and none selected → block.
+- Scroll / focus first invalid field; toast; do not call API.
+
+---
+
+## 5. Security (pending submits)
+
+Implement all of these in custom forms (or call a shared helper if you extract one):
+
+| Check | Behavior |
+|---|---|
+| **Honeypot** | Hidden input `name="website"` (off-screen, not `display:none`). If filled → return fake `FuHe3nf…` order, no API. |
+| **Timing** | If `Date.now() - formLoadTime < 3000` on pending → fake success. |
+| **In-flight lock** | `useRef` boolean around save; throw / ignore `ORDER_IN_FLIGHT`. |
+| **doubleSend** | `order-create security checksdoubleSend.ts` — key `storeId + productIds + phone`. |
+| **frontendStorage** | If security integration frontend option active: block / fake / warning per `order-create security checksfrontendStorage.ts`. |
+| **In-flight lock** | Block double-submit while pending request is open. |
+| **Pixels** | Suppress for fake ids / security treatments. Dedupe: if draft already sent Purchase, don’t send again on pending. |
+
+Drafts skip most bot checks (still use in-flight locks).
+
+---
+
+## 6. Variants, offers, addons, quantity
+
+### Variants
+
+- Path shape: `"Color/Red/Size/L"`.
+- Bundle multi-select: `"Red | Blue"` → **expand** to two `items[]` entries each `quantity: 1` before send (see `expandVariantPaths` in native).
+
+### Offers
+
+- `cart.updateCurrentItemOffer(offer)` / `cart.updateItemOffer(item, offer)`.
+- Clamp quantity to `[offer.minQuantity, offer.maxQuantity]`.
+- Send `offerCode: offer.code` on items.
+
+### Addons
+
+- Map of addon title → quantity on the cart item.
+- Send as `addons: Record<string, number>` on each item.
+
+### Quantity
+
+- Update via `cart.updateCurrentItem({ quantity })`.
+- Respect offer min/max with user feedback.
+
+### Payment
+
+- Default COD.
+- If store/product payment integration enabled: after successful pending create, show payment UI instead of immediate thank-you (native: `PaymentMethodSelection`).
+
+---
+
+## 7. Success UX
+
+Native options:
+
+- Modal `OrderSuccessDialog` + optional `autoRedirect` (~5s → `/`)
+- Track URL: `https://api.feeef.org/track/{orderId}`
+- Thank-you page: `/thanks?order={id}` (optional `name`, `total`, `phone`). Legacy `/thank-you` redirects.
+
+Never redirect / track for `FuHe3nf` fake ids.
+
+Clear cart only after confirmed real pending success.
+
+---
+
+## 8. Custom JSX checklist (react-live)
+
+```jsx
+function App() {
+  const { product } = useCurrentProduct();
+  const cartCtx = useFeeefCart();
+  const storeCtx = useStore();
+  const router = useRouter();
+  // NO ff.orders.send in browser for production — use fetch("/api/orders/create")
+
+  const cart = cartCtx?.cart;
+  const store = storeCtx?.store || cartCtx?.store;
+
+  const formLoadTimeRef = React.useRef(Date.now());
+  const draftRef = React.useRef(null);
+  const sendingRef = React.useRef(false);
+  const [honeypot, setHoneypot] = React.useState("");
+
+  // … state/city cascade per §3 …
+  // … draft on phone length per §1 …
+  // … pending via /api/orders/create per §2 …
+}
+```
+
+Must include:
+
+- [ ] Null guards for cart/store/product
+- [ ] Cart current item + shipping bootstrap
+- [ ] Legacy/new geo branch
+- [ ] Draft + pending with draft `id`
+- [ ] Honeypot `website` + 3s rule + in-flight ref
+- [ ] Fake id / pixel suppression
+- [ ] `fetch("/api/orders/create")` with JSON body
+- [ ] Expand `" | "` variant paths
+- [ ] CSS via `hsl(var(--primary))` etc.
+
+---
+
+## 9. Prefer built-in when possible
+
+Registry types:
+
+| Type | Role |
+|---|---|
+| `product_order_form` | Full form |
+| `product_order_form_variants` | Variants only |
+| `product_order_form_offers` | Offers only |
+| `product_order_form_addons` | Addons only |
+
+Compose with **slots** around native blocks when you only need custom chrome. Reimplementing the whole form in JSX is last resort.
+
+Props for native form: `built-in Lithium registry (not in this theme)` → `components.product_order_form`.
+
+---
+
+## 10. Attribution / analytics extras
+
+- `detectTrafficSource()`, `getFbc()`, `getFbp()`, Facebook params — `order-form/utils/source-detection.ts`
+- Order references session: `lib/order-references-session.ts` → `references[]` on pending, clear after success
+- Clarity: `data-clarity-unmask="true"` on phone/name; optional `metadata.clarity.userId`
+
+---
+
+## 11. File map (native)
+
+| Path | Why |
+|---|---|
+| `components/feeef/order-form/order-form.tsx` | Source of truth behavior |
+| `components/feeef/order-form-v2/*` | Newer split (submit hook) — keep in sync when reading |
+| `app/api/orders/create/route.ts` | Proxy + IP |
+| `utils/states.ts` / `utils/cities.ts` | Legacy DZ geo |
+| `order-create security checks*` | Double-send, storage, pixel suppress |
+| `lib/bootstrap-product-cart-shipping.ts` | Cart shipping init |
+| `components/forms/cart-form.tsx` | Multi-item cart checkout variant |
+
+---
+
+## 12. Anti-patterns (order forms)
+
+| Bad | Good |
+|---|---|
+| `ff.orders.send(...)` in custom JSX | `fetch("/api/orders/create", …)` |
+| Free-text wilaya/city always | Cascade + correct legacy indices / new codes |
+| Draft on every keypress | Exact digit length + sending ref |
+| `useState` only for submit lock | `useRef` in-flight |
+| Fire Purchase on fake `FuHe3nf` | Suppress pixels |
+| One item with `variantPath: "A \| B"` | Expand to two items |
+| Skip shipping bootstrap | `setShippingMethod` + address before prices |
+| Re-bootstrap on `[cartCtx]` and wipe state/city | Once per product; preserve address ([09](./09-THEME-PORTING.md)) |
+| Copy dawn-order-form as complete | Use this doc + native `order-form.tsx` |