@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. package/README.md +174 -156
  2. package/VENDOR.md +69 -0
  3. package/assets/openspec/config.yaml +38 -0
  4. package/assets/templates/AGENTS.md +76 -0
  5. package/assets/templates/app/app/[[...slug]]/page.tsx +56 -2
  6. package/assets/templates/app/app/[[...slug]]/renderer.tsx +44 -2
  7. package/assets/templates/app/app/globals.css +5 -8
  8. package/assets/templates/app/app/layout.tsx +1 -5
  9. package/assets/templates/app/app/robots.ts +9 -3
  10. package/assets/templates/app/app/sitemap.ts +64 -5
  11. package/assets/templates/app/lib/__STOREFRONT__/account-boundary.client.tsx +76 -0
  12. package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +461 -0
  13. package/assets/templates/app/lib/__STOREFRONT__/account-mutation.client.ts +46 -0
  14. package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +103 -0
  15. package/assets/templates/app/lib/__STOREFRONT__/account-reconcile.client.ts +465 -0
  16. package/assets/templates/app/lib/__STOREFRONT__/account-session.core.ts +177 -0
  17. package/assets/templates/app/lib/__STOREFRONT__/account-session.ts +44 -0
  18. package/assets/templates/app/lib/__STOREFRONT__/account-user.core.ts +65 -0
  19. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +135 -16
  20. package/assets/templates/app/lib/__STOREFRONT__/catalog.ts +19 -9
  21. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +61 -0
  22. package/assets/templates/app/lib/__STOREFRONT__/composition.ts +26 -0
  23. package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +36 -4
  24. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +17 -18
  25. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +209 -0
  26. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.ts +247 -0
  27. package/assets/templates/app/lib/__STOREFRONT__/registry.tsx +123 -62
  28. package/assets/templates/app/lib/__STOREFRONT__/runtime.ts +3 -0
  29. package/assets/templates/app/lib/__STOREFRONT__/schema.ts +78 -25
  30. package/assets/templates/app/lib/__STOREFRONT__/section-observation.ts +182 -0
  31. package/assets/templates/app/lib/__STOREFRONT__/section-sources.ts +128 -0
  32. package/assets/templates/app/lib/__STOREFRONT__/shell/content.ts +31 -7
  33. package/assets/templates/app/lib/__STOREFRONT__/shell/props.ts +4 -0
  34. package/assets/templates/app/lib/__STOREFRONT__/spec/index.ts +81 -26
  35. package/assets/templates/app/lib/__STOREFRONT__/spec/seo.ts +165 -0
  36. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +4 -2
  37. package/assets/templates/app/lib/__STOREFRONT__/store-context.ts +26 -7
  38. package/assets/templates/app/lib/__STOREFRONT__/views/sections/cta.client.tsx +1 -1
  39. package/assets/templates/app/lib/__STOREFRONT__/views/sections/faq.client.tsx +1 -1
  40. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +2 -1
  41. package/assets/templates/app/lib/__STOREFRONT__/views/sections/logoCloud.tsx +1 -1
  42. package/assets/templates/app/lib/__STOREFRONT__/views/sections/pricing.tsx +1 -1
  43. package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.client.tsx +100 -0
  44. package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.tsx +19 -0
  45. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.products.ts +39 -0
  46. package/assets/templates/app/lib/__STOREFRONT__/views/sections/statistics.tsx +1 -1
  47. package/assets/templates/app/lib/__STOREFRONT__/views/sections/testimonials.tsx +1 -1
  48. package/assets/templates/features/checkout/handlers.ts +6 -0
  49. package/assets/templates/features/customer-auth/handlers.ts +19 -23
  50. package/assets/templates/features/customer-auth/state.ts +31 -1
  51. package/assets/templates/views/account/index.tsx +20 -8
  52. package/assets/templates/views/account/registry.tsx +294 -154
  53. package/assets/templates/views/account/schema.ts +1 -0
  54. package/assets/templates/views/cart/content.ts +11 -0
  55. package/assets/templates/views/cart/data.ts +23 -0
  56. package/assets/templates/views/cart/index.tsx +53 -0
  57. package/assets/templates/views/cart/props.ts +12 -0
  58. package/assets/templates/views/cart/registry.tsx +82 -0
  59. package/assets/templates/views/cart/schema.ts +52 -0
  60. package/assets/templates/views/category/assembly/assembly.json +2 -1
  61. package/assets/templates/views/category/assembly/index.skeleton.tsx +64 -6
  62. package/assets/templates/views/category/assembly/registry.skeleton.tsx +7 -6
  63. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/binding.json +5 -0
  64. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/catalog.part +4 -0
  65. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/element.part +7 -0
  66. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/registry.part +18 -0
  67. package/assets/templates/views/category/index.tsx +76 -7
  68. package/assets/templates/views/category/props.ts +7 -0
  69. package/assets/templates/views/category/registry.tsx +25 -6
  70. package/assets/templates/views/category/schema.ts +13 -0
  71. package/assets/templates/views/checkout/registry.tsx +3 -5
  72. package/assets/templates/views/home/assembly/assembly.json +12 -3
  73. package/assets/templates/views/home/assembly/index.skeleton.tsx +24 -5
  74. package/assets/templates/views/home/assembly/registry.skeleton.tsx +4 -1
  75. package/assets/templates/views/home/assembly/slots/benefits/cards/binding.json +5 -0
  76. package/assets/templates/views/home/assembly/slots/benefits/cards/registry.part +17 -0
  77. package/assets/templates/views/home/assembly/slots/benefits/split/binding.json +5 -0
  78. package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → split}/registry.part +6 -2
  79. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/binding.json +5 -0
  80. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/catalog.part +8 -0
  81. package/assets/templates/views/home/assembly/slots/categories/{ProductCategory2 → CategoryGrid}/element.part +1 -1
  82. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/registry.part +31 -0
  83. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/binding.json +5 -0
  84. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/catalog.part +4 -0
  85. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/element.part +5 -0
  86. package/assets/templates/views/home/assembly/slots/hero/{StorefrontHero1 → StorefrontHero}/registry.part +5 -3
  87. package/assets/templates/views/home/content.ts +22 -0
  88. package/assets/templates/views/home/data.ts +9 -0
  89. package/assets/templates/views/home/index.tsx +34 -11
  90. package/assets/templates/views/home/props.ts +1 -0
  91. package/assets/templates/views/home/registry.tsx +41 -17
  92. package/assets/templates/views/home/schema.ts +141 -24
  93. package/assets/templates/views/product/data.ts +5 -3
  94. package/assets/templates/views/product/index.tsx +49 -5
  95. package/assets/templates/views/product/props.ts +7 -0
  96. package/assets/templates/views/product/registry.tsx +34 -5
  97. package/assets/templates/views/product/schema.ts +49 -1
  98. package/assets/templates/views/static/content.ts +4 -4
  99. package/assets/templates/views/static/index.tsx +1 -1
  100. package/bin/storefront.js +1231 -154
  101. package/examples/merchandising/category-led.json +37 -0
  102. package/examples/merchandising/collection-led.json +37 -0
  103. package/package.json +10 -7
  104. package/recipes/archetypes.json +33 -46
  105. package/recipes/catalog.json +245 -153
  106. package/recipes/catalog.mjs +10 -0
  107. package/recipes/catalog.schema.json +4 -0
  108. package/recipes/features.json +28 -5
  109. package/recipes/recipe.schema.json +1 -1
  110. package/recipes/recipes.json +159 -59
  111. package/recipes/sections.json +10 -0
  112. package/recipes/validate.mjs +75 -4
  113. package/scripts/candidate.mjs +4 -4
  114. package/scripts/composers.mjs +25 -5
  115. package/scripts/env-file.mjs +86 -0
  116. package/scripts/file-classes.mjs +15 -0
  117. package/scripts/migrate-english-routes.mjs +276 -0
  118. package/scripts/ownership-conflict.mjs +5 -2
  119. package/scripts/pinning.mjs +74 -5
  120. package/scripts/plan-apply.mjs +149 -5
  121. package/scripts/reconcile.mjs +49 -11
  122. package/scripts/render-templates.mjs +97 -44
  123. package/scripts/section-config.mjs +253 -0
  124. package/scripts/starter.mjs +17 -0
  125. package/scripts/theme/color.mjs +185 -0
  126. package/scripts/theme/css-theme.mjs +233 -0
  127. package/scripts/theme/fonts.mjs +123 -0
  128. package/scripts/theme/import-export.mjs +125 -0
  129. package/scripts/theme/preset.mjs +93 -0
  130. package/scripts/theme/theme-plan.mjs +292 -0
  131. package/scripts/theme/tokens.mjs +137 -0
  132. package/scripts/view-assembly.mjs +57 -3
  133. package/scripts/view-selection.mjs +1 -1
  134. package/skills/sf-feature/SKILL.md +32 -19
  135. package/skills/sf-setup/SKILL.md +79 -0
  136. package/skills/sf-theme-gen/SKILL.md +99 -36
  137. package/skills/sf-theme-gen/references/shadcn-theming.md +87 -0
  138. package/skills/{shadcn-theming/references/templates → sf-theme-gen/references}/theme-setup.md +15 -19
  139. package/skills/{shadcn-theming → sf-theme-gen}/references/theming-guide.md +6 -11
  140. package/skills/sf-view-gen/SKILL.md +63 -40
  141. package/skills/sf-view-gen/assets/recipes/archetypes.json +33 -46
  142. package/skills/sf-view-gen/assets/recipes/catalog.json +245 -153
  143. package/skills/sf-view-gen/assets/recipes/catalog.schema.json +4 -0
  144. package/skills/sf-view-gen/assets/recipes/features.json +28 -5
  145. package/skills/sf-view-gen/assets/recipes/recipes.json +159 -59
  146. package/skills/sf-view-gen/assets/recipes/sections.json +10 -0
  147. package/skills/sf-view-gen/assets/templates/views/sections/cta.client.tsx +1 -1
  148. package/skills/sf-view-gen/assets/templates/views/sections/faq.client.tsx +1 -1
  149. package/skills/sf-view-gen/assets/templates/views/sections/logoCloud.client.tsx +1 -1
  150. package/skills/sf-view-gen/assets/templates/views/sections/pricing.client.tsx +1 -1
  151. package/skills/sf-view-gen/assets/templates/views/sections/products.client.tsx +100 -0
  152. package/skills/sf-view-gen/assets/templates/views/sections/products.tsx +19 -0
  153. package/skills/sf-view-gen/assets/templates/views/sections/schema.products.ts +39 -0
  154. package/skills/sf-view-gen/assets/templates/views/sections/statistics.client.tsx +1 -1
  155. package/skills/sf-view-gen/assets/templates/views/sections/testimonials.client.tsx +1 -1
  156. package/skills/{json-render-core/SKILL.md → sf-view-gen/references/json-render-core.md} +4 -27
  157. package/skills/{json-render-next/SKILL.md → sf-view-gen/references/json-render-next.md} +5 -8
  158. package/skills/{json-render-react/SKILL.md → sf-view-gen/references/json-render-react.md} +3 -5
  159. package/skills/{json-render-shadcn/SKILL.md → sf-view-gen/references/json-render-shadcn.md} +3 -5
  160. package/skills/sf-view-gen/references/views.md +28 -37
  161. package/skills/sf-view-gen/scripts/catalog.mjs +10 -0
  162. package/skills/sf-view-gen/scripts/validate.mjs +75 -4
  163. package/skills/storefront-workflow/SKILL.md +94 -31
  164. package/skills/{storefront-best-practices/reference/design.md → storefront-workflow/references/design-consistency.md} +13 -29
  165. package/CHANGELOG.md +0 -84
  166. package/assets/templates/views/home/assembly/slots/benefits/Feature1/binding.json +0 -5
  167. package/assets/templates/views/home/assembly/slots/benefits/Feature2/binding.json +0 -5
  168. package/assets/templates/views/home/assembly/slots/benefits/Feature2/registry.part +0 -10
  169. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/binding.json +0 -5
  170. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/catalog.part +0 -4
  171. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/registry.part +0 -16
  172. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/binding.json +0 -5
  173. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/catalog.part +0 -4
  174. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/element.part +0 -5
  175. package/assets/templates/views/user-panel/index.tsx +0 -106
  176. package/assets/templates/views/user-panel/registry.tsx +0 -54
  177. package/assets/templates/views/user-panel/schema.ts +0 -79
  178. package/commands/sf-add-view.md +0 -57
  179. package/commands/sf-feature.md +0 -28
  180. package/commands/sf-theme.md +0 -26
  181. package/commands/sf-view.md +0 -67
  182. package/skills/building-storefronts/SKILL.md +0 -178
  183. package/skills/building-storefronts/references/frontend-integration.md +0 -229
  184. package/skills/json-render-remotion/SKILL.md +0 -111
  185. package/skills/json-render-solid/SKILL.md +0 -204
  186. package/skills/nextjs-shadcn/SKILL.md +0 -367
  187. package/skills/nextjs-shadcn/references/architecture.md +0 -499
  188. package/skills/nextjs-shadcn/references/project-setup.md +0 -162
  189. package/skills/nextjs-shadcn/references/shadcn-platform.md +0 -261
  190. package/skills/nextjs-shadcn/references/sidebar.md +0 -274
  191. package/skills/nextjs-shadcn/references/styling.md +0 -555
  192. package/skills/shadcn-component-discovery/SKILL.md +0 -273
  193. package/skills/shadcn-component-discovery/references/registries.md +0 -226
  194. package/skills/shadcn-theming/SKILL.md +0 -104
  195. package/skills/storefront-best-practices/SKILL.md +0 -421
  196. package/skills/storefront-best-practices/reference/components/breadcrumbs.md +0 -123
  197. package/skills/storefront-best-practices/reference/components/cart-popup.md +0 -189
  198. package/skills/storefront-best-practices/reference/components/country-selector.md +0 -298
  199. package/skills/storefront-best-practices/reference/components/footer.md +0 -112
  200. package/skills/storefront-best-practices/reference/components/hero.md +0 -241
  201. package/skills/storefront-best-practices/reference/components/megamenu.md +0 -239
  202. package/skills/storefront-best-practices/reference/components/navbar.md +0 -397
  203. package/skills/storefront-best-practices/reference/components/popups.md +0 -221
  204. package/skills/storefront-best-practices/reference/components/product-card.md +0 -125
  205. package/skills/storefront-best-practices/reference/components/product-reviews.md +0 -217
  206. package/skills/storefront-best-practices/reference/components/product-slider.md +0 -174
  207. package/skills/storefront-best-practices/reference/components/search.md +0 -101
  208. package/skills/storefront-best-practices/reference/connecting-to-backend.md +0 -391
  209. package/skills/storefront-best-practices/reference/features/promotions.md +0 -307
  210. package/skills/storefront-best-practices/reference/features/wishlist.md +0 -230
  211. package/skills/storefront-best-practices/reference/layouts/account.md +0 -380
  212. package/skills/storefront-best-practices/reference/layouts/cart.md +0 -316
  213. package/skills/storefront-best-practices/reference/layouts/checkout.md +0 -486
  214. package/skills/storefront-best-practices/reference/layouts/home-page.md +0 -264
  215. package/skills/storefront-best-practices/reference/layouts/order-confirmation.md +0 -231
  216. package/skills/storefront-best-practices/reference/layouts/product-details.md +0 -527
  217. package/skills/storefront-best-practices/reference/layouts/product-listing.md +0 -520
  218. package/skills/storefront-best-practices/reference/layouts/static-pages.md +0 -356
  219. package/skills/storefront-best-practices/reference/medusa.md +0 -307
  220. /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/catalog.part +0 -0
  221. /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/element.part +0 -0
  222. /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/catalog.part +0 -0
  223. /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/element.part +0 -0
  224. /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/mobile-responsiveness.md +0 -0
  225. /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/seo.md +0 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sf-view-gen
