@akinon/pz-theme 2.0.162-beta.0 → 2.0.162

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.162-beta.0
+## 2.0.162
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.162-beta.0
-  - @akinon/theme-contract@2.0.162-beta.0
+- 8758f3a3: ZERO-5391: Per-country placeholder content. When the request locale names a country (`en-ae` → `ae`) and the `theme-regions` registry lists a placeholder for it, the placeholder renders from that country's copy (`<slug>-region-<cc>`; in draft mode its `-preview-<id>` blob first) instead of the shared default, with the data-source records the copy carries (`theme_region_dataSources`) filling in any id theme-config lacks (theme-config's record wins when it has the id). Unlisted placeholders, language-only locales and a missing or unreadable registry keep today's reads; a server process that has read the registry keeps using it for up to 15 minutes while reads fail. `PLACEHOLDERS_AVAILABLE` now carries `contentCapabilities`, `localeUrlStrategy` and `defaultLocale`, and placeholders always report their canonical slug as `placeholderId`.
+  - @akinon/next@2.0.162
+  - @akinon/theme-contract@2.0.162
 
 ## 2.0.161
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.162-beta.0",
+  "version": "2.0.162",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.162-beta.0",
+    "@akinon/next": "2.0.162",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.162-beta.0",
+    "@akinon/theme-contract": "2.0.162",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.162-beta.0",
+    "@akinon/next": "2.0.162",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/readme.md

@@ -26,6 +26,28 @@ export default async function Page() {
 
 Developer-authored sections and blocks are written against `@akinon/pz-theme/src/custom` — see [`src/custom/README.md`](./src/custom/README.md) and [`src/custom/README-sections.md`](./src/custom/README-sections.md). Reference examples live in `examples/header/` at the root of the pz-next repository; they are not shipped in the npm package.
 
+## Per-country content (ZERO-5391)
+
+The theme editor can give one country its own copy of a placeholder (a page body, the header or footer, a custom page, a modal) while every other visitor keeps the shared content. pz-theme serves it without any change in the brand's code:
+
+- The country ("region") is the last part of the request locale when that part is a two-letter code: `en-ae` and `ar-ae` both read `ae`, `zh-hant-tw` reads `tw`. A language-only locale (`en`, `tr`) has no region, and its requests make no new reads.
+- The editor lists each country's customised placeholders in the `theme-regions` widget. A listed placeholder renders from `<slug>-region-<cc>`, with the data-source records that copy carries (`theme_region_dataSources`) filling in any id theme-config lacks; theme-config's record wins when it has the id. An unlisted placeholder is never looked up under a country slug.
+- Country content that cannot be read is replaced by the shared content, which is what the country's visitors saw before the area was customised. That covers a listed copy that does not answer or has no section order, and a registry that is missing or unreadable (a server process that has read the registry before keeps using that one for a while; see below).
+- Placeholders report their canonical slug (`header`, never `header-region-ae`) as `placeholderId`.
+- Every `PLACEHOLDERS_AVAILABLE` frame carries `contentCapabilities: ['region-content']`, `localeUrlStrategy` and `defaultLocale` (from `settings.localization`). The editor offers countries only to a storefront that announces the capability, does not use `LocaleUrlStrategy.Subdomain` (switching the preview's locale would change its origin) and has at least two audiences: its distinct countries, plus one if any locale is language-only.
+
+There is no on-demand revalidation, so changes reach visitors as caches expire:
+
+- Customising or reverting an area: up to about two minutes (the registry is cached for 60 s in Redis and kept for 60 s per server process), plus the page's ISR window. An area reverted and customised again inside the widget cache window can briefly show its previous country content.
+- When a registry read fails, is unreadable or finds no registry, a server process that has read one before keeps serving that one for up to 15 minutes after its last successful read, trying again every 10 seconds, so an outage does not flip countries back to the shared content. A registry that is deleted on purpose stays in effect just as long.
+- Publishing a country's edits: the same caching as any widget (Redis 900 s, then ISR).
+
+Requirements and known limits:
+
+- Live country content works on every core this package supports.
+- Country previews (the editor's draft, "View on site" and signed draft links in a country locale) need `@akinon/next` 1.126.15 or later and the `[pz]` route segment, as named previews do. Without them a country's draft cannot be previewed on the storefront, and its pages show live content.
+- A signed draft link opened in a country locale shows the shared DRAFT in the areas that country has not customised, while the editor's canvas shows the shared LIVE content there. Customised areas show the country's own draft in both.
+
 ## Using pz-theme on the v1 line
 
 `@akinon/pz-theme` and `@akinon/theme-contract` have a single release line. They are developed on `main` and published with the 2.x packages; the `v1` branch has no copy of them and publishes no 1.x version. A brand still on v1 (Next 14.2, React 18, `@akinon/next` 1.x) installs the same releases as a v2 brand.

package/src/__tests__/custom-catalog-announce.test.ts

@@ -460,4 +460,114 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     ]);
     expect(second.placeholders).toEqual(['header', 'footer']);
   });
