@akinon/projectzero 1.126.15-v1-rc.12 → 1.126.15

package/CHANGELOG.md

@@ -1,10 +1,6 @@
 # @akinon/projectzero
 
-## 1.126.15-v1-rc.12
-
-### Patch Changes
-
-- a34bb1b: ZERO-5168: Post the attribute-based shipping selection to the page name Commerce reports
+## 1.126.15
 
 ## 1.126.14
 

package/app-template/.env.example

@@ -16,3 +16,13 @@ NEXT_PUBLIC_VIRTUAL_TRY_ON_API_URL=https://d2a26507c7094f359aba349b96a96881.lb.a
 # CACHE_KEY_PREFIX=
 
 # BF_CACHE=false
+
+# Widget preview (theme editor named previews).
+# PREVIEW_SECRET signs the expiring preview links the editor requests from
+# /api/preview/link; it never travels in a url. Unset = preview disabled.
+# MAIN_APP_URL is the Omnitron the editor is signed into — the link endpoint
+# verifies the editor's session token there before minting a link.
+# PREVIEW_LINK_TTL_SECONDS: how long a link stays valid (default 86400 = 24h).
+# PREVIEW_SECRET=
+# MAIN_APP_URL=https://<omnitron-host>
+# PREVIEW_LINK_TTL_SECONDS=86400

package/app-template/CHANGELOG.md

@@ -1,40 +1,42 @@
 # projectzeronext
 
-## 1.126.15-v1-rc.12
-
-### Patch Changes
-
-- Updated dependencies [560e209]
-- Updated dependencies [d480941]
-- Updated dependencies [a34bb1b]
-- Updated dependencies [560e209]
-- Updated dependencies [182a639b]
-  - @akinon/pz-tamara-extension@1.126.15-v1-rc.12
-  - @akinon/pz-masterpass-rest@1.126.15-v1-rc.12
-  - @akinon/next@1.126.15-v1-rc.12
-  - @akinon/pz-virtual-try-on@1.126.15-v1-rc.12
-  - @akinon/pz-akifast@1.126.15-v1-rc.12
-  - @akinon/pz-apple-pay@1.126.15-v1-rc.12
-  - @akinon/pz-b2b@1.126.15-v1-rc.12
-  - @akinon/pz-basket-gift-pack@1.126.15-v1-rc.12
-  - @akinon/pz-bkm@1.126.15-v1-rc.12
-  - @akinon/pz-checkout-gift-pack@1.126.15-v1-rc.12
-  - @akinon/pz-click-collect@1.126.15-v1-rc.12
-  - @akinon/pz-credit-payment@1.126.15-v1-rc.12
-  - @akinon/pz-cybersource-uc@1.126.15-v1-rc.12
-  - @akinon/pz-flow-payment@1.126.15-v1-rc.12
-  - @akinon/pz-google-pay@1.126.15-v1-rc.12
-  - @akinon/pz-gpay@1.126.15-v1-rc.12
-  - @akinon/pz-haso@1.126.15-v1-rc.12
-  - @akinon/pz-hepsipay@1.126.15-v1-rc.12
-  - @akinon/pz-masterpass@1.126.15-v1-rc.12
-  - @akinon/pz-multi-basket@1.126.15-v1-rc.12
-  - @akinon/pz-one-click-checkout@1.126.15-v1-rc.12
-  - @akinon/pz-otp@1.126.15-v1-rc.12
-  - @akinon/pz-pay-on-delivery@1.126.15-v1-rc.12
-  - @akinon/pz-saved-card@1.126.15-v1-rc.12
-  - @akinon/pz-similar-products@1.126.15-v1-rc.12
-  - @akinon/pz-tabby-extension@1.126.15-v1-rc.12
+## 1.126.15
+
+### Patch Changes
+
+- 4f2f9b8: ZERO-5149: Bring the theme editor's widget preview to the v1 line
+
+  Storefronts on @akinon/next 1.x can now open the theme editor's named previews the way 2.x storefronts do. The editor asks `/api/preview/link` for a signed, expiring link, and `?preview=<token>` enters Next.js draft mode through `/api/preview`. While draft mode is on, `getWidgetData` tries `<slug>-preview-<id>` first, the theme-previews registry retires deleted previews, and `getPreviewSnapshot` hands @akinon/pz-theme (2.0.79 or later) the placeholder snapshot it renders from. Preview content is only rendered when Next 14 itself treats the render as a draft, so it can never reach the shared ISR cache. Normal traffic renders live as before.
+
+  A storefront needs the `[pz]` route layout (`usePzSegment: true`). Legacy `[commerce]/[locale]/[currency]` projects migrate first with `npx projectzero codemod --codemod=migrate-segments`, otherwise previews render live. On top of that it needs `PREVIEW_SECRET` and `MAIN_APP_URL` (optionally `PREVIEW_LINK_TTL_SECONDS`), the `/api/preview` and `/api/preview/link` route handlers, the `?preview` entry in `src/middleware.ts` and the `preview` segment in `settings.js` `pzSegments`, all as in projectzeronext. The new segment changes every page's pz value once, so ISR entries are rebuilt after the upgrade.
+
+- Updated dependencies [4f2f9b8]
+  - @akinon/next@1.126.15
+  - @akinon/pz-virtual-try-on@1.126.15
+  - @akinon/pz-akifast@1.126.15
+  - @akinon/pz-apple-pay@1.126.15
+  - @akinon/pz-b2b@1.126.15
+  - @akinon/pz-basket-gift-pack@1.126.15
+  - @akinon/pz-bkm@1.126.15
+  - @akinon/pz-checkout-gift-pack@1.126.15
+  - @akinon/pz-click-collect@1.126.15
+  - @akinon/pz-credit-payment@1.126.15
+  - @akinon/pz-cybersource-uc@1.126.15
+  - @akinon/pz-flow-payment@1.126.15
+  - @akinon/pz-google-pay@1.126.15
+  - @akinon/pz-gpay@1.126.15
+  - @akinon/pz-haso@1.126.15
+  - @akinon/pz-hepsipay@1.126.15
+  - @akinon/pz-masterpass@1.126.15
+  - @akinon/pz-masterpass-rest@1.126.15
+  - @akinon/pz-multi-basket@1.126.15
+  - @akinon/pz-one-click-checkout@1.126.15
+  - @akinon/pz-otp@1.126.15
+  - @akinon/pz-pay-on-delivery@1.126.15
+  - @akinon/pz-saved-card@1.126.15
+  - @akinon/pz-similar-products@1.126.15
+  - @akinon/pz-tabby-extension@1.126.15
+  - @akinon/pz-tamara-extension@1.126.15
 
 ## 1.126.14
 

