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

package/CHANGELOG.md

@@ -1,12 +1,14 @@
 # @akinon/next
 
-## 1.126.15-v1-rc.12
+## 1.126.15
 
 ### Patch Changes
 
-- d480941: ZERO-4399: add card rewards to pz-masterpass-rest
-- a34bb1b: ZERO-5168: Post the attribute-based shipping selection to the page name Commerce reports
-- 182a639b: ZERO-4483: Verify v1-rc maintenance pipeline (no-op patch to confirm v1-rc dist-tag flow)
+- 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.
 
 ## 1.126.14
 

package/__tests__/widget-preview.test.ts

@@ -0,0 +1,300 @@
+const mockDraftMode = { isEnabled: false };
+// Next 14's own draft decision for the render — false when it will be cached.
+const mockStaticGenerationStore = { isDraftMode: false };
+const mockServerVariables = { locale: 'en', currency: 'usd', previewId: '' };
+const mockWidgets: Record<string, unknown> = {};
+const mockAppFetch = jest.fn();
+const mockCacheWrap = jest.fn();
+
+jest.mock('server-only', () => ({}));
+
+jest.mock('next/headers', () => ({
+  draftMode: () => mockDraftMode
+}));
+
+jest.mock(
+  'next/dist/client/components/static-generation-async-storage.external',
+  () => ({
+    staticGenerationAsyncStorage: { getStore: () => mockStaticGenerationStore }
+  })
+);
+
+jest.mock('../utils/server-variables', () => ({
+  ServerVariables: mockServerVariables
+}));
+
+jest.mock('../data/urls', () => ({
+  widgets: { getWidget: (slug: string) => `/widgets/${slug}/` }
+}));
+
+jest.mock('../utils/app-fetch', () => ({
+  __esModule: true,
+  default: (...args: unknown[]) => mockAppFetch(...args)
+}));
+
+jest.mock('../lib/cache', () => ({
+  Cache: {
+    wrap: (...args: unknown[]) => mockCacheWrap(...args)
+  },
+  CacheKey: { Widget: (slug: string) => `widget_${slug}` }
+}));
+
+import { getPreviewSnapshot, getWidgetData } from '../data/server/widget';
+
+type FetchArgs = { url: string; init?: { next?: { revalidate: number } } };
+
+const registry = (...ids: string[]) => ({
+  attributes: {
+    theme_previews: {
+      value: JSON.stringify({
+        version: 1,
+        previews: ids.map((id) => ({ id, name: id }))
+      })
+    }
+  }
+});
+
+const liveWidget = (slug: string) => ({ slug, attributes: { live: true } });
+
+const fetchedUrls = () =>
+  mockAppFetch.mock.calls.map(([args]) => (args as FetchArgs).url);
+
+// The registry is remembered for 5s across requests; every test starts past it.
+let now = 1_800_000_000_000;
+
+beforeEach(() => {
+  now += 60_000;
+  jest.spyOn(Date, 'now').mockReturnValue(now);
+  mockDraftMode.isEnabled = true;
+  mockStaticGenerationStore.isDraftMode = true;
+  mockServerVariables.previewId = 'kis';
+  for (const key of Object.keys(mockWidgets)) delete mockWidgets[key];
+  mockWidgets['/widgets/theme-previews/'] = registry('draft', 'kis');
+  mockAppFetch.mockReset();
+  mockAppFetch.mockImplementation(async ({ url }: FetchArgs) =>
+    url in mockWidgets ? mockWidgets[url] : { detail: 'Not found.' }
+  );
+  mockCacheWrap.mockReset();
+  mockCacheWrap.mockImplementation(async (key: string) =>
+    liveWidget(key.replace(/^widget_/, ''))
+  );
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe('getWidgetData in widget preview', () => {
+  it('serves the live widget when draft mode is off, without touching preview slugs', async () => {
+    mockDraftMode.isEnabled = false;
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+      liveWidget('home-banner')
+    );
+    expect(mockAppFetch).not.toHaveBeenCalled();
+  });
+
+  it('serves live when Next 14 caches the render despite a valid bypass cookie', async () => {
+    // __prerender_bypass valid (draftMode() on) but Next is writing this render
+    // to the shared ISR entry, e.g. because a junk __next_preview_data rode along.
+    mockStaticGenerationStore.isDraftMode = false;
+    mockWidgets['/widgets/home-banner-preview-kis/'] = {
+      attributes: { title: 'Draft banner' }
+    };
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+      liveWidget('home-banner')
+    );
+    expect(mockAppFetch).not.toHaveBeenCalled();
+  });
+
+  it('serves live when there is no request scope (build-time prerender)', async () => {
+    const headers = jest.requireMock('next/headers');
+    jest.spyOn(headers, 'draftMode').mockImplementation(() => {
+      throw new Error('`draftMode` was called outside a request scope');
+    });
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+      liveWidget('home-banner')
+    );
+    expect(mockAppFetch).not.toHaveBeenCalled();
+  });
+
+  it.each(['', 'Bad--Id', '../x'])(
+    'ignores an absent or invalid preview id (%j)',
+    async (previewId) => {
+      mockServerVariables.previewId = previewId;
+
+      expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+        liveWidget('home-banner')
+      );
+      expect(mockAppFetch).not.toHaveBeenCalled();
+    }
+  );
+
+  it("returns this preview's copy, read uncached, when it exists", async () => {
+    const copy = { attributes: { title: 'Draft banner' } };
+    mockWidgets['/widgets/home-banner-preview-kis/'] = copy;
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toBe(copy);
+    const previewRead = mockAppFetch.mock.calls
+      .map(([args]) => args as FetchArgs)
+      .find(({ url }) => url === '/widgets/home-banner-preview-kis/');
+    expect(previewRead?.init?.next).toEqual({ revalidate: 0 });
+    expect(mockCacheWrap).not.toHaveBeenCalled();
+  });
+
+  it('falls back to live when the preview has no copy of the widget', async () => {
+    expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+      liveWidget('home-banner')
+    );
+    expect(fetchedUrls()).toContain('/widgets/home-banner-preview-kis/');
+  });
+
+  it('never serves a snapshot holder as the widget itself', async () => {
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = {
+      attributes: { preview_snapshot: '{"version":0}' }
+    };
+
+    expect(await getWidgetData({ slug: 'homepage-body' })).toEqual(
+      liveWidget('homepage-body')
+    );
+  });
+
+  it('never overlays theme-config and never nests a copy of this preview', async () => {
+    await getWidgetData({ slug: 'theme-config' });
+    await getWidgetData({ slug: 'header-preview-kis' });
+
+    expect(fetchedUrls()).not.toContain('/widgets/theme-config-preview-kis/');
+    expect(fetchedUrls()).not.toContain(
+      '/widgets/header-preview-kis-preview-kis/'
+    );
+  });
+
+  it('overlays a live slug that merely looks like a copy of another preview', async () => {
+    const copy = { attributes: { title: 'Draft page' } };
+    mockWidgets['/widgets/page-summer-preview-2026-preview-kis/'] = copy;
+
+    expect(await getWidgetData({ slug: 'page-summer-preview-2026' })).toBe(
+      copy
+    );
+  });
+
+  it('renders live for a preview the registry no longer lists', async () => {
+    mockWidgets['/widgets/theme-previews/'] = registry('draft');
+    mockWidgets['/widgets/home-banner-preview-kis/'] = {
+      attributes: { title: 'Deleted preview' }
+    };
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toEqual(
+      liveWidget('home-banner')
+    );
+    expect(fetchedUrls()).not.toContain('/widgets/home-banner-preview-kis/');
+  });
+
+  it('fails open when the registry cannot be read', async () => {
+    const copy = { attributes: { title: 'Draft banner' } };
+    mockWidgets['/widgets/home-banner-preview-kis/'] = copy;
+    mockWidgets['/widgets/theme-previews/'] = {
+      attributes: { theme_previews: 'not json' }
+    };
+
+    expect(await getWidgetData({ slug: 'home-banner' })).toBe(copy);
+  });
+
+  it('reads the registry at most once within its 5s window', async () => {
+    const registryReads = () =>
+      fetchedUrls().filter((url) => url === '/widgets/theme-previews/');
+
+    await getWidgetData({ slug: 'home-banner' });
+    jest.spyOn(Date, 'now').mockReturnValue(now + 4_999);
+    await getWidgetData({ slug: 'footer' });
+    expect(registryReads()).toHaveLength(1);
+
+    jest.spyOn(Date, 'now').mockReturnValue(now + 5_000);
+    await getWidgetData({ slug: 'header' });
+    expect(registryReads()).toHaveLength(2);
+  });
+});
+
+describe('getPreviewSnapshot', () => {
+  const snapshot = {
+    version: 2,
+    savedAt: '2026-09-29T10:00:00.000Z',
+    themeSettings: {},
+    dataSources: [],
+    breakpoints: [{ id: 'tablet', minWidth: 768 }],
+    customPages: [],
+    sections: [{ id: 's1', blocks: [] }]
+  };
+
+  const holder = (value: unknown) => ({
+    attributes: { preview_snapshot: value }
+  });
+
+  it('returns the blob exactly as the editor wrote it', async () => {
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = holder(
+      JSON.stringify(snapshot)
+    );
+
+    expect(await getPreviewSnapshot({ slug: 'homepage-body' })).toEqual(
+      snapshot
+    );
+    const read = mockAppFetch.mock.calls
+      .map(([args]) => args as FetchArgs)
+      .find(({ url }) => url === '/widgets/homepage-body-preview-kis/');
+    expect(read?.init?.next).toEqual({ revalidate: 0 });
+  });
+
+  it('unwraps an attribute stored as { value }', async () => {
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = holder({
+      value: JSON.stringify({ ...snapshot, version: 1 })
+    });
+
+    expect((await getPreviewSnapshot({ slug: 'homepage-body' }))?.version).toBe(
+      1
+    );
+  });
+
+  it.each([
+    ['a discarded snapshot', '{"version":0}'],
+    ['malformed JSON', '{"version":2,'],
+    ['sections that are not a list', '{"version":2,"sections":{}}'],
+    ['a non-numeric version', '{"version":"2","sections":[]}'],
+    ['an empty value', '']
+  ])('treats %s as no snapshot', async (_label, value) => {
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = holder(value);
+
+    expect(await getPreviewSnapshot({ slug: 'homepage-body' })).toBeNull();
+  });
+
+  it('is null outside draft mode or without a registered preview', async () => {
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = holder(
+      JSON.stringify(snapshot)
+    );
+
+    mockDraftMode.isEnabled = false;
+    expect(await getPreviewSnapshot({ slug: 'homepage-body' })).toBeNull();
+
+    // Only the registry can refuse here: this preview's holder does exist.
+    mockDraftMode.isEnabled = true;
+    mockServerVariables.previewId = 'winter';
+    mockWidgets['/widgets/homepage-body-preview-winter/'] = holder(
+      JSON.stringify(snapshot)
+    );
+    expect(await getPreviewSnapshot({ slug: 'homepage-body' })).toBeNull();
+    expect(fetchedUrls()).not.toContain(
+      '/widgets/homepage-body-preview-winter/'
+    );
+  });
+
+  it('is null when Next 14 caches the render despite a valid bypass cookie', async () => {
+    mockStaticGenerationStore.isDraftMode = false;
+    mockWidgets['/widgets/homepage-body-preview-kis/'] = holder(
+      JSON.stringify(snapshot)
+    );
+
+    expect(await getPreviewSnapshot({ slug: 'homepage-body' })).toBeNull();
+    expect(mockAppFetch).not.toHaveBeenCalled();
+  });
+});

