@akinon/pz-theme 2.0.91-beta.0 → 2.0.91

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.91-beta.0
+## 2.0.91
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.91-beta.0
-  - @akinon/theme-contract@2.0.91-beta.0
+- 340440f3: ZERO-4983: Document that a region seed is a one-way door
+  - @akinon/next@2.0.91
+  - @akinon/theme-contract@2.0.91
 
 ## 2.0.90
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.91-beta.0",
+  "version": "2.0.91",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.91-beta.0",
+    "@akinon/next": "2.0.91",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.91-beta.0",
+    "@akinon/theme-contract": "2.0.91",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.91-beta.0",
+    "@akinon/next": "2.0.91",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/custom/README-sections.md

@@ -95,8 +95,30 @@ reorder it or insert beside it — your JSX owns the layout, and no drag in the
 layer tree changes where it renders.
 
 `properties`, `styles` and `value` on a region are a **seed**: what it looks
-like the moment the section is added. They are written once, at insert, and
-nothing re-applies them, so a merchant's edit is never quietly reverted.
+like the moment the section is added. They are copied into the merchant's
+composition once, at insert, and nothing re-applies them — not a later load,
+not a publish, not a deploy.
+
+That cuts both ways and only one half of it is usually noticed. A merchant's
+edit is never quietly reverted; a DEVELOPER's later edit is never delivered.
+Change a seeded colour and every store that already placed the section keeps
+the old one, and nothing on either side says so — no load compares a placed
+region against the descriptor it was seeded from, so the build has nothing to
+report and the editor draws no badge. The two disagree in silence.
+
+There IS a way back, but only one a person can take. Selecting the row (or the
+section itself) puts **Reset to code** in the right panel's Danger zone, which
+rewrites that one row from today's descriptor in place — keeping the blocks
+inside it, its id, its scoped custom CSS and its place in the list — after
+showing exactly which settings and styles it will overwrite. It is a merchant's
+deliberate click, never automatic, because the editor cannot tell a value the
+merchant chose from one the code seeded: both live in the same map with no
+marker. So a seed is still a ONE-WAY DOOR as far as shipping goes — a seed
+change reaches nobody you do not tell. Say it in the release note, name the
+stores, and give the merchant those steps.
+[Evolving a section that is already placed](#evolving-a-section-that-is-already-placed)
+is the rest of the rule.
+
 `value` is there for the block types that keep their content there rather than
 in `properties` — an `image` reads `block.value` for its src.
 
@@ -121,6 +143,94 @@ of them.
 | Merchant can reorder | no | yes, inside the slot |
 | Merchant can delete | yes, and it stays deleted (Add back restores it) | the row itself, no |
 
+## Evolving a section that is already placed
+
+A placed section is a composition sitting in someone's store, and your next
+commit reaches only part of it. Some changes arrive on the next deploy with
+nobody doing anything; one costs the merchant a click per placement; some
+arrive nowhere at all. Nothing in the JSX tells the three apart, which is why
+this has to be a habit rather than a check you run.
+
+**The test: if you can imagine changing this value in six months, it must not
+be a seed.** Put it in `ThemeEditable` or `useThemeSetting` on the section's own
+JSX instead. A section is inserted with no stored settings whatsoever — its
+insert template carries the region blocks and the slot nodes and nothing else —
+so a `useThemeSetting` default is read at RENDER, on every render, in every
+store, and changing it changes what every placement the merchant never touched
+shows on the next deploy. The authored JSX inside a `ThemeEditable` is live for
+the same reason. A seed is the one thing in this file that is copied into the
+merchant's data and then left there.
+
+**And the counterweight, because that rule over-applies easily.** A region's
+`styles` and the section root's `styles` have no live substitute and are seeds
+deliberately. A section's parts cannot reach inside a region — part rules carry
+an ownership guard that excludes anything under a descendant `[data-block-id]`
+and every region renders inside one, which is what "Parts must live on YOUR
+markup" says below. And the section root is the wrapper your component renders
+INSIDE, so nothing the component draws can style the box it sits in. Seed both,
+and treat the first paint as the only one you get.
+
+### Identity strings are never renamed
+
+A region name, a slot name, a setting key, the record key in
+`registerCustomSections` and the vendor are all identity: each is matched
+LITERALLY against something already saved in a merchant's composition. A rename
+is therefore not a rename. It is a delete plus an unrelated insert, performed
+silently, on data you cannot see:
+
+| Renamed | What it costs the merchant |
+|---|---|
+| a region name | the seeded block keeps the old name and no `<ThemeRegion>` asks for it any more, so it renders nowhere; the new name was never seeded, so the editor lists it under **Not placed** and **Add back** builds a FRESH block — without the original's styling, id or scoped custom CSS |
+| a slot name | the load pass creates a node for the new name and adopts nothing, so everything the merchant put in the slot stays under the old node, drawn nowhere — and that node cannot be deleted either, because delete refuses any `custom-slot` node whether or not the type still declares it |
+| a setting key | the stored value stays under the old key forever and the new key reads the declared default, so the control resets to code in every store at once |
+| the record key or the vendor | the type string changes, so every composition holding the old one names a type this build does not register: nothing live, a labelled band in the designer |
+
+If a rename is genuinely unavoidable, register the SAME component under both
+keys and wrap the retiring one in its own `defineCustomSection` whose options
+carry `placeholders: []`. It keeps drawing every composition that already names
+it and stops being offered for new ones. It costs one of the sixteen section
+types this build may declare, which is the honest price of the old name.
+
+**Never change a region's `block` type either.** A region resolves by NAME, so
+`<ThemeRegion name="basket" />` goes on rendering whatever type the node was
+born as, and every surface agrees that it is correct. **Reset to code** does not
+help here and deliberately hides itself when the types no longer match: it
+rewrites a node's settings and styles, and re-typing one in place would leave a
+row the editor can never delete again — delete refuses any node that hosts a
+slot, without checking whether the new type still declares one. So the
+merchant's only route to the new type is deleting the region and adding it back,
+which takes the block's own subtree with it.
+
+**Never re-use a setting key you removed.** Nothing in the editor or the
+renderer deletes a stored property key, so the merchant's old value is still
+sitting in the composition and it shadows the new default permanently — the
+setting comes up holding whatever was typed into a control that no longer
+exists.
+
+**Ship a setting `type` change as a NEW key, not an edit.** The panel builds the
+control from today's descriptor and reads the value stored under that key with
+no conversion of any kind, so a `text` that becomes a `select` draws a select
+with nothing matching the string the merchant free-typed, and the storefront is
+handed that same string. Add the new key beside the old one and stop reading
+the old one.
+
+**Name every slot.** A slot declared without one is the slot you can never name
+later: its contents are the section's own direct children rather than the
+children of a node, and the pass that materializes slot nodes adopts nothing.
+Name it the day you write it and there is nothing left to strand.
+
+### What reaches a section already on the page
+
+| Change | Reaches placed instances |
+|---|---|
+| any JSX, CSS or component change | yes, on the next deploy |
+| adding a setting with a default | yes — nothing is stored under the key until the merchant sets it |
+| moving a `<ThemeRegion>` in the JSX | yes — the JSX decides where a region renders; the node's position in `section.blocks` decides nothing |
+| adding a named slot | yes — slot nodes are re-materialized on every theme load, so the row is there the next time the editor opens |
+| changing a slot's `accepts` or `max` | yes — both are read from today's descriptor at the moment a block is written into the slot, so a drag and a paste obey them too |
+| adding a REGION | one click per placement — regions are seeded at insert and back-filled nowhere, so a new one arrives under **Not placed**, indistinguishable from one the merchant deleted, and stays empty on the live site until someone clicks **Add back** |
+| changing a seed — a region's `properties`, `styles` or `value`, or the section's own `styles` | one click per placement, and only if someone knows to make it — nothing is re-applied and nothing announces the change, so the merchant has to open the section, select the row (or the section itself) and use **Reset to code** in the Danger zone. Every placement that nobody visits keeps what it was born with |
+
 ## Commerce data
 
 Two different things want data and only one of them is yours.