package/app-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectzeronext",
-  "version": "1.126.15-v1-rc.12",
+  "version": "1.126.15",
   "private": true,
   "license": "MIT",
   "scripts": {
@@ -24,32 +24,32 @@
     "test:middleware": "jest middleware-matcher.test.ts --bail"
   },
   "dependencies": {
-    "@akinon/next": "1.126.15-v1-rc.12",
-    "@akinon/pz-akifast": "1.126.15-v1-rc.12",
-    "@akinon/pz-apple-pay": "1.126.15-v1-rc.12",
-    "@akinon/pz-b2b": "1.126.15-v1-rc.12",
-    "@akinon/pz-basket-gift-pack": "1.126.15-v1-rc.12",
-    "@akinon/pz-bkm": "1.126.15-v1-rc.12",
-    "@akinon/pz-checkout-gift-pack": "1.126.15-v1-rc.12",
-    "@akinon/pz-click-collect": "1.126.15-v1-rc.12",
-    "@akinon/pz-credit-payment": "1.126.15-v1-rc.12",
-    "@akinon/pz-cybersource-uc": "1.126.15-v1-rc.12",
-    "@akinon/pz-flow-payment": "1.126.15-v1-rc.12",
-    "@akinon/pz-google-pay": "1.126.15-v1-rc.12",
-    "@akinon/pz-gpay": "1.126.15-v1-rc.12",
-    "@akinon/pz-haso": "1.126.15-v1-rc.12",
-    "@akinon/pz-hepsipay": "1.126.15-v1-rc.12",
-    "@akinon/pz-masterpass": "1.126.15-v1-rc.12",
-    "@akinon/pz-masterpass-rest": "1.126.15-v1-rc.12",
-    "@akinon/pz-multi-basket": "1.126.15-v1-rc.12",
-    "@akinon/pz-one-click-checkout": "1.126.15-v1-rc.12",
-    "@akinon/pz-otp": "1.126.15-v1-rc.12",
-    "@akinon/pz-pay-on-delivery": "1.126.15-v1-rc.12",
-    "@akinon/pz-saved-card": "1.126.15-v1-rc.12",
-    "@akinon/pz-similar-products": "1.126.15-v1-rc.12",
-    "@akinon/pz-tabby-extension": "1.126.15-v1-rc.12",
-    "@akinon/pz-tamara-extension": "1.126.15-v1-rc.12",
-    "@akinon/pz-virtual-try-on": "1.126.15-v1-rc.12",
+    "@akinon/next": "1.126.15",
+    "@akinon/pz-akifast": "1.126.15",
+    "@akinon/pz-apple-pay": "1.126.15",
+    "@akinon/pz-b2b": "1.126.15",
+    "@akinon/pz-basket-gift-pack": "1.126.15",
+    "@akinon/pz-bkm": "1.126.15",
+    "@akinon/pz-checkout-gift-pack": "1.126.15",
+    "@akinon/pz-click-collect": "1.126.15",
+    "@akinon/pz-credit-payment": "1.126.15",
+    "@akinon/pz-cybersource-uc": "1.126.15",
+    "@akinon/pz-flow-payment": "1.126.15",
+    "@akinon/pz-google-pay": "1.126.15",
+    "@akinon/pz-gpay": "1.126.15",
+    "@akinon/pz-haso": "1.126.15",
+    "@akinon/pz-hepsipay": "1.126.15",
+    "@akinon/pz-masterpass": "1.126.15",
+    "@akinon/pz-masterpass-rest": "1.126.15",
+    "@akinon/pz-multi-basket": "1.126.15",
+    "@akinon/pz-one-click-checkout": "1.126.15",
+    "@akinon/pz-otp": "1.126.15",
+    "@akinon/pz-pay-on-delivery": "1.126.15",
+    "@akinon/pz-saved-card": "1.126.15",
+    "@akinon/pz-similar-products": "1.126.15",
+    "@akinon/pz-tabby-extension": "1.126.15",
+    "@akinon/pz-tamara-extension": "1.126.15",
+    "@akinon/pz-virtual-try-on": "1.126.15",
     "@hookform/resolvers": "2.9.0",
     "@next/third-parties": "14.1.0",
     "@react-google-maps/api": "2.17.1",
@@ -72,7 +72,7 @@
     "yup": "0.32.11"
   },
   "devDependencies": {
-    "@akinon/eslint-plugin-projectzero": "1.126.15-v1-rc.12",
+    "@akinon/eslint-plugin-projectzero": "1.126.15",
     "@semantic-release/changelog": "6.0.2",
     "@semantic-release/exec": "6.0.3",
     "@semantic-release/git": "10.0.1",

package/app-template/src/app/[pz]/layout.tsx

@@ -12,6 +12,9 @@ import PzRoot from '@akinon/next/components/pz-root';
 import MobileAppToggler from '@akinon/next/components/mobile-app-toggler';
 import pwaTags from '@theme/components/pwa-tags';
 import type { Viewport } from 'next';
+import { PREVIEW_PZ_SEGMENT } from '@akinon/next/utils/preview';
+import { isDraftRender } from '@akinon/next/utils/preview-render';
+import { parsePzParams } from '@akinon/next/utils/pz-segments';
 import settings from '@theme/settings';
 
 export const viewport: Viewport = {
@@ -42,11 +45,34 @@ export async function generateMetadata() {
   return result;
 }
 
-async function RootLayout({ locale, translations, children }: RootLayoutProps) {
+async function RootLayout({
+  locale,
+  translations,
+  params,
+  children
+}: RootLayoutProps) {
+  // Widget preview indicator — reading draftMode does NOT opt the page into
+  // dynamic rendering; it is only true behind the /api/preview bypass cookie,
+  // and never in a render Next 14 is about to cache (utils/preview-render.ts).
+  const isPreview = isDraftRender();
+  // Which named preview is being viewed, so the banner says so — several can
+  // exist side by side and they look identical otherwise.
+  const previewId = parsePzParams(params, settings)[PREVIEW_PZ_SEGMENT] ?? '';
+
   return (
     <html lang={locale.isoCode} {...(locale.rtl ? { dir: 'rtl' } : {})}>
       <head />
       <body className="overflow-x-hidden">
+        {isPreview && (
+          <div className="fixed bottom-3 left-1/2 -translate-x-1/2 z-[9999] flex items-center gap-2 rounded bg-black/80 px-3 py-1.5 text-xs text-white">
+            <span>{previewId ? `Preview: ${previewId}` : 'Preview'}</span>
+            {/* Relative query-only href: exits preview and returns to the
+                SAME page via the middleware ?preview=exit interception. */}
+            <a href="?preview=exit" className="underline">
+              Exit
+            </a>
+          </div>
+        )}
         <PzRoot translations={translations} locale={locale.value}>
           <ClientRoot>
             <div className="overflow-x-hidden">

package/app-template/src/app/api/preview/link/route.ts

@@ -0,0 +1,119 @@
+import { isValidPreviewId, PREVIEW_ID_QUERY_PARAM } from '@akinon/next/utils/preview';
+import {
+  DEFAULT_PREVIEW_LINK_TTL_SECONDS,
+  signPreviewToken
+} from '@akinon/next/utils/preview-token';
+import { NextRequest, NextResponse } from 'next/server';
+
+// Next 14 caches GET route handlers by default; every call must mint a fresh
+// token.
+export const dynamic = 'force-dynamic';
+
+/**
+ * Mints a signed, expiring preview entry token for the theme editor.
+ *
+ * The editor is a static SPA on another origin and must never hold the
+ * storefront's PREVIEW_SECRET. Instead it proves it is an editor user by
+ * forwarding its Omnitron session token; this handler verifies that token
+ * against Omnitron (`MAIN_APP_URL`) and answers with a token the editor puts
+ * on the link as `?preview=<token>`. The link opens exactly one preview and
+ * stops working after PREVIEW_LINK_TTL_SECONDS (default 24h).
+ *
+ * CORS is open on purpose: the request carries no cookies, only the caller's
+ * Omnitron token, and the response is worthless without one.
+ */
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, OPTIONS',
+  'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+  'Access-Control-Max-Age': '600',
+  'Cache-Control': 'no-store'
+};
+
+const json = (body: Record<string, unknown>, status: number) =>
+  NextResponse.json(body, { status, headers: CORS_HEADERS });
+
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
+}
+
+/** Bounded wait for Omnitron — an unreachable host must fail fast, not hang the editor. */
+const OMNITRON_TIMEOUT_MS = 8_000;
+
+/** True when Omnitron accepts the token as a signed-in user. */
+const isEditorUser = async (
+  omnitronUrl: string,
+  authorization: string
+): Promise<boolean> => {
+  try {
+    const response = await fetch(
+      `${omnitronUrl.replace(/\/+$/, '')}/api/v1/active_user/`,
+      {
+        headers: { Authorization: authorization, Accept: 'application/json' },
+        cache: 'no-store',
+        signal: AbortSignal.timeout(OMNITRON_TIMEOUT_MS)
+      }
+    );
+    return response.status === 200;
+  } catch {
+    return false;
+  }
+};
+
+export async function GET(request: NextRequest) {
+  const secret = process.env.PREVIEW_SECRET;
+  const omnitronUrl = process.env.MAIN_APP_URL;
+  if (!secret || !omnitronUrl) {
+    return json(
+      {
+        error: 'preview-disabled',
+        message:
+          'Preview links are disabled: PREVIEW_SECRET and MAIN_APP_URL must both be configured on the storefront.'
+      },
+      503
+    );
+  }
+
+  const previewId =
+    request.nextUrl.searchParams.get(PREVIEW_ID_QUERY_PARAM) ?? '';
+  if (!isValidPreviewId(previewId)) {
+    return json(
+      { error: 'invalid-preview-id', message: 'A valid preview_id is required.' },
+      400
+    );
+  }
+
+  const authorization = request.headers.get('authorization') ?? '';
+  if (!/^Token \S+$/i.test(authorization)) {
+    return json(
+      { error: 'unauthorized', message: 'An Omnitron token is required.' },
+      401
+    );
+  }
+  if (!(await isEditorUser(omnitronUrl, authorization))) {
+    return json(
+      {
+        error: 'unauthorized',
+        message: `Omnitron at ${omnitronUrl} did not accept the token (or did not answer).`
+      },
+      401
+    );
+  }
+
+  const ttl =
+    Number(process.env.PREVIEW_LINK_TTL_SECONDS) ||
+    DEFAULT_PREVIEW_LINK_TTL_SECONDS;
+  const expiresAt = Math.floor(Date.now() / 1000) + ttl;
+  const token = await signPreviewToken({ previewId, expiresAt }, secret);
+
+  return json(
+    {
+      token,
+      previewId,
+      expiresAt: new Date(expiresAt * 1000).toISOString(),
+      // Ready to append to any page url of this storefront.
+      query: `preview=${encodeURIComponent(token)}`
+    },
+    200
+  );
+}

package/app-template/src/app/api/preview/route.ts

@@ -0,0 +1,107 @@
+import { PREVIEW_ID_COOKIE, PREVIEW_ID_QUERY_PARAM } from '@akinon/next/utils/preview';
+import { verifyPreviewToken } from '@akinon/next/utils/preview-token';
+import { cookies, draftMode } from 'next/headers';
+import { NextRequest, NextResponse } from 'next/server';
+
+// Next 14 caches GET route handlers by default; entering and leaving preview
+// must run on every request.
+export const dynamic = 'force-dynamic';
+
+// Next 14's redirect() cannot carry a ';' in its url (it splits its own
+// digest on ';' and the route answers 500), so the 307 is built by hand.
+// Next still appends the cookies the handler set through draftMode() and
+// cookies().
+const redirectTo = (location: string) =>
+  new NextResponse(null, { status: 307, headers: { location } });
+
+/**
+ * Enables/disables Next.js Draft Mode for widget previews, and records WHICH
+ * named preview is being viewed.
+ *
+ * Visitors never call this directly — any page url carrying `?preview` is
+ * redirected here by the middleware (see src/middleware.ts), and redirected
+ * back to the same page once the cookies are set. With draft mode on, the
+ * widget fetch layer serves `<slug>-preview-<id>` copies (falling back to
+ * live).
+ *
+ * The preview id rides in its own cookie rather than the url: pages keep
+ * their clean addresses and links followed afterwards stay inside the same
+ * preview. The cookie is folded into the pz route segment by the middleware
+ * (see settings.js `pzSegments`) because the widget pages are force-static,
+ * where Next.js blanks `cookies()` inside the render.
+ *
+ * Deny-by-default: entering preview ALWAYS requires `?preview=<token>` — a
+ * signed, expiring token minted by /api/preview/link for an editor user (see
+ * utils/preview-token.ts); PREVIEW_SECRET is the signing key and never
+ * travels in a url. Environments without the env have preview disabled
+ * entirely. Exiting never requires a token.
+ */
+export async function GET(request: NextRequest) {
+  const { searchParams } = request.nextUrl;
+
+  // Only ever redirect within the site — the target comes from the query.
+  const target = searchParams.get('redirect') ?? '/';
+  let safeTarget =
+    target.startsWith('/') && !target.startsWith('//') ? target : '/';
+  // Never bounce back to a url that still carries ?preview — that would
+  // re-enter the middleware redirect and loop.
+  const targetUrl = new URL(safeTarget, request.nextUrl.origin);
+  targetUrl.searchParams.delete('preview');
+  targetUrl.searchParams.delete(PREVIEW_ID_QUERY_PARAM);
+  safeTarget = `${targetUrl.pathname}${targetUrl.search}`;
+  // URL normalization can reintroduce a protocol-relative target the first
+  // guard already rejected (e.g. '/..//evil.com' normalizes to pathname
+  // '//evil.com', which browsers resolve to https://evil.com) — re-check the
+  // FINAL string, not just the raw input.
+  if (!safeTarget.startsWith('/') || safeTarget.startsWith('//')) {
+    safeTarget = '/';
+  }
+
+  const draft = draftMode();
+  const cookieStore = cookies();
+
+  if (searchParams.has('exit')) {
+    draft.disable();
+    cookieStore.delete(PREVIEW_ID_COOKIE);
+    return redirectTo(safeTarget);
+  }
+
+  const secret = process.env.PREVIEW_SECRET;
+  if (!secret) {
+    return new NextResponse(
+      'Preview is disabled: PREVIEW_SECRET is not configured.',
+      { status: 401 }
+    );
+  }
+
+  const verdict = await verifyPreviewToken(
+    searchParams.get('token') ?? '',
+    secret
+  );
+  if (verdict.ok !== true) {
+    const { reason } = verdict;
+    return new NextResponse(
+      reason === 'expired'
+        ? 'This preview link has expired — open the page from the editor again to get a fresh one.'
+        : 'Preview link is invalid or missing. Preview pages are opened from the theme editor.',
+      { status: 401 }
+    );
+  }
+  const { previewId } = verdict.claims;
+
+  draft.enable();
+  // Same flags Next gives its own draft cookie (SameSite=None; Secure outside
+  // development): the storefront may be embedded cross-site (editor,
+  // Omnitron), and a Lax id cookie would be dropped there while the draft
+  // cookie survives — draft mode on, no id, live content under a "Preview"
+  // banner. `nextUrl.protocol` is not consulted: behind a TLS-terminating
+  // proxy it reads http even in production.
+  const isDevelopment = process.env.NODE_ENV === 'development';
+  cookieStore.set(PREVIEW_ID_COOKIE, previewId, {
+    path: '/',
+    httpOnly: true,
+    sameSite: isDevelopment ? 'lax' : 'none',
+    secure: !isDevelopment
+  });
+  return redirectTo(safeTarget);
+}

package/app-template/src/middleware.ts

@@ -1,4 +1,5 @@
-import { withPzDefault } from '@akinon/next/middlewares';
+import { PzNextRequest, withPzDefault } from '@akinon/next/middlewares';
+import { PREVIEW_ID_QUERY_PARAM } from '@akinon/next/utils/preview';
 import { NextMiddleware, NextResponse } from 'next/server';
 
 /**
@@ -32,4 +33,47 @@ const middleware: NextMiddleware = () =>
     return NextResponse.next();
   };
 
-export default withPzDefault(middleware);
+const pzMiddleware = withPzDefault(middleware);
+
+const PREVIEW_EXIT_VALUES = new Set(['exit', 'off', '0', 'false']);
+
+/**
+ * Widget preview entry: any page url carrying `?preview` is redirected to the
+ * draft-mode route handler (/api/preview), which sets/clears the bypass and
+ * preview-id cookies and returns to the same page without the params. Runs
+ * BEFORE withPzDefault so the redirect is not subject to its response
+ * rewriting (pz-override-response).
+ *
+ * The `?preview` value is a signed token naming WHICH preview to view (see
+ * utils/preview-token.ts); it travels only as far as the route handler, which
+ * stores the preview id for the rest of the session. A stray `preview_id`
+ * from an old-style link is dropped from the return url.
+ */
+const previewEntryMiddleware: NextMiddleware = (req, event) => {
+  const url = req.nextUrl;
+
+  if (url.searchParams.has('preview')) {
+    const value = url.searchParams.get('preview') ?? '';
+    const target = url.clone();
+    target.searchParams.delete('preview');
+    target.searchParams.delete(PREVIEW_ID_QUERY_PARAM);
+
+    const previewApi = url.clone();
+    previewApi.pathname = '/api/preview';
+    previewApi.search = '';
+    previewApi.searchParams.set(
+      'redirect',
+      `${target.pathname}${target.search}`
+    );
+    if (PREVIEW_EXIT_VALUES.has(value.toLowerCase())) {
+      previewApi.searchParams.set('exit', '1');
+    } else {
+      if (value) previewApi.searchParams.set('token', value);
+    }
+    return NextResponse.redirect(previewApi);
+  }
+
+  return pzMiddleware(req as PzNextRequest, event);
+};
+
+export default previewEntryMiddleware;

package/app-template/src/settings.js

@@ -1,4 +1,8 @@
 const { LocaleUrlStrategy } = require('@akinon/next/localization');
+const {
+  PREVIEW_PZ_SEGMENT,
+  resolvePreviewSegment
+} = require('@akinon/next/utils/preview');
 const { ROUTES } = require('@theme/routes');
 
 const commerceUrl = encodeURI(process.env.SERVICE_BACKEND_URL ?? 'default');
@@ -64,5 +68,18 @@ module.exports = {
   },
   customNotFoundEnabled: false,
   usePzSegment: true,
+  pzSegments: {
+    segments: [
+      {
+        // Carries WHICH named preview is being viewed into the render. The
+        // widget pages are force-static, where cookies() is blanked, so the
+        // middleware folds the preview cookie into the route instead.
+        // Empty for ordinary visitors — nothing renders from preview unless
+        // draft mode is on as well.
+        name: PREVIEW_PZ_SEGMENT,
+        resolve: (context) => resolvePreviewSegment(context.req)
+      }
+    ]
+  },
   commerceRedirectionIgnoreList: ['/users/reset']
 };

package/app-template/src/utils/__tests__/preview-contract.test.ts

@@ -0,0 +1,223 @@
+import {
+  isPreviewCopySlug,
+  isPreviewSlug,
+  isValidPreviewId,
+  previewSlug,
+  resolvePreviewSegment
+} from '@akinon/next/utils/preview';
+import {
+  decodePzValue,
+  encodePzValue,
+  getPzSegmentsConfig
+} from '@akinon/next/utils/pz-segments';
+import {
+  signPreviewToken,
+  verifyPreviewToken
+} from '@akinon/next/utils/preview-token';
+import { webcrypto } from 'node:crypto';
+import { TextEncoder as NodeTextEncoder } from 'node:util';
+
+// jsdom ships neither Web Crypto nor TextEncoder; the token code needs both.
+if (!globalThis.crypto?.subtle) {
+  Object.defineProperty(globalThis, 'crypto', { value: webcrypto });
+}
+if (typeof globalThis.TextEncoder === 'undefined') {
+  Object.defineProperty(globalThis, 'TextEncoder', { value: NodeTextEncoder });
+}
+
+/**
+ * The half of the preview contract this app owns: which named preview a
+ * request belongs to, and the widget slug that preview's copies live under.
+ * The theme editor builds the same slugs — if these change, previews stop
+ * resolving and every page silently falls back to live.
+ */
+
+const req = (cookie?: string, draft = true) => ({
+  cookies: {
+    get: (name: string) => {
+      if (name === '__prerender_bypass') {
+        return draft ? { value: 'bypass' } : undefined;
+      }
+      return name === 'pz-preview-id' && cookie !== undefined
+        ? { value: cookie }
+        : undefined;
+    }
+  }
+});
+
+describe('preview id validation', () => {
+  it('accepts the ids the editor produces', () => {
+    expect(isValidPreviewId('staging')).toBe(true);
+    expect(isValidPreviewId('black-friday')).toBe(true);
+    expect(isValidPreviewId('kis-kampanyasi-2026')).toBe(true);
+    expect(isValidPreviewId('a'.repeat(32))).toBe(true);
+  });
+
+  it('rejects anything that could escape the slug', () => {
+    // Ids arrive from a cookie, so this is a trust boundary.
+    expect(isValidPreviewId('')).toBe(false);
+    expect(isValidPreviewId('-leading')).toBe(false);
+    expect(isValidPreviewId('Upper')).toBe(false);
+    expect(isValidPreviewId('has space')).toBe(false);
+    expect(isValidPreviewId('../etc')).toBe(false);
+    expect(isValidPreviewId('a'.repeat(33))).toBe(false);
+    expect(isValidPreviewId(undefined)).toBe(false);
+    // `--` is the pz segment separator; the editor never produces it.
+    expect(isValidPreviewId('a--b')).toBe(false);
+    expect(isValidPreviewId('trailing-')).toBe(false);
+  });
+});
+
+describe('preview slugs', () => {
+  it('suffixes the live slug with the preview id', () => {
+    expect(previewSlug('homepage-body-new', 'staging')).toBe(
+      'homepage-body-new-preview-staging'
+    );
+    expect(previewSlug('homepage-body-new', 'black-friday')).toBe(
+      'homepage-body-new-preview-black-friday'
+    );
+  });
+
+  it('recognises its own output so previews are never nested', () => {
+    expect(isPreviewSlug('homepage-body-new-preview-staging')).toBe(true);
+    expect(isPreviewSlug('homepage-body-new')).toBe(false);
+    // The old single-preview suffix carries no id and is not one of ours.
+    expect(isPreviewSlug('homepage-body-new-preview')).toBe(false);
+  });
+
+  it('only treats a slug as a copy when it belongs to THIS preview', () => {
+    expect(isPreviewCopySlug('header-preview-staging', 'staging')).toBe(true);
+    // Another preview's copy is not ours to skip.
+    expect(isPreviewCopySlug('header-preview-winter', 'staging')).toBe(false);
+    // A live custom page whose name merely looks like a copy still gets its
+    // overlay — the shape-only check used to skip it and render live.
+    expect(isPreviewCopySlug('page-summer-preview-2026', 'staging')).toBe(
+      false
+    );
+    expect(isPreviewCopySlug('header', '')).toBe(false);
+  });
+});
+
+describe('the preview id inside the pz segment', () => {
+  const settings = {
+    pzSegments: { segments: [{ name: 'preview' }] }
+  };
+  const config = getPzSegmentsConfig(settings);
+  const url = encodeURIComponent('https://shop.test/collections/summer--sale');
+
+  it('round-trips a url containing the separator with a preview id after it', () => {
+    const encoded = encodePzValue(
+      { locale: 'en', currency: 'usd', url, preview: 'staging' },
+      config
+    );
+    expect(decodePzValue(encoded, config)).toEqual({
+      locale: 'en',
+      currency: 'usd',
+      url,
+      preview: 'staging'
+    });
+  });
+
+  it('round-trips such a url when no preview is active', () => {
+    const encoded = encodePzValue(
+      { locale: 'en', currency: 'usd', url, preview: '' },
+      config
+    );
+    expect(decodePzValue(encoded, config)).toEqual({
+      locale: 'en',
+      currency: 'usd',
+      url,
+      preview: ''
+    });
+  });
+
+  it('still reads a plain segment positionally', () => {
+    expect(decodePzValue('tr--try--%2F--kis', config)).toEqual({
+      locale: 'tr',
+      currency: 'try',
+      url: '%2F',
+      preview: 'kis'
+    });
+  });
+});
+
+describe('resolvePreviewSegment', () => {
+  it('passes a valid cookie through to the pz segment', () => {
+    expect(resolvePreviewSegment(req('staging'))).toBe('staging');
+  });
+
+  it('yields no preview for a missing or tampered cookie', () => {
+    expect(resolvePreviewSegment(req())).toBe('');
+    expect(resolvePreviewSegment(req(''))).toBe('');
+    expect(resolvePreviewSegment(req('../../evil'))).toBe('');
+    expect(resolvePreviewSegment(req('Staging'))).toBe('');
+  });
+
+  it('ignores the id cookie unless draft mode is on', () => {
+    // An anonymous visitor forging pz-preview-id must not get a private
+    // cache key per request — without the draft cookie the id is inert.
+    expect(resolvePreviewSegment(req('staging', false))).toBe('');
+  });
+});
+
+describe('signed preview links', () => {
+  const secret = 'k3y';
+  const now = 1_800_000_000_000; // ms
+  const inAnHour = Math.floor(now / 1000) + 3600;
+
+  it('round-trips the preview id and expiry it was minted with', async () => {
+    const token = await signPreviewToken(
+      { previewId: 'kis-kampanyasi', expiresAt: inAnHour },
+      secret
+    );
+    expect(token.startsWith('v1.kis-kampanyasi.')).toBe(true);
+    expect(await verifyPreviewToken(token, secret, now)).toEqual({
+      ok: true,
+      claims: { previewId: 'kis-kampanyasi', expiresAt: inAnHour }
+    });
+  });
+
+  it('dies at its expiry', async () => {
+    const token = await signPreviewToken(
+      { previewId: 'staging', expiresAt: inAnHour },
+      secret
+    );
+    expect(await verifyPreviewToken(token, secret, inAnHour * 1000)).toEqual({
+      ok: false,
+      reason: 'expired'
+    });
+  });
+
+  it('rejects tampering with the id, the expiry or the key', async () => {
+    const token = await signPreviewToken(
+      { previewId: 'staging', expiresAt: inAnHour },
+      secret
+    );
+    const [v, , exp, sig] = token.split('.');
+    expect(
+      (await verifyPreviewToken(`${v}.winter.${exp}.${sig}`, secret, now)).ok
+    ).toBe(false);
+    expect(
+      (await verifyPreviewToken(`${v}.staging.${exp + 1}.${sig}`, secret, now))
+        .ok
+    ).toBe(false);
+    expect((await verifyPreviewToken(token, 'other-key', now)).ok).toBe(false);
+  });
+
+  it('treats anything else as malformed — including the old raw secret', async () => {
+    expect(await verifyPreviewToken('pz-preview-local', secret, now)).toEqual({
+      ok: false,
+      reason: 'malformed'
+    });
+    expect((await verifyPreviewToken('', secret, now)).ok).toBe(false);
+    expect(
+      (await verifyPreviewToken('v1.Bad Id.123.sig', secret, now)).ok
+    ).toBe(false);
+  });
+
+  it('refuses to mint for an invalid id', async () => {
+    await expect(
+      signPreviewToken({ previewId: '../x', expiresAt: inAnHour }, secret)
+    ).rejects.toThrow();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/projectzero",
-  "version": "1.126.15-v1-rc.12",
+  "version": "1.126.15",
   "private": false,
   "description": "CLI tool to manage your Project Zero Next project",
   "bin": {