@akinon/pz-theme 2.0.121-rc.0 → 2.0.122-beta.0

package/CHANGELOG.md

@@ -1,40 +1,21 @@
 # @akinon/pz-theme
 
-## 2.0.121-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d458]
-- Updated dependencies [dca12811]
-  - @akinon/next@2.0.121-rc.0
-  - @akinon/theme-contract@2.0.121-rc.0
+## 2.0.122-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.122-beta.0
+  - @akinon/theme-contract@2.0.122-beta.0
+
+## 2.0.121
+
+### Patch Changes
+
+- 60fc43e: ZERO-5108: A theme link fetches nothing ahead of time unless its caller asks for it. Next otherwise fetches a link's page as soon as the link is on screen, and because the language lives in a cookie that any such request rewrites, one link that escaped the locale rules switched the whole session's language with nobody clicking anything. next/link now has a single importer in the package, held there by a test, so a block cannot bring its own link back in without the locale or this default.
+- e64e783: ZERO-5107: Put the page locale on a link in the browser as well. A public env var is inlined when the app is built and ACC hands the container its environment afterwards, so the client bundle carried no site address: the server rendered the localized path, hydration put the merchant's full URL back, Next fetched that unprefixed path ahead of the shopper and the middleware answered it by switching the language cookie. The browser now falls back to the address it is served from, and every caller asks the same question through one helper.
+  - @akinon/next@2.0.121
+  - @akinon/theme-contract@2.0.121
 
 ## 2.0.120
 

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.121-rc.0",
+  "version": "2.0.122-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.121-rc.0",
+    "@akinon/next": "2.0.122-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.121-rc.0",
+    "@akinon/theme-contract": "2.0.122-beta.0",
     "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.121-rc.0",
+    "@akinon/next": "2.0.122-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/group-block.tsx

@@ -1,7 +1,11 @@
 import React from 'react';
 import { ThemeLink as NextLink } from '../components/theme-link';
 import { getResponsiveValue } from '../utils';
