@soloworks/smking-next 0.9.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @soloworks/smking-next
 
+## 0.12.0 — 2026-05-15
+
+**AI crawler + AI referral telemetry — `smkingProxy` Next.js middleware.**
+
+### Added
+
+- **`@soloworks/smking-next/proxy` subpath export.** New `smkingProxy({ apiKey, baseUrl? })` middleware factory + `composeProxy([...handlers])` helper. Detects AI bot UAs (17 patterns covering GPTBot / ClaudeBot / PerplexityBot / Google-Extended / Applebot / CCBot / Bytespider / meta-externalagent / Amazonbot / Cohere / Diffbot) and AI-referrer hostnames (chatgpt.com / perplexity.ai / claude.ai / gemini.google.com / copilot.microsoft.com / bing.com), then fire-and-forgets a `POST /api/v1/crawler-hit` ingest via Vercel `after()` so the customer's response is never delayed.
+
+  Install:
+
+  ```ts
+  // proxy.ts
+  import { smkingProxy } from "@soloworks/smking-next/proxy";
+
+  export const proxy = smkingProxy({ apiKey: process.env.SMKING_API_KEY! });
+
+  export const config = {
+    matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+  };
+  ```
+
+  Composing with an existing proxy:
+
+  ```ts
+  import { composeProxy, smkingProxy } from "@soloworks/smking-next/proxy";
+  import { customerProxy } from "./their-proxy";
+
+  export const proxy = composeProxy([
+    smkingProxy({ apiKey: process.env.SMKING_API_KEY! }),
+    customerProxy,
+  ]);
+  ```
+
+  Fail-open: missing `SMKING_API_KEY` / `SMKING_BASE_URL` → no-op (matches `getAeoContent` convention). Ingestion endpoint down / 4xx / 5xx → silent skip. Customer site never breaks because of telemetry.
+
+### Why
+
+Crawler telemetry feeds the new 4-pillar AEO Scorecard (visibility / bot engagement / content readiness / traffic impact). Without per-customer-site detection, the scorecard's Bot Engagement and Traffic Impact pillars stay at zero forever. SDK ships the detection so customers don't need to roll their own — `pnpm update @soloworks/smking-next` + add 5-line `proxy.ts` = done.
+
+### Customer migration
+
+- **Caret rule reminder**: `^0.11` resolves to `>=0.11.0 <0.12.0`, so `pnpm update` will NOT pull 0.12 automatically. Bump constraint to `^0.12` in `package.json` to receive this release.
+- No other breaking changes vs 0.11. AEO / CMS / webhook surfaces unchanged.
+
+## 0.11.0 — 2026-05-15
+
+**Substrate pivot: unified webhook channel.**
+
+### BREAKING
+
+- **Unified webhook endpoint.** `@soloworks/smking-next/webhook` replaces the previous split: `/route` (AEO Bearer-authed) AND `/cms-webhook` (CMS HMAC). Single HMAC-signed endpoint, payload `.kind` (`"aeo" | "cms_page" | ...`) dispatches which revalidate tag namespace to use.
+
+  Customer migration:
+  1. **Env**: `SMKING_WEBHOOK_TOKEN` → `SMKING_WEBHOOK_SECRET` (HMAC key — same secret you got from the install prompt for CMS, now used for everything).
+  2. **Route shim**: replace both `app/api/smking-revalidate/route.ts` (AEO) AND `app/api/smking/webhook/route.ts` (CMS) with a single `app/api/smking/webhook/route.ts` exporting `POST` from `@soloworks/smking-next/webhook`.
+  3. **Dashboard webhook URL** field should point at the single `/api/smking/webhook` path.
+
+- **Revalidate tag namespaces changed.** Customer code calling `revalidateTag` directly (rare — most customers use `<SmkingAEO />` / `<SmkingCms />` which handle this internally) must update:
+  - `smking:path:*` → `smking:aeo:*`
+  - `smking:cms:*` → `smking:cms_page:*`
+
+- **`/route` and `/cms-webhook` exports removed.** Importing either at v0.11 fails with a "Module not found" error pointing customers at the migration. Old source files deleted from the package (git history preserves them).
+
+### Why
+
+PostHog architectural pattern study (`docs/cms-tech-suggestions-posthog.md`) flagged the split webhook as substrate-discipline violation. One channel for the substrate; payload `kind` distinguishes projection. Future product surfaces (widget config, crawler analytics, Shopify connector) extend the discriminator without growing the SDK.
+
+## 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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.9.1",
+  "version": "0.12.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,9 +15,13 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
-    "./route": {
-      "types": "./src/route.ts",
-      "default": "./src/route.ts"
+    "./cms": {
+      "types": "./src/components/smking-cms.tsx",
+      "default": "./src/components/smking-cms.tsx"
+    },
+    "./webhook": {
+      "types": "./src/lib/webhook-route.ts",
+      "default": "./src/lib/webhook-route.ts"
     },
     "./robots": {
       "types": "./src/lib/robots.ts",
@@ -30,6 +34,10 @@
     "./llms-txt": {
       "types": "./src/lib/llms-txt-route.ts",
       "default": "./src/lib/llms-txt-route.ts"
+    },
+    "./proxy": {
+      "types": "./src/lib/proxy.ts",
+      "default": "./src/lib/proxy.ts"
     }
   },
   "bin": {
@@ -60,6 +68,11 @@
   "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/smking-cms.tsx

@@ -0,0 +1,163 @@
+import { getCmsPage } from "../lib/cms-client";
+import type { Block, 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"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * 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 tiptap-html, so the customer SDK
+ * needs zero Tiptap dependencies). Hero / nav-* blocks render inline;
+ * full server-side data fetch for nav-recent-posts / nav-taxonomy-list
+ * / nav-search arrives in M2+ — they emit pending markers for now so
+ * customer pages don't 500 if the page contains them.
+ *
+ * Returns null when the response isn't ready (pending / not_found /
+ * unreachable / mis-configured) — fail-open by design.
+ *
+ * Emits `<title>` / `<meta>` / `og:*` / canonical inline; React 19
+ * hoists them into `<head>` automatically.
+ */
+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;
+  const blocks = data.page.blocks ?? [];
+  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-content-type={data.page.contentType}
+      >
+        {data.page.title && (
+          <h1 className="smk-cms__title">{data.page.title}</h1>
+        )}
+        {blocks.map((block) => renderBlock(block))}
+      </article>
+    </>
+  );
+}
+
+/**
+ * Dispatch a single block to its rendered React element.
+ *
+ * Trust boundary for `article` blocks: HTML is rendered server-side at
+ * write time by `@tiptap/html/server` inside the SaaS (Tiptap's renderer
+ * only emits HTML for known nodes per the configured schema, so author
+ * input can't smuggle arbitrary tags through). Customer site renders
+ * that HTML as-is via React's raw-HTML escape hatch. If customer wants
+ * defence-in-depth beyond the SaaS sanitisation tier, layer CSP on
+ * their host page (smking SDK does not ship a customer-side sanitiser
+ * to keep zero-dep customer install).
+ */
+function renderBlock(block: Block) {
+  switch (block.component) {
+    case "article": {
+      const articleHtml: { __html: string } = { __html: block.props.html };
+      return (
+        <div
+          key={block.id}
+          className="smk-block smk-block--article"
+          data-block-id={block.id}
+          // eslint-disable-next-line react/no-danger -- HTML pre-rendered server-side via @tiptap/html/server; trust boundary = SaaS schema. See function-level doc-comment above.
+          dangerouslySetInnerHTML={articleHtml}
+        />
+      );
+    }
+    case "hero":
+      return (
+        <section
+          key={block.id}
+          className="smk-block smk-block--hero smk-hero"
+          data-block-id={block.id}
+        >
+          {block.props.image && (
+            <img
+              src={block.props.image.url}
+              alt={block.props.image.alt}
+              className="smk-hero__image"
+            />
+          )}
+          <h2 className="smk-hero__title">{block.props.title}</h2>
+          {block.props.subtitle && (
+            <p className="smk-hero__subtitle">{block.props.subtitle}</p>
+          )}
+          {block.props.cta && (
+            <a className="smk-hero__cta" href={block.props.cta.href}>
+              {block.props.cta.label}
+            </a>
+          )}
+        </section>
+      );
+    case "nav-recent-posts":
+    case "nav-taxonomy-list":
+    case "nav-search":
+      // Server-side data fetch + render lands in M2+ alongside the
+      // public posts / taxonomy / search endpoints. Emit a marker so
+      // customer pages don't 500 if an editor publishes a page with
+      // one of these blocks before M2 ships.
+      return (
+        <section
+          key={block.id}
+          className={`smk-block smk-block--${block.component} smk-nav-pending`}
+          data-block-id={block.id}
+          data-block-component={block.component}
+        />
+      );
+    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}
+        />
+      );
+  }
+}

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/client.ts