+
+  // ZERO-5391 — per-country content.
+
+  it('announces per-country content and the locale settings before the editor proves itself', () => {
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // On the gated frame, like the action list: for a build with no custom
+    // catalog it is the only frame the editor ever gets, and a frame without
+    // the capability keeps the editor's country picker hidden.
+    //
+    // Literals rather than the constants, for the same reason as the action
+    // list: these pin the wire values. The locale values are the ones
+    // jest/__mocks__/settings.js carries.
+    const [payload] = frames();
+    expect(payload.contentCapabilities).toEqual(['region-content']);
+    expect(payload.localeUrlStrategy).toBe('hide-default-locale');
+    expect(payload.defaultLocale).toBe('en-us');
+  });
+
+  it('keeps the per-country fields on both frames of the designer re-announce', () => {
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+      })
+    );
+    jest.advanceTimersByTime(100);
+
+    // Every frame, not just the first. The editor replaces what it holds with
+    // each announce, so a later frame without the capability would take the
+    // country picker away halfway through a session.
+    expect(postMessage).toHaveBeenCalledTimes(2);
+    expect(
+      frames().map(
+        ({ contentCapabilities, localeUrlStrategy, defaultLocale }) => ({
+          contentCapabilities,
+          localeUrlStrategy,
+          defaultLocale
+        })
+      )
+    ).toEqual([
+      {
+        contentCapabilities: ['region-content'],
+        localeUrlStrategy: 'hide-default-locale',
+        defaultLocale: 'en-us'
+      },
+      {
+        contentCapabilities: ['region-content'],
+        localeUrlStrategy: 'hide-default-locale',
+        defaultLocale: 'en-us'
+      }
+    ]);
+  });
+
+  it('announces the locale settings the build actually routes by', () => {
+    // The stub's strategy is also the fallback, so only settings of another
+    // shape prove the frame reads them rather than a constant.
+    jest.doMock('settings', () => ({
+      localization: { localeUrlStrategy: 'subdomain', defaultLocaleValue: 'tr' }
+    }));
+    try {
+      const { registry } = load();
+
+      registry.registerPlaceholder('header');
+      jest.advanceTimersByTime(100);
+
+      const [payload] = frames();
+      expect(payload.localeUrlStrategy).toBe('subdomain');
+      expect(payload.defaultLocale).toBe('tr');
+      expect(payload.contentCapabilities).toEqual(['region-content']);
+    } finally {
+      jest.dontMock('settings');
+    }
+  });
+
+  it('still announces when the settings cannot be read', () => {
+    jest.doMock('settings', () => ({
+      get localization() {
+        throw new Error('settings are not readable');
+      }
+    }));
+    try {
+      const { registry } = load();
+
+      registry.registerPlaceholder('header');
+      jest.advanceTimersByTime(100);
+
+      // The frame is what every editor load waits for. Losing it to a settings
+      // read would cost the whole canvas, not just the country picker.
+      expect(postMessage).toHaveBeenCalledTimes(1);
+      const [payload] = frames();
+      expect(payload.placeholders).toEqual(['header']);
+      expect(payload.localeUrlStrategy).toBe('hide-default-locale');
+      expect(payload.defaultLocale).toBe('');
+    } finally {
+      jest.dontMock('settings');
+    }
+  });
 });

package/src/chrome/composition-source.ts

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { CompositionState, readCompositionState } from './composition-state';
 import { getPlaceholderPreviewSnapshot } from './preview-snapshot-source';
 import { getWidgetDataWithRetry } from './retrying-widget-data';
+import { readMarketPlaceholderCopy } from '../region/region-source'; // ZERO-5391
 
 // `React.cache` exists on the RSC-capable React this package renders under;
 // fall back to the raw function on older cores, where correctness is identical
