create-kywi-app 0.6.1 → 0.6.3

package/lib/templates.mjs

@@ -755,20 +755,30 @@ export function clientRuntimeEnabled(): boolean {
 
 /** The self-ID widget config in the serializable shape the client runtime reads. */
 export interface PublicSelfIdWidget {
-  fields: Array<{ id: string; label: string; type: 'select'; options?: string[]; required?: boolean }>
+  fields: Array<{
+    id: string
+    label: string
+    type: 'select'
+    options?: Array<{ value: string; label: string }>
+    required?: boolean
+  }>
   headline: string
   subheadline?: string
   submitLabel: string
   skipLabel?: string
-  displayMode: 'modal' | 'inline' | 'slide-in'
+  displayMode: 'modal' | 'inline' | 'slide-in' | 'hello_bar_top' | 'hello_bar_bottom' | 'drawer'
   frequency: 'once' | 'session' | 'always'
   trigger: SelfIdTrigger
 }
 
+// The admin's five display modes (SelfIdWidgetConfig['displayMode']) and the
+// client runtime's (PublicSelfIdWidget['displayMode'], @kywi-software/js) are the
+// same set — the runtime implements hello_bar_top/hello_bar_bottom/drawer as
+// their own layouts, not folded into slide-in (kywi-cms#97) — so this is a
+// passthrough. Kept as a named function (rather than assigning displayMode
+// directly) so the two types stay checked against each other at compile time.
 function mapDisplayMode(mode: SelfIdWidgetConfig['displayMode']): PublicSelfIdWidget['displayMode'] {
-  if (mode === 'modal') return 'modal'
-  if (mode === 'inline') return 'inline'
-  return 'slide-in' // hello bars + drawer both animate in from an edge
+  return mode
 }
 
 function mapFrequency(freq: SelfIdWidgetConfig['frequency']): PublicSelfIdWidget['frequency'] {
@@ -797,7 +807,10 @@ export async function resolveSelfIdWidget(runtime: KywiRuntime): Promise<PublicS
       id: f.id,
       label: f.label,
       type: 'select' as const,
-      options: f.picklist.map((p) => p.value),
+      // {value, label} pairs, not bare values — the client runtime renders the
+      // label and submits the value (kywi-cms#96); dropping the label here is
+      // what made every option render as its raw value.
+      options: f.picklist,
       required: f.required,
     }))
   if (fields.length === 0) return null
@@ -921,10 +934,33 @@ async function fetchFreshAccessToken(origin: string, refreshToken: string): Prom
   }
 }
 
