@soloworks/smking-next 0.21.2 → 0.21.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @soloworks/smking-next
 
+## 0.21.4 — 2026-07-20
+
+**Doctor checks now validate the actual App Router root and the public API contract.**
+
+- Recursively finds nested root layouts such as `app/[locale]/layout.tsx`; a missing root is now a failure.
+- Probes the public AEO endpoint with its documented `?key=` parameter.
+- Treats a valid `not_found` response as proof that the API key was accepted and fails on unexpected `4xx` responses.
+- Uses Page Zero as the default SaaS origin and in customer-facing CLI output.
+
+## 0.21.3 — 2026-07-03
+
+**AEO original-vs-enhanced audits can now fetch the true host HTML.**
+
+`<SmkingAEO>` now honors `x-smking-origin-mode: raw` by returning `null`
+before calling the SaaS. This lets Page Zero fetch a customer page's real
+pre-injection HTML for source-change detection, then compare it against the
+served enhanced version. No customer code change; customers already on `^0.21`
+receive it on the next install/update.
+
 ## 0.21.2 — 2026-07-02
 
 **CMS taxonomy page types caught up with the SaaS catalog (types only — no runtime change).**
@@ -521,36 +540,33 @@ Next.js's `MetadataRoute.Robots` type doesn't model Cloudflare's `Content-Signal
 
 ```ts
 // app/robots.ts — Next.js MetadataRoute (NO Content-Signal)
-import type { MetadataRoute } from 'next';
-import { smkingRobotsRules } from '@soloworks/smking-next/robots';
+import type { MetadataRoute } from "next";
+import { smkingRobotsRules } from "@soloworks/smking-next/robots";
 
 export default function robots(): MetadataRoute.Robots {
   return {
-    rules: [
-      { userAgent: '*', disallow: ['/admin/'] },
-      ...smkingRobotsRules(),
-    ],
-    sitemap: 'https://example.com/sitemap.xml',
+    rules: [{ userAgent: "*", disallow: ["/admin/"] }, ...smkingRobotsRules()],
+    sitemap: "https://example.com/sitemap.xml",
   };
 }
 ```
 
 ```ts
 // app/robots.txt/route.ts — full robots.txt body (Content-Signal included)
-import { smkingRobotsTxt } from '@soloworks/smking-next/robots';
+import { smkingRobotsTxt } from "@soloworks/smking-next/robots";
 
 export function GET() {
   return new Response(
     smkingRobotsTxt({
-      rules: [{ userAgent: '*', disallow: ['/admin/'] }],
-      sitemap: 'https://example.com/sitemap.xml',
+      rules: [{ userAgent: "*", disallow: ["/admin/"] }],
+      sitemap: "https://example.com/sitemap.xml",
     }),
-    { headers: { 'Content-Type': 'text/plain' } },
+    { headers: { "Content-Type": "text/plain" } },
   );
 }
 ```
 
-Customer rules render *before* the smking AI bot block in both surfaces. `bots` config replaces (not merges) the default list — `{ CCBot: 'disallow' }` produces only one bot block, not eight. `contentSignal: null` (or `""`) drops the directive entirely; passing nothing uses the default `search=yes, ai-input=no, ai-train=no`.
+Customer rules render _before_ the smking AI bot block in both surfaces. `bots` config replaces (not merges) the default list — `{ CCBot: 'disallow' }` produces only one bot block, not eight. `contentSignal: null` (or `""`) drops the directive entirely; passing nothing uses the default `search=yes, ai-input=no, ai-train=no`.
 
 ### Default policy
 
@@ -580,8 +596,8 @@ Minimal-surface rewrite. The package is now three focused files instead of a 21-
 ### Public surface
 
 ```ts
-import { SmkingAEO, getAeoContent } from '@soloworks/smking-next';
-import { POST, GET } from '@soloworks/smking-next/route';
+import { SmkingAEO, getAeoContent } from "@soloworks/smking-next";
+import { POST, GET } from "@soloworks/smking-next/route";
 ```
 
 Plus types: `AeoResponse`, `AeoStatus`, `SeoMeta`, `FaqItem`, `ChatLinks`, `DiscoverParams`.

package/README.md

