@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,209 @@
1
+ 'use client'
2
+
3
+ // Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx)
4
+ //
5
+ // React binding for the projection-ownership ledger. The renderer creates one
6
+ // ledger per tab and provides it here; account mutation/reconciliation code
7
+ // (tasks 3.x) reads the SAME instance through `useProjectionOwnership` so a
8
+ // successful mutation claims the account slice and the renderer stops a later,
9
+ // older server projection from overwriting it. No global mutable and no token.
10
+ //
11
+ // `useAccountOwnership` is the atomic account-ownership helper: claiming the
12
+ // overlay and writing `/account*` in one call keeps the two in lockstep (a
13
+ // divergence would make the overlay mask a different store value). It MUST be
14
+ // called from a client component rendered inside the storefront renderer — a
15
+ // React hook cannot run in a Server Action. Server Actions return data; the
16
+ // client handler awaits the action and then calls `claimAccount(result)` or
17
+ // `claimResolved(result, guard)`.
18
+ //
19
+ // INVARIANT (Important-D): an older server snapshot never overwrites a newer
20
+ // result. The ledger orders CLAIMS, so any authoritative result you display —
21
+ // login/register/logout, or a cross-tab re-resolution (4.x) — MUST be claimed
22
+ // via `claimResolved(result, guard)` (generation guard + claim, atomic). Never
23
+ // display a result and then release to the server: `releaseAccount` /
24
+ // `reconcileAccount` carry no age evidence, so an arbitrary delayed
25
+ // `router.refresh()`/RSC projection could overwrite it. `reconcileAccount` is
26
+ // only an explicit transfer that accepts the NEXT server refresh.
27
+ //
28
+ // IDENTITY-CHANGE INVALIDATION (task 3.3): `claimAccount` also clears the
29
+ // identity-dependent account-PRIVATE order slice whenever the identity key
30
+ // changes, ATOMICALLY with the trio write and only after a `claimResolved`
31
+ // guard. Because every authoritative identity change (login/register/logout,
32
+ // retry/reconcile re-resolution, shell/4.2 claim) flows through `claimAccount`,
33
+ // the private reset happens AT the trigger even when the `/account` panel is
34
+ // unmounted and no effect can run. Same-identity claims are a no-op and the
35
+ // guest cart is never touched (`clearAccountPrivateOrders`).
36
+
37
+ import { createContext, useContext, useMemo, useRef, type ReactNode } from 'react'
38
+ import { useStateStore } from '@json-render/react'
39
+ import type { AccountIdentity, AccountResolution } from './account-session.core'
40
+ import { accountIdentityKey, clearAccountPrivateOrders } from './account-private.core'
41
+ import {
42
+ ACCOUNT_OWNED_KEYS,
43
+ createProjectionOwnership,
44
+ type OwnershipToken,
45
+ type ProjectionOwnership,
46
+ } from './projection-ownership'
47
+
48
+ const ProjectionOwnershipContext = createContext<ProjectionOwnership | null>(null)
49
+
50
+ /**
51
+ * Provide the per-tab ownership ledger. Passing `ownership` is for composition
52
+ * and tests; in the renderer an internal instance is created once and kept for
53
+ * the mounted lifetime of the tab.
54
+ */
55
+ export function ProjectionOwnershipProvider({
56
+ ownership,
57
+ children,
58
+ }: {
59
+ ownership?: ProjectionOwnership
60
+ children: ReactNode
61
+ }) {
62
+ const ref = useRef<ProjectionOwnership | null>(null)
63
+ if (ref.current === null) ref.current = ownership ?? createProjectionOwnership()
64
+ return (
65
+ <ProjectionOwnershipContext.Provider value={ref.current}>
66
+ {children}
67
+ </ProjectionOwnershipContext.Provider>
68
+ )
69
+ }
70
+
71
+ /** Access the tab's ownership ledger. Throws outside the storefront renderer. */
72
+ export function useProjectionOwnership(): ProjectionOwnership {
73
+ const ownership = useContext(ProjectionOwnershipContext)
74
+ if (!ownership) {
75
+ throw new Error('useProjectionOwnership must be used within the storefront renderer')
76
+ }
77
+ return ownership
78
+ }
79
+
80
+ /** The allowlisted account values a mutation claims and writes together. */
81
+ export interface AccountClaimValues {
82
+ accountCustomer: AccountIdentity | null
83
+ accountAuthenticated: boolean
84
+ accountResolution: AccountResolution
85
+ }
86
+
87
+ /** Atomic account ownership: claim the overlay and write the store in one call. */
88
+ export interface AccountOwnership {
89
+ /**
90
+ * Claim the account slice and write `/account*` with the same values. When the
91
+ * identity key changes, the identity-dependent private order slice is cleared
92
+ * in the SAME call (atomic with the trio write); a same-identity claim is a
93
+ * no-op and the guest cart is never touched.
94
+ */
95
+ claimAccount(values: AccountClaimValues): OwnershipToken
96
+ /**
97
+ * Apply an authoritative action/reconciliation result ATOMICALLY with its
98
+ * generation guard. When `guard` is no longer current (a newer mutation or
99
+ * reconciliation already superseded it), the stale result is discarded and
100
+ * null is returned; otherwise the result is claimed (overlay + store write) so
101
+ * it wins over any later-arriving OLDER server projection, and the new token is
102
+ * returned. This is the REQUIRED path for any authoritative result you display
103
+ * (login/register/logout, cross-tab re-resolution in 4.x). Never display a
104
+ * result and then release to the server: `release`/`reconcileAccount` carry no
105
+ * age evidence, so an arbitrary delayed router projection could overwrite it.
106
+ */
107
+ claimResolved(values: AccountClaimValues, guard?: OwnershipToken | null): OwnershipToken | null
108
+ /** Return the account slice to the server when `token` is still current. */
109
+ releaseAccount(token: OwnershipToken): void
110
+ /**
111
+ * Explicit transfer of the account slice to the NEXT server projection (e.g. a
112
+ * `router.refresh()` whose ordering the framework/app guarantees). Use it ONLY
113
+ * when the authoritative values will arrive through that refresh — NOT for a
114
+ * cross-tab/action result you display (`claimResolved` is that path). Releases
115
+ * whether the slice was seeded or claimed, so a tab that only mounted still
116
+ * adopts the next refresh.
117
+ */
118
+ reconcileAccount(): void
119
+ /** True while `token` is still the current account claim. */
120
+ isCurrent(token: OwnershipToken): boolean
121
+ /**
122
+ * Acquire the per-tab auth-mutation gate shared by every consumer in this
123
+ * renderer (the global mount, the account forms, a future nav sign-out).
124
+ * Returns false when another auth mutation/reconciliation is already in
125
+ * flight, so two consumers cannot issue concurrent auth requests. The gate is
126
+ * per-tab ledger state — never a module global.
127
+ */
128
+ acquireAuthMutation(): boolean
129
+ /** Release the per-tab auth-mutation gate (the acquirer only). */
130
+ releaseAuthMutation(): void
131
+ /** True while an auth mutation/reconciliation holds the gate. */
132
+ isAuthMutationPending(): boolean
133
+ }
134
+
135
+ /**
136
+ * The atomic account-ownership helper. Call it from a client component inside
137
+ * the renderer (for example the account registry) — a React hook cannot run in a
138
+ * Server Action. Server Actions return data; the client handler awaits the
139
+ * action and then calls `claimAccount`/`claimResolved`.
140
+ *
141
+ * Invariant: an older server snapshot never overwrites a newer result. The
142
+ * ledger orders CLAIMS (a claim wins until release), so any authoritative result
143
+ * you display must be claimed — `claimResolved(result, guard)` — never released
144
+ * to the server after display. `reconcileAccount`/`releaseAccount` only hand the
145
+ * slice to the next server projection.
146
+ */
147
+ export function useAccountOwnership(): AccountOwnership {
148
+ const ownership = useProjectionOwnership()
149
+ const { set, getSnapshot } = useStateStore()
150
+ return useMemo(() => {
151
+ const claimAccount = (values: AccountClaimValues): OwnershipToken => {
152
+ // Normalize once so the overlay and the store cannot diverge (Minor-A).
153
+ const accountCustomer = values.accountCustomer ?? null
154
+ const accountAuthenticated = values.accountAuthenticated === true
155
+ // Identity-change invalidation, ATOMIC with the trio write and
156
+ // generation-safe (this only runs after a guard check in `claimResolved`):
157
+ // when the authorized customer changes — logout, customer switch,
158
+ // expiry/invalidation, or unavailable — clear the identity-dependent
159
+ // private order slice in the SAME call, so the reset happens AT the
160
+ // trigger even when the `/account` panel is unmounted and no effect can
161
+ // run. The prior key is read from the LIVE store (not a render closure),
162
+ // so it is correct regardless of which route is mounted. A same-identity
163
+ // claim (a re-resolution, or `beginMutation`'s snapshot claim) is a no-op,
164
+ // and `clearAccountPrivateOrders` never writes a guest cart key.
165
+ const priorKey = accountIdentityKey(
166
+ (getSnapshot().accountCustomer ?? null) as { id?: string | null } | null,
167
+ )
168
+ const nextKey = accountIdentityKey(accountCustomer)
169
+ const token = ownership.claim(ACCOUNT_OWNED_KEYS, {
170
+ accountCustomer,
171
+ accountAuthenticated,
172
+ accountResolution: values.accountResolution,
173
+ })
174
+ // Clear BEFORE writing the new identity so no reader ever observes the
175
+ // new identity alongside the previous customer's private rows.
176
+ if (priorKey !== nextKey) clearAccountPrivateOrders(set)
177
+ set('/accountCustomer', accountCustomer)
178
+ set('/accountAuthenticated', accountAuthenticated)
179
+ set('/accountResolution', values.accountResolution)
180
+ return token
181
+ }
182
+ return {
183
+ claimAccount,
184
+ claimResolved(values, guard = null) {
185
+ if (guard && !ownership.isCurrent(guard)) return null
186
+ return claimAccount(values)
187
+ },
188
+ releaseAccount(token) {
189
+ ownership.release(token)
190
+ },
191
+ reconcileAccount() {
192
+ const token = ownership.currentToken(ACCOUNT_OWNED_KEYS)
193
+ if (token) ownership.release(token)
194
+ },
195
+ isCurrent(token) {
196
+ return ownership.isCurrent(token)
197
+ },
198
+ acquireAuthMutation() {
199
+ return ownership.acquireMutationGate()
200
+ },
201
+ releaseAuthMutation() {
202
+ ownership.releaseMutationGate()
203
+ },
204
+ isAuthMutationPending() {
205
+ return ownership.isMutationGateHeld()
206
+ },
207
+ }
208
+ }, [ownership, set])
209
+ }
@@ -0,0 +1,247 @@
1
+ // Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/projection-ownership.ts)
2
+ //
3
+ // Client-owned projection arbitration for the storefront renderer.
4
+ //
5
+ // `@json-render/react`'s StateProvider re-applies the initial values whose
6
+ // flattened pointers changed between two *server* projections. A client edit
7
+ // made with `set()` lives only in the store, so a changed server projection for
8
+ // the same key overwrites it. Storefront state is therefore split:
9
+ //
10
+ // - server-owned keys (route/catalog/spec/SEO/product data): the server always
11
+ // wins, so navigation keeps working;
12
+ // - client-owned keys (`CLIENT_OWNED_KEYS` = the account slice the SSR projects
13
+ // and the cart slice the cart Server Actions mutate): seeded from the first
14
+ // projection and then protected, so a later (or older) projection cannot
15
+ // overwrite a live cart or a newer local auth result.
16
+ //
17
+ // A mutation can `claim` a client-owned key with a generation (its value wins
18
+ // until release). Authoritative reconciliation releases the slice back to the
19
+ // server: `currentToken(keys)` + `release(token)` downgrades a claim OR a seed,
20
+ // so a tab that only seeded (mounted then never mutated) can still adopt a later
21
+ // logout/expiry projection without a prior local mutation. The generation guards
22
+ // make an older in-flight result unable to release or supersede a newer claim
23
+ // (task 3.3).
24
+ //
25
+ // INVARIANT: the ledger orders CLAIMS, not server projections. A `release` hands
26
+ // the slice to the next server projection and carries no age evidence, so any
27
+ // authoritative result that is displayed MUST be claimed (a newer claim wins
28
+ // until release) — never released to the server after display. The client helper
29
+ // `claimResolved(values, guard)` performs the generation guard + claim
30
+ // atomically; `reconcileAccount` is only an explicit transfer that accepts the
31
+ // next server refresh.
32
+ //
33
+ // Framework-free: no React/Next import, no global state, no token. The per-tab
34
+ // instance lives in `./projection-ownership.client`. `claim`/`seed` store only
35
+ // the declared keys, so a value carrying extra (for example secret) fields can
36
+ // never reach the projection.
37
+
38
+ /** The account state keys the catch-all SSR seeds and an auth mutation owns. */
39
+ export const ACCOUNT_OWNED_KEYS = [
40
+ 'accountCustomer',
41
+ 'accountAuthenticated',
42
+ 'accountResolution',
43
+ ] as const
44
+
45
+ /**
46
+ * The cart slice the cart Server Actions mutate locally and the SSR seeds. The
47
+ * server's read-failure/status flags (`cartReadError`, `receiptAvailable`) are
48
+ * deliberately NOT here: they are server-owned so an outage still surfaces.
49
+ */
50
+ export const CART_OWNED_KEYS = [
51
+ 'cart',
52
+ 'cartTotals',
53
+ 'cartId',
54
+ 'cartQuantity',
55
+ 'cartCompleted',
56
+ 'cartSelectedShippingOptionId',
57
+ ] as const
58
+
59
+ /** Every key the renderer protects from a changed server projection. */
60
+ export const CLIENT_OWNED_KEYS = [...ACCOUNT_OWNED_KEYS, ...CART_OWNED_KEYS] as const
61
+
62
+ /**
63
+ * A claim handle. `generation` is monotonic per ownership instance and is the
64
+ * token downstream mutation/reconciliation paths use to discard stale work.
65
+ */
66
+ export interface OwnershipToken {
67
+ readonly generation: number
68
+ readonly keys: readonly string[]
69
+ }
70
+
71
+ /** How a client-owned key is currently governed. */
72
+ export type OwnershipAuthority = 'seed' | 'client' | 'server'
73
+
74
+ /** The ownership ledger the renderer arbitrates against. */
75
+ export interface ProjectionOwnership {
76
+ /** The latest generation issued; 0 before any claim. */
77
+ generation(): number
78
+ /**
79
+ * Capture the first server value of every client-owned key not yet seen, so it
80
+ * is protected from later projections. Idempotent: an already-seeded key is
81
+ * never overwritten, and an existing claim is never replaced.
82
+ */
83
+ seed(projection: Record<string, unknown> | undefined): void
84
+ /**
85
+ * Take client ownership of `keys` with `values` (every key must be present),
86
+ * superseding any earlier claim for those keys. Returns the generation token.
87
+ */
88
+ claim(keys: readonly string[], values: Record<string, unknown>): OwnershipToken
89
+ /**
90
+ * The generation token for the current ownership (seed or claim) of `keys`, or
91
+ * null when they are already server-owned. Use it to release a SEEDED slice
92
+ * during authoritative reconciliation, without a prior local mutation.
93
+ */
94
+ currentToken(keys: readonly string[]): OwnershipToken | null
95
+ /**
96
+ * Return authority to the server for the keys of `token` when it is still the
97
+ * current ownership (seed or claim). An older token is ignored, so a late
98
+ * reconciliation cannot drop a newer claim.
99
+ */
100
+ release(token: OwnershipToken): void
101
+ /** True while `token` is still the current client claim for all its keys. */
102
+ isCurrent(token: OwnershipToken): boolean
103
+ /** True while `key` is protected from the server projection. */
104
+ isOwned(key: string): boolean
105
+ /** The client-owned key/value overlay across every seeded/claimed key. */
106
+ overlay(): Record<string, unknown>
107
+ /**
108
+ * Acquire the per-tab auth-mutation gate. Returns false when another auth
109
+ * mutation/reconciliation already holds it, so two consumers sharing this tab
110
+ * (the global mount, an account form, a nav sign-out control) cannot issue
111
+ * concurrent auth requests. The gate is per-tab state on this ledger — never a
112
+ * module global — so it cannot leak across requests, tabs, or store contexts.
113
+ */
114
+ acquireMutationGate(): boolean
115
+ /** Release the per-tab auth-mutation gate (the acquirer only). */
116
+ releaseMutationGate(): void
117
+ /** True while an auth mutation/reconciliation holds the gate. */
118
+ isMutationGateHeld(): boolean
119
+ }
120
+
121
+ interface OwnedEntry {
122
+ authority: OwnershipAuthority
123
+ generation: number
124
+ value: unknown
125
+ }
126
+
127
+ /** Create one per-tab ownership ledger. */
128
+ export function createProjectionOwnership(): ProjectionOwnership {
129
+ const owned = new Map<string, OwnedEntry>()
130
+ let generation = 0
131
+ // Per-tab auth-mutation gate: one in-flight auth request at a time across
132
+ // every consumer that shares this ledger (the global mount, the account forms,
133
+ // a future nav sign-out). Deliberately NOT a module global — a new ledger per
134
+ // tab/request keeps tabs and store contexts isolated.
135
+ let mutationGateHeld = false
136
+
137
+ return {
138
+ generation: () => generation,
139
+ seed(projection) {
140
+ if (!projection) return
141
+ for (const key of CLIENT_OWNED_KEYS) {
142
+ if (owned.has(key)) continue
143
+ if (Object.prototype.hasOwnProperty.call(projection, key)) {
144
+ owned.set(key, { authority: 'seed', generation: 0, value: projection[key] })
145
+ }
146
+ }
147
+ },
148
+ claim(keys, values) {
149
+ const missing = keys.filter((key) => !Object.prototype.hasOwnProperty.call(values, key))
150
+ if (missing.length > 0) {
151
+ throw new Error(
152
+ `ProjectionOwnership.claim: missing value(s) for owned key(s): ${missing.join(', ')}`,
153
+ )
154
+ }
155
+ generation += 1
156
+ const token: OwnershipToken = { generation, keys: [...keys] }
157
+ for (const key of keys) owned.set(key, { authority: 'client', generation, value: values[key] })
158
+ return token
159
+ },
160
+ release(token) {
161
+ for (const key of token.keys) {
162
+ const entry = owned.get(key)
163
+ if (entry && entry.authority !== 'server' && entry.generation === token.generation) {
164
+ owned.set(key, { authority: 'server', generation: token.generation, value: undefined })
165
+ }
166
+ }
167
+ },
168
+ currentToken(keys) {
169
+ // Assumes a slice's keys share one generation: `claimAccount` always passes
170
+ // all ACCOUNT_OWNED_KEYS and `page.tsx` seeds the whole account slice or
171
+ // none. A key absent from the first projection yields null (no-op release).
172
+ let generationForKeys = -1
173
+ for (const key of keys) {
174
+ const entry = owned.get(key)
175
+ if (!entry || entry.authority === 'server') return null
176
+ generationForKeys = Math.max(generationForKeys, entry.generation)
177
+ }
178
+ return generationForKeys < 0 ? null : { generation: generationForKeys, keys: [...keys] }
179
+ },
180
+ isCurrent(token) {
181
+ return token.keys.every((key) => {
182
+ const entry = owned.get(key)
183
+ return entry?.authority === 'client' && entry.generation === token.generation
184
+ })
185
+ },
186
+ isOwned(key) {
187
+ const entry = owned.get(key)
188
+ return entry !== undefined && entry.authority !== 'server'
189
+ },
190
+ overlay() {
191
+ const result: Record<string, unknown> = {}
192
+ for (const [key, entry] of owned) {
193
+ if (entry.authority !== 'server') result[key] = entry.value
194
+ }
195
+ return result
196
+ },
197
+ acquireMutationGate() {
198
+ if (mutationGateHeld) return false
199
+ mutationGateHeld = true
200
+ return true
201
+ },
202
+ releaseMutationGate() {
203
+ mutationGateHeld = false
204
+ },
205
+ isMutationGateHeld() {
206
+ return mutationGateHeld
207
+ },
208
+ }
209
+ }
210
+
211
+ /**
212
+ * Merge the client-owned overlay over a server projection. Server-owned keys are
213
+ * always taken from the server, so a protected cart/account slice never freezes
214
+ * the route/catalog data. When nothing is owned the original projection is
215
+ * returned by reference.
216
+ */
217
+ export function arbitrateProjection(
218
+ ownership: ProjectionOwnership,
219
+ serverProjection: Record<string, unknown> | undefined,
220
+ ): Record<string, unknown> {
221
+ const base = serverProjection ?? {}
222
+ const overlay = ownership.overlay()
223
+ if (Object.keys(overlay).length === 0) return base
224
+ return { ...base, ...overlay }
225
+ }
226
+
227
+ /** A projection stabilized by serialized content, so an equivalent refresh is a no-op. */
228
+ export interface StabilizedProjection {
229
+ readonly key: string
230
+ readonly value: Record<string, unknown>
231
+ }
232
+
233
+ /**
234
+ * Keep the previous stabilized projection while the serialized content is
235
+ * unchanged, so `StateProvider` does not re-apply identical server values (which
236
+ * would reset client-owned state). A genuinely changed projection yields a new
237
+ * value. This is the reference-stability the renderer relies on.
238
+ */
239
+ export function stabilizeProjection(
240
+ previous: StabilizedProjection | null,
241
+ projection: Record<string, unknown> | undefined,
242
+ ): StabilizedProjection {
243
+ const value = projection ?? {}
244
+ const key = JSON.stringify(value)
245
+ if (previous && previous.key === key) return previous
246
+ return { key, value }
247
+ }