@soloworks/smking-next 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @soloworks/smking-next
 
+## 0.15.0 — 2026-05-24
+
+**Customer Mode A now consumes Plate-serialized HTML directly — Preview tab = customer site, byte-identical.**
+
+### Architecture flip
+
+SaaS publish handler now runs Plate's `serializeHtml` over the full page (with nav-* snapshots injected) and ships the result as `page.bodyHtml`. `<SmkingCms>` echoes that HTML inside the canonical `.smk-cms` wrapper — no per-block React dispatch when bodyHtml is present. Dashboard Preview tab runs the same Plate plugin chain client-side via PlateStatic, so what the editor sees = what the customer site renders, byte-for-byte (modulo data-* attrs that the publish handler strips post-process).
+
+### Removed (breaking)
+
+- **`CmsThemeMode` type + `mode` prop on `<SmkingCms>`** — Mode B (`tailwind-prose`) dropped. Customers still wanting Tailwind Typography wrap can put a `<article class="prose dark:prose-invert">` around `<SmkingCms>` themselves; typography plugin will style the emitted `<h2>`/`<p>`/`<ul>` etc as normal.
+- **`renderBlockProse` / `renderNavListProse` / `renderNavSearchProse`** helper functions — internal, was the Mode B dispatcher.
+- **`SMKING_CMS_THEME` env var** — ignored; was Mode B selection signal.
+
+### Changed
+
+- `<SmkingCms>` outer wrapper always emits `<article class="smk-cms">`. When `bodyHtml` is null (SaaS deployment that hasn't republished pages since v0.16), falls back to the legacy `renderBlock` switch path so customer pages keep rendering during the rollout window.
+- Always emit canonical `<style data-smking="cms-styles">` (previously gated on Mode A vs Mode B). Conditionally emit `<smking-carousel>` IIFE — now also detected by `<smking-carousel` substring match in bodyHtml.
+
+### Pairs with
+
+- `smking/laravel` v0.16.0 — same Mode B removal + bodyHtml echo path on the Laravel side.
+- `@soloworks/smking-wizard` v0.5.0 — theme-mode-select TUI screen removed alongside the Tailwind plugin install path.
+
+### Customer migration
+
+```bash
+pnpm update @soloworks/smking-next   # → 0.15.0
+```
+
+If you were using Mode B (`SMKING_CMS_THEME=tailwind-prose`):
+
+```tsx
+// Before (v0.14.x)
+<SmkingCms apiKey={...} slug="..." mode="tailwind-prose" />
+
+// After (v0.15.0) — wrap in your own .prose for typography plugin
+<article className="prose dark:prose-invert mx-auto">
+  <SmkingCms apiKey={...} slug="..." />
+</article>
+```
+
+The SDK canonical `<style data-smking="cms-styles">` will still emit; you can either keep both styling layers (typography wins specificity-wise inside `.prose`) or `config('smking.cms.inline_styles', false)` to disable the SDK stylesheet.
+
 ## 0.14.1 — 2026-05-23
 
 **Carousel polish in canonical CSS — nav buttons, dots indicator, image-frame, caption-row + download icon now ship to customer Mode A pages.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/components/smking-cms.tsx

@@ -4,28 +4,11 @@ import { SMKING_ELEMENTS_IIFE } from "../lib/smking-elements-iife";
 import type {
   Block,
   CmsParams,
-  CmsThemeMode,
   ModuleHeader,
   NavSearchIndexEntry,
   NavSnapshotEntry,
 } from "../types";
 
-/**
- * Pick the active theme mode for this render. Precedence:
- *   1. explicit `mode` prop (per-render override)
- *   2. SMKING_CMS_THEME env var (per-deployment default)
- *   3. 'css' (Mode A — the SDK ships its own styles)
- *
- * Wizard auto-detect writes the env var on install; customer can still
- * flip per-page via the prop.
- */
-function resolveThemeMode(modeProp?: CmsThemeMode): CmsThemeMode {
-  if (modeProp === "css" || modeProp === "tailwind-prose") return modeProp;
-  const env = process.env.SMKING_CMS_THEME;
-  if (env === "tailwind-prose") return "tailwind-prose";
-  return "css";
-}
-
 /**
  * Server Component that renders a published smking CMS page.
  *
@@ -59,7 +42,7 @@ function resolveThemeMode(modeProp?: CmsThemeMode): CmsThemeMode {
  * Emits `<title>` / `<meta>` / `og:*` / canonical inline; React 19
  * hoists them into `<head>` automatically.
  */
-export async function SmkingCms(props: CmsParams & { mode?: CmsThemeMode }) {
+export async function SmkingCms(props: CmsParams) {
   const data = await getCmsPage(props);
   if (!data || data.status !== "ready" || !data.page) return null;
 
@@ -69,34 +52,27 @@ export async function SmkingCms(props: CmsParams & { mode?: CmsThemeMode }) {
   // also sets these still overrides ours where present.
   const seo = data.seo;
   const blocks = data.page.blocks ?? [];
-  const mode = resolveThemeMode(props.mode);
-  // Emit the Web Component registration `<script>` once if any block
-  // needs `<smking-carousel>` / `<smking-slide>`. The IIFE is
-  // self-guarded so duplicate emits are harmless; gating here keeps
-  // zero-dep pages truly zero-byte.
-  // Web Component IIFE is needed only when the page actually contains
-  // a `<smking-carousel>`. nav-search emits its own self-contained
-  // inline IIFE (no Web Component registration needed) so we don't gate
-  // on it here.
-  const needsSmkingElements = blocks.some((b) => b.component === "carousel");
+  const bodyHtml = data.page.bodyHtml ?? null;
+  // Emit the Web Component registration `<script>` once when the page
+  // contains a `<smking-carousel>`. With bodyHtml we'd have to parse
+  // the HTML to detect; conservatively check blocks (still emitted for
+  // back-compat) or fall back to always emitting when bodyHtml is
+  // present (cheap — the IIFE is small + self-guarded).
+  const needsSmkingElements =
+    blocks.some((b) => b.component === "carousel") ||
+    (bodyHtml !== null && /<smking-carousel/i.test(bodyHtml));
   // IIFE / CSS sources are hand-authored package constants (not user
   // data) — passing them through __html here is the standard React
   // server-side inline-script / inline-style emit pattern.
   const elementsScript: { __html: string } = { __html: SMKING_ELEMENTS_IIFE };
   const cmsStylesPayload: { __html: string } = { __html: SMKING_CMS_STYLES };
-  // Mode A (`css`) — emit the canonical SDK stylesheet once. Mode B
-  // (`tailwind-prose`) opts the customer's Tailwind + Typography
-  // plugin into rendering and skips this entirely.
-  const shouldEmitInlineStyles = mode === "css";
   return (
     <>
-      {shouldEmitInlineStyles && (
-        <style
-          data-smking="cms-styles"
-          // eslint-disable-next-line react/no-danger -- CSS source is a package constant generated from packages/shared/src/styles/cms-styles.css.
-          dangerouslySetInnerHTML={cmsStylesPayload}
-        />
-      )}
+      <style
+        data-smking="cms-styles"
+        // eslint-disable-next-line react/no-danger -- CSS source is a package constant generated from packages/shared/src/styles/cms-styles.css.
+        dangerouslySetInnerHTML={cmsStylesPayload}
+      />
       {needsSmkingElements && (
         <script
           data-smking="elements"
@@ -129,16 +105,25 @@ export async function SmkingCms(props: CmsParams & { mode?: CmsThemeMode }) {
         <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
       )}
 
-      {mode === "tailwind-prose" ? (
+      {bodyHtml !== null ? (
+        // v0.15+ canonical path — SaaS publish handler ran Plate's
+        // serializeHtml on the entire page (with nav-* snapshots
+        // injected) and ships the result. SDK echoes it inside the
+        // canonical `<article class="smk-cms">` wrapper. Trust boundary:
+        // HTML emitted server-side by Plate from the schema the SaaS
+        // controls — same trust boundary as the legacy article block
+        // path.
         <article
-          className="prose lg:prose-xl dark:prose-invert mx-auto"
+          className="smk-cms"
           data-smking="cms"
           data-content-type={data.page.contentType}
-        >
-          {data.page.title && <h1>{data.page.title}</h1>}
-          {blocks.map((block) => renderBlockProse(block))}
-        </article>
+          // eslint-disable-next-line react/no-danger -- bodyHtml is SaaS-emitted, schema-bounded Plate output. See trust note above.
+          dangerouslySetInnerHTML={{ __html: bodyHtml }}
+        />
       ) : (
+        // Legacy fallback — SaaS hasn't republished the page since the
+        // v0.16 upgrade, so bodyHtml is null. Fall back to the per-block
+        // dispatch path so customer pages keep rendering.
         <article
           className="smk-cms"
           data-smking="cms"
@@ -479,264 +464,3 @@ function formatPublishedAt(iso: string): string {
   }
 }
 
-// ── Mode B (`tailwind-prose`) dispatcher ─────────────────────────────
-//
-// Mirror of `renderBlock` but emits Tailwind utility classes instead
-// of `.smk-*` namespace. The outer `<article class="prose">` wrapper
-// (set up in SmkingCms above) styles `article` blocks automatically;
-// structured blocks (hero/nav/carousel/search) sit inside `not-prose`
-// resets and re-apply Tailwind utility styling.
-//
-// Required Tailwind safelist (the wizard adds these on install):
-//   prose / prose-invert / lg:prose-xl / dark:prose-invert / not-prose
-//   mx-auto / my-* / mt-* / mb-* / px-* / py-* / pt-* / pb-* / p-*
-//   text-* / font-* / tracking-* / leading-*
-//   bg-* / border / border-* / rounded-*
-//   grid / flex / gap-* / items-* / justify-* / space-y-*
-//   w-* / h-* / aspect-*
-function renderBlockProse(block: Block) {
-  switch (block.component) {
-    case "article": {
-      const articleHtml: { __html: string } = { __html: block.props.html };
-      // Article HTML inherits `prose` from the outer wrapper.
-      return (
-        <div
-          key={block.id}
-          data-block-id={block.id}
-          // eslint-disable-next-line react/no-danger -- same trust boundary as renderBlock article case.
-          dangerouslySetInnerHTML={articleHtml}
-        />
-      );
-    }
-    case "hero":
-      return (
-        <section
-          key={block.id}
-          className="not-prose my-12 text-center bg-zinc-50 dark:bg-zinc-900 py-16 px-6 rounded-lg"
-          data-block-id={block.id}
-        >
-          {block.props.image && (
-            <img
-              src={block.props.image.url}
-              alt={block.props.image.alt}
-              className="mx-auto mb-8 rounded-lg max-w-full h-auto"
-              loading="lazy"
-            />
-          )}
-          {block.props.title && (
-            <h2 className="text-4xl md:text-5xl font-serif font-extrabold tracking-tight leading-tight mb-4">
-              {block.props.title}
-            </h2>
-          )}
-          {block.props.subtitle && (
-            <p className="text-sm text-zinc-600 dark:text-zinc-400 mt-6">
-              {block.props.subtitle}
-            </p>
-          )}
-          {block.props.cta && (
-            <a
-              className="inline-block mt-8 px-6 py-3 bg-zinc-900 dark:bg-zinc-100 text-zinc-100 dark:text-zinc-900 rounded font-medium"
-              href={block.props.cta.href}
-            >
-              {block.props.cta.label}
-            </a>
-          )}
-        </section>
-      );
-    case "nav-recent-posts":
-    case "nav-taxonomy-list":
-      return renderNavListProse(block);
-    case "nav-search":
-      return renderNavSearchProse(block);
-    case "carousel": {
-      const aspectClass = (() => {
-        switch (block.props.aspectRatio) {
-          case "4:3":
-            return "aspect-[4/3]";
-          case "1:1":
-            return "aspect-square";
-          case "3:4":
-            return "aspect-[3/4]";
-          case "9:16":
-            return "aspect-[9/16]";
-          default:
-            return "aspect-video";
-        }
-      })();
-      return (
-        <section
-          key={block.id}
-          className="not-prose my-8"
-          data-block-id={block.id}
-        >
-          <div className="grid grid-flow-col auto-cols-[80%] md:auto-cols-[60%] gap-4 overflow-x-auto snap-x snap-mandatory pb-2 -mx-6 px-6">
-            {block.props.slides.map((slide, i) => (
-              <div
-                key={i}
-                className="snap-start bg-zinc-100 dark:bg-zinc-900 rounded-lg overflow-hidden"
-              >
-                {slide.imageUrl && (
-                  <img
-                    src={slide.imageUrl}
-                    alt=""
-                    className={`w-full ${aspectClass} object-cover block`}
-                    loading="lazy"
-                  />
-                )}
-                {slide.caption && (
-                  <div className="px-4 py-3 text-sm text-zinc-500 dark:text-zinc-400">
-                    {slide.caption}
-                  </div>
-                )}
-              </div>
-            ))}
-          </div>
-        </section>
-      );
-    }
-    default:
-      // Unknown component — render nothing in Mode B.
-      return null;
-  }
-}
-
-function renderNavListProse(
-  block: Extract<
-    Block,
-    { component: "nav-recent-posts" | "nav-taxonomy-list" }
-  >,
-) {
-  const snapshot: NavSnapshotEntry[] = block.props.snapshot ?? [];
-  const layout = block.props.layout ?? "list";
-  const heading = (block.props as ModuleHeader).heading;
-  const viewAll = (block.props as ModuleHeader).viewAll;
-
-  const listClass =
-    layout === "grid"
-      ? "grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-5 list-none p-0 m-0"
-      : layout === "carousel"
-        ? "grid grid-flow-col auto-cols-[70%] md:auto-cols-[40%] gap-4 list-none p-0 m-0 overflow-x-auto snap-x snap-mandatory"
-        : "flex flex-col list-none p-0 m-0";
-
-  return (
-    <section
-      key={block.id}
-      className="not-prose my-10 border-t border-zinc-200 dark:border-zinc-800 pt-8"
-      data-block-id={block.id}
-    >
-      {heading && (
-        <h2 className="text-xs font-bold uppercase tracking-widest text-zinc-500 dark:text-zinc-400 mb-6">
-          {heading}
-        </h2>
-      )}
-      {snapshot.length === 0 ? (
-        <p className="text-zinc-400 italic py-4">No posts yet.</p>
-      ) : (
-        <ul className={listClass}>
-          {snapshot.map((entry) => {
-            const itemClass =
-              layout === "grid"
-                ? "group"
-                : layout === "carousel"
-                  ? "snap-start bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 rounded-lg overflow-hidden"
-                  : "border-t border-zinc-200 dark:border-zinc-800 first:border-t-0";
-            const linkClass =
-              layout === "grid"
-                ? "flex flex-col bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 rounded-lg overflow-hidden no-underline text-inherit hover:-translate-y-0.5 hover:shadow-lg transition"
-                : layout === "carousel"
-                  ? "flex flex-col no-underline text-inherit"
-                  : "flex gap-5 items-center py-5 no-underline text-inherit hover:opacity-80 transition";
-            const thumbClass =
-              layout === "list"
-                ? "w-24 h-24 object-cover rounded shrink-0 bg-zinc-100 dark:bg-zinc-900"
-                : "w-full aspect-[16/10] object-cover bg-zinc-100 dark:bg-zinc-900";
-            const metaClass = layout === "list" ? "flex-1 min-w-0" : "p-4";
-            return (
-              <li key={entry.slug} className={itemClass}>
-                <a href={`/${entry.slug}`} className={linkClass}>
-                  {entry.featuredImageUrl && (
-                    <img
-                      src={entry.featuredImageUrl}
-                      alt=""
-                      className={thumbClass}
-                      loading="lazy"
-                    />
-                  )}
-                  <div className={metaClass}>
-                    <h3 className="text-lg font-serif font-bold leading-snug mb-2 tracking-tight">
-                      {entry.title || entry.slug}
-                    </h3>
-                    {entry.excerpt && (
-                      <p className="text-sm text-zinc-500 dark:text-zinc-400 line-clamp-2 leading-relaxed">
-                        {entry.excerpt}
-                      </p>
-                    )}
-                    {entry.publishedAt && (
-                      <time
-                        className="block text-xs text-zinc-400 mt-2 uppercase tracking-wider"
-                        dateTime={entry.publishedAt}
-                      >
-                        {formatPublishedAt(entry.publishedAt)}
-                      </time>
-                    )}
-                  </div>
-                </a>
-              </li>
-            );
-          })}
-        </ul>
-      )}
-      {viewAll && (
-        <a
-          className="inline-flex items-center gap-1 mt-6 text-sm font-semibold text-zinc-900 dark:text-zinc-100 no-underline hover:underline"
-          href={viewAll.href}
-        >
-          {viewAll.label} <span aria-hidden>→</span>
-        </a>
-      )}
-    </section>
-  );
-}
-
-function renderNavSearchProse(
-  block: Extract<Block, { component: "nav-search" }>,
-) {
-  const index: NavSearchIndexEntry[] = block.props.index ?? [];
-  const placeholder = block.props.placeholder || "Search…";
-  const indexJson = JSON.stringify(index).replace(/</g, "\\u003c");
-  const scriptSrc =
-    "(function(){var s=document.currentScript;var r=s&&s.previousElementSibling;if(!r)return;var i=r.querySelector('[data-smk-search-input]');var u=r.querySelector('[data-smk-search-results]');var e=r.querySelector('[data-smk-search-empty]');var idx=" +
-    indexJson +
-    ";function up(){var q=(i.value||'').trim().toLowerCase();u.textContent='';if(!q){u.hidden=true;e.hidden=true;return}var m=idx.filter(function(x){return((x.title||'')+' '+(x.excerpt||'')+' '+(x.slug||'')).toLowerCase().indexOf(q)>=0}).slice(0,20);if(m.length===0){u.hidden=true;e.hidden=false;return}e.hidden=true;u.hidden=false;m.forEach(function(x){var li=document.createElement('li');li.className='border-t border-zinc-200 dark:border-zinc-800 first:border-t-0';var a=document.createElement('a');a.href='/'+x.slug;a.className='block px-4 py-3 text-zinc-900 dark:text-zinc-100 no-underline hover:bg-zinc-50 dark:hover:bg-zinc-900';a.textContent=x.title||x.slug;li.appendChild(a);u.appendChild(li)})}i.addEventListener('input',up)})();";
-
-  return (
-    <section
-      key={block.id}
-      className="not-prose my-8 border-t border-zinc-200 dark:border-zinc-800 pt-6"
-      data-block-id={block.id}
-    >
-      <div className="relative">
-        <input
-          type="search"
-          data-smk-search-input
-          placeholder={placeholder}
-          className="w-full px-4 py-3 border border-zinc-200 dark:border-zinc-800 rounded-lg bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100 text-base focus:outline-none focus:border-zinc-900 dark:focus:border-zinc-100 focus:ring-4 focus:ring-zinc-900/10 dark:focus:ring-zinc-100/10 transition"
-        />
-        <ul
-          data-smk-search-results
-          hidden
-          className="list-none p-0 mt-3 border border-zinc-200 dark:border-zinc-800 rounded-lg bg-white dark:bg-zinc-900 overflow-hidden shadow-lg"
-        />
-        <p
-          data-smk-search-empty
-          hidden
-          className="text-zinc-400 pt-4 text-sm"
-        >
-          No matches.
-        </p>
-      </div>
-      {/* eslint-disable-next-line react/no-danger -- inline IIFE; index JSON-escaped against </script> smuggling. */}
-      <script dangerouslySetInnerHTML={{ __html: scriptSrc }} />
-    </section>
-  );
-}

package/src/types.ts

@@ -58,24 +58,10 @@ export type CmsStatus = "ready" | "pending" | "not_found";
 
 export type CmsContentType = "article" | "landing" | "listing";
 
-/**
- * Theme mode (v0.14+) — decides how `<SmkingCms>` ships styling.
- *
- * - `'css'` (Mode A, default) — SDK inlines the canonical
- *   `<style data-smking="cms-styles">` once per render plus emits
- *   `.smk-*` class hooks on every block. Zero dependency on Tailwind.
- *   Customers theme via CSS variable overrides (`:root { --smk-accent: … }`).
- *
- * - `'tailwind-prose'` (Mode B) — SDK skips the inline stylesheet,
- *   wraps the article in `<article class="prose dark:prose-invert">`
- *   and emits Tailwind utility classes on each block. Customer must
- *   have `@tailwindcss/typography` plugin wired up and the required
- *   classes safelisted (the wizard does this on install).
- *
- * Resolution order: explicit `<SmkingCms mode>` prop → `SMKING_CMS_THEME`
- * env var → 'css'.
- */
-export type CmsThemeMode = "css" | "tailwind-prose";
+// `CmsThemeMode` removed in v0.15.0 — Mode B (`tailwind-prose`) dropped
+// in favour of the canonical Plate-serialized HTML render (Mode A only).
+// Customers still wanting Tailwind Typography wrap can put a
+// `<article class="prose">` around `<SmkingCms>` themselves.
 
 /**
  * v2 substrate block primitives. Mirrors `apps/web/src/features/cms/types.ts`
@@ -193,6 +179,14 @@ export interface CmsPage {
   slug: string;
   title: string;
   contentType: CmsContentType;
+  /**
+   * v0.15+ canonical render — full Plate-serialized HTML for the
+   * published page. Customer SDK Mode A echoes this directly via
+   * raw-HTML escape hatch. Nullable when the page hasn't been
+   * republished since the SaaS publish-handler v0.16 upgrade
+   * (SDK falls back to `blocks` Block[] dispatch in that case).
+   */
+  bodyHtml?: string | null;
   blocks: Block[];
   excerpt?: string | null;
   featuredImageUrl?: string | null;