@@ -3,20 +3,20 @@
 AI-native SEO (AEO) for Next.js. One server component injects JSON-LD, OG tags, AI summary, and FAQ on every page so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your content.
 
 - **One server component** in your root layout — every URL gets its own AEO content automatically (`/products/nike-air`, `/products/adidas/red`, anything dynamic, no codemod needed).
-- **Fail-fast, fail-open.** 2-second timeout + Next.js ISR — if smking is down, your page renders without injection. Never blocks.
+- **Fail-fast, fail-open.** 2-second timeout + Next.js ISR — if Page Zero is down, your page renders without injection. Never blocks.
 - **Push updates** — webhook handler invalidates only the changed paths via `revalidateTag`.
 
 ## Install
 
-**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.
+**Don't follow this README to install.** Your Page Zero 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.
 
 Two ways to get it:
 
 ```bash
 # Option 1 — one-shot wizard (installs deps + writes env + runs doctor)
-npx @soloworks/smking-wizard
+npx @soloworks/smking-wizard@latest
 
-# Option 2 — copy the prompt manually from your smking dashboard's
+# Option 2 — copy the prompt manually from your Page Zero dashboard's
 # install panel into your editor / coding agent.
 ```
 
@@ -26,10 +26,10 @@ The wizard owns: `pnpm add @soloworks/smking-next`, `<SmkingAEO />` mount in `ap
 
 Both `<SmkingAEO />` and your own `generateMetadata` emit head tags. Next.js + React 19 head dedup applies last-write-wins:
 
-- **No `generateMetadata`** → smking's `<title>` / `og:*` are used.
-- **You write `generateMetadata` in a layout / page** → your tags override smking's for that route segment.
+- **No `generateMetadata`** → Page Zero's `<title>` / `og:*` are used.
+- **You write `generateMetadata` in a layout / page** → your tags override Page Zero's for that route segment.
 
-This is the pattern: smking provides AEO/SEO baseline, you override per-page when you want. No HOF, no codemod.
+This is the pattern: Page Zero provides the AEO/SEO baseline, and you override per-page when needed. No HOF, no codemod.
 
 For client pages (`'use client'`) that need dynamic metadata, write a sibling `layout.tsx` with `generateMetadata` — standard Next.js workflow, unrelated to smking.
 
@@ -38,8 +38,8 @@ For client pages (`'use client'`) that need dynamic metadata, write a sibling `l
 `getAeoContent` wraps `fetch` with `AbortSignal.timeout(2000)` and Next.js ISR (`next: { revalidate: 3600, tags: ['smking:path:<path>'] }`):
 
 - **Cache hit** (the common path): zero network. Tags allow webhook-driven invalidation.
-- **Cache miss + smking healthy**: one network roundtrip, response cached for 1h.
-- **Cache miss + smking down / hung**: returns null after at most 2s, page renders without injection. Next.js ISR retries on the next request after `revalidate`.
+- **Cache miss + Page Zero healthy**: one network roundtrip, response cached for 1h.
+- **Cache miss + Page Zero down / hung**: returns null after at most 2s, page renders without injection. Next.js ISR retries on the next request after `revalidate`.
 - **5xx / 4xx / parse error**: same fail-open path.
 
 No circuit breaker, no retry, no status command — Next.js infrastructure already covers what those would do.
@@ -50,10 +50,10 @@ No circuit breaker, no retry, no status command — Next.js infrastructure alrea
 
 ```ts
 interface SmkingAEOProps {
-  apiKey: string;        // required
-  baseUrl?: string;      // override SMKING_BASE_URL env
-  path?: string;         // explicit path; auto-resolved from headers() otherwise
-  revalidate?: number;   // ISR seconds; default 3600 (1h)
+  apiKey: string; // required
+  baseUrl?: string; // override SMKING_BASE_URL env
+  path?: string; // explicit path; auto-resolved from headers() otherwise
+  revalidate?: number; // ISR seconds; default 3600 (1h)
 }
 ```
 