3
- description: Add or remove a Thor Commerce storefront view, compose a view's faq/cta sections, or customize a view's user-owned files. Use when the user runs /sf-add-view or /sf-view, or asks to add/remove a view, add/remove/reorder a section, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
3
+ description: Add or remove a Thor Commerce storefront view, compose and reorder a view's executable sections, or customize a view's user-owned files. Use when the user asks to add or remove a view (home, category, product, cart, account, static), add/remove/reorder a section (faq, cta, products), change a variant, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
4
4
  ---
5
5
 
6
6
  # sf-view-gen
@@ -10,51 +10,49 @@ Choose a view's composition **by meaning**, delegate the structural write to the
10
10
  manifest (`storefront.config.json`) is the structural authority; the CLI is the
11
11
  only writer of derived files.
12
12
 
13
- ## Read the registry through the CLI (never from memory)
13
+ ## Read the curated view set through the CLI (never from memory)
14
14
 
15
15
  Run from the storefront project root. The CLI resolves the project from the
16
16
  current directory; do not pass a directory.
17
17
 
18
18
  ```bash
19
- npx @thorprovider/storefront views --json # views, routes, supported intents/variants, installed
19
+ npx @thorprovider/storefront views --json # views, routes, intents/variants, installed
20
20
  npx @thorprovider/storefront recipes --json # whole curated registry (views + features)
21
21
  npx @thorprovider/storefront features --json # feature bundles and what they own
22
22
  ```
