create-kywi-app 0.7.0 → 0.8.0

package/assets/agent-patterns.md

@@ -443,7 +443,15 @@ interchangeable.
   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.
+  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.
 - **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

package/lib/templates.mjs

@@ -1087,11 +1087,57 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 `
 }
 
+/**
+ * Client-side wrapper around core's SHARED nav renderer — the same component the
+ * `navigation` module uses — so the site header and footer get identical markup,
+ * CSS (`.kywi-nav-*`) and @kywi-software/js enhancement to any nav placed in a
+ * page body. `items` is whatever app/(site)/layout.tsx resolved server-side (the
+ * owner-managed menu, or the site tree as fallback); nothing is decided here.
+ *
+ * WHY THIS FILE EXISTS — it is `'use client'` on purpose, and the layout that
+ * renders it is a Server Component. `BUILT_IN_MODULE_COMPONENTS` is exported
+ * from one of core's `'use client'` modules, so a Server Component that imports
+ * the map gets a client *reference*, not a real object:
+ * `BUILT_IN_MODULE_COMPONENTS.navigation` reads back `undefined` there and React
+ * throws "Element type is invalid… got: undefined" on every page (kywi-cms#112
+ * follow-up). Crossing the boundary here, in a client module, is what makes the
+ * lookup resolve to the real component — mirrors apps/reference/components/nav.tsx.
+ */
+function siteNavComponent() {
+  return `'use client'
+
+import React from 'react'
+import { BUILT_IN_MODULE_COMPONENTS } from '@kywi-software/core/layout'
+import type { NavMenuItem } from '@kywi-software/core/nav'
+
+// BUILT_IN_MODULE_COMPONENTS is a Record<string, …>, so a literal-key lookup is
+// typed as possibly-undefined under noUncheckedIndexedAccess; 'navigation' is
+// always present — it's one of core's own built-in modules, not user data.
+const NavRenderer = BUILT_IN_MODULE_COMPONENTS.navigation!
+
+export interface SiteNavProps {
+  items: NavMenuItem[]
+  /** \`horizontal\`/\`mega\`/\`vertical\` for the header bar, \`footer\` for the footer columns. */
+  variant: 'horizontal' | 'mega' | 'vertical' | 'footer'
+  ariaLabel: string
+  depth?: number
+}
+
+/** Renders one resolved menu (header or footer) through core's shared nav renderer. */
+export function SiteNav({ items, variant, ariaLabel, depth }: SiteNavProps) {
+  if (items.length === 0) return null
+  return (
+    <NavRenderer props={{ items, variant, ariaLabel, ...(depth ? { depth } : {}) }} />
+  )
+}
+`
+}
+
 /** @param {Answers} a — coupled public site shell. */
 function siteLayout(a) {
   return `import React from 'react'
 import { headers } from 'next/headers'
-import { themeTokenStyleBlock, BUILT_IN_MODULE_COMPONENTS } from '@kywi-software/core/layout'
+import { themeTokenStyleBlock } from '@kywi-software/core/layout'
 import { navTreeToMenuItems, normalizePath } from '@kywi-software/core/nav'
 // Neutral, token-driven defaults for everything Kywi renders (prose, the layout
 // grid + modules, forms, the edit overlay). Restyle via theme tokens, not by
@@ -1101,6 +1147,7 @@ import '@kywi-software/core/site/styles.css'
 import './site.css'
 import config from '../../kywi.config'
 import { getKywi } from '../../lib/kywi'