@@ -92,11 +92,15 @@ Add `<SmkingRuntime />` once in your root layout — it emits a `<link>` to the
 // app/layout.tsx
 import { SmkingRuntime } from "@soloworks/smking-next";
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return (
     <html>
       <body>
-        <SmkingRuntime />
+        <SmkingRuntime apiKey={process.env.SMKING_API_KEY!} />
         {children}
       </body>
     </html>
@@ -104,42 +108,44 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-Optional `baseUrl` prop overrides `process.env.SMKING_BASE_URL`. Default: `https://smking.app`.
+Optional `baseUrl` prop overrides `process.env.SMKING_BASE_URL`. Default: `https://getpagezero.com`.
 
 Without `<SmkingRuntime />`, `<SmkingCms>` content still renders but the Tailwind utility classes from the dashboard's cva variants resolve to dead strings — the page reaches the browser unstyled. The wizard installer auto-adds this mount; if you're upgrading manually from < v0.16.1, add the one line above.
 
 ## CMS rendering (optional, v0.11.0+)
 
-The base install only wires AEO. If you author content in the smking dashboard's CMS and want to render it on your Next.js site, use the `<SmkingCms slug="…" />` Server Component.
+The base install only wires AEO. If you author content in the Page Zero dashboard CMS and want to render it on your Next.js site, use the `<SmkingCms slug="…" />` Server Component.
 
 The SDK **does not have a "CMS root" config** — you choose any URL prefix (`/blog`, `/knowledge`, `/shop/articles`) and wire your own route. The component takes a `slug` prop, fetches the published page from `${SMKING_BASE_URL}/api/v1/public/page?slug=…`, and renders the Tiptap ProseMirror JSON as `<article class="smk-cms">…</article>` via `@tiptap/static-renderer/pm/react`. SEO `<title>` / `<meta>` / `og:*` / canonical hoist into `<head>` automatically via React 19.
 
-### Catch-all route (handles flat + nested slugs)
+### Optional catch-all route (handles the CMS root + nested slugs)
 
-smking CMS slugs can be nested — e.g. `blog/123`, `blog/seo/intro`. Use Next.js catch-all `[...slug]` (three dots, not single `[slug]`) so one route handles every depth:
+Page Zero CMS slugs can be nested, and the CMS root uses an empty slug. Use
+Next.js optional catch-all `[[...slug]]` so one route handles `/blog`, flat
+slugs, and every nested depth:
 
 ```tsx
-// app/blog/[...slug]/page.tsx
+// app/blog/[[...slug]]/page.tsx
 import { SmkingCms } from "@soloworks/smking-next/cms";
 
 export default async function Page({
   params,
 }: {
-  params: Promise<{ slug: string[] }>;
+  params: Promise<{ slug?: string[] }>;
 }) {
   const { slug } = await params;
   return (
     <SmkingCms
       apiKey={process.env.SMKING_API_KEY!}
-      slug={slug.join("/")}  // ← array → "blog/seo/intro" matches dashboard slug format
+      slug={slug?.join("/") ?? ""}
     />
   );
 }
 ```
 
-`[...slug]` accepts both flat (`/blog/hello` → `["hello"]`) and nested (`/blog/seo/intro` → `["seo", "intro"]`). The `.join("/")` reconstructs the dashboard slug string.
-
-Single-bracket `[slug]` (without the three dots) **only matches one segment** — pick this if you know your slugs are always flat.
+At `/blog`, `params.slug` is undefined and maps to the empty CMS slug. Flat
+and nested paths map to `"hello"` and `"seo/intro"` respectively. A required
+`[...slug]` would miss the CMS root.
 
 ### Markup contract for CSS
 
@@ -148,17 +154,21 @@ Single-bracket `[slug]` (without the three dots) **only matches one segment**
   <h1 class="smk-cms__title">…</h1>
   <p>standard prose</p>
   <h2>headings</h2>
-  <ul><li>lists</li></ul>
+  <ul>
+    <li>lists</li>
+  </ul>
   <blockquote>…</blockquote>
   <pre><code>code blocks</code></pre>
   <a href="…">links</a>
-  <img src="…" alt="…">
-  <div data-type="gallery"
-       data-layout="grid"
-       data-columns="3"
-       class="smk-gallery smk-gallery--grid">
+  <img src="…" alt="…" />
+  <div
+    data-type="gallery"
+    data-layout="grid"
+    data-columns="3"
+    class="smk-gallery smk-gallery--grid"
+  >
     <figure class="smk-gallery__item">
-      <img src="…" alt="…" loading="lazy">
+      <img src="…" alt="…" loading="lazy" />
       <figcaption>optional</figcaption>
     </figure>
   </div>

package/bin/install.mjs

@@ -22,7 +22,13 @@
  * Conventional Next.js layout assumed: `app/` at repo root (or under
  * `src/app/` — detected). Both subcommands exit 1 on missing app/.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 // ── install (file scaffold) ─────────────────────────────────────
@@ -124,7 +130,6 @@ function loadEnvFiles() {
   }
 }
 
