@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
@@ -0,0 +1,38 @@
1
+ # Storefront OpenSpec configuration — seeded by @thorprovider/storefront.
2
+ #
3
+ # This file is storefront-owned: `storefront update` re-applies it after
4
+ # re-running `openspec init`. Put customization in the storefront's own files,
5
+ # not here.
6
+ schema: spec-driven
7
+
8
+ context: |
9
+ This project is a generated Thor Commerce storefront. A storefront is defined by
10
+ its manifest (storefront.config.json) and produced by the `storefront` CLI. The
11
+ CLI is the authority for every structural change — views, features, sections,
12
+ theme, and setup — and it is the only writer of derived files. Manual edits are
13
+ limited to user-owned files (view content/props/data/schema, mappers, icon-map,
14
+ shell) plus the bounded external surface of app/globals.css and app/layout.tsx,
15
+ and must preserve the CLI-managed imports and markers.
16
+ Determinism first: a change the CLI performs deterministically stays with the CLI.
17
+ A deterministic change the CLI records in storefront.config.json is trivial and
18
+ does not require an OpenSpec change; the manifest is its record. A change that
19
+ requires judgment — content authoring, prop/data mapping, composition reshaping,
20
+ or a cross-file redesign whose acceptance is not a CLI assertion — is non-trivial
21
+ and is driven through the spec-driven loop, surfaced to the user as the five
22
+ stages explore → plan → build → verify → inform, orchestrated by the agent
23
+ without asking the user to confirm each artifact. Keep any OpenSpec change
24
+ consistent with the storefront authorities: structural edits still go through
25
+ the CLI.
26
+
27
+ rules:
28
+ proposal:
29
+ - "State the why, the observable storefront change, and the affected view(s) or feature(s); keep deferred scope explicit."
30
+ - "Do not restate this context or these rules in the artifact body."
31
+ specs:
32
+ - "New capabilities start with ## Purpose and ## ADDED Requirements; scenarios use exactly four hashtags (#### Scenario:) and every requirement has at least one."
33
+ - "Describe observable behavior, not implementation details."
34
+ design:
35
+ - "Record each decision with its why and the alternative considered; state how the change respects the CLI-as-authority and the user-owned surface."
36
+ tasks:
37
+ - "Group tasks by dependency; each task is a checkbox and states its own verification."
38
+ - "Never report the change complete until `storefront sync` and `storefront doctor` pass and the change's acceptance is met."
@@ -0,0 +1,76 @@
1
+ # AGENTS.md — __SITE_NAME__ storefront
2
+
3
+ This storefront was generated by `@thorprovider/storefront`. It is governed by a
4
+ manifest (`storefront.config.json` at the project root) and produced by the
5
+ `storefront` CLI. This file is managed: `storefront sync` regenerates it from the
6
+ package template, and `storefront doctor` reports it as drift when edited by
7
+ hand. Read it before changing anything.
8
+
9
+ ## RULE 0 — Non-negotiable
10
+
11
+ 1. **The `storefront` CLI is the authority.** Every structural change — adding or
12
+ removing a view or feature, composing sections, changing the theme mode,
13
+ connecting the backend — goes through `npx @thorprovider/storefront …`. Never
14
+ copy templates or scaffold structure by hand.
15
+ 2. **Derived files are CLI-only; never hand-edit them.** The CLI is the only
16
+ writer of derived files. If a change seems to need a capability the CLI does
17
+ not expose, first check the CLI subcommands and the `plan` → `apply`
18
+ operations envelope; if it is still missing, **STOP and report the gap** —
19
+ do not hand-edit a derived file. A hand edit is silently overwritten by the
20
+ next `sync`.
21
+ 3. **Hand-edit only user-owned files and the bounded external surface.** Manual
22
+ edits are limited to the declared user-owned files:
23
+ `lib/<name>/views/<view>/{schema,content,props,data}.ts`, `lib/<name>/mappers.ts`,
24
+ `lib/<name>/icon-map.ts`, and `lib/<name>/shell/**` — plus the bounded external
25
+ customization surface of `app/globals.css` and `app/layout.tsx`: theme design
26
+ tokens and their foreground pairs, font wiring, and global identity/metadata.
27
+ Prefer the deterministic `storefront theme` controls (colors, radius, fonts,
28
+ presets, imports) over hand edits; the bounded surface remains editable when a
29
+ value has no CLI control.
30
+ Editing the external files must preserve the CLI-managed wiring: the library
31
+ stylesheet import, the provider import and marker, the theme-mode marker, and
32
+ the block token contract. The CLI only appends that wiring idempotently, so a
33
+ restructure that removes it is drift, not a customization. Everything else is
34
+ derived (CLI-only).
35
+ 4. **Respect the architecture invariants.** UI components come only from
36
+ `@thorprovider/blocks`; data comes only from `@thorprovider/adapters` and
37
+ `@thorprovider/runtime/commerce` (never HTTP directly); routing stays the
38
+ catch-all `app/[[...slug]]/page.tsx`; `@thorprovider/medusa-extended` is not
39
+ used.
40
+ 5. **Verify after every change.** Run `npx @thorprovider/storefront sync`, then
41
+ `npx @thorprovider/storefront doctor`. `doctor` must report no drift; a build
42
+ (`yarn build`) is the final acceptance.
43
+ 6. **Drive non-trivial customization through the spec-driven loop.** A change
44
+ that needs judgment — content authoring, prop/data mapping, composition
45
+ reshaping, or a cross-file redesign whose acceptance is not a CLI assertion —
46
+ is **non-trivial**: drive it through the spec-driven loop and surface the five
47
+ stages to the user, **explore → plan → build → verify → inform**. A change the
48
+ CLI performs deterministically (theme mode, `view add|remove`,
49
+ `feature add|remove`, `setup`) is recorded in `storefront.config.json` and does
50
+ **not** require an OpenSpec change — the manifest is its record. Never ask the
51
+ user to run `openspec` or to approve individual artifacts.
52
+
53
+ ## Workflow model
54
+
55
+ **bootstrap → compose → customize → verify.** The manifest
56
+ (`storefront.config.json`) is the structural source of truth; the CLI is the only
57
+ writer of derived files; the developer (or agent) edits only user-owned files and
58
+ the bounded external surface of `app/globals.css` and `app/layout.tsx`.
59
+ Customization that needs judgment runs through the spec-driven loop surfaced as
60
+ explore → plan → build → verify → inform.
61
+ See the `storefront-workflow` skill for the full model and the ownership classes.
62
+
63
+ ## Router — intent → skill → CLI
64
+
65
+ The user states the intent in natural language; load the skill and delegate the
66
+ write to the CLI. Never edit a derived file to achieve the intent.
67
+
68
+ | Intent | Load skill | Delegate to CLI |
69
+ |---|---|---|
70
+ | Add or remove a view; compose a view's sections | `sf-view-gen` | `storefront views --json`, then `storefront view add\|remove …`; sections via `plan` → `apply` |
71
+ | Customize the theme: colors, radius, fonts, presets; identity/SEO | `sf-theme-gen` | `storefront theme` — `--brand orange`, `--primary <color>`, `--accent <color>`, `--radius <length>`, `--font-sans google:Inter`, `--set light.primary=#f97316`, `--preset <ref>`, `--import <src>`, `--export <file>`, `--mode light\|dark\|system`. Visual values live in `app/globals.css`; the mode in `storefront.config.json`. Inspect with `storefront theme --inspect`. The bounded external surface stays editable by hand |
72
+ | Add or remove a feature (e.g. `checkout`) | `sf-feature` | `storefront features --json`, then `storefront feature add\|remove …` |
73
+ | Connect or re-point the Medusa backend; change region, sales channel, or publishable key | `sf-setup` | `storefront setup --backend-url … --publishable-key … --sales-channel-id … --region-id …` |
74
+ | Edit a view's content/props/data; map props or data; reshape composition; any change whose acceptance is not a CLI assertion (non-trivial) | `storefront-workflow` | spec-driven loop surfaced as **explore → plan → build → verify → inform** — the agent drives it and never asks the user to confirm OpenSpec artifacts; structural edits still go through `storefront …`, verified with `storefront sync` then `storefront doctor` |
75
+
76
+ The step-by-step procedures live in the skills, not in this file.
@@ -1,8 +1,12 @@
1
1
  // Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/page.tsx)
