@soloworks/smking-next 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @soloworks/smking-next
 
+## 0.10.0 — 2026-05-14
+
+**`SmkingCms` typing fix + CMS revalidate default aligned to 5 min.**
+
+### Fixed
+
+- `SeoMeta.metaDescription` was missing from the TypeScript interface, but the SaaS public-page endpoint and `smking/laravel` both emit this field inside the seo block. Customers pulling v0.9.1 with `<SmkingCms />` hit a `TS2551` compile error on `seo.metaDescription`. Added as optional since the AEO endpoint emits `metaDescription` at `AeoResponse` top level instead — AEO callers still see `undefined`, CMS callers get the value.
+
+### Behavioral change
+
+- `getCmsPage` / `<SmkingCms />` `revalidate` default reduced from `3600` (1h) → `300` (5min). CMS content is hand-edited (frequent updates) vs AEO which is SaaS-generated (more stable), so a shorter ISR backstop is the correct fallback. Matches `smking/laravel`'s `cms_ttl` default. Override via the `revalidate` prop if you need the previous 1h behaviour. Customers with the CMS publish webhook wired (`SMKING_WEBHOOK_SECRET` + `@soloworks/smking-next/cms-webhook` handler) are unaffected — push invalidation bypasses ISR entirely.
+
+### README
+
+- Install section trimmed to a pointer at the dashboard install prompt / `npx @soloworks/smking-wizard`. Reduces drift between the SDK README and the per-site install prompt that's the source of truth.
+
+## 0.9.1 — 2026-05-13
+
+**`smking-next doctor` subcommand for self-check + machine-readable output.** The CLI bin now accepts two subcommands: `install` (existing one-shot scaffold) and the new `doctor` (self-check). With `--json`, doctor emits structured output for the new `@smking/wizard` install agent's `run_doctor` tool.
+
+### What's new
+
+`npx @soloworks/smking-next doctor` runs four checks:
+
+- `SMKING_API_KEY` set (and starts with `pk_`)
+- `SMKING_BASE_URL` set (and starts with `http`)
+- `<SmkingAEO />` imported in the root `app/layout.{tsx,jsx,ts,js}`
+- Live probe of `${SMKING_BASE_URL}/api/v1/public/aeo` (3s timeout)
+
+Exit code is `0` when every required check passes, `1` otherwise. Identical between pretty and JSON modes.
+
+### `--json` shape
+
+```json
+{
+  "checks": [
+    { "name": "...", "status": "pass" | "fail" | "info", "detail": "..." }
+  ],
+  "summary": { "passed": N, "failed": N, "info": N, "ok": <bool> }
+}
+```
+
+`summary.ok` is the short-circuit boolean for agentic consumers. The shape is a stable wizard contract — schema changes will bump wizard version.
+
+### Why
+
+Mirrors `smking/laravel`'s `php artisan smking:doctor --json` (v0.10.1). The `@smking/wizard` CLI now runs the same install verification step for both stacks without needing to scrape ANSI-coloured terminal output.
+
+Pure addition — existing `npx @soloworks/smking-next install` calls are unchanged, default behaviour preserved.
+
 ## 0.9.0 — 2026-05-12
 
 **Drop-in takeover for `/sitemap.xml`, `/robots.txt`, and `/llms.txt` plus a one-shot install CLI.** Customers with no sitemap (or a broken one), no `robots.txt`, or no `llms.txt` for AI agents previously had to write all three themselves. With v0.9.0 the SDK serves them from the smking SaaS — one line of customer code per file, scaffolded automatically.

package/README.md

@@ -8,59 +8,19 @@ AI-native SEO (AEO) for Next.js. One server component injects JSON-LD, OG tags,
 
 ## Install
 
-```bash
-pnpm add @soloworks/smking-next
-```
+**Don't follow this README to install.** Your smking dashboard generates a per-site install prompt with the real `SMKING_API_KEY`, `SMKING_BASE_URL`, and (if you use CMS) `SMKING_WEBHOOK_SECRET` baked in, plus copy-pasteable layout / route shims. The prompt is the source of truth and stays in sync with the SDK version.
 