-import { asSitePath, isRootRelativeHref } from '../utils/localize-href';
+import {
+  asSitePath,
+  isRootRelativeHref,
+  storefrontOrigin
+} from '../utils/localize-href';
 import {
   buildCommerceItem,
   emitCommerceEvent,
@@ -76,7 +80,7 @@ const GroupBlock = ({
   const routerHref = isRootRelativeHref(href)
     ? href.trim()
     : typeof href === 'string'
-      ? asSitePath(href.trim(), process.env.NEXT_PUBLIC_URL)
+      ? asSitePath(href.trim(), storefrontOrigin())
       : undefined;
   const useRouterLink = tag === 'a' && !isDesigner && routerHref !== undefined;
   if (tag === 'a' && href && !useRouterLink) {
@@ -119,7 +123,6 @@ const GroupBlock = ({
       return (
         <NextLink
           href={routerHref as string}
-          prefetch={false}
           className="contents"
           onClick={handleAnchorAnalytics}
         />
@@ -168,7 +171,6 @@ const GroupBlock = ({
     return (
       <NextLink
         href={routerHref as string}
-        prefetch={false}
         className="contents"
         onClick={handleAnchorAnalytics}
       >

package/src/blocks/oauth-buttons-block.tsx

@@ -5,7 +5,7 @@ import React from 'react';
 // `/{provider}/login/`, so there is no locale to add. `localizeHref` leaves that
 // route alone too (`OAUTH_ROUTE`), which keeps a row template that renders
 // `item.url` through a button or group working on an English page.
-import NextLink from 'next/link';
+import { ThemeLink as NextLink } from '../components/theme-link';
 import { getResponsiveValue, partAttrs } from '../utils';
 import { DesignerPlaceholder, readToggle } from './product-block-utils';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
@@ -149,8 +149,9 @@ const OauthButtonsBlock = ({
             data-oauth-button={provider}
             {...partAttrs(`button-${provider}`)}
             href={isDesigner ? '#' : providerHref(provider)}
-            // The handshake leaves the Next.js app entirely, so the client router
-            // must not try to prefetch or soft-navigate it.
+            // The handshake leaves the Next.js app entirely, so the client
+            // router must not soft-navigate it. `ThemeLink` leaves an OAuth
+            // route's href exactly as it is and prefetches nothing by default.
             prefetch={false}
             onClick={(event) => {
               if (isDesigner) event.preventDefault();

package/src/components/__tests__/link-prefetch.test.tsx

@@ -0,0 +1,121 @@
+import fs from 'fs';
+import path from 'path';
+import React from 'react';
+import { render } from '@testing-library/react';
+
+/**
+ * ZERO-5108: a theme link prefetches nothing unless its caller asks.
+ *
+ * Next fetches a link's page as soon as the link is on screen, and the locale
+ * lives in a cookie that any request to an unprefixed path rewrites. One link
+ * that escapes the locale rules therefore stops being a wrong destination and
+ * becomes a silent language switch for the whole session, with nobody clicking
+ * anything — which is exactly how zsa-zsa-zsu's English storefront started
+ * serving Turkish menus. The rules still apply; this removes the mechanism
+ * that made a single miss cost the session.
+ *
+ * Asserted on the props `next/link` receives, because a boolean that React
+ * never puts on the anchor cannot be read back off the DOM.
+ */
+const received: Array<Record<string, unknown>> = [];
+
+jest.mock('next/link', () => ({
+  __esModule: true,
+  default: (props: Record<string, unknown>) => {
+    received.push(props);
+    return React.createElement('a', {
+      href: typeof props.href === 'string' ? props.href : '#'
+    });
+  }
+}));
+
+jest.mock('@akinon/next/hooks', () => ({
+  __esModule: true,
+  useLocalization: () => ({
+    locale: 'tr',
+    defaultLocaleValue: 'tr',
+    localeUrlStrategy: 'hide-default-locale'
+  })
+}));
+
+import { ThemeLink } from '../theme-link';
+
+beforeEach(() => {
+  received.length = 0;
+});
+
+describe('ThemeLink prefetching', () => {
+  it('asks for no prefetch by default', () => {
+    render(<ThemeLink href="/yatak-odasi/">Yatak odası</ThemeLink>);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].prefetch).toBe(false);
+  });
+
+  it('lets a caller turn it back on for its own case', () => {
+    render(
+      <ThemeLink href="/yatak-odasi/" prefetch>
+        Yatak odası
+      </ThemeLink>
+    );
+
+    expect(received[0].prefetch).toBe(true);
+  });
+
+  /**
+   * `oauth-buttons-block` renders its handshake through this component now.
+   * The handshake leaves the app, and the core middleware matches only the
+   * unprefixed path, so `/en/google/login/` would reach a page that does not
+   * exist.
+   */
+  it('leaves an OAuth handshake unprefixed and unprefetched', () => {
+    render(<ThemeLink href="/google/login/">Continue with Google</ThemeLink>);
+
+    expect(received[0]).toMatchObject({
+      href: '/google/login/',
+      prefetch: false
+    });
+  });
+
+  it('keeps passing everything else through', () => {
+    render(
+      <ThemeLink href="/yatak-odasi/" className="row" data-part="link">
+        Yatak odası
+      </ThemeLink>
+    );
+
+    expect(received[0]).toMatchObject({
+      href: '/yatak-odasi/',
+      className: 'row',
+      'data-part': 'link'
+    });
+  });
+});
+
+/**
+ * The guard that keeps the rule true for code written later: `next/link` is
+ * imported in exactly one file, so no block can bring its own link back in —
+ * with neither the locale nor this default on it.
+ */
+describe('next/link has one importer', () => {
+  const SRC = path.resolve(__dirname, '../..');
+
+  const sourceFiles = (dir: string): string[] =>
+    fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        return entry.name === '__tests__' || entry.name === 'node_modules'
+          ? []
+          : sourceFiles(full);
+      }
+      return /\.tsx?$/.test(entry.name) ? [full] : [];
+    });
+
+  it('is components/theme-link.tsx and nothing else', () => {
+    const importers = sourceFiles(SRC)
+      .filter((file) => /from\s+'next\/link'/.test(fs.readFileSync(file, 'utf8')))
+      .map((file) => path.relative(SRC, file).split(path.sep).join('/'));
+
+    expect(importers).toEqual(['components/theme-link.tsx']);
+  });
+});

package/src/components/__tests__/theme-link.test.tsx

@@ -85,10 +85,9 @@ describe('ThemeLink', () => {
   });
 
   /**
-   * The storefront's own address reaches the rules as `NEXT_PUBLIC_URL`, which
-   * Next inlines into the server render and the client bundle alike — so a
-   * merchant's pasted full URL reads as a path on both sides, and the anchor
-   * the shopper sees is the same one the server sent.
+   * The storefront's own address reaches the rules as `NEXT_PUBLIC_URL`, so a
+   * merchant's pasted full URL reads as a path and the anchor the shopper sees
+   * is the same one the server sent.
    */
   describe('with the site address configured', () => {
     const configured = process.env.NEXT_PUBLIC_URL;
@@ -134,6 +133,56 @@ describe('ThemeLink', () => {
     });
   });
 
+  /**
+   * ZERO-5107: a public env var is inlined at BUILD time and ACC hands the
+   * container its environment afterwards, so no client bundle built there
+   * carries `NEXT_PUBLIC_URL` at all. Without a fallback the server rendered
+   * `/en/yeni-urunler/`, hydration put the full URL back, Next prefetched that
+   * unprefixed path and the middleware answered it with `pz-locale=tr`.
+   */
+  describe('with the site address missing from the bundle', () => {
+    const configured = process.env.NEXT_PUBLIC_URL;
+
+    beforeEach(() => {
+      delete process.env.NEXT_PUBLIC_URL;
+    });
+
+    afterAll(() => {
+      if (configured === undefined) delete process.env.NEXT_PUBLIC_URL;
+      else process.env.NEXT_PUBLIC_URL = configured;
+    });
+
+    it('falls back to the address the page is served from', () => {
+      mockLocalization = { ...TURKISH, locale: 'en' };
+
+      expect(
+        hrefOf(
+          <ThemeLink href={`${window.location.origin}/yeni-urunler/`}>
+            New in
+          </ThemeLink>
+        )
+      ).toBe('/en/yeni-urunler/');
+    });
+
+    it('keeps that address as it was written on the Turkish page', () => {
+      const href = `${window.location.origin}/yeni-urunler/`;
+
+      expect(hrefOf(<ThemeLink href={href}>Yeni ürünler</ThemeLink>)).toBe(
+        href
+      );
+    });
+
+    it('still leaves another site alone', () => {
+      mockLocalization = { ...TURKISH, locale: 'en' };
+
+      expect(
+        hrefOf(
+          <ThemeLink href="https://lookbook.example.com/x">Lookbook</ThemeLink>
+        )
+      ).toBe('https://lookbook.example.com/x');
+    });
+  });
+
   it('keeps every other prop and forwards a ref to the anchor', () => {
     mockLocalization = { ...TURKISH, locale: 'en' };
     const ref = React.createRef<HTMLAnchorElement>();

package/src/components/theme-link.tsx

@@ -18,15 +18,26 @@ type ThemeLinkProps = React.ComponentPropsWithoutRef<typeof NextLink>;
  * Rendered through `next/link` rather than `@akinon/next`'s `Link` so a ref
  * still reaches the anchor, and so links and imperative navigations share one
  * rule set.
+ *
+ * NOTHING IS PREFETCHED UNLESS THE CALLER ASKS (ZERO-5108). Next fetches a
+ * link's page as soon as the link scrolls into view, and the locale lives in a
+ * cookie that any request to an unprefixed path rewrites — so one link that
+ * escapes the rules above stops being a wrong destination and becomes a silent
+ * language switch for the whole session, with nobody clicking anything. A
+ * composition is a wall of links the merchant arranged, and the cost of not
+ * prefetching them is paid once per click by the shopper who actually
+ * navigates. `prefetch` is still a prop: a caller that measured its own case
+ * can pass `true`.
  */
 export const ThemeLink = forwardRef<HTMLAnchorElement, ThemeLinkProps>(
-  function ThemeLink({ href, ...rest }, ref) {
+  function ThemeLink({ href, prefetch = false, ...rest }, ref) {
     const localize = useLocalizeHref();
 
     return (
       <NextLink
         ref={ref}
         href={typeof href === 'string' ? localize(href) : href}
+        prefetch={prefetch}
         {...rest}
       />
     );

package/src/custom/README.md

@@ -175,6 +175,12 @@ write the locale yourself; there are three places it goes on for you:
 | Any other link | `ThemeLink` in place of `next/link`, with the same props |
 | A bare string: a plain `<a>`, `router.push`, a url read off commerce data | `const localize = useLocalizeHref();` then `localize(url)` |
 
+`ThemeLink` prefetches nothing unless you pass `prefetch`. Next otherwise
+fetches a link's page the moment it scrolls into view, and because the locale
+lives in a cookie that any request to an unprefixed path rewrites, one link
+that slips past these rules would switch the whole session's language without
+anyone clicking it.
+
 All three come from `@akinon/pz-theme/src/custom`. An `<a>` nested deeper
 inside a `ThemeEditable` is not touched — that one is a link of yours, so it
 takes the row it belongs to above.

package/src/hooks/use-localize-href.ts

@@ -3,7 +3,7 @@
 import { useCallback } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
 import { urlLocaleMatcherRegex } from '@akinon/next/utils';
-import { localizeHref } from '../utils/localize-href';
+import { localizeHref, storefrontOrigin } from '../utils/localize-href';
 
 /**
  * `localizeHref` bound to the active locale, for anything that navigates
@@ -11,14 +11,11 @@ import { localizeHref } from '../utils/localize-href';
  *
  * Everything that localizes goes through this hook rather than calling
  * `localizeHref` itself, because this is the only place that knows the
- * storefront's own address — and without it a merchant's full URL to this same
- * site would not be recognized as a path. `NEXT_PUBLIC_URL` is a public env
- * var, so Next inlines the same literal into the server render and the client
- * bundle, and the two cannot disagree about which links are internal.
+ * storefront's own address.
  */
 export const useLocalizeHref = (): ((href: string) => string) => {
   const { locale, defaultLocaleValue, localeUrlStrategy } = useLocalization();
-  const siteUrl = process.env.NEXT_PUBLIC_URL;
+  const site = storefrontOrigin();
 
   return useCallback(
     (href: string) =>
@@ -27,8 +24,8 @@ export const useLocalizeHref = (): ((href: string) => string) => {
         defaultLocaleValue,
         localeUrlStrategy,
         localeMatcher: urlLocaleMatcherRegex,
-        siteUrl
+        siteUrl: site
       }),
-    [locale, defaultLocaleValue, localeUrlStrategy, siteUrl]
+    [locale, defaultLocaleValue, localeUrlStrategy, site]
   );
 };

package/src/utils/localize-href.ts

@@ -67,6 +67,27 @@ const hasNoLocaleVariant = (path: string): boolean => {
   return /\.[^.]+$/.test(lastSegment);
 };
 
+/**
+ * The storefront's own address, which is what makes a merchant's full URL to
+ * this same site recognizable as one of its paths.
+ *
+ * `NEXT_PUBLIC_URL` is read first and is the only value the server has. The
+ * browser falls back to the address it is actually being served from, because
+ * a public env var is inlined at BUILD time and ACC hands the container its
+ * environment afterwards: no client bundle built there carries the value at
+ * all. Without the fallback the server rendered `/en/yeni-urunler/` and
+ * hydration put the full URL back, Next prefetched that unprefixed path, and
+ * the middleware answered it with `pz-locale=tr` — every client request on an
+ * English page came back Turkish (ZERO-5107, live on 2026-09-23).
+ *
+ * Exported because a block that decides whether an href is internal has to ask
+ * the same question the same way; `group-block` read the env var directly and
+ * answered "not this site" in every browser.
+ */
+export const storefrontOrigin = (): string | undefined =>
+  process.env.NEXT_PUBLIC_URL ||
+  (typeof window === 'undefined' ? undefined : window.location.origin);
+
 /**
  * `www.` is not a different site. A merchant pastes whichever host their
  * browser showed them, and the storefront answers on both.