@soloworks/smking-next 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @soloworks/smking-next
 
+## 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.**
+
+### Added
+
+- `packages/shared/src/styles/cms-styles.css` (regenerated into `SMKING_CMS_STYLES` const) now carries the full Apple-newsroom-style carousel CSS: container-query-anchored nav buttons (vertical centre tracks the image height across all 5 aspect ratios), per-slide `image-frame` with placeholder state, caption-row with download icon affordance, dots indicator with active state. Same rules the smking dashboard preview already used — bringing customer parity.
+- Carousel works identically regardless of whether the Web Component IIFE has upgraded the markup: CSS positions everything relative to the `<smking-carousel>` container query, so static HTML renders just as well as the JS-upgraded interactive variant.
+
+### Pairs with
+
+- `smking/laravel` v0.15.1 — same canonical CSS payload (identical sha256), Laravel `<x-smking-cms />` Mode A render picks up the polish automatically on view-cache clear.
+
+### Customer
+
+```bash
+pnpm update @soloworks/smking-next   # → 0.14.1
+```
+
+No code change required. Existing `<SmkingCms>` Mode A renders get nav / dots / image-frame styling on the next page load.
+
+## 0.14.0 — 2026-05-23
+
+**Single-source CSS distribution + theme mode toggle.** `<SmkingCms>` now ships its own polished default styles by default — no customer CSS work needed. Customers who already use Tailwind + `@tailwindcss/typography` can flip to a prose-utility markup variant via the `mode` prop or `SMKING_CMS_THEME` env var.
+
+### Added
+
+- **Mode A (`css`, default)** — `<SmkingCms>` emits a `<style data-smking="cms-styles">` block once per render carrying the canonical SDK stylesheet. Class hooks `.smk-cms` / `.smk-block--*` / `.smk-hero` / `.smk-nav` / `.smk-carousel`. Customer themes via CSS variables on `:root` (`--smk-accent`, `--smk-font-serif`, etc).
+- **Mode B (`tailwind-prose`)** — opt-in via `<SmkingCms mode="tailwind-prose" ... />` or `SMKING_CMS_THEME=tailwind-prose` env var. Wraps the article in `<article class="prose dark:prose-invert">` and emits Tailwind utility classes on every block (`not-prose` resets around hero/nav/carousel/search). Requires the customer's `@tailwindcss/typography` plugin and a tailwind safelist (the `@soloworks/smking-wizard` 0.4+ installs both automatically).
+- **`CmsThemeMode` type export** — discriminated string literal `'css' | 'tailwind-prose'` for typed prop usage.
+- **`SMKING_CMS_STYLES` constant** at `@soloworks/smking-next/lib/smking-cms-styles` — auto-generated from `packages/shared/src/styles/cms-styles.css` via the monorepo `pnpm sync:cms-styles` script. Customers who want to ship the SDK stylesheet as a standalone CSS file (CDN / static asset) can copy this constant verbatim.
+
+### Changed
+
+- `SmkingCms` props now accept `mode?: CmsThemeMode` alongside the existing `CmsParams`. No breaking change — omitted prop defaults to `'css'` (legacy behavior plus the new inline style block).
+
+### Pairs with
+
+- `smking/laravel` v0.15.0 — identical theme-mode toggle on the Laravel side. Both SDKs ship byte-identical canonical CSS in Mode A; Mode B markup also mirrors across both runtimes.
+- `@soloworks/smking-wizard` v0.4.0 — install-time Tailwind detect + theme-mode-select TUI step. When Tailwind is detected the wizard offers Mode B and installs `@tailwindcss/typography` + safelist patches automatically.
+
 ## 0.13.0 — 2026-05-22
 
 **Dynamic CMS blocks — `nav-recent-posts`, `nav-taxonomy-list`, `nav-search` now render with real publish-time data.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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,31 @@
 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";
+}
+
 /**
  * Server Component that renders a published smking CMS page.
  *
@@ -41,7 +59,7 @@ import type {
  * Emits `<title>` / `<meta>` / `og:*` / canonical inline; React 19
  * hoists them into `<head>` automatically.
  */
