@soloworks/smking-next 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @soloworks/smking-next
 
+## 0.16.0 — 2026-05-24
+
+**Raw passthrough render — `<SmkingCms>` now echoes the full Plate-serialized bodyHtml exactly, no `<article class="smk-cms">` wrapper and no inline CSS injection.**
+
+### What changed
+
+Companion release to a SaaS-side simplification: the publish pipeline now calls Plate's stock `serializeHtml(editor)` with no options — preserving the full class chain (Tailwind utility from the dashboard cva variants + `slate-*` hook classes + `data-slate-*` attrs) instead of running an in-house `stripPlateNoise()` post-process. `<SmkingCms>` mirrors that posture: drop the wrapper, drop the canonical CSS inject, let bodyHtml render exactly as the dashboard Edit / Preview tabs render it.
+
+### Removed (breaking)
+
+- **`<article class="smk-cms">` shell wrapper** — replaced with a plain `<div data-smking="cms">`. Customer sites that depended on `.smk-cms` for layout (max-width / padding) need to reapply that themselves.
+- **Inline canonical CSS injection** — gone. Customer sites that rely on the canonical block CSS must now ship it themselves (the constant `SMKING_CMS_STYLES` is still exported from `lib/smking-cms-styles` for sites that want to opt in).
+- **Block[] dispatch path** — `renderBlock` + `renderNavList` + `renderNavSearch` + `formatPublishedAt` helpers (~325 lines) removed. Pages still on the legacy `page.blocks` shape will not render until the SaaS re-publishes them (every page since v0.15 has a bodyHtml field, so this only affects truly ancient drafts that have not been touched in months).
+- **Smking Web Component IIFE injection** — `<smking-carousel>` registration script is no longer auto-emitted. Customer sites with carousel blocks need to ship their own registration; the IIFE constant remains exported from `lib/smking-elements-iife` for sites that want to inline it manually.
+
+### Why
+
+Dashboard now publishes the same Plate output the Edit canvas renders. Wrapping that markup in a separate "customer article shell" with its own typography tokens broke the WYSIWYG promise — author saw one thing in the editor, customer saw another. Raw passthrough makes the contract unambiguous: bodyHtml is the source of truth, customer site owns layout.
+
+### Migration
+
+If your customer site relied on the `.smk-cms` shell or the canonical CSS inject, ship them at the customer side before bumping — import `SMKING_CMS_STYLES` from `@soloworks/smking-next/lib/smking-cms-styles` and emit it via a `<style>` tag, then wrap `<SmkingCms>` in your own `<article className="smk-cms">`. For Tailwind sites: utility classes in bodyHtml (`text-4xl`, `font-bold`, etc.) resolve natively — no extra step needed.
+
+## 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.16.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

@@ -1,30 +1,5 @@
 import { getCmsPage } from "../lib/cms-client";