2
2
 
3
3
  import { notFound } from 'next/navigation'
4
+ import { buildBreadcrumbListJsonLd, serializeJsonLd } from '@thorprovider/runtime/contracts'
4
5
  import { __STOREFRONT_CAMEL__App } from '@/lib/__STOREFRONT__/runtime'
5
6
  import { readCartStateForRender } from '@/lib/__STOREFRONT__/cart-state'
7
+ import { readAccountSession } from '@/lib/__STOREFRONT__/account-session'
8
+ import { toAccountInitialState } from '@/lib/__STOREFRONT__/account-session.core'
9
+ import { mountedFeatureNames } from '@/lib/__STOREFRONT__/composition'
6
10
  import { StorefrontRenderer } from './renderer'
7
11
 
8
12
  export const { generateMetadata, generateStaticParams } = __STOREFRONT_CAMEL__App
@@ -22,7 +26,57 @@ export default async function Page({
22
26
  // Read the signed cookie and load the backend cart for the initial render.
23
27
  // This never creates a cart; a guest identity is issued by a Server Action.
24
28
  const cartState = await readCartStateForRender()
25
- const initialState = { ...(data.initialState ?? {}), ...cartState }
26
29
 
27
- return <StorefrontRenderer {...data} initialState={initialState} />
30
+ // Seed the request-scoped account identity BEFORE the shell renders, and only
31
+ // when the customer-auth capability is mounted: an unmounted feature performs
32
+ // no auth resolution. The reader is render-safe and request-scoped (no shared
33
+ // cache, so concurrent requests and store contexts stay isolated); only the
34
+ // allowlisted display identity enters the initial state, never a token.
35
+ const accountState = mountedFeatureNames.includes('customer-auth')
36
+ ? toAccountInitialState(await readAccountSession())
37
+ : {}
38
+
39
+ const initialState = { ...(data.initialState ?? {}), ...cartState, ...accountState }
40
+
41
+ // Entity structured data is server-rendered from the real loaded entity and
42
+ // sanitized so entity text cannot terminate the script element.
43
+ const jsonLd = data.entitySeo?.jsonLd
44
+ // The entity OpenGraph type (`product`/`CollectionPage`) is emitted here, not
45
+ // through Next metadata: Next validates `og:type` against the OpenGraph
46
+ // vocabulary and rejects those entity types, so a raw `property` tag is the
47
+ // only way to carry the entity type into the rendered `<head>`.
48
+ const ogType = data.entitySeo?.openGraph?.type
49
+ // The navigability feature's real trail is server-rendered as a sanitized
50
+ // `BreadcrumbList` alongside the entity structured data. It is built from the
51
+ // loader's own state, so it always matches the rendered breadcrumb.
52
+ const breadcrumbItems = (data.initialState as Record<string, unknown> | undefined)
53
+ ?.breadcrumbItems
54
+ const breadcrumbJsonLd = buildBreadcrumbListJsonLd(
55
+ Array.isArray(breadcrumbItems)
56
+ ? (breadcrumbItems as { label?: string; href?: string }[])
57
+ : undefined,
58
+ )
59
+
60
+ return (
61
+ <>
62
+ {ogType ? <meta property="og:type" content={ogType} /> : null}
63
+ {jsonLd ? (
64
+ <script
65
+ type="application/ld+json"
66
+ dangerouslySetInnerHTML={{ __html: serializeJsonLd(jsonLd) }}
67
+ />
68
+ ) : null}
69
+ {breadcrumbJsonLd ? (
70
+ <script
71
+ type="application/ld+json"
72
+ dangerouslySetInnerHTML={{ __html: serializeJsonLd(breadcrumbJsonLd) }}
73
+ />
74
+ ) : null}
75
+ <StorefrontRenderer
76
+ spec={data.spec}
77
+ layoutSpec={data.layoutSpec}
78
+ initialState={initialState}
79
+ />
80
+ </>
81
+ )
28
82
  }
@@ -2,9 +2,51 @@
2
2
 
3
3
  // Generated by Thor Commerce storefront (template: assets/templates/app/app/[[...slug]]/renderer.tsx)
4
4
 
5
+ import { useRef } from 'react'
5
6
  import { PageRenderer } from '@json-render/next'
6
7
  import type { PageData } from '@json-render/next'
8
+ import {
9
+ arbitrateProjection,
10
+ createProjectionOwnership,
11
+ stabilizeProjection,
12
+ type ProjectionOwnership,
13
+ type StabilizedProjection,
14
+ } from '@/lib/__STOREFRONT__/projection-ownership'
15
+ import { ProjectionOwnershipProvider } from '@/lib/__STOREFRONT__/projection-ownership.client'
7
16
 
8
- export function StorefrontRenderer(data: PageData) {
9
- return <PageRenderer {...data} />
17
+ export interface StorefrontRendererProps extends PageData {
18
+ /**
19
+ * The per-tab ownership ledger, injected for composition/tests. The renderer
20
+ * creates and keeps one internally when omitted.
21
+ */
22
+ ownership?: ProjectionOwnership
23
+ }
24
+
25
+ export function StorefrontRenderer({ initialState, ownership: injected, ...data }: StorefrontRendererProps) {
26
+ const ownershipRef = useRef<ProjectionOwnership | null>(null)
27
+ if (ownershipRef.current === null) {
28
+ ownershipRef.current = injected ?? createProjectionOwnership()
29
+ }
30
+ const ownership = ownershipRef.current
31
+
32
+ // The server recomputes `initialState` on every render and a Server Action
33
+ // triggers an RSC refresh, so the prop is a fresh object each time even when
34
+ // its content is unchanged. Capture the first client-owned (account + cart)
35
+ // values so a later or older projection cannot overwrite a live cart or a
36
+ // newer local auth result, then arbitrate (a claim overrides the seed) and
37
+ // keep a STABLE reference while the serialized content is unchanged so
38
+ // `@json-render/react`'s StateProvider does not re-apply identical values and
39
+ // reset client-owned state. Server-owned keys always propagate, so navigation
40
+ // keeps working.
41
+ ownership.seed(initialState)
42
+ const projection = arbitrateProjection(ownership, initialState)
43
+ const stableRef = useRef<StabilizedProjection | null>(null)
44
+ const stable = stabilizeProjection(stableRef.current, projection)
45
+ stableRef.current = stable
46
+
47
+ return (
48
+ <ProjectionOwnershipProvider ownership={ownership}>
49
+ <PageRenderer {...data} initialState={stable.value} />
50
+ </ProjectionOwnershipProvider>
51
+ )
10
52
  }
@@ -28,10 +28,10 @@
28
28
  --color-border: var(--border);
29
29
  --color-input: var(--input);
30
30
  --color-ring: var(--ring);
31
- --radius-sm: var(--radius-sm);
32
- --radius-md: var(--radius-md);
33
- --radius-lg: var(--radius-lg);
34
- --radius-xl: var(--radius-xl);
31
+ --radius-sm: calc(var(--radius) - 4px);
32
+ --radius-md: calc(var(--radius) - 2px);
33
+ --radius-lg: var(--radius);
34
+ --radius-xl: calc(var(--radius) + 4px);
35
35
  --font-sans: var(--font-geist-sans);
36
36
  }
37
37
 
@@ -59,10 +59,7 @@
59
59
  --border: oklch(0.88 0.003 90);
60
60
  --input: oklch(0.92 0.003 90);
61
61
  --ring: oklch(0.15 0 0);
62
- --radius-sm: 0.25rem;
63
- --radius-md: 0.375rem;
64
- --radius-lg: 0.5rem;
65
- --radius-xl: 0.75rem;
62
+ --radius: 0.5rem;
66
63
  }
