@soloworks/smking-next 0.20.1 → 0.20.3

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @soloworks/smking-next
 
+## 0.20.3 — 2026-06-08
+
+**CMS draft preview URL now carries a visible `?smking_preview=1` marker.**
+
+The `/smking-preview` route still enables Next.js Draft Mode + stashes the
+token in an httpOnly cookie, but now redirects to `…/path?smking_preview=1`
+instead of the bare path. This makes a preview tab's URL visibly distinct from
+the published page so authors can tell draft from live at a glance (parity with
+the Laravel SDK). The token stays in the cookie — never the URL. Additive, so
+`^0.20` gets it automatically.
+
+## 0.20.2 — 2026-06-08
+
+**Feature (additive — shipped as a patch): CMS draft preview via Next.js Draft Mode.**
+
+The dashboard 預覽 button can now show unpublished draft content on the real
+customer page using a short-lived (15min) token. Everything here is additive,
+so customers on `^0.20` get it automatically — no constraint change needed.
+
+- New `./preview` export — a Draft Mode route handler. The install wizard
+  writes `app/smking-preview/route.ts` for you; to add it by hand:
+  ```ts
+  // app/smking-preview/route.ts
+  export { GET } from "@soloworks/smking-next/preview";
+  ```
+  It enables Draft Mode + stashes the token in an httpOnly cookie, then
+  redirects to the page.
+- `<SmkingCms>` now renders draftBlocks (status `"preview"`) when Draft Mode
+  is on, fetched with `cache: "no-store"`. Published render is unchanged.
+- New `CmsParams.previewToken` + `CmsStatus` gains `"preview"`.
+
+**Install-only + fail-open:** pages without the preview route never enter
+Draft Mode → always the published render. Existing installs are unaffected
+until they add the route (re-run `npx @soloworks/smking-wizard` to get it).
+
 ## 0.20.1 — 2026-06-03
 
 **Chore: removed dead carousel / nav-recent-posts / nav-search block types.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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",