-import { SMKING_CMS_STYLES } from "../lib/smking-cms-styles";
-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";
-}
+import type { CmsParams } from "../types";
 
 /**
  * Server Component that renders a published smking CMS page.
@@ -37,21 +12,22 @@ function resolveThemeMode(modeProp?: CmsThemeMode): CmsThemeMode {
  *   return (
  *     <SmkingCms
  *       apiKey={process.env.SMKING_API_KEY!}
- *       slug="hello"
+ *       slug=""              // root → /blog landing
  *     />
  *   );
  * }
  * ```
  *
- * v0.11+ substrate pivot: fetches a Block[] array and dispatches each
- * block by `component`. Article block carries pre-rendered HTML
- * (server-rendered at write time via Plate's `serializeHtml`, so the
- * customer SDK needs zero editor dependencies). Hero / carousel render
- * inline. Dynamic nav-* blocks (`nav-recent-posts` /
- * `nav-taxonomy-list` / `nav-search`) carry a publish-time materialized
- * `snapshot` (or `index`) embedded in their props — SDK echoes that
- * directly, zero round-trip back to smking. If smking is down, the
- * customer's page still renders the last published snapshot.
+ * **Raw passthrough mode** — echoes the full Plate-serialized bodyHtml
+ * exactly as the SaaS publish handler emits it (Tailwind utility
+ * classes + `slate-*` hook classes + `data-slate-*` attrs all
+ * intact). The component itself does NOT wrap the markup in an
+ * `<article>` shell or inject canonical CSS — what the dashboard
+ * Edit / Preview tabs render is what reaches the customer page. If
+ * your customer site uses Tailwind, the utility classes resolve
+ * natively; otherwise you can ship `cms-styles.css` (still exported
+ * from this package via `lib/smking-cms-styles`) alongside, which
+ * targets `.slate-*` hooks in plain CSS.
  *
  * Returns null when the response isn't ready (pending / not_found /
  * unreachable / mis-configured) — fail-open by design.
@@ -59,51 +35,18 @@ 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;
 
-  // v0.11+ — emit SEO head tags inline. React 19 hoists `<title>` and
-  // `<meta>` tags found anywhere in the tree into `<head>` automatically
-  // (last write wins on duplicate tags), so a deeper layout / page that
-  // also sets these still overrides ours where present.
+  // SEO head tags emit inline. React 19 hoists `<title>` and `<meta>`
+  // tags found anywhere in the tree into `<head>` automatically (last
+  // write wins on duplicates).
   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");
-  // 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";
+  const bodyHtml = data.page.bodyHtml ?? "";
+
   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}
-        />
-      )}
-      {needsSmkingElements && (
-        <script
-          data-smking="elements"
-          // eslint-disable-next-line react/no-danger -- IIFE source is a package constant.
-          dangerouslySetInnerHTML={elementsScript}
-        />
-      )}
       {seo?.title && <title data-smking="cms">{seo.title}</title>}
       {seo?.metaDescription && (
         <meta
@@ -129,614 +72,20 @@ export async function SmkingCms(props: CmsParams & { mode?: CmsThemeMode }) {
         <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
       )}
 
-      {mode === "tailwind-prose" ? (
-        <article
-          className="prose lg:prose-xl dark:prose-invert mx-auto"
-          data-smking="cms"
-          data-content-type={data.page.contentType}
-        >
-          {data.page.title && <h1>{data.page.title}</h1>}
-          {blocks.map((block) => renderBlockProse(block))}
-        </article>
-      ) : (
-        <article
-          className="smk-cms"
+      {/* Raw passthrough — bodyHtml is SaaS-emitted Plate output (Tailwind
+          utility + slate-* hooks + data-slate-* attrs all intact). No
+          article shell, no canonical CSS injection: what the dashboard
+          renders is what the customer page renders. Trust boundary:
+          schema-bounded Plate serialize on the SaaS side, same posture
+          as the previous wrapped version. */}
+      {bodyHtml ? (
+        <div
           data-smking="cms"
           data-content-type={data.page.contentType}
-        >
-          {data.page.title && (
-            <h1 className="smk-cms__title">{data.page.title}</h1>
-          )}
-          {blocks.map((block) => renderBlock(block))}
-        </article>
-      )}
-    </>
-  );
-}
-
-/**
- * Dispatch a single block to its rendered React element.
- *
- * Trust boundary for `article` blocks: HTML is rendered server-side at
- * write time by `@tiptap/html/server` inside the SaaS (Tiptap's renderer
- * only emits HTML for known nodes per the configured schema, so author
- * input can't smuggle arbitrary tags through). Customer site renders
- * that HTML as-is via React's raw-HTML escape hatch. If customer wants
- * defence-in-depth beyond the SaaS sanitisation tier, layer CSP on
- * their host page (smking SDK does not ship a customer-side sanitiser
- * to keep zero-dep customer install).
- */
-function renderBlock(block: Block) {
-  switch (block.component) {
-    case "article": {
-      const articleHtml: { __html: string } = { __html: block.props.html };
-      return (
-        <div
-          key={block.id}
-          className="smk-block smk-block--article"
-          data-block-id={block.id}
-          // eslint-disable-next-line react/no-danger -- HTML pre-rendered server-side via @tiptap/html/server; trust boundary = SaaS schema. See function-level doc-comment above.
-          dangerouslySetInnerHTML={articleHtml}
-        />
-      );
-    }
-    case "hero":
-      return (
-        <section
-          key={block.id}
-          className="smk-block smk-block--hero smk-hero"
-          data-block-id={block.id}
-        >
-          {block.props.image && (
-            <img
-              src={block.props.image.url}
-              alt={block.props.image.alt}
-              className="smk-hero__image"
-            />
-          )}
-          <h2 className="smk-hero__title">{block.props.title}</h2>
-          {block.props.subtitle && (
-            <p className="smk-hero__subtitle">{block.props.subtitle}</p>
-          )}
-          {block.props.cta && (
-            <a className="smk-hero__cta" href={block.props.cta.href}>
-              {block.props.cta.label}
-            </a>
-          )}
-        </section>
-      );
-    case "carousel": {
-      // Canonical `<smking-carousel>` markup — the Web Component
-      // registered by `SMKING_ELEMENTS_IIFE` upgrades this into a
-      // swipe + nav + dots carousel on the client. Custom-element
-      // tags aren't in React's JSX intrinsic types by default; cast
-      // through a string ref so we don't need a global d.ts in the
-      // customer's package.
-      const CustomCarousel = "smking-carousel" as unknown as "section";
-      const CustomSlide = "smking-slide" as unknown as "div";
-      const aspect = block.props.aspectRatio ?? "16:9";
-      return (
-        <CustomCarousel
-          key={block.id}
-          className="smk-block smk-block--carousel smk-carousel"
-          data-block-id={block.id}
-          data-aspect={aspect}
-        >
-          <div className="smk-carousel__viewport">
-            {block.props.slides.map((slide, i) => (
-              <CustomSlide key={i}>
-                <div className="smk-carousel__image-frame">
-                  {slide.imageUrl ? (
-                    <img
-                      src={slide.imageUrl}
-                      alt=""
-                      className="smk-carousel__image"
-                    />
-                  ) : (
-                    <div className="smk-carousel__image smk-carousel__image--placeholder" />
-                  )}
-                </div>
-                <div className="smk-carousel__caption-row">
-                  <div className="smk-carousel__caption">{slide.caption}</div>
-                  {slide.imageUrl ? (
-                    <a
-                      className="smk-carousel__download"
-                      href={slide.imageUrl}
-                      download
-                      aria-label="Download image"
-                    >
-                      <svg
-                        width="14"
-                        height="14"
-                        viewBox="0 0 24 24"
-                        fill="none"
-                        stroke="currentColor"
-                        strokeWidth={2.4}
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        aria-hidden
-                      >
-                        <path d="M12 5v14M5 12l7 7 7-7" />
-                      </svg>
-                    </a>
-                  ) : null}
-                </div>
-              </CustomSlide>
-            ))}
-          </div>
-          <button
-            type="button"
-            className="smk-carousel__nav-prev"
-            aria-label="Previous slide"
-          >
-            <svg
-              width="16"
-              height="16"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth={2.4}
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              aria-hidden
-            >
-              <path d="M15 18l-6-6 6-6" />
-            </svg>
-          </button>
-          <button
-            type="button"
-            className="smk-carousel__nav-next"
-            aria-label="Next slide"
-          >
-            <svg
-              width="16"
-              height="16"
-              viewBox="0 0 24 24"
-              fill="none"
-              stroke="currentColor"
-              strokeWidth={2.4}
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              aria-hidden
-            >
-              <path d="M9 6l6 6-6 6" />
-            </svg>
-          </button>
-          <div className="smk-carousel__dots" />
-        </CustomCarousel>
-      );
-    }
-    case "nav-recent-posts":
-      return renderNavList(block, "smk-nav-recent-posts");
-    case "nav-taxonomy-list":
-      return renderNavList(block, "smk-nav-taxonomy-list");
-    case "nav-search":
-      return renderNavSearch(block);
-    default:
-      // Forward-compat: unknown block component — emit empty marker
-      // so the page renders. Better than throwing.
-      return (
-        <section
-          key={(block as { id: string }).id}
-          className="smk-block smk-block--unknown"
-          data-block-component={(block as { component: string }).component}
+          // eslint-disable-next-line react/no-danger -- see trust note above.
+          dangerouslySetInnerHTML={{ __html: bodyHtml }}
         />
-      );
-  }
-}
-
-// ── nav-* render helpers ─────────────────────────────────────────────
-
-/**
- * Card-list render for `nav-recent-posts` + `nav-taxonomy-list`. Both
- * blocks expose the same `{heading, viewAll, layout, snapshot}` shape;
- * only the source of the snapshot differs (resolver-side concern, not
- * SDK-side). The `layout` prop drives the wrapper's `data-layout` attr
- * so customer CSS can style list / grid / carousel variants. Default
- * styling ships sufficient base CSS for the list variant to be usable
- * without customer overrides.
- *
- * Slugs in the snapshot are stored without leading slash (matching the
- * `productContent.slug` DB column); we prepend one when forming hrefs.
- * Customer's catch-all route at `/[...slug]` resolves them.
- */
-function renderNavList(
-  block: Extract<
-    Block,
-    { component: "nav-recent-posts" | "nav-taxonomy-list" }
-  >,
-  baseClass: string,
-) {
-  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;
-
-  return (
-    <section
-      key={block.id}
-      className={`smk-block smk-block--${block.component} smk-nav ${baseClass}`}
-      data-block-id={block.id}
-      data-block-component={block.component}
-      data-layout={layout}
-    >
-      {heading && <h2 className="smk-nav__heading">{heading}</h2>}
-      {snapshot.length === 0 ? (
-        <p className="smk-nav__empty">No posts yet.</p>
-      ) : (
-        <ul className="smk-nav__list">
-          {snapshot.map((entry) => (
-            <li key={entry.slug} className="smk-nav__item">
-              <a href={`/${entry.slug}`} className="smk-nav__link">
-                {entry.featuredImageUrl && (
-                  <img
-                    src={entry.featuredImageUrl}
-                    alt=""
-                    className="smk-nav__thumb"
-                    loading="lazy"
-                  />
-                )}
-                <div className="smk-nav__meta">
-                  <h3 className="smk-nav__title">
-                    {entry.title || entry.slug}
-                  </h3>
-                  {entry.excerpt && (
-                    <p className="smk-nav__excerpt">{entry.excerpt}</p>
-                  )}
-                  {entry.publishedAt && (
-                    <time
-                      className="smk-nav__date"
-                      dateTime={entry.publishedAt}
-                    >
-                      {formatPublishedAt(entry.publishedAt)}
-                    </time>
-                  )}
-                </div>
-              </a>
-            </li>
-          ))}
-        </ul>
-      )}
-      {viewAll && (
-        <a className="smk-nav__view-all" href={viewAll.href}>
-          {viewAll.label}
-        </a>
-      )}
-    </section>
-  );
-}
-
-/**
- * `nav-search` ships a server-rendered `<input>` + result `<ul>`, then
- * an inline IIFE that wires keystroke → filter → list mutate. Zero
- * client-component dependency on the customer side (no React hydration,
- * no use client boundary). Index lives in DOM via `JSON.stringify` with
- * `</` escape — prevents `</script>` smuggling.
- *
- * Match algorithm: case-insensitive substring against `title`, `excerpt`,
- * and `slug`. Top 20 results shown. Customer can override the script by
- * shipping their own `<SmkingSearch>` component if they want fancier
- * matching (fuzzy, stemming, weighting).
- */
-function renderNavSearch(
-  block: Extract<Block, { component: "nav-search" }>,
-) {
-  const index: NavSearchIndexEntry[] = block.props.index ?? [];
-  const placeholder = block.props.placeholder || "Search…";
-
-  // Escape `</` so the JSON payload can't terminate the surrounding
-  // <script> tag — standard React-docs-recommended JSON-in-script
-  // hardening, since we serialize titles / excerpts that came from
-  // arbitrary author input.
-  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='smk-nav-search__result';var a=document.createElement('a');a.href='/'+x.slug;a.textContent=x.title||x.slug;li.appendChild(a);u.appendChild(li)})}i.addEventListener('input',up)})();";
-
-  return (
-    <section
-      key={block.id}
-      className="smk-block smk-block--nav-search smk-nav-search"
-      data-block-id={block.id}
-    >
-      <div className="smk-nav-search__shell">
-        <input
-          type="search"
-          data-smk-search-input
-          placeholder={placeholder}
-          className="smk-nav-search__input"
-        />
-        <ul
-          data-smk-search-results
-          hidden
-          className="smk-nav-search__list"
-        />
-        <p
-          data-smk-search-empty
-          hidden
-          className="smk-nav-search__empty"
-        >
-          No matches.
-        </p>
-      </div>
-      {/* eslint-disable-next-line react/no-danger -- inline IIFE wires search filter; index is JSON-escaped against </script> smuggling. */}
-      <script dangerouslySetInnerHTML={{ __html: scriptSrc }} />
-    </section>
-  );
-}
-
-/**
- * Best-effort locale-naive date render. SDK doesn't ship a date library;
- * customer can override via CSS / their own `<SmkingCms>` wrapper if
- * they need a specific format / timezone.
- */
-function formatPublishedAt(iso: string): string {
-  try {
-    return new Date(iso).toLocaleDateString();
-  } catch {
-    return iso.slice(0, 10);
-  }
-}
-
-// ── 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>
+      ) : null}
+    </>
   );
 }

package/src/lib/cms-client.ts

@@ -61,10 +61,13 @@ export async function getCmsPage(
     return null;
   }
 
-  if (!params.slug) {
+  // Root page is `slug=""` (empty string), customer mounts it at e.g.
+  // `/blog`. Only reject `undefined` / `null` — empty string is valid
+  // and routes to the site's root page row in `productContent`.
+  if (params.slug === undefined || params.slug === null) {
     warnOnce(
       "missing-slug",
-      "[@soloworks/smking-next/cms] slug prop is required.",
+      "[@soloworks/smking-next/cms] slug prop is required (use \"\" for the root page).",
     );
     return null;
   }

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;