create-kywi-app 0.14.0 → 0.15.1

package/assets/agent-patterns.md

@@ -185,16 +185,36 @@ every request — so writing a new definition changes every page that uses it
 immediately, published pages included, with nothing to re-publish. That is the
 whole point, and it is also the thing to be careful with.
 
-**What can be one.** A single module, a whole section (band), or a personalized /
-A-B tested band with its variants intact — the three `type` values are `module`,
-`section` and `variantContainer`. A band's variants travel with it; which arm a
-visitor sees is still decided per request, per placement, so the same personalized
-component can sit on five pages and target correctly on each.
+**What can be one.** A single module, a whole section (band), a personalized /
+A-B tested band with its variants intact, or a personalized / A-B tested **module**
+— the four `type` values are `module`, `section`, `variantContainer` (section
+level) and `moduleVariantContainer` (column level). Variants travel with the
+component in both container kinds; which arm a visitor sees is still decided per
+request, per placement, so the same personalized component can sit on five pages
+and target correctly on each.
+
+**Which container kind?** `variantContainer` is a whole band that varies —
+different sections, different layouts per audience. `moduleVariantContainer` is
+ONE module in a column that varies while everything around it stays put: a hero
+headline that changes for paid traffic, a CTA button that is A/B tested inside an
+otherwise fixed section. Reach for the module-level one when only the content of
+a single block differs; personalizing the whole band to change one headline makes
+every other module in it a copy the owner has to maintain twice.
+
+**Arms are never independently linkable.** A variant arm's module cannot be saved
+as a component of its own, and cannot be pointed at one. An arm is a challenger
+the owner edits freely; wiring it to shared content would mean editing one page's
+variant rewrote every other page's, which is the opposite of what a variant is
+for. Save the whole container instead — that is what the fourth kind is.
 
 **In the editors** (front-of-site overlay or the admin Layout tab): select the
-module, section or band → **Save as component** → name it. The selection is
-replaced in place by a linked instance, marked with an outline and a pill naming
-the component. Place it again from the section picker's *Components* rows.
+module, section, band or personalized module → **Save as component** → name it.
+The selection is replaced in place by a linked instance, marked with an outline
+and a pill naming the component. Place a section or band again from the section
+picker's *Components* rows; place a module or a personalized module by dropping
+the palette's **Component** block into a column and choosing it in the props
+rail — one list, both kinds, because the owner's question there is "which saved
+thing goes here".
 
 **Editing a linked instance ends in a question.** There are no per-prop overrides
 in v1: an instance renders its component exactly. So when you edit one and save,
@@ -224,8 +244,10 @@ per-site authorization applies.
 
 1. `POST /api/v1/components` — `{ name, type, definition, moduleType?, description? }`.
    The `definition` is the node itself: a `section` component stores the whole
-   `LayoutSection`, a `variantContainer` the whole container, a `module` component
-   stores `{ props, style }` and names its `moduleType`.
+   `LayoutSection`, a `variantContainer` the whole section-level container, a
+   `moduleVariantContainer` the whole column-level one (its `defaultModule` and
+   `variants`), and a `module` component stores `{ props, style }` and names its
+   `moduleType`.
 2. **Place it** by writing a layout that carries the link. There is no separate
    "insert" endpoint: `PUT /api/v1/content/:type/:id/layout` with the definition's
    own shape plus `componentId` on the node, giving the placement a fresh `id` of
@@ -247,8 +269,26 @@ per-site authorization applies.
    definition saved from an editor carries no `winnerId` at all; a definition
    POSTed straight over the API can, so read what you are placing. A
    `personalization` container has no binding and needs none.
+
+   **The same rule, word for word, for `moduleVariantContainer`.** It is a
+   placement root exactly as its section-level sibling is: the placement's
+   `experimentId` / `winnerId` win over the definition's, so an `ab_test`
+   placement you write over the API must carry a fresh `experimentId` and no
+   `winnerId`. The node goes in a COLUMN (`section.columns[].nodes[]`), not in a
+   region, and it carries its own `id` plus `componentId`, with the definition's
+   `defaultModule` / `variants` copied inline as the fallback copy.
+
+   **Do not bury an `ab_test` module container inside a `section` component.**
+   There it is not a placement root, nothing re-binds it per placement, and every
+   page placing that section reports into one shared run with one `winnerId`
+   deciding them all. Both editors refuse it and so does `POST /components`. A
+   `personalization` module container inside a section component is fine —
+   audiences are content and travel with the component.
 3. `GET /api/v1/components/:id/usage` — where it is placed (`instances`, `pages`,
-   the page ids and node ids, and trashed pages counted separately). This is the
+   the page ids and node ids, with trashed pages and **saved layouts** each
+   counted separately: `trashedInstances`/`trashedPages` and
+   `blueprints`/`blueprintInstances`/`blueprintItems`). `instances`/`pages` mean
+   live pages only, so the three partitions never double-count. This is the
    blast radius; read it *before* changing a definition.
 4. `PUT /api/v1/components/:id` — a body with `definition` **is the propagation
    write**: every linked instance renders the new definition on its next request.
@@ -257,15 +297,20 @@ per-site authorization applies.
 5. `POST /api/v1/components/:id/detach-all` — materialize the definition into every
    page that links it and drop the links; each page keeps rendering identically.
 6. `DELETE /api/v1/components/:id` — refuses (409) while instances exist; add