-Set two environment variables:
+Two ways to get it:
 
 ```bash
-SMKING_API_KEY=pk_...        # public key from smking dashboard
-SMKING_BASE_URL=https://...  # smking deployment origin
-```
-
-### 1. Drop the component into your root layout
-
-```tsx
-// app/layout.tsx
-import { SmkingAEO } from '@soloworks/smking-next';
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>
-        <SmkingAEO apiKey={process.env.SMKING_API_KEY!} />
-        {children}
-      </body>
-    </html>
-  );
-}
-```
-
-That's it for AEO injection. Every request to any URL fetches that URL's AEO content from smking and emits:
+# Option 1 — one-shot wizard (installs deps + writes env + runs doctor)
+npx @soloworks/smking-wizard
 
-- `<script type="application/ld+json">` for AI crawlers
-- `<title>`, `<meta name="description">`, `og:*` head tags
-- sr-only `<div>` containing FAQ, AI summary, and product image (visually hidden, in-DOM for crawlers)
-
-### 2. Wire the webhook for instant cache invalidation
-
-```ts
-// app/api/smking-revalidate/route.ts
-export { POST, GET } from '@soloworks/smking-next/route';
-```
-
-Add to environment:
-
-```bash
-SMKING_WEBHOOK_TOKEN=...  # any random string; share with smking SaaS
+# Option 2 — copy the prompt manually from your smking dashboard's
+# install panel into your editor / coding agent.
 ```
 
-Configure smking SaaS to POST `{ paths: [...] }` to your `/api/smking-revalidate` endpoint with `Authorization: Bearer <token>`. The handler calls `revalidateTag('smking:path:<path>')` for each path.
+The wizard owns: `pnpm add @soloworks/smking-next`, `<SmkingAEO />` mount in `app/layout.tsx`, env writes, `app/api/smking/webhook/route.ts` shim, and doctor verification.
 
 ## How metadata wins / loses
 

package/bin/install.ts

@@ -1,18 +1,26 @@
 #!/usr/bin/env node
 /**
- * `npx @soloworks/smking-next install`
+ * `npx @soloworks/smking-next [install|doctor] [--json]`
  *
- * One-shot scaffold for the three takeover drop-in files. Idempotent: if a
- * file already exists, we leave it alone and tell the user — never
- * overwrite customer code. Each generated file is one line of re-export
- * pointing at the SDK helper that does the real work.
+ * Two subcommands share this entry point (Node 22+ strips TS at runtime, so
+ * the package ships .ts source directly — no build step):
+ *
+ * - **install** (default) — One-shot scaffold for the three takeover
+ *   drop-in files (sitemap.ts / robots.ts / llms.txt route). Idempotent:
+ *   already-existing files are skipped, never overwritten.
+ *
+ * - **doctor** — Self-check (env presence + <SmkingAEO /> usage + API
+ *   reachable). `--json` flag emits structured output for the
+ *   @smking/wizard install agent's `run_doctor` MCP tool.
  *
  * Conventional Next.js layout assumed: `app/` at repo root (or under
- * `src/app/` — detected). The CLI exits 1 if neither exists.
+ * `src/app/` — detected). Both subcommands exit 1 on missing app/.
  */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+// ── install (既有功能) ──────────────────────────────────────────