package/data/server/widget.ts

@@ -4,13 +4,197 @@ import { CacheOptions, WidgetResultType } from '../../types';
 import appFetch from '../../utils/app-fetch';
 import { widgets } from '../urls';
 import { ServerVariables } from '../../utils/server-variables';
+import {
+  isPreviewCopySlug,
+  isValidPreviewId,
+  previewSlug
+} from '../../utils/preview';
+import { isDraftRender } from '../../utils/preview-render';
+
+/**
+ * Widget preview (draft mode): the theme editor keeps any number of NAMED
+ * previews, each storing its pages under `<slug>-preview-<previewId>`. With
+ * draft mode on (entered via /api/preview, toggled by `?preview` on any page
+ * url) and a preview id on the request, every widget fetch first tries that
+ * preview's copy and falls back to the live slug when none exists — a
+ * preview renders as "live + that preview's overlay". Preview fetches bypass
+ * Redis and the fetch data cache so the editor's latest save is visible.
+ *
+ * BOTH signals are required: draft mode alone renders live (no id ⇒ no
+ * preview slug to try), and an id alone does nothing without draft mode.
+ */
+const PREVIEW_SNAPSHOT_ATTRIBUTE = 'preview_snapshot';
+
+const PREVIEW_NO_STORE = { revalidate: 0 };
+
+// The snapshot blob owns theme settings/data sources in preview, so the
+// theme-config widget itself is never slug-transformed; a slug that is
+// already this preview's copy is never transformed twice. Checked against
+// the CURRENT id, not a shape — a live slug may legitimately end in
+// `-preview-<something>` (a custom page named `summer-preview-2026`).
+const isPreviewTransformableSlug = (slug: string, previewId: string): boolean =>
+  slug !== 'theme-config' && !isPreviewCopySlug(slug, previewId);
+
+/**
+ * The editor's directory of previews that exist (`theme-previews` widget,
+ * `theme_previews` attribute). Deleting a preview removes it here first and
+ * clears only the pages the editor had loaded — so this is what makes a
+ * deleted preview stop rendering, even for a browser that still carries its
+ * cookie. Read uncached, remembered briefly across requests: a deleted
+ * preview may linger for at most REGISTRY_TTL_MS. An unreadable registry
+ * fails OPEN (behaves as before the check existed) rather than blanking
+ * every preview on a transient backend error.
+ */
+const PREVIEW_REGISTRY_SLUG = 'theme-previews';
+const PREVIEW_REGISTRY_ATTRIBUTE = 'theme_previews';
+const REGISTRY_TTL_MS = 5_000;
+
+let registryMemo: { ids: Set<string> | null; expires: number } = {
+  ids: null,
+  expires: 0
+};
+
+const unwrapAttribute = (raw: unknown): unknown =>
+  typeof raw === 'object' && raw !== null && 'value' in raw
+    ? (raw as { value?: unknown }).value
+    : raw;
+
+const registryKnowsPreview = async (
+  previewId: string,
+  locale: string,
+  currency: string
+): Promise<boolean> => {
+  const now = Date.now();
+  if (registryMemo.expires <= now) {
+    let ids: Set<string> | null = null;
+    try {
+      const widget = await getWidgetDataHandler(
+        PREVIEW_REGISTRY_SLUG,
+        locale,
+        currency,
+        undefined,
+        PREVIEW_NO_STORE
+      )();
+      const raw = unwrapAttribute(
+        (widget as { attributes?: Record<string, unknown> } | null)
+          ?.attributes?.[PREVIEW_REGISTRY_ATTRIBUTE]
+      );
+      if (typeof raw === 'string' && raw) {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed?.previews)) {
+          ids = new Set(
+            (parsed.previews as Array<{ id?: unknown }>)
+              .map((entry) => entry?.id)
+              .filter((id): id is string => typeof id === 'string')
+          );
+        }
+      }
+    } catch {
+      ids = null;
+    }
+    registryMemo = { ids, expires: now + REGISTRY_TTL_MS };
+  }
+  return registryMemo.ids ? registryMemo.ids.has(previewId) : true;
+};
+
+/**
+ * The named preview this render belongs to, or '' when the request is not a
+ * preview at all. The id is decoded from the pz route segment (see
+ * utils/preview.ts) and re-validated here — it originates from a cookie.
+ */
+const previewIdForRequest = async (
+  locale: string = ServerVariables.locale,
+  currency: string = ServerVariables.currency
+): Promise<string> => {
+  // Draft mode as Next 14 caches it, not just the bypass cookie — see
+  // utils/preview-render.ts.
+  if (!isDraftRender()) return '';
+  const previewId = ServerVariables.previewId;
+  if (!isValidPreviewId(previewId)) return '';
+  return (await registryKnowsPreview(previewId, locale, currency))
+    ? previewId
+    : '';
+};
+
+/**
+ * Whole-placeholder preview snapshot written by the theme editor into the
+ * `preview_snapshot` attribute of `<placeholderSlug>-preview-<previewId>`.
+ * When present (draft mode only), the placeholder renders straight from this
+ * blob — no per-section fetches.
+ */
+export type PreviewSnapshot = {
+  version: number;
+  savedAt?: string;
+  themeSettings?: Record<string, unknown> | null;
+  dataSources?: unknown[];
+  sections: unknown[];
+};
+
+export const getPreviewSnapshot = async ({
+  slug,
+  locale = ServerVariables.locale,
+  currency = ServerVariables.currency
+}: {
+  slug: string;
+  locale?: string;
+  currency?: string;
+}): Promise<PreviewSnapshot | null> => {
+  const previewId = slug ? await previewIdForRequest(locale, currency) : '';
+  if (!previewId) {
+    return null;
+  }
+
+  const widget = await getWidgetDataHandler(
+    previewSlug(slug, previewId),
+    locale,
+    currency,
+    undefined,
+    PREVIEW_NO_STORE
+  )();
+
+  const rawAttribute = (
+    widget as { attributes?: Record<string, unknown> } | null
+  )?.attributes?.[PREVIEW_SNAPSHOT_ATTRIBUTE];
+  const rawValue =
+    typeof rawAttribute === 'object' &&
+    rawAttribute !== null &&
+    'value' in rawAttribute
+      ? (rawAttribute as { value?: unknown }).value
+      : rawAttribute;
+
+  if (typeof rawValue !== 'string' || !rawValue) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(rawValue);
+    // Any version the editor has shipped so far, not just the first one. The
+    // fields this reader uses (`sections`, `themeSettings`, `dataSources`)
+    // have been present since v1 and later versions only ADD keys it ignores
+    // — v2 carries the editor's own brand-config pieces (custom pages, style
+    // presets, section templates) so a theme applied into a working copy is
+    // not lost. Pinning the check to one number meant a blob the editor could
+    // write was silently unrenderable here, falling back to the LIVE page.
+    if (
+      typeof parsed?.version === 'number' &&
+      parsed.version >= 1 &&
+      Array.isArray(parsed.sections)
+    ) {
+      return parsed as PreviewSnapshot;
+    }
+  } catch {
+    // Malformed snapshot — fall back to the live render path.
+  }
+  return null;
+};
 
 const getWidgetDataHandler =
   (
     slug: string,
     locale: string,
     currency: string,
-    headers?: Record<string, string>
+    headers?: Record<string, string>,
+    next?: { revalidate: number }
   ) =>
   async () => {
     if (!slug) {
@@ -22,7 +206,8 @@ const getWidgetDataHandler =
       locale,
       currency,
       init: {
-        headers
+        headers,
+        ...(next ? { next } : {})
       }
     });
   };