@@ -20,9 +21,13 @@ export type PlaceholderWidget = {
 const fetchPlaceholderWidget = async (
   slug: string
 ): Promise<PlaceholderWidget> =>
-  (await getWidgetDataWithRetry<{
+  // ZERO-5391: a placeholder the request's region has its own copy of reads
+  // that copy; anything else, and a copy that does not answer, reads the
+  // shared default exactly as before.
+  ((await readMarketPlaceholderCopy(slug)) as PlaceholderWidget) ??
+  ((await getWidgetDataWithRetry<{
     attributes?: { theme_editor_placeholder?: unknown };
-  }>(slug)) as PlaceholderWidget;
+  }>(slug)) as PlaceholderWidget);
 
 /**
  * The one fetch of a placeholder widget per request.

package/src/chrome/preview-snapshot-source.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import * as serverData from '@akinon/next/data/server';
+import { resolveRegionSlug } from '../region/region-source'; // ZERO-5391
 
 /**
  * Whole-placeholder snapshot the theme editor writes for a named preview
@@ -31,7 +32,10 @@ const fetchPreviewSnapshot = async (
   if (!fn) return null;
 
   try {
-    return (await fn({ slug })) ?? null;
+    // ZERO-5391: a placeholder the request's region customised previews from
+    // that region's own blob; without one the loader falls through to the
+    // region's LIVE copy (getPlaceholderWidget), never to the default's blob.
+    return (await fn({ slug: await resolveRegionSlug(slug) })) ?? null;
   } catch {
     // A failed preview read must fall back to the live render, never blank it.
     return null;

package/src/content-capabilities.ts

@@ -0,0 +1,41 @@
+import { REGION_CONTENT_CAPABILITY } from './region/region-contract';
+
+/**
+ * What content this build can serve differently by AUDIENCE, announced to the
+ * editor (ZERO-5391).
+ *
+ * The third sibling of `action-capabilities.ts` and `signal-capabilities.ts`.
+ * Those say what a stored action will do and which moments the renderer can
+ * report; this one says whether the storefront can tell its visitors apart
+ * when it picks the content a placeholder renders.
+ *
+ *  - `region-content`  a placeholder renders from its country copy
+ *                      (`<slug>-region-<cc>`; in draft mode that copy's
+ *                      `-preview-<id>` blob first) for a request whose locale
+ *                      names the country (`en-ae` → `ae`), whenever the
+ *                      `theme-regions` registry lists the placeholder for it
+ *                      (`region/region-source.ts`). The editor offers its
+ *                      country picker, and with it every write to a
+ *                      `-region-` slug, only to a storefront that says so: on
+ *                      an older theme those writes would save and render
+ *                      nothing.
+ *
+ * Names rather than a version number, for the reason the action capabilities
+ * are: the editor must not have to know which release added what. A build that
+ * does not send the list is read as serving one content to every visitor,
+ * which is exactly what every renderer shipped before this one did.
+ *
+ * Unlike its siblings this list does not spell its string out. The name lives
+ * in the region contract (`region/region-contract.ts`), whose copy in the
+ * editor is held byte-identical to it by a parity test on both sides, so the
+ * two can only be renamed together — there and never here.
+ *
+ * Its own module rather than a constant beside the reader that implements it:
+ * the placeholder registry announces this from the client, and it must not
+ * have to pull the server-only region reader in to say one list of strings.
+ */
+export type ContentCapability = typeof REGION_CONTENT_CAPABILITY;
+
+export const CONTENT_CAPABILITIES: readonly ContentCapability[] = [
+  REGION_CONTENT_CAPABILITY
+];

package/src/load-placeholder-sections.ts

@@ -13,6 +13,7 @@ import {
   PreviewSnapshot
 } from './chrome/preview-snapshot-source';
 import { getThemeConfig, ThemeConfig } from './chrome/theme-config-source';
+import { withRegionDataSources } from './region/region-source'; // ZERO-5391
 import { readCustomBreakpoints } from './utils/breakpoints';
 // One acceptance rule for this loader and the designer canvas's client fetch
 // (utils/live-rows.ts), so the two cannot take different answers.
@@ -295,6 +296,11 @@ export async function loadPlaceholderSections(
       );
     }
 
