create-kywi-app 0.10.0 → 0.12.0

package/assets/agent-patterns.md

@@ -76,7 +76,7 @@ the full proposal — ten minutes of sign-off beats re-entering fifty nodes.
 | Hardcode a list (testimonials, logos, posts, products, team) | Folder of nodes + a Feed + the Feed Display module (§1) |
 | Create one-off pages with identical field shapes | A custom content type + one node per item (§2) |
 | Filter/group content by topic, industry, audience | Categories & tags, queried by feeds (§3) |
-| Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component (§4) |
+| Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component — linked, so one edit updates them all (§4) |
 | Write page sections as JSX | Build them as layout sections/modules the owner can edit (§5) |
 | Build a page as one column of full-width headings and paragraphs | Compose: section bands, columns, object modules (§5) |
 | Put a custom module's editable copy in a `json` prop | One `text`/`textarea`/`richText` prop per field the owner edits (§5) |
@@ -179,14 +179,99 @@ Anything designed once and used on multiple pages — CTA bands, promo banners,
 newsletter signup blocks, campaign snippets, "as seen in" strips — should be a
 **reusable component**, not copy-pasted sections.
 
-- In the layout editor, select the module and **Save as Component**; insert it
-  elsewhere from the component picker. Placed instances are **live
-  references**: editing the source component updates every page that uses it.
-- **Detach** an instance when a page genuinely needs a one-off variant — it
-  becomes an independent copy from that point on.
-- Rule of thumb: the second time you paste the same section, stop and make it
-  a component. The owner should be able to update the sitewide CTA in one
-  place, ten minutes before their webinar.
+A component is a **live source**, not a snapshot. Every page that places one
+holds a *link* to it (a `componentId` on the node), and the link is resolved on
+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.
+
+**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.
+
+**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,
+Kywi asks, naming the blast radius ("updates 3 instances across 2 pages, including
+published"):
+
+- **Save and update all instances** — the edit becomes the component. Every
+  instance everywhere follows it, live.
+- **Save to this page only** — this instance *detaches*: it keeps the edit as its
+  own independent content and stops following the component. Everything else is
+  untouched.
+
+**Rule of thumb:** the second time you paste the same section, stop and make it a
+component. The owner should be able to update the sitewide CTA in one place, ten
+minutes before their webinar.
+
+**Managing them:** *Components* in the admin nav is the library — every component
+with the number of pages using it, rename, an editing canvas for the definition,
+and delete. Deleting **detaches every instance first**: each page keeps rendering
+exactly what it rendered, as its own copy, and stops following.
+
+### Components over the API
+
+The admin UI is one client; the endpoints are the contract. `siteId` is optional
+and defaults to the resolved site — components are **per-site** in v1, and
+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`.
+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
+   its own. The node's inline content is the *fallback copy* — what renders if the
+   component ever stops resolving — so write the definition's content there, not a
+   placeholder.
+
+   **An `ab_test` placement must mint its own `experimentId`.** A
+   `variantContainer` definition normally carries an `experimentId` — the one the
+   band had on the page it was saved from — because `mode: 'ab_test'` without one
+   is invalid, so it cannot simply be left out of the definition. A placement that
+   names no binding of its own **inherits the definition's**. Place that component
+   on three pages and all three arms report into a *single* experiment run; a
+   `winnerId` that travels the same way locks every placement to a finished test,
+   permanently serving one arm on pages nobody tested. So when you write an
+   `ab_test` placement: set a **fresh `experimentId`** on the placement node (any
+   uuid — one run per placement is the whole model) and **never copy `winnerId`**.
+   The editors do exactly this (`buildConnectedVariantContainerNode`), and a
+   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.
+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
+   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.
+   A body with only `name` / `description` is a rename and changes nothing any page
+   renders.
+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
+   the counts into a list, in one read.
+
+**Two 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.
+
+**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
+pages the moment it returns. On a site with an editorial workflow, treat a
+definition write as a publish, not a draft: no draft, schedule or review step
+holds it back. Changeset integration is a follow-up.
 
 ## 5. Page layouts & modules — not hardcoded JSX
 
@@ -441,20 +526,22 @@ interchangeable.
   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 an **arm switcher**, each arm 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 arm 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.
+  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
-  arms are HTML strings (`defaultContent`, `variants: [{audienceId, label,
-  content}]`). Every arm ships in the HTML (default visible, the rest
+  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`.
@@ -586,7 +673,8 @@ early, so ask at scoping time.
 - Creating types and entering content before the owner signed off on a
   content model.
 - A hardcoded array of testimonials/logos/posts in a page component.
-- The same CTA JSX pasted on four pages.
+- The same CTA JSX pasted on four pages — or the same section duplicated on four
+  pages in the editor, which the owner then has to update four times (§4).
 - A `<form>` that POSTs to a hand-rolled route (or nowhere).
 - Marketing imagery in `/public`.
 - A "blog" that is a folder of `.mdx` files the owner can't edit.

package/assets/kywi-personalization-skill.md

@@ -44,16 +44,18 @@ is progressive enhancement; anonymous visitors get the default).
 ### 4b. Experiment path
 
 Admin → Experiments: create the experiment. In the layout, add an A/B