23
23
 
24
24
  The `--json` output is the same registry the CLI validates against, so it cannot
25
- advertise a selection the reconciler will not honour. `views --json` and
26
- `recipes --json` also report, per view, `registeredSlots` (the non-removable core
27
- slots), `allowedSections` (the section types the view may host), and
28
- `maxSections` (the editorial-instance bound), plus a top-level `sectionTypes`
29
- list marking each type `executable` or `held` with a reason. Do not read the JSON
30
- files directly; they are an implementation detail.
31
-
32
- ## Curated MVP set
33
-
34
- - **Standalone views:** `home`, `category`, `product` — add with `view add`.
35
- - **Feature-owned view:** `checkout` is owned by the `checkout` feature. A direct
36
- `view add checkout` is rejected; run `feature add checkout` instead (see the
37
- `sf-feature` skill).
38
- - **Held post-MVP:** `user-panel` and recommendations are rejected before any
39
- write. Do not try to install them. (Sections are composable — see below.)
25
+ advertise a selection the reconciler will not honour. There is **no fixed view
26
+ list in this skill**: `views --json` reports the authoritative curated set
27
+ (currently `home`, `product`, `cart`, `category`, `checkout`, `account`, and
28
+ `static`) annotated with `installed` and `supported`, so a view added to or
29
+ removed from the registry is reflected without editing this text.
30
+
31
+ `views --json` and `recipes --json` also report, per view, `registeredSlots` (the
32
+ non-removable core slots), `allowedSections` (the section types the view may
33
+ host), and `maxSections` (the editorial-instance bound), plus a top-level
34
+ `sectionTypes` list marking each type `executable` or `held` with a reason. Do not
35
+ read the JSON files directly; they are an implementation detail.
40
36
 