-
 /**
  * @typedef {{ name: string, status: "pass" | "fail" | "info", detail: string }} DoctorCheck
  */
@@ -157,25 +162,54 @@ function checkEnv(name, prefix) {
   };
 }
 
+/**
+ * Find the shallowest layout that owns html + body. This supports
+ * internationalized roots such as app/[locale]/layout.tsx without
+ * mistaking a nested section layout for the application root.
+ * @param {string} appDir
+ * @returns {string | null}
+ */
+function findRootLayout(appDir) {
+  const conventional = ["tsx", "jsx", "ts", "js"]
+    .map((extension) => join(appDir, `layout.${extension}`))
+    .find((path) => existsSync(path));
+  if (conventional) return conventional;
+
+  /** @type {Array<{ path: string, depth: number }>} */
+  const nested = [];
+  function visit(directory, depth) {
+    if (depth > 4) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(path, depth + 1);
+        continue;
+      }
+      if (!/^layout\.(tsx|jsx|ts|js)$/.test(entry.name)) continue;
+      const content = readFileSync(path, "utf-8");
+      if (/<html(?:\s|>)/.test(content) && /<body(?:\s|>)/.test(content)) {
+        nested.push({ path, depth });
+      }
+    }
+  }
+
+  visit(appDir, 0);
+  nested.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path));
+  return nested[0]?.path ?? null;
+}
+
 /**
  * @param {string} appDir
  * @returns {DoctorCheck}
  */
 function checkLayoutUsage(appDir) {
-  // Mirror Next.js's layout file resolution. Order matters — TS > JS to
-  // match what Next.js itself would pick.
-  const candidates = [
-    join(appDir, "layout.tsx"),
-    join(appDir, "layout.jsx"),
-    join(appDir, "layout.ts"),
-    join(appDir, "layout.js"),
-  ];
-  const layoutPath = candidates.find((p) => existsSync(p));
+  const layoutPath = findRootLayout(appDir);
   if (!layoutPath) {
     return {
       name: "<SmkingAEO /> in root layout",
-      status: "info",
-      detail: `no layout file found under ${appDir}/ — skipped`,
+      status: "fail",
+      detail: `no root layout owning <html> and <body> found under ${appDir}/`,
     };
   }
 
@@ -212,10 +246,10 @@ async function checkApiReachable() {
   // would pass for any live host (a typo'd domain, google.com); the
   // endpoint either returns the AEO payload or a known auth/validation
   // status — both confirm the route exists.
-  const url = `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo?path=%2F`;
+  const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/public/aeo`;
+  const url = `${endpoint}?key=${encodeURIComponent(apiKey)}&path=%2F`;
   try {
     const res = await fetch(url, {
-      headers: { authorization: `Bearer ${apiKey}` },
       signal: AbortSignal.timeout(3000),
     });
 
@@ -223,35 +257,45 @@ async function checkApiReachable() {
       return {
         name: "API reachable",
         status: "pass",
-        detail: `${url} → HTTP ${res.status}`,
+        detail: `${endpoint} → HTTP ${res.status}; API key accepted`,
       };
     }
     if (res.status === 401) {
       return {
         name: "API reachable",
         status: "fail",
-        detail: `HTTP 401 from ${url} — SMKING_API_KEY rejected`,
+        detail: `HTTP 401 from ${endpoint} — SMKING_API_KEY rejected`,
       };
     }
     if (res.status === 404) {
+      const payload = await res
+        .clone()
+        .json()
+        .catch(() => null);
+      if (payload?.status === "not_found") {
+        return {
+          name: "API reachable",
+          status: "pass",
+          detail: `${endpoint} → HTTP 404 not_found; API key accepted`,
+        };
+      }
       return {
         name: "API reachable",
         status: "fail",
-        detail: `HTTP 404 from ${url} — base_url likely points at the wrong host`,
+        detail: `HTTP 404 from ${endpoint} — SMKING_BASE_URL likely points at the wrong host`,
       };
     }
     if (res.status >= 500) {
       return {
         name: "API reachable",
         status: "fail",
-        detail: `upstream HTTP ${res.status} from ${url}`,
+        detail: `upstream HTTP ${res.status} from ${endpoint}`,
       };
     }
-    // 4xx (other than 401/404) — likely validation error, endpoint exists
     return {
       name: "API reachable",
-      status: "info",
-      detail: `${url} → HTTP ${res.status} (endpoint exists)`,
+      status: "fail",
+      detail: `${endpoint} returned unexpected HTTP ${res.status}`,
     };
   } catch (err) {
     return {
@@ -304,19 +348,15 @@ async function runDoctor(jsonOutput) {
 
   for (const check of checks) {
     const icon =
-      check.status === "pass"
-        ? "✅"
-        : check.status === "fail"
-          ? "❌"
-          : "ℹ️ ";
+      check.status === "pass" ? "✅" : check.status === "fail" ? "❌" : "ℹ️ ";
     console.log(`${icon} ${check.name} — ${check.detail}`);
   }
   console.log();
   if (hasFailure) {
-    console.log("❌ smking: install incomplete — fix the items above.");
+    console.log("❌ Page Zero: install incomplete — fix the items above.");
     return 1;
   }
-  console.log("✅ smking: install OK.");
+  console.log("✅ Page Zero: install OK.");
   return 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "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/cms-blocks.ts

@@ -27,6 +27,35 @@
  * slug-prefix derived, tag mode targets `taxonomies.slug`.
  */
 
+export interface YouTubeEmbedOptions {
+  autoplay?: boolean;
+  ccLangPref?: string;
+  ccLoadPolicy?: boolean;
+  color?: "red" | "white";
+  controls?: boolean;
+  disablekb?: boolean;
+  enablejsapi?: boolean;
+  end?: number;
+  fs?: boolean;
+  hl?: string;
+  ivLoadPolicy?: "show" | "hide";
+  list?: string;
+  listType?: "playlist" | "user_uploads";
+  loop?: boolean;
+  origin?: string;
+  playlist?: string;
+  playsinline?: boolean;
+  relatedMode?: "all" | "same-channel";
+  start?: number;
+  widgetReferrer?: string;
+}
+
+export interface HeroYouTubeProps extends YouTubeEmbedOptions {
+  url: string;
+  videoId: string;
+  thumbnailUrl: string;
+}
+
 export interface HeroProps {
   title: string;
   /** Generic visible meta lines. Legacy drafts may still also carry subtitle. */
@@ -39,6 +68,9 @@ export interface HeroProps {
   /** Legacy single-line fallback for SDK Mode B consumers. */
   subtitle?: string;
   image?: { url: string; alt: string };
+  /** YouTube hero media. Article body renders the embed; cards / metadata use
+   * the thumbnail so list-like pages never mount a player. */
+  youtube?: HeroYouTubeProps;
   cta?: { label: string; href: string };
   /** Header layout — omitted = the original centred hero; "start" = the
    * Apple-newsroom-style left-aligned header; "cover" = title-only banner over
@@ -90,12 +122,14 @@ export interface NavSnapshotEntry {
 }
 
 export type SearchQuickLinkSource = "category-by-path" | "tag" | "url";
+export type LinkDataAttributes = Record<string, string>;
 
 /**
- * Optional links shown beside the search trigger on desktop and inside the
- * search panel on small screens. Category/tag links keep their semantic source
- * + path so publish-time materialization can bake the customer's CMS mount
- * prefix into `href`; URL links carry the author's literal `href`.
+ * Optional links shown beside the search trigger on desktop and in a mobile
+ * hamburger dropdown outside the search panel. Category/tag links keep their
+ * semantic source + path so publish-time materialization can bake the
+ * customer's CMS mount prefix into `href`; URL links carry the author's
+ * literal `href`.
  */
 export interface SearchQuickLink {
   label: string;
@@ -104,6 +138,22 @@ export interface SearchQuickLink {
   path?: string;
   /** Materialized href for category/tag links, or the author-entered URL. */
   href?: string;
+  /** Optional author-selected data-* attributes for analytics integrations. */
+  dataAttributes?: LinkDataAttributes;
+}
+
+export interface SearchSuggestionLink {
+  label: string;
+  source: Exclude<SearchQuickLinkSource, "url">;
+  /** Category slug path or flat tag slug. */
+  path: string;
+  /** Materialized customer-site href. */
+  href: string;
+}
+
+export interface SearchSuggestionsSnapshot {
+  categories: SearchSuggestionLink[];
+  tags: SearchSuggestionLink[];
 }
 
 /**
@@ -122,22 +172,18 @@ export interface SearchProps {
   /** Content column vs wide breakout (default wide). Mirrors the media
    * blocks (image/embed). */
   widthMode?: "content" | "wide";
+  /** Desktop quick-link cluster alignment beside the search trigger. Defaults left. */
+  linkAlign?: "left" | "right";
+  /** Desktop quick-link visual treatment. Defaults badge. */
+  linkStyle?: "badge" | "plain";
   /** Optional quick links adjacent to search. */
   links?: SearchQuickLink[];
+  /** Publish-time default browse links shown before the visitor types. */
+  suggestions?: SearchSuggestionsSnapshot;
   /** Publish-time materialized snapshot — every published page on the site. */
   snapshot?: NavSnapshotEntry[];
 }
 
-export interface RecentPostsProps extends ModuleHeader {
-  /** Author-set number of latest posts to show (1..50). */
-  limit: number;
-  /** Content column vs wide breakout (default content). Mirrors the media
-   * blocks. */
-  widthMode?: "content" | "wide";
-  /** Publish-time materialized snapshot — whole-site newest-first. */
-  snapshot?: NavSnapshotEntry[];
-}
-
 /** One author-picked source for nav-related-posts. Same shape as
  * `CategoryIndexItem` (a category path OR a tag), reused so the source picker
  * UI stays identical across blocks. */
@@ -188,6 +234,28 @@ export interface ArticleTagsProps {
   snapshot?: ArticleTagSnapshot[];
 }
 
+/** One tag in the site-level tag cloud. */
+export interface TagCloudEntry {
+  slug: string;
+  name: string;
+  /** Virtual tag archive href, e.g. `/blog/tag/tofu-life`. */
+  href: string;
+  /** Number of published article pages carrying this tag. */
+  count: number;
+}
+
+/**
+ * `tag-cloud` block — site-level tag browser. It is intentionally separate
+ * from `nav-category-index`: no cards, no latest-post preview, just tag chips.
+ */
+export interface TagCloudProps {
+  heading?: string;
+  /** Content column vs wide breakout. Omitted = content. */
+  widthMode?: "content" | "wide";
+  /** Publish-time materialized tags attached to published article pages. */
+  snapshot?: TagCloudEntry[];
+}
+
 /** One author-selected category OR tag in a nav-category-index block. */
 export interface CategoryIndexItem {
   /** Slug prefix (category-by-path) or taxonomy slug (tag), per `source`.
@@ -350,6 +418,8 @@ export interface ButtonItemProps {
   /** Apple-style looks: `filled` = primary capsule, `tinted` = soft primary
    * wash, `outline` = bordered. Omitted = filled. */
   variant?: "filled" | "tinted" | "outline";
+  /** Optional author-selected data-* attributes for analytics integrations. */
+  dataAttributes?: LinkDataAttributes;
 }
 
 /**
@@ -369,7 +439,7 @@ export interface ButtonGroupProps {
  * url = renders nothing on the customer side. `widthMode` matches the other
  * media blocks (content column vs wide breakout).
  */
-export interface EmbedProps {
+export interface EmbedProps extends YouTubeEmbedOptions {
   url?: string;
   caption?: string;
   widthMode?: "content" | "wide";
@@ -416,6 +486,20 @@ export type LatestNewsSlot =
       source?: "category-by-path" | "tag";
     };
 
+/** Whole-block source mode for `latest-news`. Omitted = `manual` so old
+ * blocks keep their curated slots exactly. */
+export type LatestNewsMode =
+  | "manual"
+  | "latest"
+  | "auto-category"
+  | "category"
+  | "tag";
+
+/** First-card layout for `latest-news`. Omitted = `stacked`, the default
+ * image-above/text-below card. `split` preserves the original desktop
+ * image-left/text-right presentation. */
+export type LatestNewsLayout = "stacked" | "split";
+
 /**
  * One materialized `latest-news` card: the resolved article entry (the
  * article itself for an `article` slot, or the category's latest post for a
@@ -436,8 +520,20 @@ export interface LatestNewsCardSnapshot {
  * feeds; reuses `NavSnapshotEntry` for each resolved card.
  */
 export interface LatestNewsProps extends ModuleHeader {
+  /** First-card presentation. Omitted/default = image above text below. */
+  layout?: LatestNewsLayout;
+  /** Whole-block source mode. Omitted/manual uses `slots`; other modes resolve
+   * cards dynamically at publish time. */
+  mode?: LatestNewsMode;
   /** Author-curated slots, 3–6, in display order (first = feature card). */
   slots: LatestNewsSlot[];
+  /** Card count for automatic modes. The magazine grid supports 3–6 cards. */
+  limit?: number;
+  /** Selected category/tag path for `category` / `tag` modes. */
+  sourcePath?: string;
+  /** Editor-facing label for the selected category/tag; used as the card
+   * eyebrow in automatic source modes. */
+  sourceLabel?: string;
   /** Content column vs wide breakout (default wide). Mirrors the media
    * blocks. */
   widthMode?: "content" | "wide";
@@ -454,9 +550,9 @@ export type Block =
       props: NavTaxonomyListProps;
     }
   | { component: "search"; id: string; props: SearchProps }
-  | { component: "nav-recent-posts"; id: string; props: RecentPostsProps }
   | { component: "nav-related-posts"; id: string; props: RelatedPostsProps }
   | { component: "article-tags"; id: string; props: ArticleTagsProps }
+  | { component: "tag-cloud"; id: string; props: TagCloudProps }
   | { component: "nav-category-index"; id: string; props: CategoryIndexProps }
   | { component: "image"; id: string; props: ImageProps }
   | { component: "slideshow"; id: string; props: SlideshowProps }

package/src/components/smking-aeo.tsx

@@ -1,3 +1,5 @@
+import { headers } from "next/headers";
+
 import type { DiscoverParams } from "../types";
 import { getAeoContent } from "../lib/client";
 import { safeJson } from "../lib/safe-json";
@@ -16,6 +18,18 @@ const SR_ONLY_STYLE: React.CSSProperties = {
 
 export interface SmkingAEOProps extends DiscoverParams {}
 
+async function wantsOriginBypass(): Promise<boolean> {
+  try {
+    const requestHeaders = await headers();
+    return (
+      requestHeaders.get("x-smking-origin-mode")?.trim().toLowerCase() ===
+      "raw"
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Server Component that injects AEO + SEO content for the current
  * request. Place once in the root layout, inside `<body>`:
@@ -57,6 +71,8 @@ export interface SmkingAEOProps extends DiscoverParams {}
  * arbitrary content fetched anywhere.
  */
 export async function SmkingAEO(props: SmkingAEOProps) {
+  if (await wantsOriginBypass()) return null;
+
   const aeo = await getAeoContent(props);
   if (!aeo || aeo.status !== "ready") return null;
 

package/src/components/smking-runtime.tsx

@@ -21,13 +21,18 @@ export function SmkingRuntime({
   apiKey?: string;
 }) {
   const url = (
-    baseUrl ?? process.env.SMKING_BASE_URL ?? "https://smking.app"
+    baseUrl ??
+    process.env.SMKING_BASE_URL ??
+    "https://getpagezero.com"
   ).replace(/\/$/, "");
   return (
     <>
       <link rel="stylesheet" href={`${url}/api/v1/public/runtime.css`} />
       {apiKey && (
-        <link rel="stylesheet" href={`${url}/api/v1/public/theme.css?key=${apiKey}`} />
+        <link
+          rel="stylesheet"
+          href={`${url}/api/v1/public/theme.css?key=${apiKey}`}
+        />
       )}
       <script src={`${url}/api/v1/public/runtime.js`} async />
     </>

package/src/index.ts

@@ -21,11 +21,11 @@ export type {
   FaqItem,
   HeroProps,
   ImageProps,
+  LinkDataAttributes,
   ModuleHeader,
   NavLayout,
   NavSnapshotEntry,
   NavTaxonomyListProps,
-  RecentPostsProps,
   RelatedPostsProps,
   SearchQuickLink,
   SearchQuickLinkSource,

package/src/lib/llms-txt-route.ts

@@ -1,6 +1,6 @@
 /**
  * Drop-in `app/llms.txt/route.ts` GET handler. Proxies the canonical
- * llms.txt served by the smking SaaS at `/api/v1/public/llms-txt?key=...`.
+ * llms.txt served by Page Zero at `/api/v1/public/llms-txt?key=...`.
  *
  *   ```ts
  *   // app/llms.txt/route.ts
@@ -22,7 +22,7 @@ export async function GET(): Promise<Response> {
   if (!apiKey) {
     return new Response("Not found", { status: 404 });
   }
-  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
 
   try {
     const res = await fetch(

package/src/lib/robots.ts

@@ -64,9 +64,7 @@ export const SMKING_DEFAULT_CONTENT_SIGNAL =
  * customers who need that directive should switch to
  * `smkingRobotsTxt()` and serve via a route handler.
  */
-export function smkingRobotsRules(
-  config: SmkingRobotsConfig = {},
-): Array<{
+export function smkingRobotsRules(config: SmkingRobotsConfig = {}): Array<{
   userAgent: string;
   allow?: string;
   disallow?: string;
@@ -169,7 +167,7 @@ function toArray<T>(value: T | T[] | undefined): T[] {
 
 /**
  * Drop-in `app/robots.ts` default export. Fetches the canonical robots.txt
- * served by the smking SaaS at `/api/v1/public/robots.txt?key=...` and
+ * served by Page Zero at `/api/v1/public/robots.txt?key=...` and
  * returns a `Response` with `text/plain`. Customer code stays one line:
  *
  *   ```ts
@@ -201,7 +199,7 @@ export default async function smkingRobotsRoute(): Promise<Response> {
   }
   const apiKey = process.env.SMKING_API_KEY;
   if (!apiKey) return permissiveFallback();
-  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
 
   try {
     const res = await fetch(

package/src/lib/sitemap.ts

@@ -2,7 +2,7 @@ import type { MetadataRoute } from "next";
 
 /**
  * Drop-in `app/sitemap.ts` default export. Fetches the canonical sitemap
- * served by the smking SaaS at `/api/v1/public/sitemap.xml?key=...`, parses
+ * served by Page Zero at `/api/v1/public/sitemap.xml?key=...`, parses
  * the XML, and returns Next.js's `MetadataRoute.Sitemap` shape so the
  * framework can build the static sitemap at request time.
  *
@@ -22,13 +22,13 @@ import type { MetadataRoute } from "next";
  *
  * Required env:
  *   - `SMKING_API_KEY`        (publishable, the `pk_…` key)
- *   - `SMKING_BASE_URL`       (defaults to https://saas.smking.com)
+ *   - `SMKING_BASE_URL`       (defaults to https://getpagezero.com)
  */
 export default async function smkingSitemap(): Promise<MetadataRoute.Sitemap> {
   if (process.env.SMKING_DISABLE_TAKEOVER_SITEMAP === "1") return [];
   const apiKey = process.env.SMKING_API_KEY;
   if (!apiKey) return [];
-  const baseUrl = process.env.SMKING_BASE_URL ?? "https://saas.smking.com";
+  const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
 
   let body: string;
   try {

package/src/lib/version.ts

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

package/src/types.ts

@@ -81,11 +81,11 @@ export type {
   CategoryIndexProps,
   HeroProps,
   ImageProps,
+  LinkDataAttributes,
   ModuleHeader,
   NavLayout,
   NavSnapshotEntry,
   NavTaxonomyListProps,
-  RecentPostsProps,
   RelatedPostsProps,
   SearchQuickLink,
   SearchQuickLinkSource,