@@ -40,6 +225,35 @@ export const getWidgetData = async <T>({
   cacheOptions?: CacheOptions;
   headers?: Record<string, string>;
 }): Promise<WidgetResultType<T>> => {
+  const requestPreviewId =
+    slug === 'theme-config' ? '' : await previewIdForRequest(locale, currency);
+  const previewId = isPreviewTransformableSlug(slug, requestPreviewId)
+    ? requestPreviewId
+    : '';
+  if (previewId) {
+    const previewData = await getWidgetDataHandler(
+      previewSlug(slug, previewId),
+      locale,
+      currency,
+      headers,
+      PREVIEW_NO_STORE
+    )();
+
+    // A snapshot HOLDER (placeholder blob carrier, consumed exclusively via
+    // getPreviewSnapshot) is not a per-widget preview copy — returning it
+    // here would shadow the live widget with an attribute-less shell when
+    // its blob is malformed and the caller fell back to the live path.
+    const previewAttributes = (
+      previewData as { attributes?: Record<string, unknown> } | null
+    )?.attributes;
+    if (
+      previewAttributes &&
+      previewAttributes[PREVIEW_SNAPSHOT_ATTRIBUTE] === undefined
+    ) {
+      return previewData as WidgetResultType<T>;
+    }
+  }
+
   return Cache.wrap(
     CacheKey.Widget(slug),
     locale,

package/hocs/server/with-segment-defaults.tsx

@@ -10,6 +10,7 @@ import {
   getBuiltInSegments,
   isLegacyMode
 } from '../../utils/pz-segments';
+import { isValidPreviewId, PREVIEW_PZ_SEGMENT } from '../../utils/preview';
 
 type SegmentType = 'root-layout' | 'layout' | 'page';
 
@@ -28,6 +29,9 @@ export const withSegmentDefaults =
     let componentProps = { ...props };
     let localeValue: string;
     let currencyValue: string;
+    // Which named widget preview this render belongs to, if any — see
+    // utils/preview.ts for why it travels in the route rather than a cookie.
+    let previewValue = '';
 
     if (isLegacyMode(settings)) {
       localeValue = (props.params as any).locale;
@@ -38,6 +42,10 @@ export const withSegmentDefaults =
       const builtIn = getBuiltInSegments(parsed, settings);
       localeValue = builtIn.locale;
       currencyValue = builtIn.currency;
+      // Cookie-derived, so re-validated here rather than trusted.
+      previewValue = isValidPreviewId(parsed[PREVIEW_PZ_SEGMENT])
+        ? parsed[PREVIEW_PZ_SEGMENT]
+        : '';
     }
 
     if (options.segmentType === 'root-layout') {
@@ -51,6 +59,7 @@ export const withSegmentDefaults =
 
     ServerVariables.locale = localeValue;
     ServerVariables.currency = currencyValue;
+    ServerVariables.previewId = previewValue;
 
     return await (
       <>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@akinon/next",
   "description": "Core package for Project Zero Next",
-  "version": "1.126.15-v1-rc.12",
+  "version": "1.126.15",
   "private": false,
   "license": "MIT",
   "bin": {
@@ -35,7 +35,7 @@
     "set-cookie-parser": "2.6.0"
   },
   "devDependencies": {
-    "@akinon/eslint-plugin-projectzero": "1.126.15-v1-rc.12",
+    "@akinon/eslint-plugin-projectzero": "1.126.15",
     "@babel/core": "7.26.10",
     "@babel/preset-env": "7.26.9",
     "@babel/preset-typescript": "7.27.0",

package/utils/app-fetch.ts

@@ -52,7 +52,9 @@ const appFetch = async <T>({
       'x-forwarded-for': ip
     };
 
-    init.next = {
+    // Callers may pass their own cache directives (e.g. widget preview
+    // fetches use revalidate: 0); only apply the default when they don't.
+    init.next = init.next ?? {
       revalidate: Settings.usePrettyUrlRoute ? 0 : 60
     };
 

package/utils/preview-render.ts

@@ -0,0 +1,28 @@
+import 'server-only';
+import { draftMode } from 'next/headers';
+import { staticGenerationAsyncStorage } from 'next/dist/client/components/static-generation-async-storage.external';
+
+/**
+ * True only for a render Next.js itself treats as a draft render — one that
+ * is never written to the ISR cache.
+ *
+ * `draftMode().isEnabled` alone is not enough on Next 14. It compares only
+ * the `__prerender_bypass` cookie, while the decision to keep a render out of
+ * the ISR cache also reads the Pages Router `__next_preview_data` cookie: a
+ * valid bypass sent together with any junk data cookie renders "in draft
+ * mode" INTO the shared ISR entry, preview banner and preview content
+ * included. The static-generation store carries that caching decision
+ * (`isDraftMode`), so both have to agree. Next 15+ renders such a request as
+ * a prerender with draft mode off, which is why main reads draftMode() alone.
+ */
+export const isDraftRender = (): boolean => {
+  try {
+    return (
+      draftMode().isEnabled &&
+      staticGenerationAsyncStorage.getStore()?.isDraftMode === true
+    );
+  } catch {
+    // No request scope (e.g. build-time prerender) — never a preview.
+    return false;
+  }
+};

package/utils/preview-token.ts

@@ -0,0 +1,111 @@
+import { isValidPreviewId } from './preview';
+
+/**
+ * Signed, expiring preview entry tokens.
+ *
+ * The storefront never hands out its PREVIEW_SECRET: the editor asks
+ * `/api/preview/link` (proving it is an editor user with its Omnitron token)
+ * and receives a token that names ONE preview and dies at `expiresAt`. A leaked
+ * link therefore exposes nothing lasting, and rotating the secret invalidates
+ * every outstanding link at once.
+ *
+ * Format: `v1.<previewId>.<expiresAt unix seconds>.<base64url HMAC-SHA256>`.
+ * Web Crypto only, so the same code runs in Node route handlers and on the
+ * edge.
+ */
+export const PREVIEW_TOKEN_VERSION = 'v1';
+
+/** How long an editor-issued preview link stays valid unless configured. */
+export const DEFAULT_PREVIEW_LINK_TTL_SECONDS = 24 * 60 * 60;
+
+export interface PreviewTokenClaims {
+  previewId: string;
+  /** Unix time in SECONDS. */
+  expiresAt: number;
+}
+
+export type PreviewTokenVerdict =
+  | { ok: true; claims: PreviewTokenClaims }
+  | { ok: false; reason: 'malformed' | 'expired' | 'invalid-signature' };
+
+// Created per call: the module is also imported where TextEncoder only shows
+// up after a polyfill (jsdom), and the cost is negligible.
+const encode = (value: string) => new TextEncoder().encode(value);
+
+const base64url = (bytes: ArrayBuffer): string => {
+  const view = new Uint8Array(bytes);
+  let binary = '';
+  for (let i = 0; i < view.length; i++) {
+    binary += String.fromCharCode(view[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+const hmac = async (secret: string, payload: string): Promise<string> => {
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+  return base64url(await crypto.subtle.sign('HMAC', key, encode(payload)));
+};
+
+/** Constant-time string equality — a signature check must not leak by timing. */
+const timingSafeEqual = (a: string, b: string): boolean => {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+};
+
+const payloadOf = ({ previewId, expiresAt }: PreviewTokenClaims): string =>
+  `${PREVIEW_TOKEN_VERSION}.${previewId}.${expiresAt}`;
+
+export const signPreviewToken = async (
+  claims: PreviewTokenClaims,
+  secret: string
+): Promise<string> => {
+  if (!isValidPreviewId(claims.previewId)) {
+    throw new Error('signPreviewToken: invalid preview id');
+  }
+  if (!Number.isInteger(claims.expiresAt) || claims.expiresAt <= 0) {
+    throw new Error('signPreviewToken: invalid expiry');
+  }
+  const payload = payloadOf(claims);
+  return `${payload}.${await hmac(secret, payload)}`;
+};
+
+export const verifyPreviewToken = async (
+  token: string,
+  secret: string,
+  nowMs: number = Date.now()
+): Promise<PreviewTokenVerdict> => {
+  const parts = typeof token === 'string' ? token.split('.') : [];
+  if (parts.length !== 4 || parts[0] !== PREVIEW_TOKEN_VERSION) {
+    return { ok: false, reason: 'malformed' };
+  }
+  const [, previewId, expiresAtRaw, signature] = parts;
+  const expiresAt = Number(expiresAtRaw);
+  if (
+    !isValidPreviewId(previewId) ||
+    !/^\d+$/.test(expiresAtRaw) ||
+    !Number.isSafeInteger(expiresAt) ||
+    !signature
+  ) {
+    return { ok: false, reason: 'malformed' };
+  }
+  // Signature before expiry: an attacker must not learn which expired tokens
+  // were once valid.
+  const expected = await hmac(secret, payloadOf({ previewId, expiresAt }));
+  if (!timingSafeEqual(signature, expected)) {
+    return { ok: false, reason: 'invalid-signature' };
+  }
+  if (expiresAt * 1000 <= nowMs) {
+    return { ok: false, reason: 'expired' };
+  }
+  return { ok: true, claims: { previewId, expiresAt } };
+};

package/utils/preview.ts

@@ -0,0 +1,83 @@
+/**
+ * Widget preview contract — shared by the middleware/route handler that
+ * enters preview, the pz segment that carries which preview is being viewed,
+ * and the widget fetch layer that resolves the preview copies.
+ *
+ * The theme editor writes the other half of this contract: it creates named
+ * previews and stores each one's pages under `<slug>-preview-<id>`. The two
+ * sides must never drift.
+ */
+
+/** Suffix before the preview id — hyphenated because Omnitron slugifies. */
+export const PREVIEW_SLUG_SUFFIX = '-preview';
+
+/** Remembers which named preview this browser is viewing. */
+export const PREVIEW_ID_COOKIE = 'pz-preview-id';
+
+/** Next.js's own draft-mode cookie — set by `draftMode().enable()`. */
+export const DRAFT_MODE_COOKIE = '__prerender_bypass';
+
+/** Query key on the editor's link, consumed by the /api/preview handler. */
+export const PREVIEW_ID_QUERY_PARAM = 'preview_id';
+
+/**
+ * The pz segment carrying the preview id into the render.
+ *
+ * A cookie cannot be used directly: the pages that render widgets are
+ * `dynamic = 'force-static'`, and Next.js blanks `cookies()`/`headers()`
+ * under that config (draftMode is the exception). Route params always
+ * survive, so the middleware resolves the cookie into this segment and the
+ * server components read it from there. See settings.js `pzSegments`.
+ */
+export const PREVIEW_PZ_SEGMENT = 'preview';
+
+/**
+ * Ids come from a cookie, so they are validated everywhere they are used:
+ * lowercase slug words joined by single hyphens, bounded length — exactly
+ * what the editor produces (see slugifyPreviewId there). No `--` anywhere:
+ * that is the pz segment separator, and an id containing it would make the
+ * segment undecodable.
+ */
+export const isValidPreviewId = (id: unknown): id is string =>
+  typeof id === 'string' &&
+  id.length <= 32 &&
+  /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id);
+
+/** The slug a widget's copy lives under inside one named preview. */
+export const previewSlug = (slug: string, previewId: string): string =>
+  `${slug}${PREVIEW_SLUG_SUFFIX}-${previewId}`;
+
+/**
+ * True for slugs shaped like a preview copy of something. A HEURISTIC — a
+ * live slug can legitimately end this way (a custom page named
+ * `summer-preview-2026`), so the fetch layer does not use it to decide
+ * whether to overlay; see `isPreviewCopySlug`.
+ */
+export const isPreviewSlug = (slug: string): boolean =>
+  /-preview-[a-z0-9-]+$/.test(slug);
+
+/**
+ * True when `slug` is already the copy of something inside THIS preview —
+ * the exact check the fetch layer needs so preview slugs are never nested,
+ * without misreading live slugs that merely look like one.
+ */
+export const isPreviewCopySlug = (slug: string, previewId: string): boolean =>
+  previewId !== '' && slug.endsWith(previewSlug('', previewId));
+
+/**
+ * Resolves the pz segment value from the request — used by settings.js.
+ * An invalid or absent cookie yields '' (no preview), which the fetch layer
+ * treats as "render live".
+ *
+ * The id only counts alongside Next's draft-mode cookie: without it the
+ * request renders live anyway, and folding an unauthenticated cookie value
+ * into the route segment would let any visitor mint a fresh ISR/Redis cache
+ * key per request.
+ */
+export const resolvePreviewSegment = (req: {
+  cookies: { get: (name: string) => { value: string } | undefined };
+}): string => {
+  if (!req.cookies.get(DRAFT_MODE_COOKIE)?.value) return '';
+  const value = req.cookies.get(PREVIEW_ID_COOKIE)?.value ?? '';
+  return isValidPreviewId(value) ? value : '';
+};

package/utils/pz-segments.ts

@@ -40,15 +40,44 @@ export function encodePzValue(
     .join(config.separator);
 }
 
+/**
+ * Inverse of `encodePzValue`.
+ *
+ * The `url` segment is `encodeURIComponent(fullUrl)`, and that leaves `-`
+ * alone — so a pathname containing the separator (`/collections/summer--sale`)
+ * splits into extra parts. Only `url` can do that (locale, currency and the
+ * custom segments are validated slugs), so the segments before it are read
+ * from the front, the ones after it from the back, and whatever is left in
+ * the middle is the url re-joined. A purely positional read would hand the
+ * url's tail to the segment after it — with a preview segment present that
+ * meant rendering the wrong preview (or live) with a misleading banner.
+ */
 export function decodePzValue(
   pzValue: string,
   config: PzSegmentsConfig
 ): Record<string, string> {
   const parts = pzValue.split(config.separator);
   const result: Record<string, string> = {};
+  const urlIndex = config.segments.findIndex((seg) => seg.name === 'url');
 
+  if (urlIndex === -1 || parts.length <= config.segments.length) {
+    config.segments.forEach((seg, index) => {
+      result[seg.name] = parts[index] ?? '';
+    });
+    return result;
+  }
+
+  const trailing = config.segments.length - urlIndex - 1;
   config.segments.forEach((seg, index) => {
-    result[seg.name] = parts[index] ?? '';
+    if (index < urlIndex) {
+      result[seg.name] = parts[index] ?? '';
+    } else if (index === urlIndex) {
+      result[seg.name] = parts
+        .slice(urlIndex, parts.length - trailing)
+        .join(config.separator);
+    } else {
+      result[seg.name] = parts[parts.length - trailing + (index - urlIndex - 1)] ?? '';
+    }
   });
 
   return result;

package/utils/server-variables.ts

@@ -6,5 +6,12 @@ const { locales, defaultLocaleValue, defaultCurrencyCode } =
 export const ServerVariables = {
   locale: locales.find((l) => l.value === defaultLocaleValue)?.value ?? '',
   currency: defaultCurrencyCode,
-  globalHeaders: {}
+  globalHeaders: {},
+  /**
+   * Which named widget preview the current render belongs to, decoded from
+   * the pz route segment by withSegmentDefaults. Empty for ordinary traffic.
+   * Only ever acted on together with draft mode, so a value left behind by a
+   * concurrent request cannot leak preview content to a normal visitor.
+   */
+  previewId: ''
 };