41
37
  ## Add a view
42
38
 
43
- 1. Read `views --json`. If the view is held or feature-owned, stop and explain
44
- the correct path.
39
+ 1. Read `views --json`. If the view is held (`supported: false`) or is
40
+ feature-owned, stop and explain the correct path (a direct `view add` of a
41
+ feature-owned view is rejected — route it through the owning feature's
42
+ `feature add`; see the `sf-feature` skill).
45
43
  2. Choose an **intent by meaning** for each slot from the view's
46
- `supportedIntents` (e.g. a "dense grid" description → the matching intent).
47
- If the description is silent, use the default. Only use
48
- `--variant slot=Name` when the user names an exact supported variant.
44
+ `supportedIntents` (for example a "dense grid" description → the matching
45
+ intent). If the description is silent, use the default. Use
46
+ `--variant slot=Name` only when the user names an exact supported variant.
49
47
  3. Delegate the write:
50
48
 
51
49
  ```bash
52
50
  npx @thorprovider/storefront view add <name> [--intent slot=intent] [--variant slot=Variant]
53
51
  ```
54
52
 
55
- The CLI validates, updates the manifest, and reconciles the derived files.
56
- If it exits non-zero, show its message and the supported options; do not
57
- hand-edit derived files to work around it.
53
+ The CLI validates, updates the manifest, and reconciles the derived files. If
54
+ it exits non-zero, show its message and the supported options; do not hand-edit
55
+ derived files to work around it.
58
56
  4. Report the created view and its route.