+import { SiteNav } from '../../components/site-nav'
 
 /**
  * Public site shell. Header + footer carry this project's brand; edit them (and
@@ -1113,7 +1160,8 @@ import { getKywi } from '../../lib/kywi'
  * of the box — and the footer renders a \`'footer'\` menu when one exists. NEVER
  * hardcode this list: a menu item's href resolves from its linked page and
  * can never drift the way a pasted URL can (see AGENTS.md → Navigation).
- * Rendered through core's shared nav renderer (\`BUILT_IN_MODULE_COMPONENTS\`)
+ * Rendered through core's shared nav renderer via the generated
+ * \`components/site-nav.tsx\` (a \`'use client'\` wrapper — see that file for why)
  * rather than bespoke markup, so it gets the same CSS and \`@kywi-software/js\`
  * enhancement as a \`navigation\` module placed in the page body.
  *
@@ -1126,8 +1174,6 @@ const siteTheme =
   config.themes.find((t) => t.name === config.sites[0]?.theme) ?? config.themes[0]
 const themeVars = themeTokenStyleBlock(siteTheme?.tokens)
 
-const NavRenderer = BUILT_IN_MODULE_COMPONENTS.navigation
-
 // Content edits (a renamed page, a reordered menu) must show up without a
 // restart — same reasoning as the page route.
 export const dynamic = 'force-dynamic'
@@ -1155,7 +1201,7 @@ export default async function SiteLayout({ children }: { children: React.ReactNo
           <a className="site-brand" href="/">${escapeJsxText(a.projectName)}</a>
           <div className="site-nav">
             {headerItems.length > 0 && (
-              <NavRenderer props={{ items: headerItems, variant: 'horizontal', ariaLabel: 'Primary', depth: 2 }} />
+              <SiteNav items={headerItems} variant="horizontal" ariaLabel="Primary" depth={2} />
             )}
             <a className="site-nav__admin" href="/admin">Admin →</a>
           </div>
@@ -1167,7 +1213,7 @@ export default async function SiteLayout({ children }: { children: React.ReactNo
       <footer className="site-footer">
         <div className="site-footer__inner">
           {footerItems && footerItems.length > 0 && (
-            <NavRenderer props={{ items: footerItems, variant: 'footer', ariaLabel: 'Footer' }} />
+            <SiteNav items={footerItems} variant="footer" ariaLabel="Footer" />
           )}
           <p className="site-footer__credit">Powered by <a href="https://kywi.dev">Kywi CMS</a></p>
         </div>
@@ -1513,6 +1559,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
         initialLayout={layout ?? { regions: { main: [] } }}
         adminHref={\`/admin/content/\${contentType}/\${contentId}\`}
         moduleComponents={moduleComponents}
+        hostModules={config.modules ?? []}
       >
         {content}
       </KywiFrontEdit>
@@ -1561,6 +1608,7 @@ import {
   BUILT_IN_MODULE_COMPONENTS,
   type LayoutDocument,
   type ModuleComponentMap,
+  type ModuleConfig,
 } from '@kywi-software/core/layout'
 import type { SaveAction } from '@kywi-software/core/admin'
 
@@ -1592,6 +1640,10 @@ export interface KywiFrontEditProps {
   adminHref: string
   /** Custom (defineModule) renderers, shared with the public layout + admin (#48). */
   moduleComponents?: ModuleComponentMap
+  /** Custom (defineModule) module CONFIGS from kywi.config.ts — gives the overlay
+   *  editor each custom module's prop definitions, so the props rail and inline
+   *  text editing work for them exactly as in the admin editor (kywi-cms#118). */
+  hostModules?: ModuleConfig[]
   children: React.ReactNode
 }
 
@@ -1616,6 +1668,7 @@ export function KywiFrontEdit({
   initialLayout,
   adminHref,
   moduleComponents = {},
+  hostModules = [],
   children,
 }: KywiFrontEditProps) {
   const edit = useKywiEditMode({ canEdit, canPublish })
@@ -1629,10 +1682,14 @@ export function KywiFrontEdit({
     if (editRequested) startEdit()
   }, [editRequested, startEdit])
 
-  // Registries + renderers for the editor: built from core (no module list is
-  // re-declared here) and merged with this app's custom module renderers from
-  // lib/modules — the SAME source the admin app and public renderer use (#48).
-  const moduleRegistry = React.useMemo(() => createModuleRegistry([]), [])
+  // Registries + renderers for the editor: the module registry carries each
+  // module's prop definitions (built-ins + this app's kywi.config.ts modules —
+  // without the host list, custom modules render but are uneditable, kywi-cms#118),
+  // merged with the custom renderers from lib/modules (#48).
+  const moduleRegistry = React.useMemo(
+    () => createModuleRegistry(hostModules ?? []),
+    [hostModules],
+  )
   const themeRegistry = React.useMemo(() => createThemeRegistry(), [])
   const editorComponents = React.useMemo(
     () => ({ ...BUILT_IN_MODULE_COMPONENTS, ...moduleComponents }),
@@ -2169,10 +2226,10 @@ leaving the editor keeps \`?kywi-edit=1\` in the URL in sync, so reloading (or
 sharing the link) lands back in the same mode. It all lives in
 \`app/(site)/kywi-front-edit.tsx\`; the editor bundle (and the admin stylesheet) is
 lazy-loaded, so pages your visitors see never carry its weight — an anonymous
-or read-only visitor gets no toolbar and no extra client JS. Note: custom
-\`defineModule\` types still RENDER on the canvas, but they don't appear in the
-front-of-site editor's insert palette (it uses the built-in module set) — add
-them from the admin's Layout tab instead.
+or read-only visitor gets no toolbar and no extra client JS. Custom
+\`defineModule\` types from \`kywi.config.ts\` also appear in the front-of-site
+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.
 
 ## Personalization, A/B testing & self-ID
 
@@ -2292,7 +2349,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/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/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)'}
 \`\`\`
 `
 }
@@ -2676,6 +2733,11 @@ export function buildFileSet(answers) {
     // page at its slug. More-specific /admin and /api routes take precedence.
     files['app/(site)/layout.tsx'] = siteLayout(answers)
     files['app/(site)/site.css'] = siteStyles(answers)
+    // 'use client' wrapper around core's shared nav renderer — required because
+    // BUILT_IN_MODULE_COMPONENTS is exported from a 'use client' core module, so
+    // the (Server Component) site layout above must render it through here
+    // rather than looking it up directly (see siteNavComponent's doc comment).
+    files['components/site-nav.tsx'] = siteNavComponent()
     files['app/(site)/[[...slug]]/page.tsx'] = siteSlugPage()
     // Public-render helpers: path/locale resolution, feed + component resolvers,
     // personalization + experiments.

package/package.json

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