+    // ZERO-5391: a region copy carries the data-source records its sections
+    // reference, so they resolve even while the shared theme-config is still
+    // cached without them; any other widget keeps theme-config's list.
+    const effectiveDataSources = withRegionDataSources(dataSources, data);
+
     const sections: Section[] = [];
 
     if (data?.attributes?.theme_editor_placeholder) {
@@ -460,7 +466,7 @@ export async function loadPlaceholderSections(
 
           const dataSourceWithData = await resolveSectionDataSource(
             dataSourceId,
-            dataSources,
+            effectiveDataSources, // ZERO-5391
             sectionSlug,
             sectionData
           );
@@ -504,8 +510,12 @@ export async function loadPlaceholderSections(
 
     return {
       sections,
-      placeholderId: data?.slug?.toString() || slug,
-      dataSources,
+      // ZERO-5391: always the canonical slug. A region copy
+      // (`<slug>-region-<cc>`) or a draft-mode per-widget preview copy answers
+      // under its own slug, while the editor and every frame address
+      // placeholders canonically.
+      placeholderId: slug,
+      dataSources: effectiveDataSources, // ZERO-5391
       themeSettings,
       customBreakpoints
     };

package/src/placeholder-registry.ts

@@ -13,6 +13,15 @@ import {
   STATE_PIN_CAPABILITIES,
   type StatePinCapability
 } from './state-pin-capabilities';
+// ZERO-5391: the per-country content handshake.
+import {
+  CONTENT_CAPABILITIES,
+  type ContentCapability
+} from './content-capabilities';
+import {
+  defaultLocaleForEditor,
+  localeUrlStrategyForEditor
+} from './region/editor-handshake';
 import type { CustomSectionCatalog } from './custom/section-types';
 import type { CustomPageCatalog } from './custom/page-types';
 import type { CustomCatalog } from './custom/types';
@@ -119,6 +128,32 @@ interface PlaceholdersAvailablePayload {
    * without the field would put it back to reporting nothing.
    */
   signalCapabilities?: readonly SignalCapability[];
+
+  // ZERO-5391: the three fields below are the per-country content handshake.
+  /**
+   * Which content THIS build can serve differently by audience (see
+   * `content-capabilities.ts`). The editor offers its country picker only to
+   * a storefront that lists `region-content`.
+   *
+   * Same terms as `actionCapabilities` above and on every frame for the same
+   * reason: the editor replaces what it holds with each frame, so a frame
+   * without the field would hide the picker again halfway through a session.
+   */
+  contentCapabilities?: readonly ContentCapability[];
+  /**
+   * `settings.localization.localeUrlStrategy`, 'hide-default-locale' when
+   * unset (see `region/editor-handshake.ts`). The editor moves its canvas
+   * between countries by switching the preview's locale, which under
+   * 'subdomain' would mean another origin. Every frame, on the same terms.
+   */
+  localeUrlStrategy?: string;
+  /**
+   * `settings.localization.defaultLocaleValue`: the locale the hide-*
+   * strategies serve without a path prefix, which the editor needs to link a
+   * country's page and to choose the locale a country switch lands on. Every
+   * frame, on the same terms.
+   */
+  defaultLocale?: string;
 }
 
 const isFramed = (): boolean =>
@@ -163,7 +198,13 @@ const flush = () => {
     // Outside the designer gate for the same reason, and for one more: the
     // panel it gates is the merchant's, so a slow handshake must not be the
     // difference between a section being trackable and not.
-    signalCapabilities: SIGNAL_CAPABILITIES
+    signalCapabilities: SIGNAL_CAPABILITIES,
+    // ZERO-5391: outside the designer gate for the same reasons. A fact about
+    // this theme version and two public locale settings: what decides whether
+    // the editor offers per-country content, and how it switches countries.
+    contentCapabilities: CONTENT_CAPABILITIES,
+    localeUrlStrategy: localeUrlStrategyForEditor(),
+    defaultLocale: defaultLocaleForEditor()
   };
 
   // Omitted entirely when nothing is registered: a build with no brand pages

package/src/region/__tests__/editor-handshake.test.ts

@@ -0,0 +1,144 @@
+/**
+ * ZERO-5391 — the locale settings the storefront hands the editor on
+ * PLACEHOLDERS_AVAILABLE, read from the brand's `settings` module.
+ *
+ * `settings` resolves to `jest/__mocks__/settings.js` unless a test swaps it.
+ * Each swap loads a fresh copy of the module under test, and `afterEach`
+ * removes the swap so the next test sees the shared stub again.
+ */
+
+// Type-only, so the module under test is still loaded fresh per test below;
+// it also keeps this file a module rather than a global script.
+import type * as HandshakeModule from '../editor-handshake';
+
+type Handshake = typeof HandshakeModule;
+
+const load = (settingsModule?: unknown): Handshake => {
+  let loaded: Handshake | undefined;
+  jest.isolateModules(() => {
+    if (settingsModule !== undefined) {
+      jest.doMock('settings', () => settingsModule);
+    }
+    loaded = require('../editor-handshake');
+  });
+  return loaded!;
+};
+
+describe('editor handshake settings', () => {
+  afterEach(() => {
+    jest.dontMock('settings');
+  });
+
+  it('reads the storefront settings the jest stub carries', () => {
+    const handshake = load();
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('en-us');
+  });
+
+  it('passes the configured strategy and default locale through', () => {
+    // The brand's settings.js is CommonJS, so its default import is the
+    // module object itself.
+    const handshake = load({
+      localization: { localeUrlStrategy: 'subdomain', defaultLocaleValue: 'tr' }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('subdomain');
+    expect(handshake.defaultLocaleForEditor()).toBe('tr');
+  });
+
+  it('reads an ES-module settings default export the same way', () => {
+    const handshake = load({
+      __esModule: true,
+      default: {
+        localization: {
+          localeUrlStrategy: 'show-all-locales',
+          defaultLocaleValue: 'en-ae'
+        }
+      }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('show-all-locales');
+    expect(handshake.defaultLocaleForEditor()).toBe('en-ae');
+  });
+
+  it.each([
+    ['empty settings', {}],
+    ['no localization values', { localization: {} }],
+    ['a null localization', { localization: null }],
+    ['an undefined default export', { __esModule: true, default: undefined }]
+  ])('falls back to the defaults for %s', (_label, settingsModule) => {
+    const handshake = load(settingsModule);
+
+    // 'hide-default-locale' is what the core's locale middleware routes by
+    // when the strategy is unset, so the editor is told what really happens.
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('');
+  });
+
+  it('treats an empty or non-string strategy as unset', () => {
+    expect(
+      load({
+        localization: { localeUrlStrategy: '' }
+      }).localeUrlStrategyForEditor()
+    ).toBe('hide-default-locale');
+    expect(
+      load({
+        localization: { localeUrlStrategy: 42 }
+      }).localeUrlStrategyForEditor()
+    ).toBe('hide-default-locale');
+  });
+
+  it('sends the default locale only when it is a string', () => {
+    expect(
+      load({
+        localization: { defaultLocaleValue: ['en'] }
+      }).defaultLocaleForEditor()
+    ).toBe('');
+    expect(
+      load({
+        localization: { defaultLocaleValue: '' }
+      }).defaultLocaleForEditor()
+    ).toBe('');
+  });
+
+  it('answers the defaults instead of throwing when the settings read throws', () => {
+    // The announce these values ride is the frame every editor load waits
+    // for; a settings read must never be able to take it down.
+    const handshake = load({
+      get localization() {
+        throw new Error('settings are not readable');
+      }
+    });
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-default-locale');
+    expect(handshake.defaultLocaleForEditor()).toBe('');
+  });
+
+  it('reads nothing at module scope and the current settings on every call', () => {
+    const settingsModule = {
+      localization: {
+        localeUrlStrategy: 'hide-all-locales',
+        defaultLocaleValue: 'en'
+      }
+    };
+    const read = jest.fn(() => settingsModule.localization);
+    const handshake = load({
+      get localization() {
+        return read();
+      }
+    });
+
+    expect(read).not.toHaveBeenCalled();
+    expect(handshake.localeUrlStrategyForEditor()).toBe('hide-all-locales');
+
+    settingsModule.localization = {
+      localeUrlStrategy: 'show-all-locales',
+      defaultLocaleValue: 'tr'
+    };
+
+    expect(handshake.localeUrlStrategyForEditor()).toBe('show-all-locales');
+    expect(handshake.defaultLocaleForEditor()).toBe('tr');
+    expect(read).toHaveBeenCalledTimes(3);
+  });
+});