-export async function SmkingCms(props: CmsParams) {
+export async function SmkingCms(props: CmsParams & { mode?: CmsThemeMode }) {
   const data = await getCmsPage(props);
   if (!data || data.status !== "ready" || !data.page) return null;
 
@@ -51,6 +69,7 @@ export async function SmkingCms(props: CmsParams) {
   // 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
@@ -60,12 +79,24 @@ export async function SmkingCms(props: CmsParams) {
   // inline IIFE (no Web Component registration needed) so we don't gate
   // on it here.
   const needsSmkingElements = blocks.some((b) => b.component === "carousel");
-  // IIFE source is a hand-authored package constant (not user data) —
-  // wrapping in __html here is the standard React server-side script
-  // emit pattern used elsewhere in this SDK for the article block.
+  // 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}
+        />
+      )}
       {needsSmkingElements && (
         <script
           data-smking="elements"
@@ -98,16 +129,27 @@ export async function SmkingCms(props: CmsParams) {
         <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
       )}
 
-      <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>
+      {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"
+          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>
+      )}
     </>
   );
 }
@@ -436,3 +478,265 @@ function formatPublishedAt(iso: string): string {
     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>
+  );
+}

package/src/lib/smking-cms-styles.ts

@@ -0,0 +1,704 @@
+/**
+ * AUTO-GENERATED - do not edit by hand.
+ * Source:  packages/shared/src/styles/cms-styles.css
+ * Sync:    pnpm sync:cms-styles
+ * Hash:    f555c5fed446
+ *
+ * Inlined by <SmkingCms> (smking-cms.tsx) inside a
+ *   <style data-smking="cms-styles"> ... </style>
+ * tag exactly once per page render. Mode A only; Mode B
+ * ("tailwind-prose") skips this entirely.
+ */
+export const SMKING_CMS_STYLES = `/*
+ * smking CMS — canonical block styles (Mode A "css")
+ *
+ * Single source of truth for all customer-facing CMS render styling.
+ * Consumed at build time by \`scripts/sync-cms-styles.mjs\` which emits:
+ *   - packages/smking-next/src/lib/smking-cms-styles.ts  (TS const)
+ *   - packages/smking-laravel/resources/views/cms-styles.blade.php  (Blade)
+ *
+ * The dashboard imports the same file directly via Next.js workspace
+ * alias so what the editor preview shows = what the customer site renders
+ * (WYSIWYG strict per boss original spec).
+ *
+ * Mode B (\`tailwind-prose\`) customers do NOT load this file — their
+ * Tailwind + @tailwindcss/typography plugin replaces all styles below.
+ *
+ * Namespacing rules (cross-platform parity):
+ *   - All selectors are scoped to \`.smk-cms\` or \`.smk-block--*\` — no
+ *     global element rules (\`h1 {}\` \`p {}\`) so SDK styles never leak
+ *     into customer's other page sections.
+ *   - Wrapped in \`@layer smking-cms\` so customer CSS authoring with
+ *     Tailwind \`@layer base|components|utilities\` has predictable order.
+ *   - Tokens on \`.smk-cms\` (CSS variables) — customer overrides via
+ *     \`:root { --smk-accent: …; }\` or per-instance.
+ *
+ * Edit invariants:
+ *   1. Never write a global element selector.
+ *   2. Always declare variants via \`[data-*]\` attribute selectors — the
+ *      SDK markup emits the attributes; CSS reads them. No hard-coded
+ *      ratios / layouts / colors.
+ *   3. Test against Mode A's class hooks: smk-cms / smk-block--{type} /
+ *      smk-hero / smk-nav / smk-nav-search / smk-carousel.
+ */
+
+@layer smking-cms {
+  /* ============================================================
+     Design tokens — customer overrides on :root or .smk-cms
+     ============================================================ */
+  .smk-cms {
+    --smk-fg: #0a0a0a;
+    --smk-fg-muted: #525252;
+    --smk-fg-subtle: #a3a3a3;
+    --smk-bg: #fff;
+    --smk-bg-soft: #fafafa;
+    --smk-border: #e5e5e5;
+    --smk-border-strong: #d4d4d4;
+    --smk-accent: #0a0a0a;
+    --smk-accent-fg: #fff;
+    --smk-radius-sm: 6px;
+    --smk-radius-md: 10px;
+    --smk-radius-lg: 16px;
+    --smk-section-gap: 4rem;
+    --smk-font-serif: ui-serif, Georgia, "Iowan Old Style", "Apple Garamond",
+      "Times New Roman", serif;
+    --smk-font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI",
+      "PingFang TC", "Noto Sans CJK TC", "Microsoft JhengHei", sans-serif;
+  }
+  @media (prefers-color-scheme: dark) {
+    .smk-cms {
+      --smk-fg: #f5f5f5;
+      --smk-fg-muted: #a3a3a3;
+      --smk-fg-subtle: #525252;
+      --smk-bg: #0a0a0a;
+      --smk-bg-soft: #171717;
+      --smk-border: #262626;
+      --smk-border-strong: #404040;
+      --smk-accent: #f5f5f5;
+      --smk-accent-fg: #0a0a0a;
+    }
+  }
+
+  /* ============================================================
+     Article wrapper
+     ============================================================ */
+  .smk-cms {
+    color: var(--smk-fg);
+    font-family: var(--smk-font-sans);
+    line-height: 1.7;
+    font-size: 17px;
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: 3rem 1.5rem;
+  }
+  .smk-cms__title {
+    font-family: var(--smk-font-serif);
+    font-size: clamp(2rem, 5vw, 3rem);
+    font-weight: 700;
+    line-height: 1.1;
+    letter-spacing: -0.02em;
+    margin: 0 0 3rem;
+  }
+  .smk-cms > .smk-block + .smk-block {
+    margin-top: 2.5rem;
+  }
+  /* Hero edges out to wrapper bounds; other blocks stay readable column. */
+  .smk-cms > .smk-block--hero {
+    margin-left: -1.5rem;
+    margin-right: -1.5rem;
+  }
+
+  /* ============================================================
+     Article — Plate-rendered HTML
+     SDK emits: \`<div class="smk-block smk-block--article">{html}</div>\`
+     The inner HTML comes from Plate's serializeHtml on the SaaS side,
+     so customer SDK ships zero editor deps. Below selectors style the
+     emitted h1/h2/p/ul/blockquote etc inside the article wrapper.
+     ============================================================ */
+  .smk-block--article p {
+    margin: 0 0 1.25em;
+  }
+  .smk-block--article p:last-child {
+    margin-bottom: 0;
+  }
+  .smk-block--article h1,
+  .smk-block--article h2,
+  .smk-block--article h3 {
+    font-family: var(--smk-font-serif);
+    font-weight: 700;
+    letter-spacing: -0.015em;
+    line-height: 1.2;
+  }
+  .smk-block--article h1 {
+    font-size: 2rem;
+    margin: 2em 0 0.5em;
+  }
+  .smk-block--article h2 {
+    font-size: 1.6rem;
+    margin: 1.8em 0 0.5em;
+  }
+  .smk-block--article h3 {
+    font-size: 1.25rem;
+    margin: 1.5em 0 0.5em;
+  }
+  .smk-block--article h1:first-child,
+  .smk-block--article h2:first-child,
+  .smk-block--article h3:first-child {
+    margin-top: 0;
+  }
+  .smk-block--article ul,
+  .smk-block--article ol {
+    margin: 0 0 1.25em;
+    padding-left: 1.75em;
+  }
+  .smk-block--article li {
+    margin: 0.4em 0;
+  }
+  .smk-block--article li::marker {
+    color: var(--smk-fg-subtle);
+  }
+  .smk-block--article a {
+    color: inherit;
+    text-decoration: underline;
+    text-decoration-color: var(--smk-border-strong);
+    text-underline-offset: 3px;
+    transition: text-decoration-color 0.15s;
+  }
+  .smk-block--article a:hover {
+    text-decoration-color: currentColor;
+  }
+  .smk-block--article blockquote {
+    margin: 1.5em 0;
+    padding: 0.25em 0 0.25em 1.25rem;
+    border-left: 3px solid var(--smk-border-strong);
+    color: var(--smk-fg-muted);
+    font-style: italic;
+  }
+  .smk-block--article code {
+    background: var(--smk-bg-soft);
+    padding: 0.15em 0.4em;
+    border-radius: 4px;
+    font-size: 0.9em;
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  }
+  .smk-block--article pre {
+    background: var(--smk-bg-soft);
+    padding: 1rem;
+    border-radius: var(--smk-radius-sm);
+    overflow-x: auto;
+    margin: 1.5em 0;
+  }
+  .smk-block--article pre code {
+    background: transparent;
+    padding: 0;
+  }
+  .smk-block--article img {
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--smk-radius-sm);
+    margin: 1.5em 0;
+  }
+
+  /* ============================================================
+     Hero — magazine cover banner
+     SDK emits: \`<section class="smk-block smk-block--hero smk-hero">\`
+     ============================================================ */
+  .smk-hero {
+    text-align: center;
+    padding: 5rem 1.5rem 4rem;
+    background: var(--smk-bg-soft);
+    border-radius: 0;
+    margin-bottom: 3rem;
+    position: relative;
+  }
+  .smk-hero__image {
+    max-width: 100%;
+    height: auto;
+    margin: 0 auto 2rem;
+    border-radius: var(--smk-radius-md);
+    display: block;
+  }
+  .smk-hero__title {
+    font-family: var(--smk-font-serif);
+    font-size: clamp(2.25rem, 6vw, 4rem);
+    font-weight: 800;
+    line-height: 1.05;
+    letter-spacing: -0.025em;
+    margin: 0 0 1rem;
+    color: var(--smk-fg);
+    max-width: 32rem;
+    margin-inline: auto;
+  }
+  .smk-hero__subtitle {
+    color: var(--smk-fg-muted);
+    font-size: 0.95rem;
+    margin: 1.5rem auto 0;
+    max-width: 28rem;
+    letter-spacing: 0.02em;
+  }
+  .smk-hero__cta {
+    display: inline-block;
+    padding: 0.75rem 1.5rem;
+    margin-top: 2rem;
+    background: var(--smk-accent);
+    color: var(--smk-accent-fg);
+    border-radius: var(--smk-radius-sm);
+    text-decoration: none;
+    font-weight: 500;
+    font-size: 0.95rem;
+    transition: opacity 0.15s;
+  }
+  .smk-hero__cta:hover {
+    opacity: 0.85;
+  }
+
+  /* ============================================================
+     Nav — recent-posts / taxonomy-list
+     SDK emits: \`<section class="smk-block smk-block--nav-{type} smk-nav {sub-class}" data-layout="list|grid|carousel">\`
+     ============================================================ */
+  .smk-nav {
+    padding: 2.5rem 0;
+    border-top: 1px solid var(--smk-border);
+  }
+  .smk-nav__heading {
+    font-size: 0.75rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    color: var(--smk-fg-muted);
+    margin: 0 0 1.5rem;
+  }
+  .smk-nav__list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  /* List layout (data-layout="list") */
+  .smk-nav[data-layout="list"] .smk-nav__list {
+    display: flex;
+    flex-direction: column;
+  }
+  .smk-nav[data-layout="list"] .smk-nav__item + .smk-nav__item {
+    border-top: 1px solid var(--smk-border);
+  }
+  .smk-nav[data-layout="list"] .smk-nav__link {
+    display: flex;
+    gap: 1.25rem;
+    align-items: center;
+    padding: 1.25rem 0;
+    color: inherit;
+    text-decoration: none;
+    transition: opacity 0.15s;
+  }
+  .smk-nav[data-layout="list"] .smk-nav__thumb {
+    width: 6rem;
+    height: 6rem;
+    object-fit: cover;
+    border-radius: var(--smk-radius-sm);
+    flex-shrink: 0;
+    background: var(--smk-bg-soft);
+  }
+
+  /* Grid layout (data-layout="grid") */
+  .smk-nav[data-layout="grid"] .smk-nav__list {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+    gap: 1.25rem;
+  }
+  .smk-nav[data-layout="grid"] .smk-nav__link {
+    display: flex;
+    flex-direction: column;
+    color: inherit;
+    text-decoration: none;
+    background: var(--smk-bg);
+    border: 1px solid var(--smk-border);
+    border-radius: var(--smk-radius-md);
+    overflow: hidden;
+    transition: transform 0.15s, box-shadow 0.15s, border-color 0.15s;
+  }
+  .smk-nav[data-layout="grid"] .smk-nav__link:hover {
+    transform: translateY(-2px);
+    border-color: var(--smk-border-strong);
+    box-shadow: 0 8px 24px -8px rgb(0 0 0 / 0.12);
+  }
+  .smk-nav[data-layout="grid"] .smk-nav__thumb {
+    width: 100%;
+    aspect-ratio: 16 / 10;
+    object-fit: cover;
+    background: var(--smk-bg-soft);
+  }
+  .smk-nav[data-layout="grid"] .smk-nav__meta {
+    padding: 1rem;
+  }
+
+  /* Carousel layout (data-layout="carousel") — horizontal scroll-snap */
+  .smk-nav[data-layout="carousel"] .smk-nav__list {
+    display: grid;
+    grid-auto-flow: column;
+    grid-auto-columns: 70%;
+    gap: 1rem;
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    padding-bottom: 0.5rem;
+  }
+  @media (min-width: 640px) {
+    .smk-nav[data-layout="carousel"] .smk-nav__list {
+      grid-auto-columns: 40%;
+    }
+  }
+  .smk-nav[data-layout="carousel"] .smk-nav__item {
+    scroll-snap-align: start;
+    background: var(--smk-bg);
+    border: 1px solid var(--smk-border);
+    border-radius: var(--smk-radius-md);
+    overflow: hidden;
+  }
+  .smk-nav[data-layout="carousel"] .smk-nav__link {
+    display: flex;
+    flex-direction: column;
+    color: inherit;
+    text-decoration: none;
+  }
+  .smk-nav[data-layout="carousel"] .smk-nav__thumb {
+    width: 100%;
+    aspect-ratio: 16 / 10;
+    object-fit: cover;
+    background: var(--smk-bg-soft);
+  }
+  .smk-nav[data-layout="carousel"] .smk-nav__meta {
+    padding: 1rem;
+  }
+
+  /* Shared internals */
+  .smk-nav__link:hover {
+    opacity: 0.85;
+  }
+  .smk-nav[data-layout="grid"] .smk-nav__link:hover,
+  .smk-nav[data-layout="carousel"] .smk-nav__link:hover {
+    opacity: 1;
+  }
+  .smk-nav__meta {
+    flex: 1;
+    min-width: 0;
+  }
+  .smk-nav__title {
+    font-family: var(--smk-font-serif);
+    font-size: 1.15rem;
+    font-weight: 700;
+    line-height: 1.3;
+    margin: 0 0 0.5rem;
+    letter-spacing: -0.01em;
+  }
+  .smk-nav__excerpt {
+    font-size: 0.9rem;
+    color: var(--smk-fg-muted);
+    margin: 0;
+    line-height: 1.55;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+  .smk-nav__date {
+    display: block;
+    font-size: 0.75rem;
+    color: var(--smk-fg-subtle);
+    margin-top: 0.6rem;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+  .smk-nav__empty {
+    color: var(--smk-fg-subtle);
+    font-style: italic;
+    padding: 1rem 0;
+  }
+  .smk-nav__view-all {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    margin-top: 1.5rem;
+    color: var(--smk-accent);
+    font-size: 0.875rem;
+    font-weight: 600;
+    text-decoration: none;
+  }
+  .smk-nav__view-all::after {
+    content: "→";
+    transition: transform 0.15s;
+  }
+  .smk-nav__view-all:hover::after {
+    transform: translateX(3px);
+  }
+
+  /* ============================================================
+     Nav-search — inline filter input
+     SDK emits: \`<section class="smk-block smk-block--nav-search smk-nav-search">\`
+                with \`data-smk-search-input\` / \`data-smk-search-results\` /
+                \`data-smk-search-empty\` attributes the IIFE wires up.
+     ============================================================ */
+  .smk-nav-search {
+    padding: 2rem 0;
+    border-top: 1px solid var(--smk-border);
+  }
+  .smk-nav-search__shell {
+    position: relative;
+  }
+  .smk-nav-search__input {
+    width: 100%;
+    padding: 0.875rem 1.125rem;
+    border: 1px solid var(--smk-border);
+    border-radius: var(--smk-radius-md);
+    background: var(--smk-bg);
+    color: var(--smk-fg);
+    font-size: 1rem;
+    font-family: inherit;
+    transition: border-color 0.15s, box-shadow 0.15s;
+  }
+  .smk-nav-search__input::placeholder {
+    color: var(--smk-fg-subtle);
+  }
+  .smk-nav-search__input:focus {
+    outline: none;
+    border-color: var(--smk-fg);
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--smk-fg) 8%, transparent);
+  }
+  .smk-nav-search__list {
+    list-style: none;
+    padding: 0;
+    margin: 0.75rem 0 0;
+    border: 1px solid var(--smk-border);
+    border-radius: var(--smk-radius-md);
+    background: var(--smk-bg);
+    overflow: hidden;
+    box-shadow: 0 4px 12px -4px rgb(0 0 0 / 0.1);
+  }
+  .smk-nav-search__result + .smk-nav-search__result {
+    border-top: 1px solid var(--smk-border);
+  }
+  .smk-nav-search__result a {
+    display: block;
+    padding: 0.875rem 1.125rem;
+    color: var(--smk-fg);
+    text-decoration: none;
+    transition: background 0.1s;
+  }
+  .smk-nav-search__result a:hover {
+    background: var(--smk-bg-soft);
+  }
+  .smk-nav-search__empty {
+    color: var(--smk-fg-subtle);
+    padding: 1rem 0 0;
+    font-size: 0.9rem;
+  }
+
+  /* ============================================================
+     Carousel — Apple-newsroom style horizontal carousel with
+     \`data-aspect\` token-driven aspect-ratio, container-query-anchored
+     nav buttons, and dots indicator.
+     SDK emits:
+       <smking-carousel class="smk-block smk-block--carousel smk-carousel"
+                        data-aspect="16:9|4:3|1:1|3:4|9:16">
+         <div class="smk-carousel__viewport">
+           <smking-slide>
+             <div class="smk-carousel__image-frame">
+               <img class="smk-carousel__image" /> or .__image--placeholder
+             </div>
+             <div class="smk-carousel__caption-row">
+               <div class="smk-carousel__caption">…</div>
+               <a class="smk-carousel__download" href />
+             </div>
+           </smking-slide>
+         </div>
+         <button class="smk-carousel__nav-prev|next" />
+         <div class="smk-carousel__dots">
+           <button class="smk-carousel__dot" aria-current="true|false" />
+         </div>
+       </smking-carousel>
+
+     Web Component IIFE (SMKING_ELEMENTS_IIFE) upgrades the markup with
+     swipe / scroll-snap / dot-binding behaviour client-side. CSS below
+     drives all visual state — image cover-fill, nav-button vertical
+     centering anchored to image height (cqw container-queries), dot
+     active state.
+     ============================================================ */
+  smking-carousel,
+  .smk-carousel {
+    display: block;
+    position: relative;
+    margin: 2.5rem 0;
+    padding-top: 2.5rem;              /* room for editor settings overlay; harmless on customer side */
+    padding-bottom: 1.5rem;
+    container-type: inline-size;      /* enables \`cqw\` for nav-button vertical anchor */
+    --smk-carousel-aspect: 16 / 9;
+    --smk-carousel-nav-top: 28.125cqw;   /* 50cqw × 9/16 = half of image height */
+  }
+  .smk-carousel[data-aspect="4:3"],
+  smking-carousel[data-aspect="4:3"] {
+    --smk-carousel-aspect: 4 / 3;
+    --smk-carousel-nav-top: 37.5cqw;
+  }
+  .smk-carousel[data-aspect="1:1"],
+  smking-carousel[data-aspect="1:1"] {
+    --smk-carousel-aspect: 1 / 1;
+    --smk-carousel-nav-top: 50cqw;
+  }
+  .smk-carousel[data-aspect="3:4"],
+  smking-carousel[data-aspect="3:4"] {
+    --smk-carousel-aspect: 3 / 4;
+    --smk-carousel-nav-top: 66.667cqw;
+  }
+  .smk-carousel[data-aspect="9:16"],
+  smking-carousel[data-aspect="9:16"] {
+    --smk-carousel-aspect: 9 / 16;
+    --smk-carousel-nav-top: 88.889cqw;
+  }
+
+  .smk-carousel__viewport {
+    display: flex;
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    scroll-behavior: smooth;
+    scrollbar-width: none;
+    -webkit-overflow-scrolling: touch;
+  }
+  .smk-carousel__viewport::-webkit-scrollbar {
+    display: none;
+  }
+
+  smking-slide,
+  .smk-carousel__slide {
+    display: flex;
+    flex-direction: column;
+    flex: 0 0 100%;
+    scroll-snap-align: start;
+    min-width: 0;
+    padding-inline: 0.5rem;
+    gap: 1rem;
+  }
+
+  /* Image frame — fixed-aspect box. Image cover-fills. */
+  .smk-carousel__image-frame {
+    position: relative;
+    aspect-ratio: var(--smk-carousel-aspect);
+    overflow: hidden;
+    border-radius: var(--smk-radius-md);
+  }
+  .smk-carousel__image {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+  .smk-carousel__image--placeholder {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--smk-bg-soft);
+    border: 1px dashed var(--smk-border);
+  }
+
+  /* Caption row — text on the left, download icon on the right. Matches
+     Apple newsroom's per-slide attribution + asset-download pattern. */
+  .smk-carousel__caption-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+    padding-inline: 0.25rem;
+  }
+  .smk-carousel__caption {
+    flex: 1;
+    text-align: center;
+    font-size: 0.875rem;
+    color: var(--smk-fg-muted);
+    line-height: 1.5;
+  }
+  .smk-carousel__download {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    border-radius: 9999px;
+    color: var(--smk-fg-muted);
+    text-decoration: none;
+    transition: background-color 0.15s, color 0.15s;
+  }
+  .smk-carousel__download:hover {
+    background: var(--smk-bg-soft);
+    color: var(--smk-fg);
+  }
+
+  /* Nav buttons — circular cards overlapping the image edges. Top is
+     centered on the IMAGE (not the whole carousel) via container query:
+     image height = 100cqw × (ratio_h / ratio_w); half = nav-top var.
+     2.5rem offset = container padding-top. */
+  .smk-carousel__nav-prev,
+  .smk-carousel__nav-next {
+    position: absolute;
+    top: calc(2.5rem + var(--smk-carousel-nav-top));
+    transform: translateY(-50%);
+    z-index: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.5rem;
+    height: 2.5rem;
+    padding: 0;
+    border-radius: 9999px;
+    border: 1px solid var(--smk-border);
+    background: var(--smk-bg);
+    color: var(--smk-fg);
+    cursor: pointer;
+    box-shadow: 0 1px 3px rgb(0 0 0 / 0.06);
+    transition: background-color 0.15s, transform 0.15s;
+  }
+  .smk-carousel__nav-prev { left: 0.75rem; }
+  .smk-carousel__nav-next { right: 0.75rem; }
+  .smk-carousel__nav-prev:hover,
+  .smk-carousel__nav-next:hover {
+    background: var(--smk-bg-soft);
+  }
+  .smk-carousel__nav-prev:active,
+  .smk-carousel__nav-next:active {
+    transform: translateY(-50%) scale(0.95);
+  }
+
+  /* Dots — small circles centered below the caption row. Inactive is
+     hairline grey, active fills with foreground colour. */
+  .smk-carousel__dots {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 0.5rem;
+    margin-top: 0.75rem;
+  }
+  .smk-carousel__dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    padding: 0;
+    border-radius: 9999px;
+    border: none;
+    background: color-mix(in srgb, var(--smk-fg) 20%, transparent);
+    cursor: pointer;
+    transition: background-color 0.15s, transform 0.15s;
+  }
+  .smk-carousel__dot:hover {
+    background: color-mix(in srgb, var(--smk-fg) 45%, transparent);
+  }
+  .smk-carousel__dot[aria-current="true"] {
+    background: var(--smk-fg);
+    transform: scale(1.1);
+  }
+
+  /* ============================================================
+     Unknown block — forward-compat fallback
+     ============================================================ */
+  .smk-block--unknown {
+    display: none;
+  }
+}
+`;

package/src/types.ts

@@ -58,6 +58,25 @@ 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";
+
 /**
  * v2 substrate block primitives. Mirrors `apps/web/src/features/cms/types.ts`
  * on the SaaS side (kept in sync manually — when the v1 block catalog