@soloworks/smking-next 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @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.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.15.0",
+  "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,13 +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,
-  ModuleHeader,
-  NavSearchIndexEntry,
-  NavSnapshotEntry,
-} from "../types";
+import type { CmsParams } from "../types";
 
 /**
  * Server Component that renders a published smking CMS page.
@@ -20,21 +12,22 @@ import type {
  *   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.
@@ -46,40 +39,14 @@ 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 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 };
+  const bodyHtml = data.page.bodyHtml ?? "";
+
   return (
     <>
-      <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
@@ -105,362 +72,20 @@ export async function SmkingCms(props: CmsParams) {
         <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
       )}
 
-      {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="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}
-          // eslint-disable-next-line react/no-danger -- bodyHtml is SaaS-emitted, schema-bounded Plate output. See trust note above.
+          // eslint-disable-next-line react/no-danger -- 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"
-          data-content-type={data.page.contentType}
-        >
-          {data.page.title && (
-            <h1 className="smk-cms__title">{data.page.title}</h1>
-          )}
-          {blocks.map((block) => renderBlock(block))}
-        </article>
-      )}
+      ) : null}
     </>
   );
 }
-
-/**
- * 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}
-        />
-      );
-  }
-}
-
-// ── 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);
-  }
-}
-

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;
   }