+// Markdown content negotiation by URL suffix. Core serves markdown at
+// \`/api/v1/ax/md/slug/<slug>\` and the AX layer enables it (ax.markdown), but the
+// scaffold never wires the friendly \`/<path>.md\` URL the AX pitch (and the
+// developer copy) names — so it 404s despite the feature being on. Rewrite any
+// GET/HEAD for \`/<path>.md\` onto the core route so the named URL actually
+// resolves. Nested paths keep their full slug (e.g. /docs/foo.md -> docs/foo).
+// Never intercepts Next internals or the API — those never carry this suffix,
+// but are excluded explicitly since the matcher's own exclusion is broad.
+function handleMarkdownNegotiation(req: NextRequest): NextResponse | null {
+  const { pathname } = req.nextUrl
+  if (req.method !== 'GET' && req.method !== 'HEAD') return null
+  if (!pathname.endsWith('.md')) return null
+  if (pathname.startsWith('/api/') || pathname.startsWith('/_next/')) return null
+  const slug = pathname.replace(/^\\//, '').replace(/\\.md$/, '')
+  if (!slug) return null
+  const url = req.nextUrl.clone()
+  url.pathname = '/api/v1/ax/md/slug/' + slug
+  return NextResponse.rewrite(url)
+}
+
 export async function middleware(req: NextRequest): Promise<NextResponse> {
   const { pathname } = req.nextUrl
   if (isAuthEndpoint(pathname)) return NextResponse.next()
 
+  const md = handleMarkdownNegotiation(req)
+  if (md) return md
+
   // Public pages are never auth-gated — just give them a stable visitor id.
   const isAdmin = pathname === '/admin' || pathname.startsWith('/admin/')
   const isApi = pathname.startsWith('/api/v1/')
@@ -980,6 +1016,10 @@ export const config = {
     // any path with a file extension (static assets, /favicon.ico, /kywi.js, and
     // the AX files /robots.txt, /sitemap.xml, /llms*.txt).
     '/((?!_next/|.*\\\\..*).*)',
+    // \`/<path>.md\` — the markdown-negotiation URL. The extension-excluding
+    // pattern above skips it, so it needs its own entry to reach
+    // handleMarkdownNegotiation.
+    '/((?!_next/|api/).*\\\\.md)',
   ],
 }
 `
@@ -1239,12 +1279,17 @@ function hasRenderableLayout(layout: LayoutDocument | null | undefined): layout
 // Is the current visitor a signed-in admin who may edit? The public route is
 // outside the middleware's auth matcher, so verify the httpOnly session cookie
 // here and derive the content permissions the overlay needs. Returns null for
-// anyone who cannot edit — no edit DOM is emitted for them.
+// anyone who cannot edit — no edit DOM (not even the browse-mode toolbar) is
+// emitted for them. Called on EVERY request (not just ?kywi-edit=1 ones) so the
+// toolbar can surface itself for a signed-in admin who is just browsing — this
+// is a cookie read + JWT verify, no DB round-trip, so the cost on an anonymous
+// visitor's fast path is a fast null return (\`readSessionClaims\` bails
+// immediately when there's no cookie).
 async function resolveEditPermissions() {
   const token = (await cookies()).get(ACCESS_COOKIE)?.value
   const claims = await readSessionClaims(token, config.auth.secret)
   if (!claims || !canAccessContent(claims.role, 'write')) return null
-  return { canEdit: true, canPublish: canAccessContent(claims.role, 'publish') }
+  return { canEdit: true, canPublish: canAccessContent(claims.role, 'publish'), role: claims.role }
 }
 
 // "/" resolves the seeded Home node; any other URL resolves the published node at
@@ -1264,9 +1309,13 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
   const featured = mediaUrl(node['featuredImageId'])
   const layout = node['layout'] as LayoutDocument | null | undefined
 
-  // ?kywi-edit=1 opts an authenticated admin into the front-of-site overlay.
+  // Resolved on every request so a signed-in admin gets the persistent browse
+  // toolbar even when just browsing — ?kywi-edit=1 only decides whether the
+  // page auto-enters the full overlay editor on mount (kywi-cms#93). An
+  // anonymous/read-only visitor resolves to perms === null: zero extra client
+  // JS, identical output to before this route ever heard of the overlay.
   const editRequested = (await searchParams)['kywi-edit'] === '1'
-  const perms = editRequested ? await resolveEditPermissions() : null
+  const perms = await resolveEditPermissions()
 
   // Server-side personalization (#50), evaluated once: the winning audience (or a
   // kywi_preview_init preview) drives page variants + variantContainers, and this
@@ -1347,12 +1396,16 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
     )
   }
 
-  // Mount the overlay (client) only for an authenticated admin who asked for it.
+  // Mount the overlay (client) for any authenticated admin (write role+) —
+  // browse mode renders just the slim toolbar; ?kywi-edit=1 (editRequested)
+  // additionally auto-starts the full overlay editor. Nothing mounts for an
+  // anonymous or read-only visitor.
   if (perms) {
     return (
       <KywiFrontEdit
         canEdit={perms.canEdit}
         canPublish={perms.canPublish}
+        editRequested={editRequested}
         contentId={contentId}
         contentType={contentType}
         pageTitle={title}
@@ -1372,18 +1425,25 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
 }
 
 /**
- * Front-of-site edit overlay (client). Mounted by the public page ONLY for an
- * authenticated admin who opened the page with ?kywi-edit=1 (the page verifies
- * the session cookie server-side first).
+ * Front-of-site edit overlay (client). Mounted by the public page for ANY
+ * authenticated admin (write role+) — the page verifies the session cookie
+ * server-side first (resolveEditPermissions, called unconditionally) and only
+ * mounts this when that check passes, so canEdit is always true here.
  *
  * Two modes, same component:
- *  - **Browse** — core's slim `KywiEditToolbar` over the live page, with the
- *    editable regions outlined via the `data-kywi-*` protocol.
- *  - **Edit** (`?kywi-edit=1`, or the toolbar's Edit toggle) — the FULL
- *    `OverlayShell` layout editor, the same one the admin app mounts, rendered
- *    from the same core module registry + custom renderers. Save PUTs the layout
- *    document; Publish PUTs the layout then flips status — exactly the API the
- *    admin editor uses.
+ *  - **Browse** (default) — core's slim `KywiEditToolbar`, a persistent
+ *    WordPress-admin-bar-style strip over the live page (page title, draft/
+ *    published status, "Edit this page", "Go to admin") — this is the
+ *    discoverability fix (kywi-cms#93): an admin browsing the public site
+ *    normally, with no query param, now sees the entry point. The editable
+ *    regions are also outlined via the `data-kywi-*` protocol.
+ *  - **Edit** (the toolbar's "Edit this page", or landing with
+ *    `?kywi-edit=1`) — the FULL `OverlayShell` layout editor, the same one the
+ *    admin app mounts, rendered from the same core module registry + custom
+ *    renderers. Save PUTs the layout document; Publish PUTs the layout then
+ *    flips status — exactly the API the admin editor uses. Entering/leaving
+ *    edit mode keeps `?kywi-edit=1` in sync via history.replaceState, so a
+ *    reload (or a shared link) lands back in the same mode.
  *
  * The OverlayShell is lazy-loaded (`next/dynamic`, client-only): its weight
  * (dnd-kit, canvas, side panels) is only fetched when an editor actually enters
@@ -1420,6 +1480,8 @@ const OverlayShell = dynamic(
 export interface KywiFrontEditProps {
   canEdit: boolean
   canPublish: boolean
+  /** True when the page was requested with \`?kywi-edit=1\` — auto-starts the full overlay editor on mount. */
+  editRequested: boolean
   contentId: string
   contentType: string
   pageTitle: string
@@ -1434,13 +1496,19 @@ export interface KywiFrontEditProps {
 }
 
 /**
- * Wraps the public page with the front-of-site edit affordance. The page only
- * renders this for a signed-in admin who asked to edit (?kywi-edit=1), so the
- * permission gate (canEdit) is always satisfied here.
+ * Wraps the public page with the front-of-site edit affordance. The page
+ * renders this for ANY signed-in admin (write role+) — canEdit is always true
+ * here, since the page only mounts KywiFrontEdit once resolveEditPermissions
+ * has already confirmed it server-side. Browse mode shows the persistent
+ * KywiEditToolbar (the primary discoverability fix, kywi-cms#93); the full
+ * OverlayShell editor only mounts once edit mode actually starts — either the
+ * toolbar's "Edit this page" button, or landing with \`?kywi-edit=1\`
+ * (editRequested), which auto-starts it once on mount.
  */
 export function KywiFrontEdit({
   canEdit,
   canPublish,
+  editRequested,
   contentId,
   contentType,
   pageTitle,
@@ -1452,11 +1520,14 @@ export function KywiFrontEdit({
 }: KywiFrontEditProps) {
   const edit = useKywiEditMode({ canEdit, canPublish })
 
-  // ?kywi-edit=1 means "enter edit mode now" — flip it on once after mount.
+  // ?kywi-edit=1 (editRequested) means "enter edit mode now" — flip it on once
+  // after mount. Without it the page mounts straight into browse mode (the
+  // persistent toolbar), which is the common case now that KywiFrontEdit
+  // renders for every signed-in admin, not only deep-linked ones.
   const { startEdit, endEdit } = edit
   React.useEffect(() => {
-    startEdit()
-  }, [startEdit])
+    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
@@ -1514,15 +1585,23 @@ export function KywiFrontEdit({
   }, [contentId])
 
   // Edit mode: the full layout editor, in place, over the live page.
+  // NOTE: no \`kywi-admin-shell\` here (kywi-cms#94). That class is the admin
+  // design system's base+reset — font family, font size, colours, heading
+  // resets — and wrapping the page in it re-typesets the very content the
+  // owner is trying to judge at real width. The editor chrome carries its own
+  // styling; the page keeps the site's.
   if (edit.isEditMode && edit.canEdit) {
     return (
-      <div className="kywi-admin-shell kywi-frontend-edit">
+      <div className="kywi-frontend-edit">
         <OverlayShell
           editMode={edit}
           initialLayout={initialLayout}
           contentId={contentId}
           contentType={contentType}
           pageTitle={pageTitle}
+          /* The page's own body wrapper, so the site's page-level CSS (width,
+             gutters, rhythm) still applies while editing in place. */
+          pageClassName="page page--layout"
           themeName="default"
           themeRegistry={themeRegistry}
           moduleRegistry={moduleRegistry}
@@ -1969,14 +2048,21 @@ wired in \`app/(site)/[[...slug]]/page.tsx\`). Pages without a layout fall back
 their Body rich text. Reach for the Layout tab when a page needs sections,
 columns, or modules; use the Body for simple prose.
 
-**Front-of-site editor.** Signed in as an admin, append \`?kywi-edit=1\` to any
-public page to edit it in place. You get the full **Layout editor** (the same
-drag-and-drop canvas, module palette and props panel as the admin's Layout tab),
-mounted right over the live page — add sections and modules, then **Save** (PUTs
-the layout) or **Publish** (saves + publishes). Exit the editor for the slim
-browse toolbar with the editable-region outlines. It all lives in
+**Front-of-site editor.** Signed in as an admin, every public page shows a slim
+toolbar across the top — the page title, its draft/published status, **Edit
+this page**, and **Go to admin** (a WordPress-admin-bar equivalent, and the
+primary way to discover in-place editing; there's also an **Edit on site**
+link on each item in the admin content editor, for the reverse direction).
+Click **Edit this page** — or open a page with \`?kywi-edit=1\` as a deep link —
+to get the full **Layout editor** (the same drag-and-drop canvas, module
+palette and props panel as the admin's Layout tab) mounted right over the live
+page: add sections and modules, then **Save** (PUTs the layout) or **Publish**
+(saves + publishes). **Done** returns you to the browse toolbar. Entering or
+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. Note: custom
+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.

package/package.json

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