@feeef.dev/cli 0.2.2 → 0.2.3

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

@@ -7,8 +7,8 @@ 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"]
+    sharedDisk["shared/components/footer.tsx"]
+    placement["pages/.../footer.json\n$ref: shared.footer"]
     build["template:build"]
     dataJson["dist/data.json\nfully inlined components"]
     sharedDisk --> build
@@ -30,13 +30,21 @@ flowchart TB
   storeMeta --> resolve
 ```
 
-## 1. Theme shared library (compile-time) — **prefer this for kit themes**
+## 1. Theme shared library (compile-time) — **prefer this**
 
-**Path:** `templates/<theme>/shared/components/<id>/`
+### Paths (flat TSX required for leaves)
 
-Same shape as any component (`component.json` + optional `component.jsx` + slots/children).
+| Kind | Path |
+|---|---|
+| **Leaf custom (preferred)** | `shared/components/<id>.tsx` — `export const meta` + `function App()` |
+| **Leaf built-in / $ref stub** | `shared/components/<id>.json` or placement `.json` |
+| **With slots/children** | `shared/components/<id>/<id>.tsx` + `slots/` / `children/` |
+
+Do **not** ship customs as `component.json` + `component.jsx` pairs anymore. Meta belongs in `export const meta` inside the `.tsx` file.
 
-**Placement** (thin stub — do not copy JSX):
+### Placement (thin stub — do not copy JSX)
+
+Place next to other page components (flat stack) or inside a shell’s `slots/`:
 
 ```json
 {
@@ -44,101 +52,61 @@ Same shape as any component (`component.json` + optional `component.jsx` + slots
   "$ref": "shared.footer",
   "instanceId": "contact_footer_1",
   "title": null,
-  "props": {
-    "social_media": [{ "platform": "instagram", "url": "https://instagram.com/feeef.dz" }]
-  }
+  "props": {}
 }
 ```
 
 Shorthand: `"shared": "footer"` instead of `"$ref": "shared.footer"`.
 
+Example page stack (no nested Dawn-style shell required):
+
+```
+pages/home/components/
+  header.json      → { "$ref": "shared.header", "order": 0, … }
+  hero.tsx
+  product-rail.tsx
+  footer.json      → { "$ref": "shared.footer", "order": 99, … }
+```
+
 ### What build does
 
-1. Loads every `shared/components/<id>/` into a catalog.
+1. Loads every entry under `shared/components/` (flat `.tsx` / `.json` or folders).
 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.
+- **One place to change design** → every page updates on rebuild.
+- Git-friendly: edit `shared/components/header.tsx` once.
+- Matches historical `"$ref": "shared.navbar"` ideas as real disk files.
 
-### Dawn theme shared ids (current)
+**Rule of thumb:** if the same UI appears on 2+ pages, it **must** live under `shared/` and be referenced — do not paste duplicate JSX.
 
-| 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.
+Also ship matching entries under `library/components/` for editor drag-drop ([10-SCHEMA-LIBRARY.md](./10-SCHEMA-LIBRARY.md)). Library is **copy-on-drop**, not a live `$ref`.
 
 ## 2. Backend library references (runtime)
 
 ```json
 {
   "type": "reference",
-  "refId": "cuid_of_template_components_row",
-  "refVersion": 3,
-  "instanceId": "hero_on_home",
-  "props": { "title": "Override" },
-  "slots": {}
+  "refId": "…",
+  "props": {}
 }
 ```
 
-- 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)
+Used after publish / marketplace install. Authoring-time `$ref: "shared.*"` is expanded at **build** and is different from runtime `type: "reference"`.
 
-`(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.
+## Anti-patterns
 
-## 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.
+| Wrong | Right |
+|---|---|
+| Copy-paste header JSX onto home + products | One `shared/components/header.tsx` + two `$ref` stubs |
+| `shared/components/header/component.json` + `component.jsx` for a leaf | Flat `shared/components/header.tsx` with `export const meta` |
+| Invent deep `home-shell/slots/…` trees by hand when siblings work | Flat `pages/<page>/components/*` stack + `$ref` |
+| Duplicate `instanceId` across placements | Unique `instanceId` per placement |
 
-## 5. Anti-patterns
+## Related
 
-| 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` |
+- Flat TSX authoring: [03-CUSTOM-COMPONENTS.md](./03-CUSTOM-COMPONENTS.md)
+- Workflow: [04-WORKFLOW.md](./04-WORKFLOW.md)
+- Order form fields as shared slots: [08-ORDER-FORM.md](./08-ORDER-FORM.md)

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

@@ -10,7 +10,7 @@ Canonical native implementation:
 - 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.
+When writing a **custom** order form (`type: "custom"` / flat `.tsx`), 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.
 

package/scaffolds/blank/docs/10-SCHEMA-LIBRARY.md

@@ -1,5 +1,7 @@
 # Schema Library (`schema.library.json`)
 
+> Theme package copy — paths assume this theme folder is the project root.
+
 Theme-bundled **drag-drop catalog** for the merchant template editor.
 
 Components listed here can be **unused in `data.json`**. That is intentional: the theme ships extras the merchant can add later from the UI.
@@ -22,7 +24,7 @@ Components listed here can be **unused in `data.json`**. That is intentional: th
 flowchart LR
   schemaTs["schema.ts overlay"]
   lithium["Lithium built-ins"]
-  disk["library/components/id/"]
+  disk["library/components/id.tsx"]
   build["template:build"]
   schema["dist/schema.json"]
   editor["Flutter Theme tab"]
@@ -35,93 +37,43 @@ flowchart LR
   editor -->|"copy-on-drop"| data
 ```
 
-## Authoring (template-kit)
+## Authoring (flat TSX)
 
 ```
-templates/dawn-src/
-  library/components/<id>/
-    component.json    # type, code meta, props, schemas + catalog fields
-    component.jsx     # optional
-    slots/… children/…
-  dist/
-    schema.library.json
-    data.json
+library/components/
+  promo-banner.tsx     # preferred leaf: export const meta + App
+  # OR folder only when slots/children needed:
+  rich-block/
+    <id>.tsx
+    slots/…
 ```
 
-### Catalog fields on `component.json`
+### Catalog fields (from `export const meta` or legacy `.json`)
 
 | Field | Role |
 |---|---|
-| `libraryId` / folder name | Stable `id` in the library list |
+| folder / file name | Stable `id` in the library list (`libraryId`) |
 | `title`, `subtitle`, `category`, `tags`, `imageUrl` | Editor card |
 | `type` | Usually `custom`; may be a built-in registry type |
 | `props` | Becomes `propsDefault` on drop |
-| `code` / `component.jsx` | Custom JSX |
+| `code` (built from `.tsx`) | Custom JSX |
 | `propsSchema`, `slotsSchema`, `slotsLayout`, `slots`, `children` | Seeded on drop |
 
 Build:
 
 ```bash
-cd storefront && npm run template:build
+npm run build
 # → dist/schema.library.json
 ```
 
-## Wire shape
-
-```json
-{
-  "version": "1.0",
-  "components": [
-    {
-      "id": "dawn-promo-banner",
-      "title": "Promo Banner",
-      "subtitle": null,
-      "category": "marketing",
-      "tags": ["banner"],
-      "imageUrl": null,
-      "type": "custom",
-      "code": "function App() { return <div>{props.text}</div>; }",
-      "propsSchema": { "text": { "type": "string" } },
-      "propsDefault": { "text": "Sale" },
-      "slotsSchema": null,
-      "slotsDefault": null,
-      "slotsLayout": null,
-      "children": null
-    }
-  ]
-}
-```
-
-## Serving
+## Anti-patterns
 
-| Endpoint | Behavior |
+| Wrong | Right |
 |---|---|
-| `GET /api/template/schema` | Lithium `schema.json` **plus** `library: [...]` from `template/schema.library.json` |
-| `GET /api/template/library` | Standalone library document |
-| Dev | `FEEEF_TEMPLATE_LIBRARY_PATH` → kit `dist/schema.library.json` |
-
-`StoreTemplate.schema` should include the same `library` array when publishing a theme so `TemplateFetchResult.fromStoreTemplate` exposes it via `rawSchema['library']`.
-
-## Editor behavior
-
-- Tab **Theme** lists `controller.themeLibraryEntries` (`rawSchema['library']`).
-- Drop / tap → **inline copy** into `templateData` (`buildThemeLibraryComponent`).
-- Not a live link to the theme file: later theme updates do **not** rewrite existing placements (unlike DB `reference`).
-- Prefer `shared/` + `$ref` for compile-time consistency across pages you ship in `data.json`; use **library** for optional blocks merchants may add.
-
-## vs `shared/`
-
-| | `shared/components` | `library/components` |
-|---|---|---|
-| Purpose | DRY placements already in the theme tree | Optional catalog for the editor |
-| Build | Inlined into `data.json` via `$ref` | Emitted as `schema.library.json` |
-| Unused OK? | No (only if referenced) | **Yes** |
-
-A component can exist in **both** (shared for shipped pages + library for drag-drop of the same block elsewhere).
+| `library/components/x/component.json` + `component.jsx` for a leaf | Flat `library/components/x.tsx` |
+| Duplicating library JSX into every page | Keep library for drag-drop; use `shared/` + `$ref` for live chrome |
 
-## Rules for AI
+## Related
 
-1. New optional theme UI → add under `library/components/<id>/`, rebuild.
-2. Do not put library-only blocks into `data.json` unless the blank theme should include them.
-3. When packing a `StoreTemplate`, merge `library` into `schema`.
-4. Flutter insert = copy-on-drop, not `type: "reference"` (no DB id).
+- Shared chrome: [07-SHARED-COMPONENTS.md](./07-SHARED-COMPONENTS.md)
+- Custom TSX: [03-CUSTOM-COMPONENTS.md](./03-CUSTOM-COMPONENTS.md)

package/scaffolds/blank/docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md

@@ -1,38 +1,50 @@
-# Template Pages — checkout, thanks, product PDP
+# Template Pages — single `main` + slots
 
 > Theme package copy — paths assume this theme folder is the project root.
 
-Canonical routes and the **single-`main`-section** pattern.
+Canonical routes and the **single-`main`-section** pattern (preferred for all new themes).
 
 ## Page matrix
 
-| Page id | Path | Sections | Notes |
+| Page id | Path | Authoring | Notes |
 |---|---|---|---|
-| `product` | `/p/:id` **and** `/products/:id` | **`main` only** | Both URLs render the same PDP. Prefer `/p/` for links; `/products/:id` is an alias. |
-| `checkout` | `/checkout` | **`main` only** | Cart checkout. Prefer registry `cart_order_form` in a form slot. |
-| `thank_you` | `/thanks` | **`main` only** | Optional post-order page. Query params carry order context. Legacy `/thank-you` redirects. |
-| `not_found` | Next.js not-found | **`main` only** | Editable 404 (`type: "not_found"` or custom). |
-| `products` | `/products` | multi | Collection / PLP (unchanged). |
-| `home` / `contact` / … | … | multi | Unchanged. |
+| `home` | `/` | **`main` preferred** | Flat disk: `pages/home/components/`. Legacy `header\|hero\|main\|footer` still renders when `main` is empty. |
+| `product` | `/p/:id` **and** `/products/:id` | **`main` only** | Both URLs render the same PDP. Prefer `/p/` for links. |
+| `checkout` | `/checkout` | **`main` only** | Prefer registry `cart_order_form` in a form slot. |
+| `thank_you` | `/thanks` | **`main` only** | Query params carry order context. Legacy `/thank-you` redirects. |
+| `products` | `/products` | **`main` preferred** | Legacy multi-section keys when `main` empty. |
+| `contact` | `/contact` | **`main` preferred** | Legacy named sections when `main` empty. |
 
-## Pattern: one section, layout in slots
+## Pattern: published `main` + optional slots
+
+**Preferred disk layout for marketing pages** — flat sibling stack (builds to `sections.main`):
 
 ```text
-pages.<id>.sections.main.components[0]   ← page shell (custom)
-  slots.header[]
-  slots.body[] | slots.form[]
-  slots.footer[]
+pages/home/components/
+  header.json          # $ref shared.header
+  hero.tsx
+  rail.tsx
+  footer.json          # $ref shared.footer
 ```
 
-Next.js page components only render `sections.main`. They do **not** invent header/footer section keys.
+**When you need a shell with slots** (typical for product / checkout / thanks):
+
+```text
+pages/product/components/product-shell/
+  product-shell.tsx        # export const meta + slotsSchema
+  slots/header/….json  # $ref
+  slots/body/….tsx
+  slots/form/….json    # cart_order_form / product_order_form
+  slots/footer/….json
+```
 
-Use a single `main` section; put chrome in slots.
+Do **not** invent deep nested trees by hand when a flat sibling stack is enough.
 
 ### Product runtime fallback
 
 `ProductPageContent` prefers `main`. If `main` is empty, it still renders the legacy multi-section tree (`header` / `top` / `start` / `end` / `bottom` / `footer`) for older store blobs.
 
-New themes (Dawn) ship `main` + slots only.
+Home / products / contact use the same prefer-`main` rule via `lib/template/prefer-main-section.ts`.
 
 ## `/checkout`
 
@@ -68,14 +80,17 @@ New themes (Dawn) ship `main` + slots only.
 
 ## Authoring checklist
 
-1. Add / edit under `pages/<page>/sections/main/…`
-2. Keep a single root (or a short stack) in `main`; put chrome in slots
-3. `npm run build`
-4. Preview with `npm run dev`
-5. Do **not** reintroduce multi-section keys on these three pages in new themes
+1. Prefer flat `pages/<page>/components/<name>.tsx` (or a short stack of siblings + `$ref`)
+2. For product / checkout / thanks: one shell **folder** only if you need slots (`header` | `body`/`form` | `footer`); otherwise flat stack
+3. Chrome reused on 2+ pages → `shared/components/<id>.tsx` + `$ref` placements
+4. `npm run build` then preview with `npm run dev` / `npm run dev`
+5. Do **not** reintroduce multi-section keys on new themes
+6. Do **not** invent deep nested shell trees when flat siblings work
 
 ## Related
 
 - Order / COD contract: [08-ORDER-FORM.md](./08-ORDER-FORM.md)
 - Architecture pages list: [01-ARCHITECTURE.md](./01-ARCHITECTURE.md)
 - Schema library (optional drag-drop blocks): [10-SCHEMA-LIBRARY.md](./10-SCHEMA-LIBRARY.md)
+- Folder kit: [04-WORKFLOW.md](./04-WORKFLOW.md)
+- Flat TSX: [03-CUSTOM-COMPONENTS.md](./03-CUSTOM-COMPONENTS.md)

package/scaffolds/blank/docs/16-AUTHORING-TS-IMPORTS.md

@@ -9,28 +9,54 @@ exposes top-level `function App()` — the same contract as plain JSX.
 ## What you write
 
 ```
-# Preferred (page-level → sections.main)
+# Required default (page-level → sections.main)
 pages/home/components/hero.tsx
 
-# Folder when you need colocated helpers or slots/children
-pages/home/components/hero/
-  component.tsx
-  labels.ts
+# Shared leaf
+shared/components/header.tsx
 
-# Legacy multi-section (still supported)
+# Folder ONLY when you need slots/children or colocated helpers
+pages/product/components/product-shell/
+  product-shell.tsx
+  slots/body/gallery.tsx
+
+# Legacy multi-section (compat only — do not use for new themes)
 pages/home/sections/main/components/hero.tsx
 ```
 
+```tsx
+const propsSchema = {
+  heading: { type: "string", name: "Heading" },
+} as const;
+
+export const meta = {
+  type: "custom",
+  title: "Hero",
+  order: 0,
+  propsSchema,
+  props: { heading: "" },
+} as const satisfies FeeefComponentMeta<typeof propsSchema>;
+
+type Props = FeeefLivePropsOf<typeof propsSchema>;
+
+function App() {
+  const p = props as Props;
+  return <h1>{p.heading}</h1>;
+}
+```
+
+Local/`npm` imports are allowed in authoring files and are **bundled** into `code`:
+
 ```tsx
 import clsx from "clsx";
 import { bannerLabel } from "./labels";
 
-function App(): JSX.Element {
-  const text: string = bannerLabel("Feeef");
-  return <div className={clsx("hero")}>{text}</div>;
+function App() {
+  return <div className={clsx("hero")}>{bannerLabel("Feeef")}</div>;
 }
 ```
 
+Keep `export const meta` in the same entry file (or the kit cannot load propsSchema).
 ## What the storefront receives
 
 Build emits bundled / transpiled JS with:
@@ -60,14 +86,12 @@ npm install clsx          # example
 
 ## Plain JSX (legacy)
 
-`component.jsx` with **no** imports is copied into `code` unchanged (fast path).
-
-## Init
-
-This package came from `feeef template init`. Re-read `AGENTS.md` after upgrading the CLI.
+Older `component.jsx` with **no** imports is still copied into `code` unchanged (fast path). **New work must use flat `.tsx` + `export const meta`.**
 
 ## Do not
 
 - Expect browser-side bundling of theme `node_modules` — only build-time inlining
 - Bundle `react` into component `code`
 - Rely on Node builtins or server-only packages inside components
+- Author customs as `component.json` + `component.jsx` pairs
+- Create both `name.tsx` and `name/` for the same component id