@soloworks/smking-next 0.21.4 → 0.21.6

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @soloworks/smking-next
 
+## 0.21.6 — 2026-07-20
+
+**Next.js metadata can now be authoritative instead of duplicated.**
+
+- Added `withSmkingMetadata()` for the App Router `generateMetadata` export.
+  Ready Page Zero SEO fields override the matching host fields while unrelated
+  host metadata stays intact.
+- Added `<SmkingAEO includeSeo={false} />` so JSON-LD and hidden AEO content
+  remain rendered without emitting duplicate title and meta elements.
+
+## 0.21.5 — 2026-07-20
+
+**AEO path discovery now works on Vercel without replacing host proxy responses.**
+
+- The Page Zero proxy forwards the concrete request URL and pathname to App
+  Router Server Components before continuing the customer's existing proxy.
+- `<SmkingAEO />` now looks up the requested route instead of falling back to
+  `/` when Vercel omits pathname headers.
+- Customer redirects, rewrites, cookies, and response headers remain owned by
+  the customer's proxy.
+
 ## 0.21.4 — 2026-07-20
 
 **Doctor checks now validate the actual App Router root and the public API contract.**

package/bin/install.mjs

@@ -15,8 +15,8 @@
  *   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
+ * - **doctor** — Self-check (env presence + authoritative AEO/SEO layout
+ *   integration + 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
@@ -207,22 +207,30 @@ function checkLayoutUsage(appDir) {
   const layoutPath = findRootLayout(appDir);
   if (!layoutPath) {
     return {
-      name: "<SmkingAEO /> in root layout",
+      name: "AEO + SEO in root layout",
       status: "fail",
       detail: `no root layout owning <html> and <body> found under ${appDir}/`,
     };
   }
 
   const content = readFileSync(layoutPath, "utf-8");
-  if (!content.includes("SmkingAEO")) {
+  const missing = [];
+  if (!content.includes("SmkingAEO")) missing.push("SmkingAEO");
+  if (!content.includes("withSmkingMetadata(")) {
+    missing.push("withSmkingMetadata() in generateMetadata");
+  }
+  if (!/includeSeo\s*=\s*\{\s*false\s*\}/.test(content)) {
+    missing.push("includeSeo={false}");
+  }
+  if (missing.length > 0) {
     return {
-      name: "<SmkingAEO /> in root layout",
+      name: "AEO + SEO 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>.`,
+      detail: `${layoutPath} is missing ${missing.join(", ")}. Use withSmkingMetadata() for authoritative Next.js metadata and render <SmkingAEO includeSeo={false} /> inside <body>.`,
     };
   }
   return {
-    name: "<SmkingAEO /> in root layout",
+    name: "AEO + SEO in root layout",
     status: "pass",
     detail: layoutPath,
   };
@@ -324,7 +332,7 @@ async function runDoctor(jsonOutput) {
     appDir
       ? checkLayoutUsage(appDir)
       : {
-          name: "<SmkingAEO /> in root layout",
+          name: "AEO + SEO in root layout",
           status: "info",
           detail: "no app/ or src/app/ directory found — skipped",
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.21.4",
+  "version": "0.21.6",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",

package/src/components/smking-aeo.tsx

@@ -16,7 +16,14 @@ const SR_ONLY_STYLE: React.CSSProperties = {
   border: 0,
 };
 
-export interface SmkingAEOProps extends DiscoverParams {}
+export interface SmkingAEOProps extends DiscoverParams {
+  /**
+   * Keep the legacy React 19 metadata tags. Set false when the host uses
+   * `withSmkingMetadata()` from `generateMetadata`, which is the authoritative
+   * Next.js integration and avoids duplicate title/meta elements.
+   */
+  includeSeo?: boolean;
+}
 
 async function wantsOriginBypass(): Promise<boolean> {
   try {
@@ -82,6 +89,7 @@ export async function SmkingAEO(props: SmkingAEOProps) {
   const hasBodyFragments = Boolean(
     aeo.summaryHtml || aeo.faqHtml || seo?.ogImageUrl,
   );
+  const includeSeo = props.includeSeo ?? true;
 
   return (
     <>
@@ -93,21 +101,23 @@ export async function SmkingAEO(props: SmkingAEOProps) {
         />
       )}
 
-      {seo?.title && <title data-smking="aeo">{seo.title}</title>}
-      {description && (
+      {includeSeo && seo?.title && (
+        <title data-smking="aeo">{seo.title}</title>
+      )}
+      {includeSeo && description && (
         <meta name="description" content={description} data-smking="aeo" />
       )}
-      {seo?.ogTitle && (
+      {includeSeo && seo?.ogTitle && (
         <meta property="og:title" content={seo.ogTitle} data-smking="aeo" />
       )}
-      {seo?.ogDescription && (
+      {includeSeo && seo?.ogDescription && (
         <meta
           property="og:description"
           content={seo.ogDescription}
           data-smking="aeo"
         />
       )}
-      {seo?.ogImageUrl && (
+      {includeSeo && seo?.ogImageUrl && (
         <meta
           property="og:image"
           content={seo.ogImageUrl}

package/src/index.ts

@@ -3,6 +3,7 @@ export { SmkingCms } from "./components/smking-cms";
 export { SmkingRuntime } from "./components/smking-runtime";
 export { getAeoContent } from "./lib/client";
 export { getCmsPage } from "./lib/cms-client";
+export { withSmkingMetadata } from "./lib/metadata";
 export type {
   AeoResponse,
   AeoStatus,

package/src/lib/metadata.ts

@@ -0,0 +1,40 @@
+import type { Metadata } from "next";
+
+import type { DiscoverParams } from "../types";
+import { getAeoContent } from "./client";
+
+/**
+ * Merge Page Zero's ready SEO fields over an existing App Router metadata
+ * object. Use this from the root layout's `generateMetadata` export so Next.js
+ * emits one authoritative title and description instead of duplicate tags.
+ */
+export async function withSmkingMetadata(
+  hostMetadata: Metadata,
+  params: DiscoverParams,
+): Promise<Metadata> {
+  const aeo = await getAeoContent(params);
+  if (!aeo || aeo.status !== "ready") return hostMetadata;
+
+  const seo = aeo.seo ?? null;
+  const title = seo?.title ?? null;
+  const description = seo?.ogDescription ?? aeo.metaDescription ?? null;
+  const ogTitle = seo?.ogTitle ?? title;
+  const ogDescription = seo?.ogDescription ?? aeo.metaDescription ?? null;
+  const ogImageUrl = seo?.ogImageUrl ?? null;
+
+  return {
+    ...hostMetadata,
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(ogTitle || ogDescription || ogImageUrl
+      ? {
+          openGraph: {
+            ...(hostMetadata.openGraph ?? {}),
+            ...(ogTitle ? { title: ogTitle } : {}),
+            ...(ogDescription ? { description: ogDescription } : {}),
+            ...(ogImageUrl ? { images: [ogImageUrl] } : {}),
+          },
+        }
+      : {}),
+  };
+}

package/src/lib/path.ts

@@ -39,6 +39,22 @@ export async function resolveRequestPath(): Promise<{
   return { path, url };
 }
 
+/**
+ * Add the concrete request URL to the headers consumed by Server Components.
+ *
+ * Next.js does not expose the current pathname from `headers()` by default on
+ * Vercel. The Page Zero proxy runs before the App Router, so it records the
+ * verified `NextRequest.nextUrl` on the same request before the host proxy
+ * continues. Existing host proxy responses remain untouched.
+ */
+export function setRequestPathHeaders(
+  requestHeaders: Headers,
+  requestUrl: URL,
+): void {
+  requestHeaders.set("x-url", requestUrl.toString());
+  requestHeaders.set("x-pathname", requestUrl.pathname);
+}
+
 /**
  * Normalize a path so cache tags align across hand-written and
  * auto-resolved callers. `<SmkingAEO path="products/abc" />` and

package/src/lib/proxy.ts

@@ -1,5 +1,6 @@
 import { NextResponse, type NextRequest, after } from "next/server";
 import { classifyAiHit } from "./crawlers";
+import { setRequestPathHeaders } from "./path";
 
 /**
  * SmKing AI traffic ingestion proxy (v0.12+, Next.js 16 `proxy.ts`).
@@ -68,6 +69,11 @@ const INGEST_TIMEOUT_MS = 2000;
  */
 export function smkingProxy(config: SmkingProxyConfig = {}): ProxyMiddleware {
   return (request: NextRequest) => {
+    // Server Components cannot read the current pathname from `headers()` on
+    // Vercel unless middleware forwards it. Mutating this request keeps the
+    // host proxy's redirect, rewrite, cookie, and response behavior intact.
+    setRequestPathHeaders(request.headers, request.nextUrl);
+
     const apiKey = config.apiKey ?? process.env.SMKING_API_KEY;
     const baseUrl = (config.baseUrl ?? process.env.SMKING_BASE_URL)?.replace(
       /\/$/,

package/src/lib/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.21.4";
+export const SDK_VERSION = "0.21.6";