59
57
 
60
58
  ## Remove a view
@@ -75,11 +73,15 @@ natural language and never types a command.
75
73
 
76
74
  1. Read `views --json`. For the target view use `registeredSlots` (the core
77
75
  slots), `allowedSections` (the host allowlist), and `maxSections`; read the
78
- top-level `sectionTypes` list for which types are available.
79
- 2. Only `faq` and `cta` are `executable`. Held types (`testimonials`,
80
- `statistics`, `logoCloud`, `pricing`) are refused with a bounded reason. Never
81
- present a held type as available, and never invent a reason — relay the
82
- `reason` the registry reports.
76
+ top-level `sectionTypes` list for which types are `executable`. Never treat the
77
+ `sections --json` installed-instance list as the set of available types.
78
+ 2. Only `executable` types may be composed; a `held` type is refused with the
79
+ `reason` the registry reports — relay that reason, never invent one. A
80
+ `dataBound` `products` instance is configured separately by the developer in
81
+ `views/<view>/data.ts` → `sectionSources[id]` (a canonical query — not a sales
82
+ ranking); its variant only changes presentation, and until the selection is set
83
+ the instance renders a truthful "needs configuration" state that `doctor`
84
+ reports by file and instance id.
83
85
  3. Compose through the CLI's section operations, carried in the operations