-   `?detachAll=1` to detach-then-delete. `GET /api/v1/components?withUsage=1` folds
+   `?detachAll=1` to detach-then-delete. "Instances" includes placements held by
+   trashed pages **and by saved layouts** (kywi-cms#156), so a component nothing
+   live uses can still refuse to delete — check `blueprints` in the usage payload
+   before assuming a one-step delete. `GET /api/v1/components?withUsage=1` folds
    the counts into a list, in one read.
 
-**Two refusals to design around.** A component definition may not link to another
+**Three refusals to design around.** A component definition may not link to another
 component (one level only, deliberately: a nested link is invisible to usage counts
 and the delete gate, so the editors *materialize* an inner component when you save
 a section that contains one — the inner instance stops following its own source, and
 the dialog says so). And a stored layout that a live layout could not hold is
 rejected at the door, because detaching would copy it into every page that links it.
+And a `section` or `variantContainer` definition may not contain an **A/B tested**
+module container, for the shared-run reason above.
 
 **Component writes bypass approvals in v1.** They are not routed through
 changesets or the review workflow — a `PUT` with a definition is live on publish
@@ -286,6 +331,32 @@ reads as a styled document rather than a site. Sections are bands (each owns its
 background and padding), `columns` splits them, and the object modules below do
 the rest.
 
+### Module props: omitted takes the default, `''` stays blank
+
+Every module declares its props, and most declare a `defaultValue` — the copy or
+setting the module ships with so it renders as *something* the moment it is
+placed. That default is applied on the **write path**, so it applies however the
+module got there: dragged in by the editor, added with MCP `add_module`, or
+written straight into a layout document.
+
+The rule has two halves, and the second is the one that matters:
+
+- **A prop you OMIT takes the module's declared default.** You do not need to
+  restate a module's own defaults to make it look right, and a custom module
+  does not need a second copy of them baked into its component.
+- **A prop you write as `''` stays `''`.** An empty string is an instruction —
+  "blank on purpose" — not an absent value. Same for `null`, `0` and `false`:
+  presence of the key is the whole signal.
+
+So `add_module` with no `props` gives you a module that renders; `add_module`
+with `props: { eyebrow: '' }` gives you one with a deliberately empty eyebrow
+and every other prop defaulted. To find out what a module's defaults actually
+are, call `list_module_types` — each prop reports its `default`.
+
+Defaults are seeded onto modules a write **adds**, never re-applied to modules
+already on the page. Saving a page for an unrelated reason will not put back a
+prop that someone deliberately left off an existing module.
+
 ### The built-in palette
 
 `name` is the exact `type` value in a layout node and in MCP `add_module`. A
@@ -360,11 +431,66 @@ authored elsewhere in the admin).
 | `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 |
-| `cookieConsent` | Consent banner with message + privacy-policy link |
+| `cookieConsent` | Consent banner with message + privacy-policy link. Accept All / Reject All / Customize write the `kywi_consent` cookie, and the engine's optional cookie writes are gated on it (see below) |
 | `component` | Places a saved reusable component by slug (§4) |
 | `form` | Renders a form built in the Forms admin (§6) |
 | `formEmbed` | Embeds a form by slug — lighter-weight placement of the same |
 
+#### Cookie consent is enforced, not decorative
+
+`cookieConsent` is wired to the engine. Its buttons write `kywi_consent`, and
+`@kywi-software/core`'s `audiences/consent.ts` holds the one map from cookie name
+to category that every optional write is gated on:
+
+| Cookie | Category | Gated? |
+|---|---|---|
+| `kywi_visitor`, `kywi_signals`, `kywi_utm`, `kywi_audience`, `kywi_known` | `personalization` | yes |
+| `kywi_consent`, `kywi_optout`, `kywi_preview_init` | `essential` | no — necessary cookies are never gated |
+
+A gated cookie is neither **written** nor **read** without consent: a visitor who
+accepted last month and rejects today has those cookies deleted, and any that
+survive (`kywi_signals` is HttpOnly) are ignored on the way in. Rejecting is a
+revocation, not just a pause.
+
+One exemption: an audience the visitor picks **by hand** in the transparency
+panel is stored as an `essential` preference, on the same argument as
+`kywi_optout` — a control they operated deliberately has to be honoured, or the
+panel is lying about what its buttons do. Only the runtime's automatic
+"remember what I resolved" write is gated. The cookie records which it was
+(`switcher:<id>` vs a bare id), so the read side and the revocation sweep apply
+the same rule: rejecting personalization deletes an automatic pin but keeps one
+the visitor chose.
+
+**Undecided means not consented.** Until a visitor answers the banner, none of
+the personalization cookies are written: pages still render, audiences still
+resolve for the request in hand, experiments still return a variant — nothing is
+persisted, so the visitor keeps seeing default content instead of being tracked.
+A site that wants personalization to persist must place this module (or write
+`kywi_consent` some other way). Adding a new cookie without classifying it in
+that map fails closed, and a core test catches the omission.
+
+**The escape hatch.** `theme.personalization.requireConsent` in `kywi.config.ts`
+defaults to `true` — the behaviour above. Set it to `false` only when this site
+collects consent with EXTERNAL tooling (a third-party CMP) that suppresses
+cookies its own way; the gate then treats every category as allowed and the site
+takes responsibility for compliance. Because Next.js edge middleware cannot read
+`kywi.config.ts`, mirror the same value as `KYWI_REQUIRE_CONSENT=false` in the
+environment. **Set both or neither** — `createKywiApiHandler` throws at startup
+when they disagree, so a mismatch fails the deploy rather than silently leaving
+the middleware and the API at odds about whether a visitor may be tracked. On a
+site with no other consent mechanism, `false` is simply the non-compliant
+setting.
+
+The banner ships **hidden** (`kywi-consent-pending` on the wrapper) and reveals
+itself after mount only for a visitor with no decision on file — a theme must not
+force it visible, or every returning visitor gets a flash of a consent ask they
+already answered.
+
+When consent is required and no page places the module, the API logs a one-time
+warning on its first request: nobody can grant consent, so every personalization
+cookie stays suppressed and audiences, A/B bucketing and UTM attribution serve
+default content to everyone.
+
 ### Which do I reach for? (in order)
 
 1. **A built-in already does it** → use it. Read the tables before inventing
@@ -409,9 +535,12 @@ module's *first* prop inline-editable on the page when its type is `text`,
 directly on the live page, and `props: { variant, headline, … }` cannot.
 
 Also: create **saved layouts** (Layouts admin) as page templates — "Landing
-page", "Case study" — so new pages start from a consistent skeleton. Hand-written
-JSX stays fine for genuinely fixed chrome (a bespoke 404, legal boilerplate) —
-but if marketing will ever want to swap a headline, it's a layout page.
+page", "Case study" — so new pages start from a consistent skeleton. A saved
+layout may link reusable components like any page: the link is indexed, counted
+in the component's usage under "saved layouts", and carried into every page
+stamped out of that layout. Hand-written JSX stays fine for genuinely fixed
+chrome (a bespoke 404, legal boilerplate) — but if marketing will ever want to
+swap a headline, it's a layout page.
 
 ### Navigation: menus vs. the site tree
 
@@ -550,6 +679,27 @@ interchangeable. Two of them are current.
   forced — so a page that already has one is not broken, it is simply not the
   shape to add more of.
 
+**Two signals make campaign handoffs and site-owned self-ID cheap
+(kywi-cms#196/#200).** `query.<param>` matches the query string of the request
+being served — `/developers?from=marketer` is the rule `query.from equals
+marketer`, matched on that very request with no reload — and `session.entryPage`
+is the session's first page (path + query), so the rule survives the visitor
+navigating on. For an explicit control instead of the built-in self-ID widget,
+`Kywi.setSelfId({ role: 'marketer' })` records the answer, resolves and PINS the
+audience server-side and reloads; the pin is the part that matters, because the
+losing arms are pruned on the server (see #167 below) and only a fresh server
+render can show them. A plain form post to `/api/v1/kywi/self-id` with a
+`returnTo` field does the same with JavaScript off. Two rules that decide
+whether it works at all: **the endpoint stores only self-ID fields the site
+declared** (Audiences → Self-ID Fields), so an undeclared key is dropped; and
+**an audience with no rules never matches from answers**, because resolution
+runs the same rules everything else does. For a chooser whose options ARE
+audiences, flag them **public**, read the options from
+`GET /api/v1/kywi/audiences` (which publishes only `{ id, name, label }`), and
+pass the id straight back — `Kywi.setSelfId({}, { audienceId })`, or a hidden
+`audienceId` input on the form — which pins the visitor's pick directly, rules
+or no rules.
+
 **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
@@ -582,6 +732,39 @@ Four traps, each of which fails silently:
 Standing rule: **the default arm must be complete on its own.** It is what
 search engines, answer engines, and every opted-out visitor receive.
 
+**What actually reaches the visitor (kywi-cms#167).** A published page ships
+only the arm that visitor is served — the other arms of every section- and
+module-level container are stripped on the server, before the document crosses
+into the client renderer (`pruneLayoutToServedArms`, run last in the public
+render path). So view-source shows one arm, not all of them, and the same is
+true of page variants (`applyPageVariant` has always dropped those). Two things
+follow. First, arm copy is not shared with the people it is not for, so an
+unlaunched offer or a segment-specific price is not sitting in the HTML of
+everyone else's page. Second, **the audience RULES still are** — the client
+runtime is handed the active audiences so it can re-evaluate on client signals,
+so how a visitor is classified remains public even though the content each class
+gets is not. Author rules accordingly: they are readable.
+
+**One exception, and it is a live one: the retired `variantContainer` MODULE.**
+Pruning covers the two container NODES. It cannot cover the legacy module,
+because that module's arms are not arms of a container at all — they are HTML
+strings in its own props, and it renders every one of them into the DOM by
+design, hiding the losing ones with `display: none` for the client runtime to
+reveal. So a page that still carries one keeps publishing all of its arms in
+plain markup, where `view-source` and "inspect element" both find them
+immediately. Nothing about #167 changed that, and no amount of server-side
+resolution can: the shape is client-swap by construction. If a page you are
+working on has one, converting it is the fix — `kywi upgrade:variant-containers`
+(landing separately, for kywi-cms#172) rewrites existing placements into the
+`moduleVariantContainer` node, which is server-resolved and therefore pruned.
+Until it is converted, treat that module's arms as public, whatever the audience
+binding says.
+
+The editor is the deliberate exception — the front-edit overlay and the admin
+layout editor are handed the STORED document, every arm intact, because that is
+what is being edited. If you are writing a host page, keep the two apart: prune
+what you pass to `<KywiLayout>`, and pass the editor the layout you loaded.
+
 ### Transparency: automatic, not something you place
 
 Once the client runtime is loaded, every personalized (or opted-out-with-a-

package/assets/kywi-personalization-skill.md

@@ -34,6 +34,36 @@ Admin → Audiences: define the rules, or configure the self-ID widget and its
 fields. Use the audience test tool to confirm the rules match the intended
 visitors before wiring anything to it.
 
+### 3b. Two shortcuts worth knowing before you build rules
+
+- **A campaign link is a one-line rule.** `query.<param>` matches the query
+  string of the request being served, so `/developers?from=marketer` is
+  `query.from equals marketer` — and it matches on that very request, no
+  reload. `session.entryPage` is the first page (path + query) of the
+  visitor's session, so a rule on it keeps matching after they navigate on.
+  Neither needs a `utm_*` param invented for the purpose.
+- **A site-owned "What brings you here?" control** does not need the built-in
+  hello-bar widget. Call `Kywi.setSelfId({ role: 'marketer' })`: it records the
+  answer, resolves the audience server-side, pins it and reloads, so the server
+  re-renders with that audience's arms. `Kywi.clearSelfId()` undoes it. With
+  JavaScript off, a plain `<form method="post" action="/api/v1/kywi/self-id">`
+  carrying a `returnTo` field does the same thing and 303s back to the page.
+
+  Two things about it that are easy to get wrong:
+
+  - **Declare the self-ID field first** (Admin → Audiences → Self-ID Fields).
+    The endpoint stores only the fields the site declared, so submitting
+    `{ role }` to a site with no `role` field stores nothing and matches
+    nothing.
+  - **An audience with no rules never matches from answers.** Resolution runs
+    the same rules the rest of the engine does; an audience with zero condition
+    groups matches nobody. If you want a chooser whose options ARE audiences,
+    flag them **public** in the audience editor, read the options from
+    `GET /api/v1/kywi/audiences` (`{ id, name, label }`, never the rules), and
+    pass the id back: `Kywi.setSelfId({}, { audienceId })`, or an
+    `<input type="hidden" name="audienceId">` on the no-JS form. That pins the
+    audience the visitor picked directly, rules or no rules.
+
 ### 4a. Page-variant path
 
 In the layout editor on the target page: **+ Page Variant** → select the

package/lib/templates.mjs

@@ -44,6 +44,22 @@ const CORE_RANGE = (v) => `^${v}`
 
 /** @param {Answers} a */
 function packageJson(a) {
+  // Coupled mode's front-of-site editor (kywi-front-edit.tsx) needs the admin
+  // design system's stylesheet available at a plain, fetchable URL
+  // (/kywi-admin.css) — it is injected via a runtime <link> tag rather than a
+  // JS import (kywi-cms#130 follow-up: an import, even a dynamic one, still
+  // ships the stylesheet on every public route — see ensureAdminStylesheet in
+  // kywi-front-edit.tsx). Unlike public/kywi.js (opt-in, manually placed when
+  // personalization.clientRuntime is enabled — see README), this is a CORE
+  // feature every coupled-mode app has, so the sync is automatic.
+  const syncScripts =
+    a.mode === 'coupled'
+      ? {
+          'sync:kywi-admin-css': 'node scripts/sync-kywi-admin-css.mjs',
+          predev: 'npm run sync:kywi-admin-css',
+          prebuild: 'npm run sync:kywi-admin-css',
+        }
+      : {}
   return JSON.stringify(
     {
       name: a.projectName,
@@ -54,6 +70,7 @@ function packageJson(a) {
         dev: 'next dev',
         build: 'next build',
         start: 'next start',
+        ...syncScripts,
         // Plain `kywi migrate` (not --push): the CLI bootstraps a migration
         // journal via `drizzle-kit generate` on first run and grows it on
         // every schema-bearing release after (kywi-cms#141) — a fresh
@@ -101,6 +118,63 @@ function packageJson(a) {
   ) + '\n'
 }
 
+// ── scripts/sync-kywi-admin-css.mjs ─────────────────────────────────────────
+
+/**
+ * Syncs the admin design system's stylesheet (and a cache-busting version
+ * marker) into public/, so the front-edit overlay's `ensureAdminStylesheet`
+ * can load it via a plain `<link>` tag (kywi-cms#130) instead of a JS/CSS
+ * module import — which Next's App Router CSS collection would otherwise
+ * bundle into every public route regardless of dynamic() boundaries.
+ *
+ * Runs on every predev/prebuild (package.json's `sync:kywi-admin-css`) — NOT
+ * committed (see the generated .gitignore) — so a core upgrade always serves
+ * fresh admin CSS under a cache-busted URL (`?v=<core version>`) rather than
+ * a stale one a CDN/browser cached under the unversioned `/kywi-admin.css`
+ * path.
+ */
+function syncKywiAdminCssScript() {
+  return `#!/usr/bin/env node
+import { copyFileSync, writeFileSync, existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+try {
+  const cssPath = require.resolve('@kywi-software/core/admin/styles.css')
+
+  // Find @kywi-software/core's OWN package.json (for its version) by walking
+  // up from the resolved stylesheet path: core's package.json "exports" map
+  // does not list "./package.json", so require.resolve() can't reach it
+  // directly.
+  let dir = dirname(cssPath)
+  let version = ''
+  for (;;) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      if (pkg.name === '@kywi-software/core') {
+        version = pkg.version
+        break
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break // reached the filesystem root without finding it
+    dir = parent
+  }
+
+  copyFileSync(cssPath, 'public/kywi-admin.css')
+  // A plain-text sibling asset, not a JS/JSON import — ensureAdminStylesheet
+  // fetches it at runtime, so this never touches the CSS/JS module graph.
+  writeFileSync('public/kywi-admin.css.version', version)
+  console.log(\`synced public/kywi-admin.css (v\${version || 'unknown'})\`)
+} catch (e) {
+  console.warn('kywi-admin.css sync skipped:', e.message)
+}
+`
+}
+
 // ── kywi.config.ts ────────────────────────────────────────────────────────────
 
 /** @param {Answers} a */
@@ -258,25 +332,38 @@ function tsconfig() {
 /**
  * Ambient declaration for stylesheet imports.
  *
- * WHY THIS FILE EXISTS (found by the scaffold compile gate, kywi-cms#147 T6).
- * `app/(site)/kywi-front-edit.tsx` pulls the admin design system in LAZILY —
- * `await import('@kywi-software/core/admin/styles.css')` inside `next/dynamic`'s
- * factory — so the ~4.7k-line stylesheet never enters the public browse bundle.
- * TypeScript treats a *dynamic* import of a non-code file as an ordinary module
- * import and reports TS2307 for it, unlike a top-level `import 'x.css'` statement,
- * which it lets through as a resource import. Next type-checks during `next build`,
- * so without this declaration a freshly scaffolded project failed its own build on
- * generated code — which nothing caught, because the reference app imports that
- * stylesheet in statement form and the scaffold's own output had never been
- * type-checked at all.
+ * WHY THIS FILE EXISTS (found by the scaffold compile gate, kywi-cms#147 T6;
+ * history below). `app/(site)/kywi-front-edit.tsx` originally pulled the
+ * admin design system in via `await import('@kywi-software/core/admin/
+ * styles.css')` inside `next/dynamic`'s factory. TypeScript treats a
+ * *dynamic* import of a non-code file as an ordinary module import and
+ * reports TS2307 for it, unlike a top-level `import 'x.css'` statement, which
+ * it lets through as a resource import. Next type-checks during `next
+ * build`, so without this declaration a freshly scaffolded project failed
+ * its own build on generated code — which nothing caught, because the
+ * reference app imported that stylesheet in statement form and the
+ * scaffold's own output had never been type-checked at all.
+ *
+ * kywi-cms#130 follow-up: that dynamic import turned out to ship the
+ * stylesheet to every public route regardless of the `next/dynamic`
+ * wrapping (Next's App Router CSS collection bundles every css import it can
+ * see in the reachable module graph, dynamic or not) — see
+ * `ensureAdminStylesheet` in `frontEditOverlay()`, which replaced it with a
+ * runtime `<link>` tag. This ambient declaration is no longer load-bearing
+ * for that one case, but it costs nothing to keep as a general-purpose `*.css`
+ * declaration for any future dynamic stylesheet import.
  *
  * `*.module.css` is deliberately NOT declared here: Next's own types declare it
  * with a real `classes` record, and the more specific pattern wins.
  */
 function cssTypes() {
-  return `// Stylesheet imports (including the lazy \`await import('…/styles.css')\` in
-// app/(site)/kywi-front-edit.tsx, which TypeScript checks like any other module).
-// CSS Modules are typed by Next itself — the more specific pattern wins.
+  return `// Stylesheet imports. CSS Modules are typed by Next itself — the more
+// specific pattern wins. (History: originally required for a dynamic
+// \`await import('…/styles.css')\` in app/(site)/kywi-front-edit.tsx, which
+// TypeScript checks like any other module — see cssTypes' doc comment in
+// templates.mjs. That import was replaced by a runtime \`<link>\` tag,
+// kywi-cms#130 follow-up, so nothing in this generated app currently needs
+// this declaration — kept for any future dynamic stylesheet import.)
 declare module '*.css'
 `
 }
@@ -359,6 +446,12 @@ function gitignore() {
 .env
 .env.local
 *.log
+
+# Regenerated on every predev/prebuild (scripts/sync-kywi-admin-css.mjs) from
+# the installed @kywi-software/core package — kywi-cms#130 follow-up. Coupled
+# mode only, but harmless to list unconditionally.
+public/kywi-admin.css
+public/kywi-admin.css.version
 `
 }
 
@@ -459,6 +552,7 @@ import {
   listSelfIdFields,
   COOKIE_NAMES,
 } from '@kywi-software/core/audiences'
+import { cookieAllowedByHeader } from '@kywi-software/core/audiences/consent'
 import type {
   Audience,
   VisitorSignals,
@@ -670,6 +764,12 @@ export interface PublicPersonalization {
   audienceId: string | null
   /** Stable visitor id (middleware cookie/header); keys A/B assignment. */
   visitorId: string
+  /**
+   * True when \`visitorId\` is a durable identity this visitor consented to
+   * (kywi-cms#91). False means it was minted for this request alone — nothing
+   * may be written against it, including an A/B exposure.
+   */
+  tracked: boolean
   /** Active audiences evaluated — handed to the client runtime for re-eval. */
   audiences: Audience[]
   /** Server-resolved signals — handed to the client runtime as serverSignals. */
@@ -696,8 +796,26 @@ export async function resolvePersonalization(
   layout: LayoutDocument | null | undefined,
 ): Promise<PublicPersonalization> {
   const [h, cookieStore] = await Promise.all([headers(), cookies()])
+  // One resolution of \`theme.personalization.requireConsent\` for the whole
+  // request, handed to every gate below — the visitor-id read AND the audience
+  // engine's own collectors. They read the same cookies; disagreeing about
+  // whether consent is required would personalize half a page.
+  const gate = { requireConsent: requireConsentEnabled() }
+  // \`kywi_visitor\` is a \`personalization\` cookie, so without consent it is
+  // neither written nor read (kywi-cms#91) — the middleware hands this request a
+  // THROWAWAY id instead, freshly minted and different on the next request.
+  // \`tracked\` carries that fact to everything downstream that would otherwise
+  // write the id to the database.
+  const tracked = cookieAllowedByHeader(COOKIE_NAMES.VISITOR, h.get('cookie'), gate)
+  // The stored cookie is read THROUGH that gate too, not just written through
+  // it: a visitor who accepted last month and has since rejected still carries
+  // one, and honouring it would re-identify them under the identity they
+  // revoked. The header bridge is unaffected — the middleware already applied
+  // the same rule when it minted the id this request carries.
   const visitorId =
-    h.get('x-kywi-visitor') ?? cookieStore.get(COOKIE_NAMES.VISITOR)?.value ?? 'vis-anon'
+    h.get('x-kywi-visitor') ??
+    (tracked ? cookieStore.get(COOKIE_NAMES.VISITOR)?.value : undefined) ??
+    'vis-anon'
   const host = h.get('host') ?? 'localhost'
   const url = h.get('x-kywi-url') ?? \`http://\${host}/\`
 
@@ -706,17 +824,28 @@ export async function resolvePersonalization(
   const request = new Request(url, { headers: reqHeaders })
 
   const { db, siteId } = runtime
-  const { result, audiences } = await evaluateActiveAudiences(db, siteId, request)
+  // \`gate\` reaches the engine's server collectors, so a site whose consent is
+  // owned by an external CMP (\`requireConsent: false\`) has its stored UTM /
+  // visitor / known / pinned-audience cookies read here too, not just by the
+  // middleware and the runtime routes.
+  const { result, audiences } = await evaluateActiveAudiences(db, siteId, request, gate)
 
   const previewId = cookieStore.get(COOKIE_NAMES.PREVIEW_INIT)?.value || null
   const audienceId = isActiveAudience(previewId, audiences) ? previewId : result.winningAudienceId
 
-  const experimentAssignments = await resolveExperimentAssignments(runtime, layout, audienceId, visitorId)
+  const experimentAssignments = await resolveExperimentAssignments(
+    runtime,
+    layout,
+    audienceId,
+    visitorId,
+    tracked,
+  )
 
   return {
     personalization: { resolvedAudienceId: audienceId, experimentAssignments },
     audienceId,
     visitorId,
+    tracked,
     audiences,
     signals: result.signals,
   }
@@ -736,12 +865,19 @@ function* variantContainersInRegions(regions: Record<string, RegionNode[]>): Gen
  * exposure. Stable on visitorId → the visitor keeps the same arm across requests;
  * the write is idempotent on (experiment, visitor). Returns experimentId →
  * chosen variant key for <KywiLayout personalization.experimentAssignments>.
+ *
+ * \`tracked\` is the consent gate (kywi-cms#91): false means \`visitorId\` is a
+ * throwaway the middleware minted for this request alone, and the idempotent
+ * write stops being idempotent — every anonymous page view would insert another
+ * assignment row. The ARM IS STILL CHOSEN, so the page renders exactly as it
+ * does for anyone else; only the counting stops.
  */
 async function resolveExperimentAssignments(
   runtime: KywiRuntime,
   layout: LayoutDocument | null | undefined,
   audienceId: string | null,
   visitorId: string,
+  tracked: boolean,
 ): Promise<Record<string, string | null>> {
   if (!layout) return {}
   // Pre-resolve FIRST, then read the containers. A container component saved
@@ -766,7 +902,7 @@ async function resolveExperimentAssignments(
   for (const id of experimentIds) {
     const exp = byId.get(id)
     if (!exp) continue
-    const res = await resolveExperimentForContainer(runtime.db, exp, visitorId)
+    const res = await resolveExperimentForContainer(runtime.db, exp, visitorId, { recordExposure: tracked })
     assignments[id] = res.variantKey
   }
   return assignments
@@ -775,8 +911,12 @@ async function resolveExperimentAssignments(
 /**
  * Return the audience-resolved layout: page variants (audience → whole-page
  * region override) applied, and \`pageVariants\`/\`abExperiments\` stripped so no
- * other audience's content is serialized to this visitor. variantContainer arms
- * still resolve at render time from the threaded PersonalizationState.
+ * other audience's content is serialized to this visitor.
+ *
+ * This is only the PAGE-level half. Container-level arms (variantContainer /
+ * moduleVariantContainer) are stripped by \`pruneLayoutToServedArms\` as the last
+ * pass before \`<KywiLayout>\` — see the public page (#167). Run both, or the
+ * losing arms are still readable in the page's RSC flight payload.
  */
 export function personalizeLayout(
   layout: LayoutDocument,
@@ -806,6 +946,21 @@ export function transparencyNoticeEnabled(): boolean {
   return theme?.personalization?.transparencyNotice?.enabled !== false
 }
 
+/**
+ * Must a visitor consent before this site writes a \`personalization\` cookie
+ * (\`kywi_visitor\`, \`kywi_signals\`, \`kywi_utm\`, \`kywi_audience\`)?
+ * \`personalization.requireConsent\` — unset defaults to TRUE; only an explicit
+ * \`false\` turns Kywi's consent gate off, for a site that collects consent with
+ * external tooling (kywi-cms#91).
+ *
+ * \`middleware.ts\` runs on the edge and cannot read this config, so it mirrors
+ * the same flag with \`KYWI_REQUIRE_CONSENT=false\`. Set both, or neither.
+ */
+export function requireConsentEnabled(): boolean {
+  const theme = config.themes.find((t) => t.name === config.sites[0]?.theme) ?? config.themes[0]
+  return theme?.personalization?.requireConsent !== false
+}
+
 // ─── Self-ID widget (#50) ────────────────────────────────────────────────────
 
 /** The self-ID widget config in the serializable shape the client runtime reads. */
@@ -900,6 +1055,26 @@ import {
 // back. Its own dependency-free entry (never the DB-backed audiences barrel), so
 // it is importable from this edge middleware.
 import { UTM_COOKIE, utmCookieValue } from '@kywi-software/core/audiences/utm-persistence'
+// Same kind of edge-safe leaf: the kywi_entry writer, whose value core reads
+// back as \`session.entryPage\` (kywi-cms#196).
+import { ENTRY_COOKIE, entryPageCookieValue } from '@kywi-software/core/audiences/entry-page'
+// Same kind of edge-safe leaf entry: the cookie-consent category map + gate. The
+// visitor's decision (written by the \`cookieConsent\` layout module) decides
+// whether the personalization cookies below may be persisted at all.
+import { cookieAllowedByHeader } from '@kywi-software/core/audiences/consent'
+
+/**
+ * The edge mirror of \`theme.personalization.requireConsent\` (kywi-cms#91).
+ * Middleware runs on the edge and must not import \`kywi.config.ts\` (a config is
+ * free to pull in plugins and DB-backed code that cannot run there), so the one
+ * flag that lives in config is mirrored here as an env var.
+ * \`KYWI_REQUIRE_CONSENT=false\` turns the gate off for the two cookies this file
+ * writes. Set it together with the theme flag, never one alone —
+ * createKywiApiHandler THROWS at startup when the two disagree, so a mismatch
+ * fails the deploy instead of silently making the middleware and the API
+ * disagree about whether a visitor is tracked.
+ */
+const REQUIRE_CONSENT = process.env.KYWI_REQUIRE_CONSENT !== 'false'
 
 /**
  * Server-side auth enforcement + transparent session refresh for /admin and the
@@ -952,24 +1127,56 @@ const VISITOR_MAX_AGE = 60 * 60 * 24 * 365 * 2 // 2 years
  * would never fire on the landing page. Everything else passes through.
  */
 function handlePublicRequest(req: NextRequest): NextResponse {
-  const existing = req.cookies.get(VISITOR_COOKIE)?.value
+  // Both cookies below are \`personalization\` cookies in core's consent map, so
+  // neither is written OR READ until the visitor accepts. The header bridge is
+  // unaffected — this request still gets a visitor id and still personalizes off
+  // its own URL — so a site with no consent banner still renders, it just serves
+  // default content instead of tracking anyone. Place the \`cookieConsent\`
+  // module to let visitors turn personalization on.
+  const cookieHeader = req.headers.get('cookie')
+  const gate = { requireConsent: REQUIRE_CONSENT }
+  const mayPersonalize = cookieAllowedByHeader(VISITOR_COOKIE, cookieHeader, gate)
+  // Without consent the stored id is IGNORED, not just left un-refreshed: a
+  // visitor who accepted last month and rejected today still carries the cookie,
+  // and reading it would keep them tracked under the identity they just revoked.
+  const existing = mayPersonalize ? req.cookies.get(VISITOR_COOKIE)?.value : undefined
   const visitorId = existing ?? crypto.randomUUID()
   const headers = new Headers(req.headers)
   headers.set('x-kywi-visitor', visitorId)
   headers.set('x-kywi-url', req.nextUrl.href)
   const res = NextResponse.next({ request: { headers } })
-  if (!existing) {
+  if (!existing && mayPersonalize) {
     res.cookies.set(VISITOR_COOKIE, visitorId, { path: '/', maxAge: VISITOR_MAX_AGE, sameSite: 'lax' })
   }
   // Persist campaign UTM params so audience matching survives internal
   // navigation: core's collectUtm reads this cookie when the URL has no utm_*
   // query string. Only written when the request carries utm_* params, so an
   // ordinary page view never clobbers a persisted campaign (utmCookieValue
-  // returns null → the existing cookie is left in place).
-  const utmValue = utmCookieValue(req.nextUrl.href)
+  // returns null → the existing cookie is left in place) — and only once the
+  // visitor has consented, which utmCookieValue reads off the header we pass.
+  const utmValue = utmCookieValue(req.nextUrl.href, { cookieHeader, ...gate })
   if (utmValue) {
     res.cookies.set(UTM_COOKIE, utmValue, { path: '/', maxAge: 60 * 60 * 24 * 30, sameSite: 'lax' })
   }
+  // Record the session's ENTRY page (path + query) so rules on
+  // \`session.entryPage\` keep matching once the visitor navigates on
+  // (kywi-cms#196). Written once, consent-gated like the two above, and with no
+  // maxAge — a new visit is a new entry page. The landing request needs no
+  // cookie: core falls back to the request's own path, so \`?from=marketer\`
+  // personalizes the page it links to on that very request.
+  // Sec-Fetch-Dest / Accept are passed so ONLY a document request can name the
+  // entry page: a subresource that happens to be the session's first request
+  // (\`/kywi.js\`, a font, a route handler) would otherwise record itself as the
+  // page the visitor arrived on, and every entry-page rule would match an asset.
+  const entryValue = entryPageCookieValue(req.nextUrl.href, {
+    cookieHeader,
+    secFetchDest: req.headers.get('sec-fetch-dest'),
+    accept: req.headers.get('accept'),
+    ...gate,
+  })
+  if (entryValue) {
+    res.cookies.set(ENTRY_COOKIE, entryValue, { path: '/', sameSite: 'lax' })
+  }
   return res
 }
 
@@ -1161,6 +1368,7 @@ import './site.css'
 import config from '../../kywi.config'
 import { getKywi } from '../../lib/kywi'
 import { SiteNav } from '../../components/site-nav'
+import { KywiJsLoader } from '../../components/kywi-js-loader'
 
 /**
  * Public site shell. Header + footer carry this project's brand; edit them (and
@@ -1208,6 +1416,13 @@ export default async function SiteLayout({ children }: { children: React.ReactNo
   return (
     <div className="site-shell">
       {themeVars ? <style dangerouslySetInnerHTML={{ __html: themeVars }} /> : null}
+      {/* /kywi.js for the nav's hover-intent/keyboard/viewport-flip enhancement
+          (kywi-cms#114) — independent of personalization, gated on the exact
+          same condition <SiteNav> renders on below (a non-empty header menu),
+          so it loads whenever a \`[data-kywi-nav]\` root actually exists. Shares
+          its dedup with <PersonalizationRuntime> (lib/kywi-js-loader.ts), so a
+          page with both nav AND the client runtime enabled loads it once. */}
+      {headerItems.length > 0 && <KywiJsLoader />}
 
       <header className="site-header">
         <div className="site-header__inner">
@@ -1346,7 +1561,15 @@ import type { Metadata } from 'next'
 import { notFound } from 'next/navigation'
 import { cookies, headers } from 'next/headers'
 import { KywiBody, KywiEditableAttribute, KywiEditableRegion } from '@kywi-software/core/scope-client'
-import { KywiLayout, KywiRegion, AudienceMetaTags, hydrateLayoutFeeds, hydrateLayoutNav, type LayoutDocument } from '@kywi-software/core/layout'
+import {
+  KywiLayout,
+  KywiRegion,
+  AudienceMetaTags,
+  hydrateLayoutFeeds,
+  hydrateLayoutNav,
+  pruneLayoutToServedArms,
+  type LayoutDocument,
+} from '@kywi-software/core/layout'
 import { KywiJsonLd } from '@kywi-software/core/scope'
 import { ACCESS_COOKIE, canAccessContent, readSessionClaims } from '@kywi-software/core/host'
 import config from '../../../lib/config'
@@ -1358,6 +1581,7 @@ import {
   resolveSelfIdWidget,
   clientRuntimeEnabled,
   transparencyNoticeEnabled,
+  requireConsentEnabled,
   buildFeedResolver,
   resolveLayoutComponents,
   localeAlternates,
@@ -1478,11 +1702,24 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
   // Comments module's content-id anchor (#29); the audience/visitor ids for
   // client tooling (#50); and — when the theme opts in — the optional client
   // runtime that mounts the self-ID widget and re-evaluates audiences.
+  //
+  // \`head\` is a FUNCTION because JSON-LD must describe the layout THIS visitor
+  // is served (#195): the served document only exists after the arms are pruned
+  // below, and building the description from the STORED layout would ship the
+  // DEFAULT arm's copy to a matched visitor — the #167 leak, through structured
+  // data. The no-layout branch passes nothing, and JSON-LD then describes the
+  // node's body/metaDescription/summary alone.
   const baseUrl = await requestBaseUrl()
-  const head = (
+  const headFor = (servedLayout?: unknown) => (
     <>
       <meta name="kywi:content-id" content={contentId} />
-      <KywiJsonLd node={node} config={runtime.config} baseUrl={baseUrl} siteId={runtime.siteId} />
+      <KywiJsonLd
+        node={node}
+        config={runtime.config}
+        baseUrl={baseUrl}
+        siteId={runtime.siteId}
+        {...(servedLayout ? { layout: servedLayout } : {})}
+      />
       <AudienceMetaTags audienceId={perso.audienceId} visitorId={perso.visitorId} />
       {clientRuntimeEnabled() && perso.audiences.length > 0 ? (
         <PersonalizationRuntime
@@ -1490,6 +1727,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
           serverSignals={perso.signals}
           selfIdWidget={selfIdWidget}
           transparencyNotice={transparencyNoticeEnabled()}
+          requireConsent={requireConsentEnabled()}
         />
       ) : null}
     </>
@@ -1519,15 +1757,28 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     // KywiLayout is a client component and the renderer's resolver props are
     // functions, which cannot cross the RSC boundary (#147).
     const hydrated = await resolveLayoutComponents(navHydrated, runtime)
+    // LAST pass before the client boundary (#167): keep ONLY the arm this
+    // visitor is served in every variantContainer / moduleVariantContainer.
+    // KywiLayout is a client component, so anything still on the document here
+    // is serialized into the page's RSC flight payload — arm SELECTION was
+    // always server-side, but the losing arms crossed with it and were readable
+    // in view-source. Pruning uses the same \`perso.personalization\` the
+    // renderer is handed, so the markup is unchanged.
+    //
+    // Order matters: after component resolution (a container that is only a
+    // \`componentId\` has no arms of its own to prune yet) and after the feed/nav
+    // hydration passes. The front-edit overlay below is given the STORED
+    // \`layout\`, never this — an editor needs every arm.
+    const served = pruneLayoutToServedArms(hydrated, perso.personalization)
     content = (
       <article className="page page--layout" data-kywi-content-id={contentId}>
-        {head}
+        {headFor(served)}
         <KywiLayout
-          layout={hydrated}
+          layout={served}
           personalization={perso.personalization}
           moduleComponents={moduleComponents}
         >
-          {Object.keys(hydrated.regions).map((name) => (
+          {Object.keys(served.regions).map((name) => (
             <KywiRegion key={name} name={name} />
           ))}
         </KywiLayout>
@@ -1536,7 +1787,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
   } else {
     content = (
       <article className="page" data-kywi-content-id={contentId}>
-        {head}
+        {headFor()}
         {featured ? <img className="page__featured" src={featured} alt="" /> : null}
         <h1 className="page__title">{title}</h1>
         {perms ? (
@@ -1624,14 +1875,84 @@ import {
 } from '@kywi-software/core/layout'
 import type { SaveAction } from '@kywi-software/core/admin'
 
-// Lazy-load the full layout editor AND its stylesheet: the shell bundle (dnd-kit,
-// canvas, panels) and the ~4.7k-line admin design system are pulled INSIDE this
-// factory, so they enter the module graph only when an editor opens the overlay —
-// never in the public browse bundle a visitor downloads.
+/**
+ * Injects the admin design system's stylesheet as a plain \`<link>\` tag rather
+ * than an ES \`import\` (kywi-cms#130 follow-up). A dynamic \`import('…/admin/
+ * styles.css')\` still shipped the stylesheet on every public route that
+ * reaches this factory, regardless of the \`next/dynamic\` wrapping around
+ * it. A \`<link>\` created imperatively at runtime has no \`import\` statement
+ * for Next's CSS collector to see, so it never enters the build's CSS graph.
+ *
+ * VERIFIED (in the reference app this template mirrors) against a real
+ * \`next build && next start\`: an anonymous fetch of a real published content
+ * page shows zero OverlayShell/editor.css/admin.css references in any of its
+ * fetched resources. Fetching the SAME page against \`next dev\` still shows
+ * every one of those markers regardless of this fix — \`next dev\` bundles far
+ * more eagerly than a production build, for ALL routes, independent of any
+ * dynamic()/runtime-injection technique. A generated app's own e2e coverage
+ * of this (if any) needs to build for real, not assert against \`next dev\`.
+ *
+ * Two follow-ups from review:
+ *  - CACHE-BUSTING: \`/kywi-admin.css\` and \`/kywi-admin.css.version\` are both
+ *    synced from the installed \`@kywi-software/core\` package
+ *    (scripts/sync-kywi-admin-css.mjs, run via package.json's
+ *    \`sync:kywi-admin-css\` on every \`predev\`/\`prebuild\`) — mirroring how
+ *    \`public/kywi.js\` is synced from \`@kywi-software/js\`. The version
+ *    file's content becomes the \`?v=\` query string below, so a core upgrade
+ *    that changes the stylesheet always serves a URL a CDN/browser has never
+ *    cached, instead of a stale \`/kywi-admin.css\` response.
+ *  - FOUC: returns a Promise that resolves once the tag has actually loaded
+ *    (or failed to) — an existing, already-loaded tag resolves immediately;
+ *    a fresh or still-loading one resolves on its \`load\`/\`error\` event. The
+ *    dynamic() factory below awaits this ALONGSIDE the OverlayShell JS
+ *    import, so the editor's first paint never races its own stylesheet.
+ */
+function ensureAdminStylesheet(): Promise<void> {
+  if (typeof document === 'undefined') return Promise.resolve()
+  const existing = document.querySelector<HTMLLinkElement>('link[data-kywi-admin-css]')
+  if (existing) {
+    // \`.sheet\` is non-null only once the stylesheet has actually parsed —
+    // resolve immediately rather than re-attaching listeners to an event
+    // that already fired.
+    if (existing.sheet) return Promise.resolve()
+    return new Promise((resolve) => {
+      existing.addEventListener('load', () => resolve(), { once: true })
+      existing.addEventListener('error', () => resolve(), { once: true })
+    })
+  }
+  return fetch('/kywi-admin.css.version')
+    .then((res) => (res.ok ? res.text() : ''))
+    .catch(() => '')
+    .then(
+      (version) =>
+        new Promise<void>((resolve) => {
+          const link = document.createElement('link')
+          link.rel = 'stylesheet'
+          const v = version.trim()
+          link.href = v ? \`/kywi-admin.css?v=\${encodeURIComponent(v)}\` : '/kywi-admin.css'
+          link.dataset.kywiAdminCss = 'true'
+          // A load OR error either way lets the caller proceed — a stylesheet
+          // that 404s must never permanently block the editor from opening.
+          link.addEventListener('load', () => resolve(), { once: true })
+          link.addEventListener('error', () => resolve(), { once: true })
+          document.head.appendChild(link)
+        }),
+    )
+}
+
+// Lazy-load the full layout editor bundle: the shell's JS (dnd-kit, canvas,
+// panels) is pulled INSIDE this factory, so it enters the module graph only
+// when an editor opens the overlay — never in the public browse bundle a
+// visitor downloads. The stylesheet is handled separately — see
+// \`ensureAdminStylesheet\` above — since a css import here, even a dynamic
+// one, does not behave like the JS import right below it. Both are awaited
+// together so the editor never paints ahead of its own stylesheet (FOUC).
 const OverlayShell = dynamic(
   async () => {
-    await import('@kywi-software/core/admin/styles.css')
-    const mod = await import('@kywi-software/core/admin')
+    const [, mod] = await Promise.all([
+      ensureAdminStylesheet(),
+      import('@kywi-software/core/admin'),
+    ])
     return mod.OverlayShell
   },
   { ssr: false },
@@ -1804,6 +2125,62 @@ export function KywiFrontEdit({
 `
 }
 
+/**
+ * Shared `/kywi.js` script-injection primitive (kywi-cms#114). Two independent
+ * triggers can each want the browser bundle on the page: the site layout's nav
+ * (`<KywiJsLoader>`, purely for the hover-intent/keyboard/viewport-flip
+ * enhancement `initNavMenus()` applies unconditionally once the script boots)
+ * and `<PersonalizationRuntime>` (which additionally waits on
+ * `window.Kywi.bootAudienceEngine`). Before this fix only the personalization
+ * runtime ever injected the tag, so a site with `personalization.clientRuntime`
+ * off — or simply no active audiences — never got the nav enhancement either,
+ * even though the nav renders fully without it (kywi-cms#111's JS-off contract)
+ * and would only ever gain from it. `ensureKywiJsScript` is idempotent:
+ * whichever caller mounts first creates the ONE `<script data-kywi-js>` tag,
+ * every other caller finds it already there — so both triggers being true at
+ * once never loads the bundle twice.
+ */
+function kywiJsLoaderLib() {
+  return `export function ensureKywiJsScript(): HTMLScriptElement | null {
+  if (typeof document === 'undefined') return null
+  const existing = document.querySelector<HTMLScriptElement>('script[data-kywi-js]')
+  if (existing) return existing
+  const script = document.createElement('script')
+  script.src = '/kywi.js'
+  script.async = true
+  script.dataset.kywiJs = 'true'
+  document.body.appendChild(script)
+  return script
+}
+`
+}
+
+/**
+ * Loads `/kywi.js` for its nav enhancement alone, independent of
+ * personalization (kywi-cms#114). Rendered by the site layout whenever the
+ * resolved header menu is non-empty — the same condition `<SiteNav>` itself
+ * gates on before it renders a `[data-kywi-nav]` root — so this mounts exactly
+ * when there is a nav for `initNavMenus()` to enhance. Does nothing beyond
+ * ensuring the script tag exists: `Kywi.boot()` runs `initNavMenus()`
+ * unconditionally as part of its own bootstrap once the script loads, and
+ * never touches personalization on its own.
+ */
+function kywiJsLoaderComponent() {
+  return `'use client'
+
+import { useEffect } from 'react'
+import { ensureKywiJsScript } from '../lib/kywi-js-loader'
+
+export function KywiJsLoader() {
+  useEffect(() => {
+    ensureKywiJsScript()
+  }, [])
+
+  return null
+}
+`
+}
+
 /**
  * Client personalization runtime (kywi-cms#50). The SERVER already resolved and
  * rendered the correct audience/experiment variant and set the ids in <head>;
@@ -1814,6 +2191,12 @@ export function KywiFrontEdit({
  * stays dependency-free by default: drop the built @kywi-software/js bundle at
  * public/kywi.js to enable it (see README → "Personalization"). Without it the
  * server-rendered variant is exactly what every visitor sees.
+ *
+ * kywi-cms#114: `/kywi.js` may already be on the page independent of this
+ * component — the site layout's `<KywiJsLoader>` loads it purely for nav
+ * enhancement whenever the site has a nav. `ensureKywiJsScript` (shared with
+ * that component, lib/kywi-js-loader.ts) is idempotent, so this never injects
+ * a second copy.
  */
 function personalizationRuntime() {
   return `'use client'
@@ -1821,6 +2204,7 @@ function personalizationRuntime() {
 import React, { useEffect } from 'react'
 import type { Audience, VisitorSignals } from '@kywi-software/core/audiences/types'
 import type { PublicSelfIdWidget } from '../lib/site'
+import { ensureKywiJsScript } from '../lib/kywi-js-loader'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 declare global {
@@ -1843,15 +2227,27 @@ interface PersonalizationRuntimeProps {
    * deliberately through a \`personalizationBadge\` module. Defaults to true.
    */
   transparencyNotice?: boolean
+  /**
+   * \`personalization.requireConsent\` — false turns the client's consent gate
+   * off for a site that collects consent with external tooling. Defaults to
+   * true, so the resolved audience is only remembered for a consenting visitor
+   * (kywi-cms#91).
+   */
+  requireConsent?: boolean
 }
 
 /**
- * Loads /kywi.js and boots the audience data-layer. bootAudienceEngine reads the
- * opt-out cookie itself and resolves opted-out visitors to the default
- * experience, so opt-out is respected end to end. Rendered only when
- * theme.personalization.clientRuntime is on.
+ * Ensures /kywi.js is on the page, then boots the audience data-layer.
+ * bootAudienceEngine reads the opt-out cookie itself and resolves opted-out
+ * visitors to the default experience, so opt-out is respected end to end.
+ * Rendered only when theme.personalization.clientRuntime is on.
+ *
+ * kywi-cms#114: the script tag may already be on the page independent of this
+ * component — the site layout's <KywiJsLoader> loads it purely for nav
+ * enhancement whenever the site has a nav. ensureKywiJsScript (shared with
+ * that component) is idempotent, so this never injects a second copy.
  */
-export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget, transparencyNotice }: PersonalizationRuntimeProps) {
+export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget, transparencyNotice, requireConsent }: PersonalizationRuntimeProps) {
   useEffect(() => {
     let cancelled = false
     const ready = () => typeof window.Kywi?.bootAudienceEngine === 'function'
@@ -1868,6 +2264,7 @@ export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget,
             ? { selfIdWidget: { ...selfIdWidget, audiences, currentPath } }
             : {}),
           ...(transparencyNotice === false ? { transparencyNotice: false } : {}),
+          ...(requireConsent === false ? { requireConsent: false } : {}),
         })
         .catch(() => {
           /* client personalization is best-effort; the server already rendered defaults */
@@ -1888,18 +2285,14 @@ export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget,
       }, 60)
     }
 
-    const existing = document.querySelector<HTMLScriptElement>('script[data-kywi-js]')
-    if (existing) {
-      if (ready()) boot()
-      else existing.addEventListener('load', whenReady)
-    } else {
-      const script = document.createElement('script')
-      script.src = '/kywi.js'
-      script.async = true
-      script.dataset.kywiJs = 'true'
-      script.addEventListener('load', whenReady)
-      document.body.appendChild(script)
-    }
+    // kywi-cms#114: the script tag itself may already be on the page — the
+    // site layout's <KywiJsLoader> injects it independently, purely for nav
+    // enhancement, whenever the site has a nav. \`ensureKywiJsScript\` is the
+    // shared dedup primitive: it returns the existing tag if one is already
+    // there, so this never creates a second one.
+    const script = ensureKywiJsScript()
+    if (ready()) boot()
+    else script?.addEventListener('load', whenReady)
 
     return () => {
       cancelled = true
@@ -2243,6 +2636,14 @@ or read-only visitor gets no toolbar and no extra client JS. Custom
 editor's insert palette and are fully editable in place — the props rail and
 inline text editing work exactly as they do in the admin's Layout tab.
 
+The admin stylesheet (\`public/kywi-admin.css\`) is synced automatically from
+your installed \`@kywi-software/core\` version on every \`dev\`/\`build\` (via
+\`predev\`/\`prebuild\` — see \`scripts/sync-kywi-admin-css.mjs\`), not on
+\`install\`, and is gitignored — it is a build artifact of whichever core
+version you have, not project source. Run \`pnpm sync:kywi-admin-css\`
+yourself if you ever need it without a full dev/build cycle (e.g. before
+\`next start\` against an already-built \`.next\`).
+
 ## Personalization, A/B testing & self-ID
 
 Audiences, experiments and the self-ID widget you configure in the admin resolve
@@ -2252,7 +2653,16 @@ Audiences, experiments and the self-ID widget you configure in the admin resolve
   audience \`variantContainer\` render for the winning audience.
 - **A/B experiments** — each visitor is assigned a variant arm deterministically
   and the exposure is recorded. The assignment is stable because the
-  \`middleware.ts\` gives every visitor a persistent \`kywi_visitor\` id.
+  \`middleware.ts\` gives every visitor a persistent \`kywi_visitor\` id — once
+  they have consented. \`kywi_visitor\`, \`kywi_utm\`, \`kywi_signals\` and
+  \`kywi_audience\` are \`personalization\` cookies, and the engine will not write
+  any of them until the visitor accepts. Place the \`cookieConsent\` module to
+  give them that choice; until then pages render their default content and
+  nobody is tracked. If this site collects consent with EXTERNAL
+  tooling instead, set \`personalization: { requireConsent: false }\` on your
+  theme in \`kywi.config.ts\` **and** \`KYWI_REQUIRE_CONSENT=false\` in the
+  environment (the edge middleware cannot read the config) — that hands
+  compliance to your tooling and restores the un-gated cookie behaviour.
 - **Preview links** — an admin preview link sets \`kywi_preview_init\` and the page
   honours it, so you can preview an audience's experience.
 
@@ -2263,6 +2673,15 @@ dropping the built \`@kywi-software/js\` browser bundle at \`public/kywi.js\`; t
 generated \`components/personalization-runtime.tsx\` loads it best-effort. Without
 it, the server-rendered variant is what every visitor sees.
 
+The same \`public/kywi.js\` bundle also drives the header nav's hover-intent,
+Escape/arrow-key and viewport-edge-flip enhancement — independent of
+personalization. \`components/kywi-js-loader.tsx\` loads it whenever the site has
+a nav, whether or not \`clientRuntime\` is on, so the nav gets that polish on
+every site once the bundle is in place; the nav renders and works fully without
+it either way. (\`public/kywi-admin.css\`, the front-of-site editor's stylesheet,
+is a separate file synced automatically on \`dev\`/\`build\` — see "Front-of-site
+editor" above — unlike \`kywi.js\`, which you place yourself.)
+
 ## Locales
 
 Set \`locales\` on your site in \`kywi.config.ts\` (e.g. \`locales: ['en', 'es']\`),
@@ -2361,7 +2780,7 @@ lib/config.ts                     single import path for kywi.config.ts
 app/api/v1/[...kywi]/route.ts     the versioned API (delegates to core)
 app/admin/[[...admin]]/page.tsx   mounts the FULL core admin (all surfaces) at /admin
 lib/modules.tsx                   custom (defineModule) module renderers (admin + public)
-app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/site-nav.tsx            client wrapper around the shared nav renderer (header + footer)\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
+app/{llms,robots,sitemap,…}       root AX routes (llms.txt, robots.txt, sitemap.xml, …)${a.mode === 'coupled' ? '\napp/(site)/layout.tsx              public shell: theme tokens + your header/footer\napp/(site)/site.css                your site chrome styles (edit freely)\napp/(site)/[[...slug]]/page.tsx    renders published pages (layout + SEO + JSON-LD + i18n)\nlib/site.ts                        public-render helpers: path/locale resolution, feeds, personalization\ncomponents/site-nav.tsx            client wrapper around the shared nav renderer (header + footer)\ncomponents/kywi-js-loader.tsx      loads /kywi.js for nav enhancement whenever the site has a nav\ncomponents/personalization-runtime.tsx  optional client runtime (self-ID widget, live re-eval)\napp/(site)/kywi-front-edit.tsx     front-of-site editor: browse toolbar + in-place Layout editor (?kywi-edit=1, lazy-loaded)' : '\napp/page.tsx                       returns 404 (no public rendering in this mode)'}
 \`\`\`
 `
 }
@@ -2757,10 +3176,19 @@ export function buildFileSet(answers) {
     // Public-render helpers: path/locale resolution, feed + component resolvers,
     // personalization + experiments.
     files['lib/site.ts'] = libSite()
+    // Shared /kywi.js script-injection primitive (kywi-cms#114) — the site
+    // layout's nav loader and the personalization runtime below both use it,
+    // so loading the bundle for either reason never double-loads it.
+    files['lib/kywi-js-loader.ts'] = kywiJsLoaderLib()
+    files['components/kywi-js-loader.tsx'] = kywiJsLoaderComponent()
     // Optional client personalization runtime (self-ID widget, live re-eval). #50
     files['components/personalization-runtime.tsx'] = personalizationRuntime()
     // Front-of-site edit overlay (?kywi-edit=1), mounted by the page above.
     files['app/(site)/kywi-front-edit.tsx'] = frontEditOverlay()
+    // Syncs the admin stylesheet + a cache-busting version marker into
+    // public/ on every predev/prebuild — see the doc comment on
+    // syncKywiAdminCssScript and packageJson's syncScripts.
+    files['scripts/sync-kywi-admin-css.mjs'] = syncKywiAdminCssScript()
   } else {
     // headless + decoupled: no public rendering.
     files['app/page.tsx'] = headlessHomePage(answers)

package/package.json

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