@@ -26,8 +26,11 @@ function warnOnce(key: string, message: string): void {
  *   - JSON parse failure
  *
  * On success, cached by Next.js data cache for 1h (ISR backstop). Tagged
- * with `smking:path:<path>` so the webhook handler at `@soloworks/smking-next/route`
- * can `revalidateTag` to invalidate instantly when SaaS pushes an update.
+ * with `smking:aeo:<path>` so the unified webhook handler at
+ * `@soloworks/smking-next/webhook` can `revalidateTag` to invalidate
+ * instantly when SaaS pushes an update. Namespace changed from
+ * `smking:path:*` in v0.11 — unified channel uses payload.kind to
+ * scope tag prefix.
  *
  * Sends `{ key, path, url }` — `url` is required for first-sight
  * registration: when the SaaS hasn't seen this path before it queues a
@@ -82,7 +85,7 @@ export async function getAeoContent(
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
       next: {
         revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
-        tags: [`smking:path:${path}`],
+        tags: [`smking:aeo:${path}`],
       },
     });
     if (!res.ok) return null;

package/src/lib/cms-client.ts

@@ -0,0 +1,88 @@
+// 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_page:<slug>` so the unified `/webhook` handler
+ * can `revalidateTag` to invalidate instantly when SaaS publishes an
+ * update. Namespace changed from `smking:cms:*` in v0.11 — unified
+ * channel uses payload.kind to scope tag prefix.
+ */
+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_page:${params.slug}`],
+      },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as CmsResponse;
+  } catch {
+    return null;
+  }
+}

package/src/lib/crawlers.ts

@@ -0,0 +1,136 @@
+/**
+ * AI bot + referral detection. Shared by `smkingProxy` (Next.js middleware)
+ * and any caller that wants to classify a request before forwarding it to
+ * the smking ingestion endpoint.
+ *
+ * Patterns are 2026-04 active list — see
+ * docs/ai-tracking-implementation.md A.2 for sourcing notes. Quarterly
+ * refresh from Cloudflare Radar / Dark Visitors / each vendor's docs.
+ *
+ * Detection precedence:
+ *   1. Bot UA match → `purpose` derived from bot category
+ *   2. No bot, but referer is an AI search surface → `purpose = ai_referral`
+ *   3. Otherwise → no record (we don't store noise)
+ */
+
+export type AiBotCategory = "training" | "search" | "user_triggered";
+
+export type AiHitPurpose =
+  | "training"
+  | "realtime_citation"
+  | "ai_referral"
+  | "unknown";
+
+interface CrawlerPattern {
+  readonly name: string;
+  readonly regex: RegExp;
+  readonly category: AiBotCategory;
+}
+
+const PATTERNS: readonly CrawlerPattern[] = [
+  // OpenAI
+  { name: "GPTBot", regex: /GPTBot\/[\d.]+/, category: "training" },
+  { name: "OAI-SearchBot", regex: /OAI-SearchBot\/[\d.]+/, category: "search" },
+  { name: "ChatGPT-User", regex: /ChatGPT-User\/[\d.]+/, category: "user_triggered" },
+  // Anthropic
+  { name: "ClaudeBot", regex: /ClaudeBot\/[\d.]+/, category: "training" },
+  { name: "Claude-Web", regex: /Claude-Web\/[\d.]+/, category: "user_triggered" },
+  { name: "anthropic-ai", regex: /anthropic-ai/, category: "training" },
+  // Perplexity
+  { name: "PerplexityBot", regex: /PerplexityBot\/[\d.]+/, category: "training" },
+  { name: "Perplexity-User", regex: /Perplexity-User\/[\d.]+/, category: "user_triggered" },
+  // Google
+  { name: "Google-Extended", regex: /Google-Extended/, category: "training" },
+  { name: "GoogleOther", regex: /GoogleOther/, category: "training" },
+  // Apple
+  { name: "Applebot-Extended", regex: /Applebot-Extended\/[\d.]+/, category: "training" },
+  // Common Crawl (shared corpus for many LLMs)
+  { name: "CCBot", regex: /CCBot\/[\d.]+/, category: "training" },
+  // ByteDance / Doubao
+  { name: "Bytespider", regex: /Bytespider/, category: "training" },
+  // Meta AI
+  { name: "meta-externalagent", regex: /meta-externalagent\/[\d.]+/, category: "training" },
+  // Amazon Alexa+
+  { name: "Amazonbot", regex: /Amazonbot\/[\d.]+/, category: "training" },
+  // Cohere
+  { name: "cohere-ai", regex: /cohere-ai/, category: "training" },
+  // Diffbot
+  { name: "Diffbot", regex: /Diffbot\/[\d.]+/, category: "training" },
+];
+
+/**
+ * Hostnames that indicate the user came from an AI answer surface. Used to
+ * tag `ai_referral` traffic (no bot UA, real human session bounced from
+ * ChatGPT et al.).
+ */
+const AI_REFERRER_HOSTS: ReadonlySet<string> = new Set([
+  "chatgpt.com",
+  "chat.openai.com",
+  "perplexity.ai",
+  "www.perplexity.ai",
+  "claude.ai",
+  "gemini.google.com",
+  "copilot.microsoft.com",
+  "bing.com",
+  "www.bing.com",
+]);
+
+export interface AiBotInfo {
+  readonly name: string;
+  readonly category: AiBotCategory;
+}
+
+/**
+ * Returns bot info if the UA matches a known AI crawler pattern. Linear
+ * scan of ~17 regexes — sub-millisecond per call, fine for a hot path.
+ */
+export function detectAiBot(userAgent: string | null | undefined): AiBotInfo | null {
+  if (!userAgent) return null;
+  for (const p of PATTERNS) {
+    if (p.regex.test(userAgent)) {
+      return { name: p.name, category: p.category };
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true when the referer header points to an AI answer surface.
+ * NULL-safe and tolerant of malformed URLs.
+ */
+export function detectAiReferral(referer: string | null | undefined): boolean {
+  if (!referer) return false;
+  try {
+    const host = new URL(referer).hostname.toLowerCase();
+    return AI_REFERRER_HOSTS.has(host);
+  } catch {
+    return false;
+  }
+}
+
+export interface AiHitClassification {
+  readonly purpose: AiHitPurpose;
+  readonly bot: string | null;
+  readonly botCategory: AiBotCategory | null;
+}
+
+/**
+ * Classify a request from its UA + referer. Returns `null` when it's
+ * neither a known AI bot nor an AI-referred human session — the caller
+ * should skip recording these to keep ingestion focused.
+ */
+export function classifyAiHit(
+  userAgent: string | null | undefined,
+  referer: string | null | undefined,
+): AiHitClassification | null {
+  const bot = detectAiBot(userAgent);
+  if (bot) {
+    const purpose: AiHitPurpose =
+      bot.category === "training" ? "training" : "realtime_citation";
+    return { purpose, bot: bot.name, botCategory: bot.category };
+  }
+  if (detectAiReferral(referer)) {
+    return { purpose: "ai_referral", bot: null, botCategory: null };
+  }
+  return null;
+}

package/src/lib/path.ts

@@ -43,7 +43,7 @@ export async function resolveRequestPath(): Promise<{
  * Normalize a path so cache tags align across hand-written and
  * auto-resolved callers. `<SmkingAEO path="products/abc" />` and
  * `<SmkingAEO path="/products/abc" />` must hit the same Next.js cache
- * entry — otherwise the webhook handler's `revalidateTag('smking:path:/products/abc')`
+ * entry — otherwise the webhook handler's `revalidateTag('smking:aeo:/products/abc')`
  * misses the version of the entry that lacks the leading slash.
  */
 export function normalizePath(path: string): string {

package/src/lib/proxy.ts

@@ -0,0 +1,147 @@
+import { NextResponse, type NextRequest, after } from "next/server";
+import { classifyAiHit } from "./crawlers";
+
+/**
+ * SmKing AI traffic ingestion proxy (v0.12+, Next.js 16 `proxy.ts`).
+ *
+ * Drop-in install:
+ *
+ * ```ts
+ * // proxy.ts (project root)
+ * import { smkingProxy } from "@soloworks/smking-next/proxy";
+ *
+ * export const proxy = smkingProxy({
+ *   apiKey: process.env.SMKING_API_KEY!,
+ * });
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ * };
+ * ```
+ *
+ * What it does:
+ *   - Inspects each request's UA + referer
+ *   - If it's an AI bot or AI-referred human session, batches one
+ *     ingestion call via Vercel `after()` (post-response background)
+ *   - Otherwise: passes through with zero overhead
+ *
+ * Composing with an existing proxy:
+ *
+ * ```ts
+ * import { composeProxy, smkingProxy } from "@soloworks/smking-next/proxy";
+ * import { customerProxy } from "./their-proxy";
+ *
+ * export const proxy = composeProxy([
+ *   smkingProxy({ apiKey: process.env.SMKING_API_KEY! }),
+ *   customerProxy,
+ * ]);
+ * ```
+ *
+ * Fail-open posture (matches `getAeoContent`):
+ *   - No `apiKey` → no-op, customer site keeps running
+ *   - No `baseUrl` / `SMKING_BASE_URL` → no-op
+ *   - Ingestion endpoint down / 4xx / 5xx → silent skip, next request retries
+ *
+ * Why `after()` (not fire-and-forget `fetch`):
+ *   - Vercel serverless kills the function once the response flushes,
+ *     which can drop a naked fetch before it's sent
+ *   - `after()` keeps the function alive within the existing lifetime
+ *     for background work — designed exactly for this case
+ */
+export interface SmkingProxyConfig {
+  /** Site's public API key (`pk_*`). Falls back to `SMKING_API_KEY` env. */
+  apiKey?: string;
+  /** Ingestion base URL. Falls back to `SMKING_BASE_URL` env. */
+  baseUrl?: string;
+}
+
+export type ProxyMiddleware = (
+  request: NextRequest,
+) => NextResponse | Promise<NextResponse>;
+
+const INGEST_TIMEOUT_MS = 2000;
+
+/**
+ * Build the proxy middleware. Returns a no-op middleware when the
+ * required env / config is missing so dev / staging installs without
+ * env never crash.
+ */
+export function smkingProxy(config: SmkingProxyConfig = {}): ProxyMiddleware {
+  return (request: NextRequest) => {
+    const apiKey = config.apiKey ?? process.env.SMKING_API_KEY;
+    const baseUrl = (config.baseUrl ?? process.env.SMKING_BASE_URL)?.replace(
+      /\/$/,
+      "",
+    );
+    if (!apiKey || !baseUrl) {
+      return NextResponse.next();
+    }
+
+    const ua = request.headers.get("user-agent");
+    const referer = request.headers.get("referer");
+    const hit = classifyAiHit(ua, referer);
+    if (!hit) return NextResponse.next();
+
+    const path = request.nextUrl.pathname;
+    const pageUrl = request.nextUrl.toString();
+
+    after(async () => {
+      try {
+        await fetch(`${baseUrl}/api/v1/crawler-hit`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-public-key": apiKey,
+          },
+          body: JSON.stringify({
+            hits: [
+              {
+                bot: hit.bot,
+                bot_category: hit.botCategory,
+                purpose: hit.purpose,
+                path,
+                page_url: pageUrl,
+                user_agent: ua,
+                referer,
+                timestamp: new Date().toISOString(),
+              },
+            ],
+          }),
+          signal: AbortSignal.timeout(INGEST_TIMEOUT_MS),
+        });
+      } catch {
+        // Ingestion failure must NEVER bubble to the customer site.
+        // Next request will retry — losing a hit is acceptable.
+      }
+    });
+
+    return NextResponse.next();
+  };
+}
+
+/**
+ * Run middlewares in sequence. The first one to return a non-`next()`
+ * response (redirect / rewrite / abort) short-circuits the chain.
+ *
+ * NOTE: this assumes each middleware in the chain only adds headers or
+ * passes through — it does NOT compose response bodies. Use cases:
+ *   - smkingProxy (telemetry only) + customer auth proxy
+ *   - smkingProxy + customer feature flag proxy
+ */
+export function composeProxy(handlers: ProxyMiddleware[]): ProxyMiddleware {
+  return async (request: NextRequest) => {
+    for (const h of handlers) {
+      const result = await h(request);
+      if (!isPassThrough(result)) return result;
+    }
+    return NextResponse.next();
+  };
+}
+
+function isPassThrough(res: NextResponse): boolean {
+  // `NextResponse.next()` carries `x-middleware-next: 1` internally.
+  // Public surface: `res.headers.get('x-middleware-next')` returns "1"
+  // for a pass-through. Anything else (redirect, rewrite, body) is a
+  // terminal response.
+  return res.headers.get("x-middleware-next") === "1";
+}

package/src/lib/webhook-route.ts

@@ -0,0 +1,126 @@
+import { revalidateTag } from "next/cache";
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+
+interface WebhookPayload {
+  kind?: string;
+  paths?: string[];
+  slugs?: string[];
+  deliveredAt?: string;
+}
+
+/**
+ * SmKing unified webhook handler (v0.11+).
+ *
+ * Drop-in install:
+ *
+ * ```ts
+ * // app/api/smking/webhook/route.ts
+ * export { POST } from "@soloworks/smking-next/webhook";
+ * ```
+ *
+ * Replaces v0.10's split handlers:
+ *   - `/route`        AEO, Bearer-authed (SMKING_WEBHOOK_TOKEN) — GONE
+ *   - `/cms-webhook`  CMS, HMAC-signed (SMKING_WEBHOOK_SECRET) — GONE
+ *
+ * Single HMAC-SHA256 endpoint. Payload `.kind` (`"aeo" | "cms_page" |
+ * future kinds`) dispatches which revalidate tag namespace to use:
+ *
+ *   smking:{kind}:{identifier}
+ *
+ * Where identifier is either:
+ *   - path  (AEO: `["/products/foo"]`) — `smking:aeo:/products/foo`
+ *   - slug  (CMS: `["hello"]`) — `smking:cms_page:hello`
+ *
+ * Customer migration from v0.10:
+ *   1. env: SMKING_WEBHOOK_TOKEN → SMKING_WEBHOOK_SECRET (HMAC key)
+ *   2. route path: /api/smking-revalidate + /api/smking/webhook
+ *      → /api/smking/webhook (single)
+ *   3. revalidateTag callers update tag prefix
+ *
+ * Auth: HMAC-SHA256 only. Bearer dropped — single auth model means one
+ * env var, one shim, fewer customer mis-config paths (the disambiguation
+ * problem the v0.10 dual-handler shipped with).
+ */
+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: WebhookPayload;
+  try {
+    payload = JSON.parse(rawBody) as WebhookPayload;
+  } catch {
+    return Response.json({ error: "invalid_payload" }, { status: 400 });
+  }
+
+  const kind = payload.kind;
+  if (typeof kind !== "string" || kind.length === 0) {
+    // Forward-compat: SaaS may emit kinds we haven't taught the SDK
+    // yet — acknowledge (200) without action so SaaS doesn't retry.
+    return Response.json({ ok: true, note: "no_action_taken" });
+  }
+
+  let revalidated = 0;
+  let errors = 0;
+  for (const path of payload.paths ?? []) {
+    try {
+      revalidateTag(`smking:${kind}:${path}`, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        `[@soloworks/smking-next/webhook] revalidateTag failed for ${kind}/${path}:`,
+        err,
+      );
+    }
+  }
+  for (const slug of payload.slugs ?? []) {
+    try {
+      revalidateTag(`smking:${kind}:${slug}`, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        `[@soloworks/smking-next/webhook] revalidateTag failed for ${kind}/${slug}:`,
+        err,
+      );
+    }
+  }
+
+  return Response.json({ ok: true, kind, revalidated, errors });
+}
+
+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,114 @@ export interface AeoResponse {
   seo?: SeoMeta | null;
 }
 
+// ── CMS body content (mirrors SaaS /api/v1/public/page) ───────────────
+
+export type CmsStatus = "ready" | "pending" | "not_found";
+
+export type CmsContentType = "article" | "landing" | "listing";
+
+/**
+ * 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
+ * grows past 5 primitives, a shared workspace package replaces this
+ * duplication per `docs/superpowers/specs/2026-05-15-cms-dashboard-editor-design.md`
+ * section §11 + ai-cms-v2 §"擴充性").
+ */
+export interface HeroProps {
+  title: string;
+  subtitle?: string;
+  image?: { url: string; alt: string };
+  cta?: { label: string; href: string };
+}
+export interface ArticleProps {
+  html: string;
+}
+export interface ModuleHeader {
+  heading?: string;
+  viewAll?: { label: string; href: string };
+}
+export type NavLayout = "grid" | "list" | "carousel";
+export interface NavRecentPostsProps extends ModuleHeader {
+  limit: number;
+  layout: NavLayout;
+  contentType?: "article" | "all";
+}
+export interface NavTaxonomyListProps extends ModuleHeader {
+  /** category-by-path: slug prefix; tag: taxonomies.slug */
+  source: "category-by-path" | "tag";
+  path: string;
+  limit: number;
+  layout: NavLayout;
+}
+export interface NavSearchProps {
+  placeholder: string;
+  contentType?: "article" | "all";
+}
+
+export type Block =
+  | { component: "hero"; id: string; props: HeroProps }
+  | { component: "article"; id: string; props: ArticleProps }
+  | {
+      component: "nav-recent-posts";
+      id: string;
+      props: NavRecentPostsProps;
+    }
+  | {
+      component: "nav-taxonomy-list";
+      id: string;
+      props: NavTaxonomyListProps;
+    }
+  | { component: "nav-search"; id: string; props: NavSearchProps };
+
+/**
+ * A single published CMS page returned by the smking public API
+ * (substrate v2). Render via `<SmkingCms>` server component which
+ * dispatches each block by component type.
+ */
+export interface CmsPage {
+  slug: string;
+  title: string;
+  contentType: CmsContentType;
+  blocks: Block[];
+  excerpt?: string | null;
+  featuredImageUrl?: string | null;
+  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;

package/src/route.ts

@@ -1,112 +0,0 @@
-import { revalidateTag } from "next/cache";
-import { Buffer } from "node:buffer";
-import crypto from "node:crypto";
-
-interface WebhookPayload {
-  paths?: string[];
-}
-
-const BEARER_PREFIX = "Bearer ";
-
-/**
- * Webhook handler for SaaS-pushed cache invalidation. Drop-in install:
- *
- *   ```ts
- *   // app/api/smking-revalidate/route.ts
- *   export { POST, GET } from '@soloworks/smking-next/route';
- *   ```
- *
- * Then set `SMKING_WEBHOOK_TOKEN` in your environment and configure the
- * SaaS to POST `{ paths: [...] }` with `Authorization: Bearer <token>`.
- *
- * Bearer-token auth (not HMAC body signing) — sufficient for v1.
- * HMAC-signed body verification can layer on later if attack surface
- * justifies it. Token compare runs through `crypto.timingSafeEqual` to
- * avoid leaking length / prefix info via response time.
- */
-export async function POST(request: Request): Promise<Response> {
-  const expected = process.env.SMKING_WEBHOOK_TOKEN;
-  if (!expected) {
-    return Response.json(
-      { error: "webhook_not_configured" },
-      { status: 503 },
-    );
-  }
-
-  const auth = request.headers.get("authorization");
-  if (!auth || !verifyBearer(auth, expected)) {
-    return Response.json({ error: "unauthorized" }, { status: 401 });
-  }
-
-  let payload: WebhookPayload;
-  try {
-    payload = (await request.json()) as WebhookPayload;
-  } catch {
-    return Response.json({ error: "invalid_json" }, { status: 400 });
-  }
-
-  let revalidated = 0;
-  let errors = 0;
-  for (const p of payload.paths ?? []) {
-    try {
-      // Next.js 16 requires a cache profile; 'default' matches the
-      // implicit profile a normal `'use cache'` block uses.
-      revalidateTag(`smking:path:${p}`, "default");
-      revalidated++;
-    } catch (err) {
-      errors++;
-      console.warn(
-        `[@soloworks/smking-next] revalidateTag failed for path "${p}":`,
-        err,
-      );
-    }
-  }
-
-  return Response.json({ revalidated, errors });
-}
-
-/**
- * Liveness probe — POST-only public endpoint, but `GET` returns 401 with
- * a `WWW-Authenticate` header so customers can verify the route is wired
- * up by sending a token. Discourages anonymous probes from confirming
- * the endpoint exists.
- */
-export async function GET(request: Request): Promise<Response> {
-  const expected = process.env.SMKING_WEBHOOK_TOKEN;
-  if (!expected) {
-    return Response.json(
-      { error: "webhook_not_configured" },
-      { status: 503 },
-    );
-  }
-  const auth = request.headers.get("authorization");
-  if (auth && verifyBearer(auth, expected)) {
-    return new Response("OK", { status: 200 });
-  }
-  return new Response("Unauthorized", {
-    status: 401,
-    headers: { "WWW-Authenticate": 'Bearer realm="smking-webhook"' },
-  });
-}
-
-/**
- * Constant-time bearer-token compare. Returns false on:
- *   - missing or non-Bearer header
- *   - presented token has different length than expected (early-out;
- *     the lengths themselves leak nothing because the secret is set by
- *     the customer with a known length)
- *   - byte-different but same-length token
- */
-function verifyBearer(authHeader: string, expected: string): boolean {
-  if (!authHeader.startsWith(BEARER_PREFIX)) return false;
-  const presented = authHeader.slice(BEARER_PREFIX.length);
-  if (presented.length !== expected.length) return false;
-  try {
-    return crypto.timingSafeEqual(
-      Buffer.from(presented),
-      Buffer.from(expected),
-    );
-  } catch {
-    return false;
-  }
-}