create-kywi-app 0.15.0 → 0.15.2

package/assets/agent-patterns.md

@@ -331,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
@@ -463,7 +489,10 @@ 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.
+default content to everyone. A host that mounts the banner itself in app chrome
+instead of a page or blueprint layout (kywi-cms#193) is invisible to that scan,
+so set `theme.personalization.consentBanner: 'host'` to declare the placement
+and skip the check.
 
 ### Which do I reach for? (in order)
 
@@ -653,6 +682,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

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

@@ -1055,6 +1055,9 @@ 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.
@@ -1155,6 +1158,25 @@ function handlePublicRequest(req: NextRequest): NextResponse {
   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
 }
 
@@ -1680,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
@@ -1737,7 +1772,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     const served = pruneLayoutToServedArms(hydrated, perso.personalization)
     content = (
       <article className="page page--layout" data-kywi-content-id={contentId}>
-        {head}
+        {headFor(served)}
         <KywiLayout
           layout={served}
           personalization={perso.personalization}
@@ -1752,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 ? (
@@ -2627,7 +2662,11 @@ Audiences, experiments and the self-ID widget you configure in the admin resolve
   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.
+  compliance to your tooling and restores the un-gated cookie behaviour. If
+  you mount \`cookieConsent\` yourself in \`app/(site)/layout.tsx\` instead of
+  placing it through a page or blueprint layout, set
+  \`personalization: { consentBanner: 'host' }\` too, or the API's one-time
+  startup check will warn that nothing places it.
 - **Preview links** — an admin preview link sets \`kywi_preview_init\` and the page
   honours it, so you can preview an audience's experience.
 

package/package.json

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