84
86
  envelope `{ "formatVersion": 1, "operations": [ ... ] }`. Write the envelope
85
87
  to a file, plan it, then apply the plan:
@@ -89,14 +91,14 @@ natural language and never types a command.
89
91
  npx @thorprovider/storefront apply --plan plan.json
90
92
  ```
91
93
 
92
- - `{ "op": "section.add", "view": "home", "type": "faq" }` — optional `id`,
94
+ - `{ "op": "section.add", "view": "<view>", "type": "<type>" }` — optional `id`,
93
95
  `variant`, and `at` (0-based insertion index, default append). Omit `id` to
94
96
  auto-mint one; a `variant` must be declared by the section type.
95
- - `{ "op": "section.remove", "view": "home", "id": "home-faq-1" }` — removes an
97
+ - `{ "op": "section.remove", "view": "<view>", "id": "<id>" }` — removes an
96
98
  editorial instance. A registered slot (`slot:<slot>`) cannot be removed.
97
- - `{ "op": "section.reorder", "view": "home", "order": ["slot:hero", "home-faq-1", "slot:benefits", "slot:categories"] }` —
98
- `order` must be a permutation of the view's current entry ids: every current
99
- id exactly once, and every registered slot present.
99
+ - `{ "op": "section.reorder", "view": "<view>", "order": [ ... ] }` — `order`
100
+ must be a permutation of the view's current entry ids: every current id
101
+ exactly once, and every registered slot present.
100
102
 
101
103
  4. `plan` is read-only and validates the whole intended state; `apply --plan` is
102
104
  the only writer. On success the CLI updates the manifest and reconciles derived
@@ -107,7 +109,15 @@ natural language and never types a command.
107
109
  `content.ts`; re-adding the same `id` rebinds it, while an auto-minted id never
108
110
  rebinds preserved content.
109
111
 
110
- ## Customize a view (the `/sf-view` workflow)
112
+ ## Variants
113
+
114
+ A slot's variant is a presentation choice carried by the manifest. Change it
115
+ through the CLI (`view add`/`remove` with `--variant`, or a `section.add` /
116
+ `section.reorder` operation for editorial sections); never hand-edit a derived
117
+ `index.tsx` or registry to swap an import identifier. Variant changes go through
118
+ the CLI plan/apply path so the manifest and the derived files stay in sync.
119
+
120
+ ## Customize a view
111
121
 
112
122
  Only **user-owned** files may be edited by hand. They are consumed by thin
113
123
  derived wrappers, so `sync` regenerates the wrappers around your edits.
@@ -124,7 +134,18 @@ Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
124
134
  the event/prop contracts the derived wrapper imports.
125
135
  3. Regenerate the wrappers: `npx @thorprovider/storefront sync`.
126
136
  4. If the change needs a different block variant or a new view, use the CLI
127
- (`view add`/`remove`); never edit the derived `index.tsx` to swap a variant.
137
+ (`view add`/`remove` or the section operations); never edit a derived file to
138
+ swap a variant.
139
+
140
+ ## References
141
+
142
+ Relative to this `SKILL.md`:
143
+
144
+ - `references/views.md` — view module shape, registering, and data contracts.
145
+ - `references/json-render-core.md` — catalog zod props and spec shape.
146
+ - `references/json-render-react.md` — registry mapping, providers, and actions.
147
+ - `references/json-render-next.md` — the Next rendering shape.
148
+ - `references/json-render-shadcn.md` — standard component definitions.
128
149
 
129
150
  ## Stack constraints
130
151
 
@@ -132,11 +153,13 @@ Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
132
153
  - Data only through `@thorprovider/adapters` + `@thorprovider/runtime/commerce`.
133
154
  - Never `@thorprovider/medusa-extended`.
134
155
  - No custom blocks without explicit user authorization.
156
+ - A missing capability is a gap to report, not a reason to install another UI
157
+ framework or hand-edit a derived file.
135
158
 
136
159
  ## Workflow model
137
160
 
138
- Read `../storefront-workflow/SKILL.md` for the four phases (bootstrap → compose
139
- → customize → verify), the ownership classes, and the CLI/agent authority.
161
+ Read `../storefront-workflow/SKILL.md` for the four phases and the CLI/agent
162
+ authority.
140
163
 
141
164
  ## Completion criteria
142
165
 
@@ -7,20 +7,20 @@
7
7
  "default": "compact",
8
8
  "intents": {
9
9
  "compact": {
10
- "variant": "StorefrontHero1",
11
- "when": "A simple, text-forward hero with a single call to action and no product showcase."
10
+ "variant": "StorefrontHero",
11
+ "when": "A simple, text-forward hero with a single call to action (canonical `presentation: 'compact'`)."
12
12
  },
13
13
  "showcase": {
14
- "variant": "StorefrontHero2",
15
- "when": "A product-led hero that displays featured products alongside the headline."
14
+ "variant": "StorefrontHero",
15
+ "when": "A product-led hero with a search affordance and rotating featured products (canonical `presentation: 'showcase'`)."
16
16
  },
17
17
  "editorial": {
18
- "variant": "StorefrontHero5",
19
- "when": "A storytelling or brand-editorial hero with strong imagery and a narrative tone."
18
+ "variant": "StorefrontHero",
19
+ "when": "A storytelling hero with department navigation and optional curated deals (canonical `presentation: 'editorial'`)."
20
20
  },
21
21
  "promotional": {
22
- "variant": "StorefrontHero6",
23
- "when": "A campaign hero built around an offer, discount, or seasonal promotion."
22
+ "variant": "StorefrontHero",
23
+ "when": "A campaign hero built around real, host-supplied offers (canonical `presentation: 'promotional'`)."
24
24
  }
25
25
  }
26
26
  },
@@ -28,11 +28,11 @@
28
28
  "default": "compact",
29
29
  "intents": {
30
30
  "compact": {
31
- "variant": "Feature1",
31
+ "variant": "cards",
32
32
  "when": "A short list of benefits with icons and one-line descriptions."
33
33
  },
34
34
  "detailed": {
35
- "variant": "Feature2",
35
+ "variant": "split",
36
36
  "when": "Benefits that need longer explanations, richer layout, or supporting media."
37
37
  }
38
38
  }
@@ -41,20 +41,20 @@
41
41
  "default": "standard",
42
42
  "intents": {
43
43
  "standard": {
44
- "variant": "ProductCategory2",
45
- "when": "A balanced grid of category cards with image and label."
44
+ "variant": "CategoryGrid",
45
+ "when": "A balanced grid of category cards with image and label (canonical `presentation: 'grid'`)."
46
46
  },
47
47
  "iconGrid": {
48
- "variant": "ProductCategory1",
49
- "when": "A compact icon-based category grid for many small categories."
48
+ "variant": "CategoryGrid",
49
+ "when": "A compact icon-based category grid for many small categories (canonical `presentation: 'icons'`)."
50
50
  },
51
51
  "featured": {
52
- "variant": "ProductCategory4",
53
- "when": "Few, large featured category tiles that act as primary navigation."
52
+ "variant": "CategoryGrid",
53
+ "when": "Few, large featured category tiles that act as primary navigation (canonical `presentation: 'icons'`)."
54
54
  },
55
55
  "editorial": {
56
- "variant": "ProductCategory5",
57
- "when": "Category tiles presented as editorial imagery blocks."
56
+ "variant": "CategoryGrid",
57
+ "when": "Category tiles presented as a searchable list with subcategory chips (canonical `presentation: 'list'`)."
58
58
  }
59
59
  }
60
60
  },
@@ -62,16 +62,16 @@
62
62
  "default": "standard",
63
63
  "intents": {
64
64
  "standard": {
65
- "variant": "ProductOverview1",
66
- "when": "A straightforward product detail layout: gallery, title, price, add to cart."
65
+ "variant": "ProductOverview",
66
+ "when": "A straightforward product detail layout: gallery, title, price, add to cart (canonical `presentation: 'standard'`)."
67
67
  },
68
68
  "gallery": {
69
- "variant": "ProductOverview2",
70
- "when": "The product needs emphasis on a large image gallery with thumbnails."
69
+ "variant": "ProductOverview",
70
+ "when": "The product needs emphasis on a large image gallery with thumbnails (canonical `presentation: 'gallery'`)."
71
71
  },
72
72
  "rich": {
73
- "variant": "ProductOverview5",
74
- "when": "A detailed product page with tabs, specs, and extensive structured information."
73
+ "variant": "ProductOverview",
74
+ "when": "A detailed product page with tabs, specs, and extensive structured information (canonical `presentation: 'rich'`)."
75
75
  }
76
76
  }
77
77
  },
@@ -88,6 +88,15 @@
88
88
  }
89
89
  }
90
90
  },
91
+ "cart.view": {
92
+ "default": "review",
93
+ "intents": {
94
+ "review": {
95
+ "variant": "ShoppingCart",
96
+ "when": "A standalone cart review page: line editing plus backend-authoritative totals before checkout."
97
+ }
98
+ }
99
+ },
91
100
  "category.filter": {
92
101
  "default": "sidebar",
93
102
  "intents": {
@@ -148,28 +157,6 @@
148
157
  "when": "A signed-in shopper's order history with per-order totals and detail on demand."
149
158
  }
150
159
  }
151
- },
152
- "user-panel.shell": {
153
- "default": "standard",
154
- "intents": {
155
- "standard": {
156
- "variant": "AppShell1",
157
- "when": "A standard account shell with side navigation and content area."
158
- }
159
- }
160
- },
161
- "user-panel.orderHistory": {
162
- "default": "compact",
163
- "intents": {
164
- "compact": {
165
- "variant": "OrderHistory1",
166
- "when": "A concise list of past orders with status and totals."
167
- },
168
- "detailed": {
169
- "variant": "OrderHistory2",
170
- "when": "Order history with line-item detail, tracking, and reorder actions."
171
- }
172
- }
173
160
  }
174
161
  }
175
162
  }