-container with an arm per treatment. Assignment is deterministic per visitor
-(the scaffold's middleware issues a persistent `kywi_visitor` cookie), so a
-visitor sees the same arm on every visit — no client runtime needed.
+container with a variant per treatment (the editor UI and API both call these
+"variants"; the underlying data model calls each one an "arm" — same thing).
+Assignment is deterministic per visitor (the scaffold's middleware issues a
+persistent `kywi_visitor` cookie), so a visitor sees the same variant on every
+visit — no client runtime needed.
 
 ### 5. Verify before calling it done
 
 - **Preview tokens** (Audiences → Preview Tokens): view the page *as each
   audience* and confirm the right variant serves.
 - Experiments: two fresh browser profiles should get (possibly) different
-  arms, and each profile must get the **same** arm on reload.
+  variants, and each profile must get the **same** variant on reload.
 - Confirm exposures are being recorded in the Experiments admin.
 - Load the page as a plain anonymous visitor: the default must be complete.
 

package/lib/templates.mjs

@@ -54,7 +54,11 @@ function packageJson(a) {
         dev: 'next dev',
         build: 'next build',
         start: 'next start',
-        migrate: 'kywi migrate --push',
+        // 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
+        // scaffold is journal-managed from its very first `pnpm migrate`.
+        migrate: 'kywi migrate',
         seed: 'kywi seed',
       },
       dependencies: {
@@ -249,6 +253,34 @@ function tsconfig() {
   ) + '\n'
 }
 
+// ── types/css.d.ts ────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ *
+ * `*.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.
+declare module '*.css'
+`
+}
+
 // ── next.config.mjs ───────────────────────────────────────────────────────────
 
 function nextConfig() {
@@ -408,16 +440,19 @@ function libSite() {
 import type {
   LayoutDocument,
   RegionNode,
-  ModuleNode,
+  VariantContainer,
   FeedItemsResolver,
-  ComponentResolver,
-  SectionComponentResolver,
   PersonalizationState,
 } from '@kywi-software/core/layout'
-import { isLayoutSection, applyPageVariant } from '@kywi-software/core/layout'
+import {
+  isLayoutSection,
+  collectComponentRefs,
+  componentDetachSource,
+  resolveComponentPlacements,
+  applyPageVariant,
+} from '@kywi-software/core/layout'
 import { resolveContentByPath, normalizePath } from '@kywi-software/core/nav'
 import { getFeedBySlug, getComponentById, resolveLocaleFromRequest } from '@kywi-software/core'
-import { resolveComponentDefinition, resolveSectionComponentDefinition } from '@kywi-software/core/admin/server'
 import {
   evaluateActiveAudiences,
   getSelfIdWidgetConfig,
@@ -581,77 +616,48 @@ export function buildFeedResolver(runtime: KywiRuntime): FeedItemsResolver {
   }
 }
 
-// ─── Component resolver (#46) ────────────────────────────────────────────────
-
-function* moduleNodesInRegions(regions: Record<string, RegionNode[]>): Generator<ModuleNode> {
-  for (const nodes of Object.values(regions)) {
-    for (const node of nodes) {
-      if (isLayoutSection(node)) {
-        for (const col of node.columns) for (const m of col.nodes) yield m
-      } else {
-        for (const s of node.defaultSections) for (const col of s.columns) for (const m of col.nodes) yield m
-        for (const v of node.variants) for (const s of v.sections) for (const col of s.columns) for (const m of col.nodes) yield m
-      }
-    }
-  }
-}
+// ─── Linked components: server-side pre-resolution (#46, #69, #147) ──────────
 
-/**
- * Prefetch every connected-component (\`componentId\`) referenced by the layout and
- * return a synchronous {@link ComponentResolver} over that snapshot — the
- * renderer resolves components during render, so they must be resolved up front.
- * Returns undefined when the layout references no components (skip the prop).
- */
-export async function buildComponentResolver(
-  layout: LayoutDocument,
-  runtime: KywiRuntime,
-): Promise<ComponentResolver | undefined> {
-  const ids = new Set<string>()
-  for (const node of moduleNodesInRegions(layout.regions)) {
-    if (node.componentId) ids.add(node.componentId)
-  }
-  if (ids.size === 0) return undefined
+/** Fetch a set of component rows once and index them by id. */
+async function loadComponents(ids: string[], runtime: KywiRuntime) {
   const { db, siteId } = runtime
   const entries = await Promise.all(
-    [...ids].map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
+    ids.map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
   )
-  const map = new Map(entries)
-  return (componentId) => resolveComponentDefinition(map.get(componentId) ?? null)
-}
-
-/** Yield every section-level component reference (\`section.componentId\`) in the
- *  layout, descending into variantContainer default + variant sections (#69). */
-function* sectionComponentIds(regions: Record<string, RegionNode[]>): Generator<string> {
-  for (const nodes of Object.values(regions)) {
-    for (const node of nodes) {
-      if (isLayoutSection(node)) {
-        if (node.componentId) yield node.componentId
-      } else {
-        for (const s of node.defaultSections) if (s.componentId) yield s.componentId
-        for (const v of node.variants) for (const s of v.sections) if (s.componentId) yield s.componentId
-      }
-    }
-  }
+  return new Map(entries)
 }
 
 /**
- * Prefetch every connected *section* component (\`section.componentId\`) referenced
- * by the layout and return a synchronous {@link SectionComponentResolver} over the
- * snapshot — parallel to {@link buildComponentResolver} but for reusable sections
- * (#69). Returns undefined when the layout references none (skip the prop).
+ * Resolve every linked component (\`componentId\`) the layout places, ON THE
+ * SERVER, before the document reaches the renderer.
+ *
+ * This is the ONLY way a Server Component can render linked components.
+ * \`KywiLayout\` is a client component and its \`componentResolver\` /
+ * \`sectionComponentResolver\` / \`variantContainerComponentResolver\` props are
+ * FUNCTIONS: passing them from here throws "Functions cannot be passed directly
+ * to Client Components" and the page 500s. Pre-resolution hands the renderer a
+ * plain document instead — only data crosses the boundary — and produces exactly
+ * the markup the resolvers were meant to produce, \`data-component-id\` included.
+ *
+ * \`collectComponentRefs\` is the engine's own link walker, the same one the
+ * instance index and detach-all use, so this never falls behind on where a link
+ * may live. It also knows that a connected section's inline columns are fallback
+ * copy rather than placements, so links buried in one are not fetched — they
+ * only render when that section's own component has gone missing.
+ *
+ * Definitions are read per request with no cache, so editing a component is live
+ * on the next page view.
  */
-export async function buildSectionComponentResolver(
+export async function resolveLayoutComponents(
   layout: LayoutDocument,
   runtime: KywiRuntime,
-): Promise<SectionComponentResolver | undefined> {
-  const ids = new Set<string>(sectionComponentIds(layout.regions))
-  if (ids.size === 0) return undefined
-  const { db, siteId } = runtime
-  const entries = await Promise.all(
-    [...ids].map(async (id) => [id, await getComponentById(db, id, siteId)] as const),
+): Promise<LayoutDocument> {
+  const refs = collectComponentRefs(layout)
+  if (refs.length === 0) return layout
+  const map = await loadComponents([...new Set(refs.map((ref) => ref.componentId))], runtime)
+  return resolveComponentPlacements(layout, (componentId) =>
+    componentDetachSource(map.get(componentId) ?? null),
   )
-  const map = new Map(entries)
-  return (componentId) => resolveSectionComponentDefinition(map.get(componentId) ?? null)
 }
 
 // ─── Personalization + experiments (#50) ─────────────────────────────────────
@@ -716,7 +722,7 @@ export async function resolvePersonalization(
   }
 }
 
-function* variantContainersInRegions(regions: Record<string, RegionNode[]>): Generator<RegionNode> {
+function* variantContainersInRegions(regions: Record<string, RegionNode[]>): Generator<VariantContainer> {
   for (const nodes of Object.values(regions)) {
     for (const node of nodes) {
       if (!isLayoutSection(node)) yield node
@@ -738,10 +744,17 @@ async function resolveExperimentAssignments(
   visitorId: string,
 ): Promise<Record<string, string | null>> {
   if (!layout) return {}
-  const resolved = applyPageVariant(layout, audienceId)
+  // Pre-resolve FIRST, then read the containers. A container component saved
+  // with \`mode: 'ab_test'\` keeps its experiment in the DEFINITION; a placement
+  // that carries only a \`componentId\` would otherwise look like a plain
+  // container to this pass, no assignment would be made, and every visitor would
+  // see the Default arm of a live experiment. After pre-resolution there are no
+  // unresolved placements left to special-case — the containers here are the
+  // containers that render.
+  const resolved = await resolveLayoutComponents(applyPageVariant(layout, audienceId), runtime)
   const experimentIds = new Set<string>()
   for (const node of variantContainersInRegions(resolved.regions)) {
-    if (!isLayoutSection(node) && node.mode === 'ab_test' && !node.winnerId && node.experimentId) {
+    if (node.mode === 'ab_test' && !node.winnerId && node.experimentId) {
       experimentIds.add(node.experimentId)
     }
   }
@@ -1346,8 +1359,7 @@ import {
   clientRuntimeEnabled,
   transparencyNoticeEnabled,
   buildFeedResolver,
-  buildComponentResolver,
-  buildSectionComponentResolver,
+  resolveLayoutComponents,
   localeAlternates,
   mediaUrl,
   requestBaseUrl,
@@ -1499,12 +1511,14 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     // (menuSlug → a real menu; the tree otherwise) — the same seam as feeds,
     // so a nav module dropped into any region/section just works (#112).
     const currentPath = String(node['path'] ?? '/')
-    const hydrated = await hydrateLayoutNav(
+    const navHydrated = await hydrateLayoutNav(
       feedsHydrated,
       runtime.scope.menus.createHydrationResolver(runtime.siteId, currentPath),
     )
-    const componentResolver = await buildComponentResolver(hydrated, runtime)
-    const sectionComponentResolver = await buildSectionComponentResolver(hydrated, runtime)
+    // Linked components resolve HERE, on the server, into the document itself:
+    // 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)
     content = (
       <article className="page page--layout" data-kywi-content-id={contentId}>
         {head}
@@ -1512,8 +1526,6 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
           layout={hydrated}
           personalization={perso.personalization}
           moduleComponents={moduleComponents}
-          {...(componentResolver ? { componentResolver } : {})}
-          {...(sectionComponentResolver ? { sectionComponentResolver } : {})}
         >
           {Object.keys(hydrated.regions).map((name) => (
             <KywiRegion key={name} name={name} />
@@ -2694,6 +2706,9 @@ export function buildFileSet(answers) {
     'package.json': packageJson(answers),
     'kywi.config.ts': kywiConfig(answers),
     'tsconfig.json': tsconfig(),
+    // Ambient module declarations the generated code needs in order to type-check
+    // (see `cssTypes`). Every mode: the admin catch-all imports the stylesheet too.
+    'types/css.d.ts': cssTypes(),
     'next.config.mjs': nextConfig(),
     '.env.example': envExample(),
     '.gitignore': gitignore(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.10.0",
+  "version": "0.12.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",