@soloworks/smking-next 0.10.0 → 0.12.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.10.0",
+  "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",
@@ -19,13 +19,9 @@
       "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"
+    "./webhook": {
+      "types": "./src/lib/webhook-route.ts",
+      "default": "./src/lib/webhook-route.ts"
     },
     "./robots": {
       "types": "./src/lib/robots.ts",
@@ -38,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": {
@@ -63,29 +63,7 @@
   ],
   "peerDependencies": {
     "next": "^15.0.0 || ^16.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
-    }
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/src/components/smking-cms.tsx

@@ -1,11 +1,5 @@
-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";
+import type { Block, CmsParams } from "../types";
 
 /**
  * Server Component that renders a published smking CMS page.
@@ -24,19 +18,19 @@ import type { CmsParams } from "../types";
  * }
  * ```
  *
- * 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.
+ * 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.
  *
- * Customer install requires four Tiptap peer deps:
- *   pnpm add @tiptap/static-renderer @tiptap/starter-kit \\
- *     @tiptap/extension-image @tiptap/extension-link
+ * Emits `<title>` / `<meta>` / `og:*` / canonical inline; React 19
+ * hoists them into `<head>` automatically.
  */
 export async function SmkingCms(props: CmsParams) {
   const data = await getCmsPage(props);
@@ -47,6 +41,7 @@ export async function SmkingCms(props: CmsParams) {
   // (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>}
@@ -74,23 +69,95 @@ export async function SmkingCms(props: CmsParams) {
         <link rel="canonical" href={seo.canonicalUrl} data-smking="cms" />
       )}
 
-      <article className="smk-cms" 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>
         )}
-        {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,
-            },
-          },
-        })}
+        {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/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

@@ -33,9 +33,10 @@ function warnOnce(key: string, message: string): void {
  *
  * 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.
+ * 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,
@@ -76,7 +77,7 @@ export async function getCmsPage(
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
       next: {
         revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
-        tags: [`smking:cms:${params.slug}`],
+        tags: [`smking:cms_page:${params.slug}`],
       },
     });
     if (!res.ok) 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

@@ -56,16 +56,73 @@ export interface AeoResponse {
 
 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.
- * `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).
+ * 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;
-  body: Record<string, unknown>;
+  contentType: CmsContentType;
+  blocks: Block[];
+  excerpt?: string | null;
+  featuredImageUrl?: string | null;
   publishedAt: string | null;
 }
 

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

@@ -1,32 +0,0 @@
-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

@@ -1,68 +0,0 @@
-/**
- * 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/lib/cms-webhook-route.ts

@@ -1,107 +0,0 @@
-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/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;
-  }
-}