create-kywi-app 0.12.0 → 0.13.0

package/assets/agent-patterns.md

@@ -356,7 +356,7 @@ authored elsewhere in the admin).
 
 | `name` | Purpose |
 |---|---|
-| `variantContainer` | Module-level arms revealed client-side per audience — read §8 first |
+| ~~`variantContainer`~~ | **Retired in 0.13.0** — the raw-HTML module. Use the `moduleVariantContainer` NODE (§8) or `personalize_module`. Existing placements still render |
 | `personalizationBadge` | Optional inline status pill that opens the global transparency panel — not needed on ordinary pages (§8) |
 | `socialShare` | Share links for a URL/title across networks |
 | `map` | Embedded map at a lat/lng or address |
@@ -517,47 +517,62 @@ If no, skip it — the machinery is there when they grow into it.
 
 ### Variant containers: pick the right shape
 
-Two different things are called `variantContainer`, and they are not
-interchangeable.
-
-- **Section-level** — a *region* node, sibling of sections (`defaultSections` +
-  `variants[].sections`). Resolved **on the server** from the visitor's audience
-  or experiment arm, so the first paint is already correct: no flash, and the
-  page is complete with JavaScript off. This is the default for anything the
-  server can know — rule-based audiences (UTM, referrer, the `kywi_audience`
-  pin) and A/B experiments. Since 0.6.3 it also renders in the layout editor as
-  a badged block with a **variant switcher** (internal editor code —
-  `activeArms`, the `VariantArm` type, `data-arm-id` — still says "arm"; the
-  persisted layout field is `variants`), each variant editable with the
-  ordinary section/column/module tools, so server-resolution no longer costs
-  the owner their editing surface. Since kywi-cms#119, the owner doesn't need
-  an agent to hand-author this shape at all: the section chrome — in the
-  admin layout editor and in the in-place front-of-site overlay alike —
-  offers **Personalize this section** / **A/B test** actions that wrap an
-  ordinary section into a section-level variant container on the spot,
-  seeding the default variant from the section's current content and
-  opening straight into its config (audience/experiment picker included).
-  An agent only needs to reach for `update_layout` when scripting bulk
-  changes or building a container the UI can't reach.
-- **Module-level** — the `variantContainer` *module*, placed in a column; its
-  variants are HTML strings (`defaultContent`, `variants: [{audienceId, label,
-  content}]`). Every variant ships in the HTML (default visible, the rest
-  `display:none`) and the browser runtime reveals the matching one. Use it
-  **only for signals the server cannot read at first paint** — in practice, a
-  self-ID answer held in `localStorage`.
+Three different things have been called `variantContainer`, and they are not
+interchangeable. Two of them are current.
+
+- **Section-level `variantContainer`** — a *region* node, sibling of sections
+  (`defaultSections` + `variants[].sections`). Resolved **on the server** from
+  the visitor's audience or experiment arm, so the first paint is already
+  correct: no flash, and the page is complete with JavaScript off. Reach for it
+  when a whole band varies. Since kywi-cms#119 the owner does not need an agent
+  to author it: the section chrome — in the admin layout editor and the
+  front-of-site overlay alike — offers **Personalize** / **A/B test** actions
+  that wrap the section on the spot, seeding the default variant from its
+  current content and opening straight into its config.
+- **Module-level `moduleVariantContainer`** (kywi-cms#161) — a *column* node,
+  sibling of modules (`defaultModule` + `variants[].module`, exactly one
+  module per arm; arm module types may differ, so an image arm can face a
+  text arm). Also resolved **entirely on the server** — same no-flash,
+  JS-off-complete guarantee. Reach for it when ONE element varies inside a
+  section that otherwise stays put: a headline, a CTA, a pricing card. The
+  owner reaches it from the module's own hover chrome or its props rail (the
+  same two actions), and an agent reaches it with **`personalize_module`**
+  (kywi-cms#162), which does the read-modify-write wrap and hands back the
+  container and arm ids. It always seeds one variant arm — a detached copy of
+  the module's current content — whether or not `audienceId` is passed: pass
+  it to bind the arm immediately, or omit it and the arm starts unbound
+  (`''`, serving nobody) until something binds it later.
+- **The legacy `variantContainer` MODULE** — retired in 0.13.0 (kywi-cms#163).
+  Its arms were raw HTML strings revealed client-side by `@kywi-software/js`.
+  It is gone from the palette and from `list_module_types`, and
+  `personalize_module` is what you want instead. **Existing placements keep
+  rendering and stay editable** — nothing was deleted and no migration is
+  forced — so a page that already has one is not broken, it is simply not the
+  shape to add more of.
+
+**Neither container ever nests.** Not one inside the other, not one inside
+itself. A module already sitting in a personalized section's arm cannot be
+promoted — the editor withholds the action, `personalize_module` returns a
+structured error saying why, and `update_layout` rejects the shape outright.
+
+**`ab_test` mode needs its own `experimentId`, and it must be FRESH.** Both
+container kinds refuse to validate without one, and both the editors and
+`personalize_module` mint a new id per container. Copying an experiment id
+between pages silently enrols a second page's container in the first page's run.
 
 Four traps, each of which fails silently:
 
-1. **Use the layout module, not the React component.** `VariantContainer.tsx`
-   (`core/src/components/personalization/`) has a loading branch that renders
-   the skeleton and nothing else — a JS-off visitor gets an empty container —
-   and its `ab_test` path draws a fresh `Math.random()` per render, so the same
-   visitor sees a different arm on every refresh. The layout module
-   (`VariantContainerModule`) always renders the default arm.
-2. **Leave `skeleton` off.** With `skeleton: true` the container ships
-   `aria-busy="true"` and only the client runtime clears it — a JS-off visitor
-   sits in a loading state forever.
-3. **An audience match beats the experiment.** `resolveVariant` returns the
+1. **Don't reach for the retired `variantContainer` module, or the React
+   component.** `VariantContainer.tsx` (`core/src/components/personalization/`)
+   has a loading branch that renders the skeleton and nothing else — a JS-off
+   visitor gets an empty container — and its `ab_test` path draws a fresh
+   `Math.random()` per render, so the same visitor sees a different arm on
+   every refresh. The layout module (`VariantContainerModule`) always renders
+   the default arm.
+2. (Legacy module only.) **Leave `skeleton` off.** With `skeleton: true` the
+   container ships `aria-busy="true"` and only the client runtime clears it —
+   a JS-off visitor sits in a loading state forever.
+3. **An audience match beats the experiment.** `selectVariantArm` returns the
    audience arm first, so a visitor who matches an audience never enters the
    split. Don't run an experiment and an audience variant on the same container.
 4. **The client runtime needs `/kywi.js`.** Self-ID, behavioral re-evaluation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Scaffold a new Kywi CMS project — npx create-kywi-app my-site",
   "type": "module",
   "homepage": "https://github.com/Kywi-Software/kywi-cms#readme",