67
64
 
68
65
  .dark {
@@ -4,8 +4,6 @@ import type { Metadata } from 'next'
4
4
  import { Geist } from 'next/font/google'
5
5
  import { ThemeProvider } from 'next-themes'
6
6
  import { StorefrontProvider } from '@thorprovider/runtime/host-glue/providers'
7
- import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'
8
- import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'
9
7
  import { registry } from '@/lib/__STOREFRONT__/registry'
10
8
  import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
11
9
  import './globals.css'
@@ -15,8 +13,6 @@ const geist = Geist({
15
13
  subsets: ['latin'],
16
14
  })
17
15
 
18
- const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))
19
-
20
16
  // The canonical public origin is optional: when THOR_SITE_URL is unset no base
21
17
  // URL is invented. `metadataBase` is left undefined in that case.
22
18
  const siteUrl = getSiteUrl()
@@ -39,7 +35,7 @@ export default function RootLayout({
39
35
  <html lang="es" className={geist.variable} suppressHydrationWarning>
40
36
  <body className="font-sans antialiased">
41
37
  <ThemeProvider attribute="class" defaultTheme="__STOREFRONT_MODE__" enableSystem>
42
- <StorefrontProvider themeCss={themeCss} registry={registry}>
38
+ <StorefrontProvider registry={registry}>
43
39
  {children}
44
40
  </StorefrontProvider>
45
41
  </ThemeProvider>
@@ -1,13 +1,19 @@
1
1
  // Generated by Thor Commerce storefront (template: assets/templates/app/app/robots.ts)
2
- // Always served. Points at the sitemap only when THOR_SITE_URL is configured.
2
+ // Always served. Allows public pages, disallows private surfaces, and points at
3
+ // the sitemap only when THOR_SITE_URL is configured.
3
4
 
4
5
  import type { MetadataRoute } from 'next'
5
- import { robotsSitemapUrl } from '@/lib/__STOREFRONT__/spec/seo'
6
+ import { __STOREFRONT_CAMEL__Spec } from '@/lib/__STOREFRONT__/spec'
7
+ import { robotsDisallowPaths, robotsSitemapUrl } from '@/lib/__STOREFRONT__/spec/seo'
6
8
  import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
7
9
 
8
10
  export default function robots(): MetadataRoute.Robots {
9
11
  return {
10
- rules: { userAgent: '*', allow: '/' },
12
+ rules: {
13
+ userAgent: '*',
14
+ allow: '/',
15
+ disallow: robotsDisallowPaths(__STOREFRONT_CAMEL__Spec.routes ?? {}),
16
+ },
11
17
  sitemap: robotsSitemapUrl(getSiteUrl()),
12
18
  }
13
19
  }
@@ -1,12 +1,71 @@
1
1
  // Generated by Thor Commerce storefront (template: assets/templates/app/app/sitemap.ts)
2
- // Lists the storefront's fixed routes. Absolute URLs are emitted only when
3
- // THOR_SITE_URL is configured; otherwise the sitemap is empty (no invented URL).
2
+ // Lists the fixed public routes plus every public catalog entity, enumerated
3
+ // across adapter pagination with a bound and a cycle guard. Absolute URLs are
4
+ // emitted only when THOR_SITE_URL is configured; otherwise the sitemap is empty
5
+ // (no invented URL). An enumeration failure fails loudly (no partial sitemap).
4
6
 
5
7
  import type { MetadataRoute } from 'next'
8
+ import { getCatalog, getCatalogResults } from '@thorprovider/runtime/commerce'
6
9
  import { __STOREFRONT_CAMEL__Spec } from '@/lib/__STOREFRONT__/spec'
7
- import { sitemapUrls } from '@/lib/__STOREFRONT__/spec/seo'
10
+ import {
11
+ buildSitemapEntries,
12
+ enumeratePublicEntities,
13
+ SitemapEnumerationError,
14
+ type PublicEntityPage,
15
+ } from '@/lib/__STOREFRONT__/spec/seo'
8
16
  import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
9
17
 
10
- export default function sitemap(): MetadataRoute.Sitemap {
11
- return sitemapUrls(__STOREFRONT_CAMEL__Spec.routes ?? {}, getSiteUrl()).map((url) => ({ url }))
18
+ const ENTITY_PAGE_SIZE = 100
19
+ const MAX_PAGES = 100
20
+
21
+ async function productPage(cursor: string | undefined): Promise<PublicEntityPage> {
22
+ const page = cursor ? Number(cursor) : 1
23
+ const outcome = await getCatalogResults({
24
+ page,
25
+ pageSize: ENTITY_PAGE_SIZE,
26
+ sort: 'name',
27
+ })
28
+ if (!outcome.ok) {
29
+ throw new SitemapEnumerationError({
30
+ kind: 'enumeration',
31
+ message: outcome.error.message,
32
+ })
33
+ }
34
+ const items = outcome.results.products.map((product) => ({
35
+ id: product.id,
36
+ path: `/products/${product.handle}`,
37
+ }))
38
+ const total = outcome.results.total
39
+ const hasMore =
40
+ typeof total === 'number' ? page * ENTITY_PAGE_SIZE < total : items.length >= ENTITY_PAGE_SIZE
41
+ return hasMore ? { items, nextCursor: String(page + 1) } : { items }
42
+ }
43
+
44
+ async function categoryPage(): Promise<PublicEntityPage> {
45
+ const catalog = await getCatalog()
46
+ return {
47
+ items: catalog.categoriesRaw.map((category) => ({
48
+ id: category.id,
49
+ path: `/categories/${category.handle}`,
50
+ })),
51
+ }
52
+ }
53
+
54
+ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
55
+ const siteUrl = getSiteUrl()
56
+ if (!siteUrl) return []
57
+
58
+ const routes = __STOREFRONT_CAMEL__Spec.routes ?? {}
59
+ const [products, categories] = await Promise.all([
60
+ enumeratePublicEntities(productPage, { maxPages: MAX_PAGES }),
61
+ enumeratePublicEntities(categoryPage, { maxPages: MAX_PAGES }),
62
+ ])
63
+ if (!products.ok) throw new SitemapEnumerationError(products.failure)
64
+ if (!categories.ok) throw new SitemapEnumerationError(categories.failure)
65
+
66
+ return buildSitemapEntries({
67
+ routes,
68
+ siteUrl,
69
+ entities: [...products.entities, ...categories.entities],
70
+ })
12
71
  }
@@ -0,0 +1,76 @@
1
+ 'use client'
2
+
3
+ // Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/account-boundary.client.tsx)
4
+ //
5
+ // The `/account` route's passive account boundary. It reads the shared account
6
+ // state and renders ONE thing: an accessible, retryable "unavailable" status —
7
+ // and only when the server resolution could not establish the session. It NEVER
8
+ // fetches or owns identity on mount (the retired `AccountBoot` behaviour), so
9
+ // visiting or navigating to `/account` introduces no competing identity
10
+ // bootstrap; the identity always comes from the shared lifecycle/SSR seed.
11
+ //
12
+ // The retry is a bound action (`retryAccountSession`, registered by the globally
13
+ // mounted lifecycle): the boundary is presentational and dependency-free, and
14
+ // the recovery edge lives in the one shared lifecycle, not in a route fetch.
15
+
16
+ import { useStateStore } from '@json-render/react'
17
+ import type { BaseComponentProps } from '@json-render/react'
18
+
19
+ export function AccountBoundary({ emit }: Pick<BaseComponentProps, 'emit'>) {
20
+ const { state } = useStateStore() as { state: Record<string, unknown> }
21
+ const resolution =
22
+ typeof state.accountResolution === 'string' ? state.accountResolution : 'unresolved'
23
+ // A cross-tab/foreground reconciliation is in flight (task 4.2): present a
24
+ // neutral pending surface instead of the sign-in form (which would fake a
25
+ // signed-out state before the server confirms it) or a stale unavailable
26
+ // status. The authenticated region handles its own pending surface, so this
27
+ // branch is only for the non-authenticated case.
28
+ if (state.accountReconciling === true && state.accountAuthenticated !== true) {
29
+ return (
30
+ <p
31
+ role="status"
32
+ aria-live="polite"
33
+ data-account-reconciling="1"
34
+ className="text-muted-foreground mx-auto max-w-md px-4 py-12 text-center text-sm"
35
+ >
36
+ Actualizando tu cuenta…
37
+ </p>
38
+ )
39
+ }
40
+ // Resolved (authenticated/anonymous) or pre-projection: nothing to show. Only
41
+ // an unavailable resolution (a transport/server outage, never a fake
42
+ // sign-out) surfaces the retryable status.
43
+ if (resolution !== 'unavailable') return null
44
+
45
+ const pending = state.accountPending === true
46
+ const error = typeof state.accountError === 'string' ? state.accountError : null
47
+ // The message is the announced live status region; the retry control is a
48
+ // sibling (a native button, so it is keyboard-operable) that references the
49
+ // message as its accessible description. Keeping the interactive control OUT
50
+ // of the live region avoids re-announcing the button on every status update
51
+ // (task 4.3).
52
+ return (
53
+ <div
54
+ data-account-boundary="unavailable"
55
+ className="mx-auto flex max-w-md flex-col items-center gap-3 px-4 py-12 text-center"
56
+ >
57
+ <p
58
+ id="account-unavailable-message"
59
+ role="status"
60
+ aria-live="polite"
61
+ className="text-muted-foreground text-sm"
62
+ >
63
+ {error ?? 'No pudimos verificar tu sesión. Revisa tu conexión e inténtalo de nuevo.'}
64
+ </p>
65
+ <button
66
+ type="button"
67
+ disabled={pending}
68
+ aria-describedby="account-unavailable-message"
69
+ onClick={() => emit?.('retry')}
70
+ className="bg-primary text-primary-foreground focus-visible:ring-ring rounded-md px-4 py-2 text-sm font-medium transition-colors hover:opacity-90 focus-visible:ring-2 focus-visible:outline-none disabled:pointer-events-none disabled:opacity-60"
71
+ >
72
+ {pending ? 'Reintentando…' : 'Reintentar'}
73
+ </button>
74
+ </div>
75
+ )
76
+ }