+
 interface FileSpec {
   path: string; // relative to detected app root
   content: string;
@@ -48,7 +56,7 @@ function detectAppDir(): string | null {
   return null;
 }
 
-function main(): number {
+function runInstall(): number {
   const appDir = detectAppDir();
   if (!appDir) {
     console.error(
@@ -82,4 +90,202 @@ function main(): number {
   return 0;
 }
 
-process.exit(main());
+// ── doctor (新增) ──────────────────────────────────────────────
+
+interface DoctorCheck {
+  name: string;
+  status: "pass" | "fail" | "info";
+  detail: string;
+}
+
+function checkEnv(name: string, prefix?: string): DoctorCheck {
+  const value = process.env[name];
+  if (!value) {
+    return {
+      name: `${name} set`,
+      status: "fail",
+      detail: `not set; add ${name}=... to .env.local`,
+    };
+  }
+  if (prefix && !value.startsWith(prefix)) {
+    return {
+      name: `${name} set`,
+      status: "fail",
+      detail: `value must start with \`${prefix}\``,
+    };
+  }
+  return {
+    name: `${name} set`,
+    status: "pass",
+    detail: `${value.slice(0, 8)}…`,
+  };
+}
+
+function checkLayoutUsage(appDir: string): DoctorCheck {
+  // Mirror Next.js's layout file resolution. Order matters — TS > JS to
+  // match what Next.js itself would pick.
+  const candidates = [
+    join(appDir, "layout.tsx"),
+    join(appDir, "layout.jsx"),
+    join(appDir, "layout.ts"),
+    join(appDir, "layout.js"),
+  ];
+  const layoutPath = candidates.find((p) => existsSync(p));
+  if (!layoutPath) {
+    return {
+      name: "<SmkingAEO /> in root layout",
+      status: "info",
+      detail: `no layout file found under ${appDir}/ — skipped`,
+    };
+  }
+
+  const content = readFileSync(layoutPath, "utf-8");
+  // Substring check is intentional rather than AST parsing. A customer
+  // commenting it out or aliasing the import shows up as fail/info either
+  // way, and AST adds a TypeScript parser dependency for trivial value.
+  if (!content.includes("SmkingAEO")) {
+    return {
+      name: "<SmkingAEO /> in root layout",
+      status: "fail",
+      detail: `${layoutPath} does not import SmkingAEO. Add: import { SmkingAEO } from "@soloworks/smking-next"; then render <SmkingAEO apiKey={process.env.SMKING_API_KEY!} /> inside <body>.`,
+    };
+  }
+  return {
+    name: "<SmkingAEO /> in root layout",
+    status: "pass",
+    detail: layoutPath,
+  };
+}
+
+async function checkApiReachable(): Promise<DoctorCheck> {
+  const apiKey = process.env.SMKING_API_KEY;
+  const baseUrl = process.env.SMKING_BASE_URL;
+  if (!apiKey || !baseUrl) {
+    return {
+      name: "API reachable",
+      status: "info",
+      detail: "skipped — SMKING_API_KEY or SMKING_BASE_URL not set",
+    };
+  }
+
+  // Probe the actual AEO endpoint, not the base URL root. Hitting root
+  // would pass for any live host (a typo'd domain, google.com); the
+  // endpoint either returns the AEO payload or a known auth/validation
+  // status — both confirm the route exists.
+  const url = `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo?path=%2F`;
+  try {
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(3000),
+    });
+
+    if (res.ok) {
+      return {
+        name: "API reachable",
+        status: "pass",
+        detail: `${url} → HTTP ${res.status}`,
+      };
+    }
+    if (res.status === 401) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `HTTP 401 from ${url} — SMKING_API_KEY rejected`,
+      };
+    }
+    if (res.status === 404) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `HTTP 404 from ${url} — base_url likely points at the wrong host`,
+      };
+    }
+    if (res.status >= 500) {
+      return {
+        name: "API reachable",
+        status: "fail",
+        detail: `upstream HTTP ${res.status} from ${url}`,
+      };
+    }
+    // 4xx (other than 401/404) — likely validation error, endpoint exists
+    return {
+      name: "API reachable",
+      status: "info",
+      detail: `${url} → HTTP ${res.status} (endpoint exists)`,
+    };
+  } catch (err) {
+    return {
+      name: "API reachable",
+      status: "fail",
+      detail: `connection failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+async function runDoctor(jsonOutput: boolean): Promise<number> {
+  const appDir = detectAppDir();
+  const checks: DoctorCheck[] = [
+    checkEnv("SMKING_API_KEY", "pk_"),
+    checkEnv("SMKING_BASE_URL", "http"),
+    appDir
+      ? checkLayoutUsage(appDir)
+      : {
+          name: "<SmkingAEO /> in root layout",
+          status: "info" as const,
+          detail: "no app/ or src/app/ directory found — skipped",
+        },
+    await checkApiReachable(),
+  ];
+
+  const hasFailure = checks.some((c) => c.status === "fail");
+
+  // JSON mode: parseable structured output for @smking/wizard's run_doctor
+  // tool. Stable shape — do not break without bumping wizard version.
+  if (jsonOutput) {
+    const summary = {
+      passed: checks.filter((c) => c.status === "pass").length,
+      failed: checks.filter((c) => c.status === "fail").length,
+      info: checks.filter((c) => c.status === "info").length,
+      ok: !hasFailure,
+    };
+    console.log(JSON.stringify({ checks, summary }));
+    return hasFailure ? 1 : 0;
+  }
+
+  for (const check of checks) {
+    const icon =
+      check.status === "pass"
+        ? "✅"
+        : check.status === "fail"
+          ? "❌"
+          : "ℹ️ ";
+    console.log(`${icon} ${check.name} — ${check.detail}`);
+  }
+  console.log();
+  if (hasFailure) {
+    console.log("❌ smking: install incomplete — fix the items above.");
+    return 1;
+  }
+  console.log("✅ smking: install OK.");
+  return 0;
+}
+
+// ── Entry dispatcher ────────────────────────────────────────────
+
+async function main(): Promise<number> {
+  const subcommand = process.argv[2];
+  const jsonOutput = process.argv.includes("--json");
+
+  if (subcommand === "doctor") {
+    return runDoctor(jsonOutput);
+  }
+  if (subcommand === "install" || subcommand === undefined) {
+    return runInstall();
+  }
+  console.error(
+    `Unknown subcommand: ${subcommand}. Available: install (default), doctor.`,
+  );
+  return 1;
+}
+
+main().then((code) => process.exit(code));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -15,6 +15,14 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./cms": {
+      "types": "./src/components/smking-cms.tsx",
+      "default": "./src/components/smking-cms.tsx"
+    },
+    "./cms-webhook": {
+      "types": "./src/lib/cms-webhook-route.ts",
+      "default": "./src/lib/cms-webhook-route.ts"
+    },
     "./route": {
       "types": "./src/route.ts",
       "default": "./src/route.ts"
@@ -55,11 +63,38 @@
   ],
   "peerDependencies": {
     "next": "^15.0.0 || ^16.0.0",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "@tiptap/static-renderer": "^3.0.0",
+    "@tiptap/core": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
+    "@tiptap/extension-image": "^3.0.0",
+    "@tiptap/extension-link": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tiptap/static-renderer": {
+      "optional": true
+    },
+    "@tiptap/core": {
+      "optional": true
+    },
+    "@tiptap/starter-kit": {
+      "optional": true
+    },
+    "@tiptap/extension-image": {
+      "optional": true
+    },
+    "@tiptap/extension-link": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "@tiptap/core": "^3.23.4",
+    "@tiptap/extension-image": "^3.23.4",
+    "@tiptap/extension-link": "^3.23.4",
+    "@tiptap/starter-kit": "^3.23.4",
+    "@tiptap/static-renderer": "^3.23.4",
     "@types/react": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",
     "jsdom": "^29.1.0",

package/src/components/cms-nodes/gallery-extension.ts

@@ -0,0 +1,32 @@
+import { Node } from "@tiptap/core";
+
+/**
+ * Schema-only Gallery extension for the static renderer.
+ *
+ * The full SaaS-side `GalleryNode` (apps/web/src/components/tiptap-node/
+ * gallery-node/gallery-node-extension.ts) ships with addNodeView,
+ * addCommands, parseHTML — everything Tiptap needs in the editor. For
+ * read-only static rendering we only need the SCHEMA (name, group,
+ * atom, attrs) so `@tiptap/static-renderer` recognises the "gallery"
+ * node type when walking the JSON; the actual rendering is handled by
+ * the GalleryNodeView passed via `nodeMapping`.
+ *
+ * Keep attrs in sync with the SaaS schema and the Laravel PHP node
+ * (packages/smking-laravel/src/Tiptap/Nodes/Gallery.php). All three
+ * must agree on field names + defaults.
+ */
+export const Gallery = Node.create({
+  name: "gallery",
+  group: "block",
+  atom: true,
+  draggable: true,
+  selectable: true,
+
+  addAttributes() {
+    return {
+      images: { default: [] },
+      layout: { default: "grid" },
+      columns: { default: 3 },
+    };
+  },
+});

package/src/components/cms-nodes/gallery-node.tsx

@@ -0,0 +1,68 @@
+/**
+ * SmKing Gallery — read-only React render for static-renderer's
+ * nodeMapping.
+ *
+ * Markup MUST stay byte-equal to:
+ *   - apps/web/src/components/tiptap-node/gallery-node/gallery-node-
+ *     extension.ts (SaaS authoring → preview)
+ *   - packages/smking-laravel/src/Tiptap/Nodes/Gallery.php (Laravel
+ *     SDK PHP renderer)
+ *
+ * If you change ANY attribute / class / nesting here, change it in the
+ * other two and bump version on all three SDKs together. Customer site
+ * CSS targets `.smk-gallery`, `.smk-gallery--{layout}`,
+ * `.smk-gallery__item` — those names are public API.
+ */
+
+interface GalleryImage {
+  url: string;
+  alt?: string;
+  caption?: string;
+}
+
+interface GalleryNodeAttrs {
+  images?: GalleryImage[];
+  layout?: string;
+  columns?: number;
+}
+
+/**
+ * Shape matches what `@tiptap/static-renderer/pm/react`'s nodeMapping
+ * passes: `{ node: ProseMirror Node }` whose `attrs` are typed via the
+ * Gallery extension. We narrow loosely here — the SaaS sometimes ships
+ * stringly-typed attrs (jsonb round-trips lose number type for columns).
+ */
+export function GalleryNodeView({
+  node,
+}: {
+  node: { attrs?: GalleryNodeAttrs };
+}) {
+  const attrs = node.attrs ?? {};
+  const images = Array.isArray(attrs.images) ? attrs.images : [];
+  const layout = typeof attrs.layout === "string" ? attrs.layout : "grid";
+  const columnsRaw = attrs.columns;
+  const columns =
+    typeof columnsRaw === "number" && columnsRaw > 0
+      ? columnsRaw
+      : typeof columnsRaw === "string" && Number(columnsRaw) > 0
+        ? Number(columnsRaw)
+        : 3;
+
+  return (
+    <div
+      data-type="gallery"
+      data-layout={layout}
+      data-columns={String(columns)}
+      className={`smk-gallery smk-gallery--${layout}`}
+      style={{ "--smk-gallery-cols": columns } as React.CSSProperties}
+    >
+      {images.map((img, i) => (
+        <figure key={i} className="smk-gallery__item">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img src={img.url} alt={img.alt ?? ""} loading="lazy" />
+          {img.caption && <figcaption>{img.caption}</figcaption>}
+        </figure>
+      ))}
+    </div>
+  );
+}

package/src/components/smking-cms.tsx

@@ -0,0 +1,96 @@
+import { renderToReactElement } from "@tiptap/static-renderer/pm/react";
+import StarterKit from "@tiptap/starter-kit";
+import Image from "@tiptap/extension-image";
+import Link from "@tiptap/extension-link";
+import { Gallery } from "./cms-nodes/gallery-extension";
+import { GalleryNodeView } from "./cms-nodes/gallery-node";
+import { getCmsPage } from "../lib/cms-client";
+import type { CmsParams } from "../types";
+
+/**
+ * Server Component that renders a published smking CMS page.
+ *
+ * Usage:
+ * ```tsx
+ * import { SmkingCms } from '@soloworks/smking-next/cms';
+ *
+ * export default function Page() {
+ *   return (
+ *     <SmkingCms
+ *       apiKey={process.env.SMKING_API_KEY!}
+ *       slug="hello"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * Fetches the page server-side, walks the Tiptap ProseMirror JSON via
+ * `@tiptap/static-renderer/pm/react`, and renders it as a React tree.
+ * Standard nodes (paragraph / heading / image / list / link / blockquote
+ * / code-block) come from StarterKit. The custom Gallery node is
+ * mapped to GalleryNodeView whose markup is byte-equal to the SaaS
+ * preview side and the Laravel SDK PHP renderer.
+ *
+ * Returns null when the response isn't ready (pending / not_found /
+ * unreachable / mis-configured) — fail-open by design.
+ *
+ * Customer install requires four Tiptap peer deps:
+ *   pnpm add @tiptap/static-renderer @tiptap/starter-kit \\
+ *     @tiptap/extension-image @tiptap/extension-link
+ */
+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.
+  const seo = data.seo;
+  return (
+    <>
+      {seo?.title && <title data-smking="cms">{seo.title}</title>}
+      {seo?.metaDescription && (
+        <meta
+          name="description"
+          content={seo.metaDescription}
+          data-smking="cms"
+        />
+      )}
+      {seo?.ogTitle && (
+        <meta property="og:title" content={seo.ogTitle} data-smking="cms" />
+      )}
+      {seo?.ogDescription && (
+        <meta
+          property="og:description"
+          content={seo.ogDescription}
+          data-smking="cms"
+        />
+      )}
+      {seo?.ogImageUrl && (
+        <meta property="og:image" content={seo.ogImageUrl} data-smking="cms" />
+      )}
+      {seo?.canonicalUrl && (
+        <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
+      )}
+
+      <article className="smk-cms" data-smking="cms">
+        {data.page.title && (
+          <h1 className="smk-cms__title">{data.page.title}</h1>
+        )}
+        {renderToReactElement({
+          extensions: [StarterKit, Image, Link, Gallery],
+          content: data.page.body,
+          options: {
+            nodeMapping: {
+              // Custom node renderer for our gallery; standard nodes
+              // (paragraph, heading, list, etc.) auto-render from
+              // StarterKit's schema.
+              gallery: GalleryNodeView,
+            },
+          },
+        })}
+      </article>
+    </>
+  );
+}

package/src/index.ts

@@ -1,9 +1,15 @@
 export { SmkingAEO } from "./components/smking-aeo";
+export { SmkingCms } from "./components/smking-cms";
 export { getAeoContent } from "./lib/client";
+export { getCmsPage } from "./lib/cms-client";
 export type {
   AeoResponse,
   AeoStatus,
   ChatLinks,
+  CmsPage,
+  CmsParams,
+  CmsResponse,
+  CmsStatus,
   DiscoverParams,
   FaqItem,
   SeoMeta,

package/src/lib/cms-client.ts

@@ -0,0 +1,87 @@
+// Type-only import loads Next.js's RequestInit augmentation so the
+// `next: { revalidate, tags }` property on fetch options typechecks.
+import type {} from "next";
+
+import type { CmsParams, CmsResponse } from "../types";
+
+// CMS-specific TTL — shorter than AEO's 1h because CMS body is
+// hand-edited (frequent updates) vs AEO which is SaaS-generated
+// (more stable). Matches smking/laravel `cms_ttl` default for
+// cross-SDK behavioral consistency. Customer can override via the
+// `revalidate` prop. Webhook delivery (when SMKING_WEBHOOK_SECRET
+// is wired) bypasses this entirely via revalidateTag.
+const DEFAULT_REVALIDATE_SECONDS = 300;
+const FETCH_TIMEOUT_MS = 2000;
+
+const _warnedKeys = new Set<string>();
+function warnOnce(key: string, message: string): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (_warnedKeys.has(key)) return;
+  _warnedKeys.add(key);
+  console.warn(message);
+}
+
+/**
+ * Fetch a published CMS page from the smking public API.
+ *
+ * Mirrors `getAeoContent` shape — same fail-open posture, same Next.js
+ * data-cache integration. Returns null when:
+ *   - apiKey or baseUrl missing (one-time dev warning)
+ *   - network failure / 2s timeout
+ *   - 4xx / 5xx response
+ *   - JSON parse failure
+ *
+ * On success, cached by Next.js data cache for 5min by default
+ * (ISR backstop — see DEFAULT_REVALIDATE_SECONDS rationale).
+ * Tagged with `smking:cms:<slug>` so the `cms-webhook` handler can
+ * `revalidateTag` to invalidate instantly when SaaS publishes an
+ * update.
+ */
+export async function getCmsPage(
+  params: CmsParams,
+): Promise<CmsResponse | null> {
+  if (!params.apiKey) {
+    warnOnce(
+      "missing-api-key",
+      "[@soloworks/smking-next/cms] apiKey is empty — skipping CMS render. Set SMKING_API_KEY or pass apiKey prop.",
+    );
+    return null;
+  }
+
+  const baseUrl = (params.baseUrl ?? process.env.SMKING_BASE_URL)?.replace(
+    /\/$/,
+    "",
+  );
+  if (!baseUrl) {
+    warnOnce(
+      "missing-base-url",
+      "[@soloworks/smking-next/cms] SMKING_BASE_URL is not configured — skipping CMS render. Set the env var or pass baseUrl prop.",
+    );
+    return null;
+  }
+
+  if (!params.slug) {
+    warnOnce(
+      "missing-slug",
+      "[@soloworks/smking-next/cms] slug prop is required.",
+    );
+    return null;
+  }
+
+  try {
+    const url = `${baseUrl}/api/v1/public/page?key=${encodeURIComponent(
+      params.apiKey,
+    )}&slug=${encodeURIComponent(params.slug)}`;
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      next: {
+        revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
+        tags: [`smking:cms:${params.slug}`],
+      },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as CmsResponse;
+  } catch {
+    return null;
+  }
+}

package/src/lib/cms-webhook-route.ts

@@ -0,0 +1,107 @@
+import { revalidateTag } from "next/cache";
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+
+/**
+ * SmKing CMS publish webhook handler for Next.js.
+ *
+ * Drop-in install:
+ *
+ * ```ts
+ * // app/api/smking/webhook/route.ts
+ * export { POST } from "@soloworks/smking-next/cms-webhook";
+ * ```
+ *
+ * Then set `SMKING_WEBHOOK_SECRET` in your env and paste this route's
+ * full URL (e.g. `https://your-site.com/api/smking/webhook`) into the
+ * SmKing dashboard's site settings webhook field.
+ *
+ * On a verified `cms.page.published` event the handler calls
+ * `revalidateTag("smking:cms:<slug>", "default")` — invalidates the
+ * cached `getCmsPage` fetch tagged with that slug so the next page
+ * render reads fresh content from SaaS.
+ *
+ * Wire shape matches @smking-saas/features/cms/lib/webhook.ts and the
+ * Laravel SDK WebhookController:
+ *
+ *   POST /api/smking/webhook
+ *   X-Smking-Signature: sha256=<hex>
+ *   X-Smking-Event: cms.page.published
+ *   { event, siteId, slug, publishedAt, deliveredAt }
+ *
+ * HMAC-SHA256 sig verification runs constant-time via `timingSafeEqual`
+ * to prevent secret-extraction via response latency. Unknown event
+ * types accept (200) without action so SaaS doesn't retry — forward-
+ * compat for future event types (cms.page.unpublished / deleted).
+ */
+export async function POST(request: Request): Promise<Response> {
+  const secret = process.env.SMKING_WEBHOOK_SECRET;
+  if (!secret) {
+    return Response.json(
+      { error: "webhook_secret_missing" },
+      { status: 503 },
+    );
+  }
+
+  // Raw body for HMAC verify — re-encoding via JSON.parse + stringify
+  // would change byte order / spacing and invalidate the signature.
+  const rawBody = await request.text();
+  const providedSig = request.headers.get("x-smking-signature");
+  if (!verifySignature(rawBody, providedSig, secret)) {
+    return Response.json({ error: "invalid_signature" }, { status: 401 });
+  }
+
+  let payload: { event?: string; slug?: string };
+  try {
+    payload = JSON.parse(rawBody) as { event?: string; slug?: string };
+  } catch {
+    return Response.json({ error: "invalid_payload" }, { status: 400 });
+  }
+
+  if (
+    payload.event !== "cms.page.published" ||
+    typeof payload.slug !== "string" ||
+    payload.slug.length === 0
+  ) {
+    // Forward-compat: unknown event types ack-without-action so SaaS
+    // doesn't retry. Future event types (cms.page.unpublished) branch
+    // here without breaking older customer SDKs.
+    return Response.json({ ok: true, note: "no_action_taken" });
+  }
+
+  try {
+    // Next.js 16 requires explicit cache profile; "default" matches the
+    // profile a normal `'use cache'` block uses.
+    revalidateTag(`smking:cms:${payload.slug}`, "default");
+  } catch (err) {
+    console.warn(
+      `[@soloworks/smking-next/cms-webhook] revalidateTag failed for slug "${payload.slug}":`,
+      err,
+    );
+    return Response.json({ error: "revalidate_failed" }, { status: 500 });
+  }
+
+  return Response.json({ ok: true, evicted: payload.slug });
+}
+
+function verifySignature(
+  rawBody: string,
+  signatureHeader: string | null,
+  secret: string,
+): boolean {
+  if (!signatureHeader || !signatureHeader.startsWith("sha256=")) return false;
+  const provided = signatureHeader.slice("sha256=".length);
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(rawBody)
+    .digest("hex");
+  if (expected.length !== provided.length) return false;
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(expected, "hex"),
+      Buffer.from(provided, "hex"),
+    );
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -21,9 +21,19 @@ export interface ChatLinks {
  * Server-resolved SEO metadata. Public API does fallback chains
  * server-side (ogTitle → title, ogDescription → metaDescription,
  * ogImageUrl → imageUrl, canonicalUrl → pageUrl).
+ *
+ * `metaDescription` is emitted by the CMS public endpoint (per-page
+ * search-snippet override). The AEO public endpoint emits its own
+ * metaDescription at the top level of `AeoResponse` instead — keep both
+ * paths since they cover different surfaces.
  */
 export interface SeoMeta {
   title: string | null;
+  /**
+   * Optional — only present on the CMS surface. AEO emits its own
+   * metaDescription at `AeoResponse.metaDescription` (top level).
+   */
+  metaDescription?: string | null;
   ogTitle: string | null;
   ogDescription: string | null;
   ogImageUrl: string | null;
@@ -42,6 +52,57 @@ export interface AeoResponse {
   seo?: SeoMeta | null;
 }
 
+// ── CMS body content (mirrors SaaS /api/v1/public/page) ───────────────
+
+export type CmsStatus = "ready" | "pending" | "not_found";
+
+/**
+ * A single published CMS page returned by the smking public API.
+ * `body` is the raw Tiptap ProseMirror JSON document the user authored
+ * in /write — render it via the SmkingCms server component (which
+ * wraps @tiptap/static-renderer/pm/react with our extension list).
+ */
+export interface CmsPage {
+  slug: string;
+  title: string;
+  body: Record<string, unknown>;
+  publishedAt: string | null;
+}
+
+/**
+ * Mirrors AeoResponse status taxonomy so existing fail-open patterns
+ * apply identically. `page` + `seo` only present when status === "ready".
+ *
+ * SEO meta (v0.11+) lets the Server Component emit `<title>` / `<meta>`
+ * head tags alongside the body, so customer Next.js pages get a
+ * search-friendly meta block for free without a separate fetch.
+ * Server-resolved with fallback chains (ogTitle→seoTitle→title etc) —
+ * consumer just renders whatever's present.
+ */
+export interface CmsResponse {
+  status: CmsStatus;
+  page?: CmsPage;
+  seo?: SeoMeta | null;
+}
+
+export interface CmsParams {
+  /** Public API key (`pk_*`). Required. */
+  apiKey: string;
+  /** Page slug — required. PoC ships with hardcoded "hello" on the SaaS. */
+  slug: string;
+  /**
+   * smking deployment origin. Required — pass directly or set
+   * `SMKING_BASE_URL` env. Missing value short-circuits to fail-open.
+   */
+  baseUrl?: string;
+  /**
+   * Next.js `fetch` revalidate seconds. Defaults to 300 (5min ISR
+   * backstop — shorter than AEO's 1h because CMS content is hand-edited
+   * and changes more often; matches `smking/laravel`'s `cms_ttl`).
+   */
+  revalidate?: number;
+}
+
 export interface DiscoverParams {
   /** Public API key (`pk_*`). Required. */
   apiKey: string;