@@ -38,6 +38,10 @@
     "./proxy": {
       "types": "./src/lib/proxy.ts",
       "default": "./src/lib/proxy.ts"
+    },
+    "./preview": {
+      "types": "./src/lib/preview-route.ts",
+      "default": "./src/lib/preview-route.ts"
     }
   },
   "bin": {

package/src/components/smking-cms.tsx

@@ -1,3 +1,5 @@
+import { cookies, draftMode } from "next/headers";
+
 import { getCmsPage } from "../lib/cms-client";
 import { safeJson } from "../lib/safe-json";
 import type { CmsParams } from "../types";
@@ -35,10 +37,39 @@ import type { CmsParams } from "../types";
  *
  * Emits `<title>` / `<meta>` / `og:*` / canonical inline; React 19
  * hoists them into `<head>` automatically.
+ *
+ * Do NOT also mount `<SmkingAEO>` on a page rendered by `<SmkingCms>`:
+ * both serve the same engine `@graph` (via `/public/page` and
+ * `/public/aeo` respectively), so stacking them emits a duplicate
+ * `<script type="application/ld+json">`. Pick one per page — `<SmkingCms>`
+ * for smking-hosted CMS pages, `<SmkingAEO>` for your own pages.
  */
 export async function SmkingCms(props: CmsParams) {
-  const data = await getCmsPage(props);
-  if (!data || data.status !== "ready" || !data.page) return null;
+  // Draft preview: when Next Draft Mode is on (set by the
+  // @soloworks/smking-next/preview route), carry the short-lived token from
+  // the cookie so getCmsPage hits the draft branch. Install-only + fail-open:
+  // pages without the preview route never enable draft mode → published render.
+  let previewToken: string | undefined;
+  try {
+    const { isEnabled } = await draftMode();
+    if (isEnabled) {
+      previewToken = (await cookies()).get("smking_preview_token")?.value;
+    }
+  } catch {
+    // draftMode/cookies unavailable (static export / outside request) →
+    // fall through to the published render.
+  }
+
+  const data = await getCmsPage(
+    previewToken ? { ...props, previewToken } : props,
+  );
+  if (
+    !data ||
+    (data.status !== "ready" && data.status !== "preview") ||
+    !data.page
+  ) {
+    return null;
+  }
 
   // SEO head tags emit inline. React 19 hoists `<title>` and `<meta>`
   // tags found anywhere in the tree into `<head>` automatically (last

package/src/lib/cms-client.ts

@@ -103,13 +103,23 @@ export async function getCmsPage(
     if (appEnv) {
       apiUrl += `&app_env=${encodeURIComponent(appEnv)}`;
     }
+    if (params.previewToken) {
+      apiUrl += `&preview_token=${encodeURIComponent(params.previewToken)}`;
+    }
 
     const res = await fetch(apiUrl, {
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-      next: {
-        revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
-        tags: [`smking:cms_page:${params.slug}`],
-      },
+      // Preview (draft) reads must never hit the ISR data cache — always
+      // fresh, and they expire when the token does. Published reads keep
+      // the 5min ISR backstop + revalidate tags for webhook invalidation.
+      ...(params.previewToken
+        ? { cache: "no-store" as const }
+        : {
+            next: {
+              revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
+              tags: [`smking:cms_page:${params.slug}`],
+            },
+          }),
     });
     if (!res.ok) return null;
     return (await res.json()) as CmsResponse;

package/src/lib/preview-route.ts

@@ -0,0 +1,54 @@
+import { cookies, draftMode } from "next/headers";
+import { redirect } from "next/navigation";
+
+/**
+ * Drop-in CMS draft preview entry. Customer adds:
+ *
+ * ```ts
+ * // app/smking-preview/route.ts
+ * export { GET } from "@soloworks/smking-next/preview";
+ * ```
+ *
+ * Flow: the dashboard 預覽鈕 opens `/smking-preview?token=…&path=/blog/x` →
+ * this enables Next.js Draft Mode + stashes the short-lived token in an
+ * httpOnly cookie → redirects to `/blog/x?smking_preview=1`, which
+ * `<SmkingCms>` then renders from draftBlocks (status "preview").
+ *
+ * The `?smking_preview=1` marker makes the preview tab's URL visibly distinct
+ * from the live page at a glance (parity with the Laravel SDK's
+ * `?smking_preview=` URL). The token itself stays in the httpOnly Draft Mode
+ * cookie — never the URL — so it can't leak via the address bar / referrer.
+ *
+ * Fail-safe / install-only:
+ *   - No token → plain redirect to the live page (Draft Mode NOT enabled).
+ *   - Only same-origin relative paths are honored (open-redirect guard):
+ *     anything not starting with a single "/" redirects to "/".
+ *   - Sites without this route never enter draft mode → published render.
+ */
+export async function GET(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const token = url.searchParams.get("token");
+  const rawPath = url.searchParams.get("path") ?? "/";
+  const path =
+    rawPath.startsWith("/") && !rawPath.startsWith("//") ? rawPath : "/";
+
+  let target = path;
+  if (token) {
+    (await draftMode()).enable();
+    (await cookies()).set("smking_preview_token", token, {
+      httpOnly: true,
+      sameSite: "lax",
+      path: "/",
+      maxAge: 60 * 15,
+    });
+    // Visible marker so the preview tab's URL differs from the live page at a
+    // glance (parity with the Laravel SDK). The token rides the httpOnly
+    // cookie above — deliberately kept OUT of the URL: it'd be a dead param
+    // (<SmkingCms> reads the cookie) and would leak into address bar / referrer.
+    const sep = path.includes("?") ? "&" : "?";
+    target = `${path}${sep}smking_preview=1`;
+  }
+
+  // redirect() throws NEXT_REDIRECT — expected control flow in route handlers.
+  redirect(target);
+}

package/src/types.ts

@@ -54,7 +54,7 @@ export interface AeoResponse {
 
 // ── CMS body content (mirrors SaaS /api/v1/public/page) ───────────────
 
-export type CmsStatus = "ready" | "pending" | "not_found";
+export type CmsStatus = "ready" | "preview" | "pending" | "not_found";
 
 export type CmsContentType = "article" | "landing" | "listing";
 
@@ -141,7 +141,9 @@ export interface CmsPage {
   /**
    * v0.M1+ engine-precomputed schema.org @graph. `<SmkingCms>` inlines it
    * as `<script type="application/ld+json">`. Null until the page is
-   * republished under the structured-data engine.
+   * republished under the structured-data engine. Don't also render
+   * `<SmkingAEO>` on the same page — it serves the same @graph and would
+   * duplicate the ld+json script.
    */
   jsonLd?: Record<string, unknown> | null;
 }
@@ -184,6 +186,14 @@ export interface CmsParams {
   path?: string;
   /** Optional app environment (e.g. 'development', 'production'). */
   appEnv?: string;
+  /**
+   * Short-lived preview JWT (from the dashboard 預覽鈕, carried via the
+   * `smking_preview_token` cookie that `@soloworks/smking-next/preview`
+   * sets). When present, fetches draftBlocks (status "preview") with
+   * `cache: "no-store"`. Absent → normal published render. Install-only:
+   * pages without the preview route never see this.
+   */
+  previewToken?: string;
 }
 
 export interface DiscoverParams {