@akinon/projectzero 1.125.0-rc.1 → 1.126.0-rc.0

package/CHANGELOG.md

@@ -1,8 +1,6 @@
 # @akinon/projectzero
 
-## 1.125.0-rc.1
-
-## 1.125.0-rc.0
+## 1.126.0-rc.0
 
 ### Minor Changes
 
@@ -10,6 +8,8 @@
 - d99a6a7d: ZERO-3457_1: Fixed the settings prop and made sure everything is customizable.
 - e18836b2: ZERO-4160: Restore scope in Sentry addon configuration in akinon.json
 
+## 1.125.0
+
 ## 1.124.0
 
 ## 1.123.0

package/app-template/CHANGELOG.md

@@ -1,42 +1,6 @@
 # projectzeronext
 
-## 1.125.0-rc.1
-
-### Minor Changes
-
-- c0228aff: ZERO-4159: Upgrade the package versions
-
-### Patch Changes
-
-- Updated dependencies [c0228aff]
-  - @akinon/pz-b2b@1.125.0-rc.1
-  - @akinon/next@1.125.0-rc.1
-  - @akinon/pz-akifast@1.125.0-rc.1
-  - @akinon/pz-apple-pay@1.125.0-rc.1
-  - @akinon/pz-basket-gift-pack@1.125.0-rc.1
-  - @akinon/pz-bkm@1.125.0-rc.1
-  - @akinon/pz-checkout-gift-pack@1.125.0-rc.1
-  - @akinon/pz-click-collect@1.125.0-rc.1
-  - @akinon/pz-credit-payment@1.125.0-rc.1
-  - @akinon/pz-cybersource-uc@1.125.0-rc.1
-  - @akinon/pz-flow-payment@1.125.0-rc.1
-  - @akinon/pz-google-pay@1.125.0-rc.1
-  - @akinon/pz-gpay@1.125.0-rc.1
-  - @akinon/pz-haso@1.125.0-rc.1
-  - @akinon/pz-hepsipay@1.125.0-rc.1
-  - @akinon/pz-masterpass@1.125.0-rc.1
-  - @akinon/pz-masterpass-rest@1.125.0-rc.1
-  - @akinon/pz-multi-basket@1.125.0-rc.1
-  - @akinon/pz-one-click-checkout@1.125.0-rc.1
-  - @akinon/pz-otp@1.125.0-rc.1
-  - @akinon/pz-pay-on-delivery@1.125.0-rc.1
-  - @akinon/pz-saved-card@1.125.0-rc.1
-  - @akinon/pz-similar-products@1.125.0-rc.1
-  - @akinon/pz-tabby-extension@1.125.0-rc.1
-  - @akinon/pz-tamara-extension@1.125.0-rc.1
-  - @akinon/pz-virtual-try-on@1.125.0-rc.1
-
-## 1.125.0-rc.0
+## 1.126.0-rc.0
 
 ### Minor Changes
 
@@ -45,6 +9,7 @@
 - 143be2b9: ZERO-3457: Crop styles are customizable and logic improved for rendering similar products modal
 - 9f8cd3bc: ZERO-3449: AI Search Active Filters & Crop Style changes have been implemented
 - d99a6a7d: ZERO-3457_1: Fixed the settings prop and made sure everything is customizable.
+- c0228aff: ZERO-4159: Upgrade the package versions
 - b05c3543: ZERO-2570: Category filters routes to absolute url
 - e18836b2: ZERO-4160: Restore scope in Sentry addon configuration in akinon.json
 - c3244a31: ZERO-4013: Update runtime version to node:25-alpine in project configuration
@@ -55,7 +20,6 @@
 - Updated dependencies [b55acb76]
 - Updated dependencies [760258c1]
 - Updated dependencies [143be2b9]
-- Updated dependencies [cd68a97a]
 - Updated dependencies [9f8cd3bc]
 - Updated dependencies [bfafa3f4]
 - Updated dependencies [d99a6a7d]
@@ -63,34 +27,67 @@
 - Updated dependencies [4de5303c]
 - Updated dependencies [63a72000]
 - Updated dependencies [95b139dc]
+- Updated dependencies [c0228aff]
 - Updated dependencies [3909d322]
 - Updated dependencies [e18836b2]
-  - @akinon/next@1.125.0-rc.0
-  - @akinon/pz-similar-products@1.125.0-rc.0
-  - @akinon/pz-masterpass-rest@1.125.0-rc.0
-  - @akinon/pz-virtual-try-on@1.125.0-rc.0
-  - @akinon/pz-akifast@1.125.0-rc.0
-  - @akinon/pz-apple-pay@1.125.0-rc.0
-  - @akinon/pz-b2b@1.125.0-rc.0
-  - @akinon/pz-basket-gift-pack@1.125.0-rc.0
-  - @akinon/pz-bkm@1.125.0-rc.0
-  - @akinon/pz-checkout-gift-pack@1.125.0-rc.0
-  - @akinon/pz-click-collect@1.125.0-rc.0
-  - @akinon/pz-credit-payment@1.125.0-rc.0
-  - @akinon/pz-cybersource-uc@1.125.0-rc.0
-  - @akinon/pz-flow-payment@1.125.0-rc.0
-  - @akinon/pz-google-pay@1.125.0-rc.0
-  - @akinon/pz-gpay@1.125.0-rc.0
-  - @akinon/pz-haso@1.125.0-rc.0
-  - @akinon/pz-hepsipay@1.125.0-rc.0
-  - @akinon/pz-masterpass@1.125.0-rc.0
-  - @akinon/pz-multi-basket@1.125.0-rc.0
-  - @akinon/pz-one-click-checkout@1.125.0-rc.0
-  - @akinon/pz-otp@1.125.0-rc.0
-  - @akinon/pz-pay-on-delivery@1.125.0-rc.0
-  - @akinon/pz-saved-card@1.125.0-rc.0
-  - @akinon/pz-tabby-extension@1.125.0-rc.0
-  - @akinon/pz-tamara-extension@1.125.0-rc.0
+  - @akinon/next@1.126.0-rc.0
+  - @akinon/pz-similar-products@1.126.0-rc.0
+  - @akinon/pz-masterpass-rest@1.126.0-rc.0
+  - @akinon/pz-b2b@1.126.0-rc.0
+  - @akinon/pz-virtual-try-on@1.126.0-rc.0
+  - @akinon/pz-akifast@1.126.0-rc.0
+  - @akinon/pz-apple-pay@1.126.0-rc.0
+  - @akinon/pz-basket-gift-pack@1.126.0-rc.0
+  - @akinon/pz-bkm@1.126.0-rc.0
+  - @akinon/pz-checkout-gift-pack@1.126.0-rc.0
+  - @akinon/pz-click-collect@1.126.0-rc.0
+  - @akinon/pz-credit-payment@1.126.0-rc.0
+  - @akinon/pz-cybersource-uc@1.126.0-rc.0
+  - @akinon/pz-flow-payment@1.126.0-rc.0
+  - @akinon/pz-google-pay@1.126.0-rc.0
+  - @akinon/pz-gpay@1.126.0-rc.0
+  - @akinon/pz-haso@1.126.0-rc.0
+  - @akinon/pz-hepsipay@1.126.0-rc.0
+  - @akinon/pz-masterpass@1.126.0-rc.0
+  - @akinon/pz-multi-basket@1.126.0-rc.0
+  - @akinon/pz-one-click-checkout@1.126.0-rc.0
+  - @akinon/pz-otp@1.126.0-rc.0
+  - @akinon/pz-pay-on-delivery@1.126.0-rc.0
+  - @akinon/pz-saved-card@1.126.0-rc.0
+  - @akinon/pz-tabby-extension@1.126.0-rc.0
+  - @akinon/pz-tamara-extension@1.126.0-rc.0
+
+## 1.125.0
+
+### Patch Changes
+
+- Updated dependencies [cd68a97a]
+  - @akinon/next@1.125.0
+  - @akinon/pz-virtual-try-on@1.125.0
+  - @akinon/pz-akifast@1.125.0
+  - @akinon/pz-apple-pay@1.125.0
+  - @akinon/pz-b2b@1.125.0
+  - @akinon/pz-basket-gift-pack@1.125.0
+  - @akinon/pz-bkm@1.125.0
+  - @akinon/pz-checkout-gift-pack@1.125.0
+  - @akinon/pz-click-collect@1.125.0
+  - @akinon/pz-credit-payment@1.125.0
+  - @akinon/pz-cybersource-uc@1.125.0
+  - @akinon/pz-flow-payment@1.125.0
+  - @akinon/pz-google-pay@1.125.0
+  - @akinon/pz-gpay@1.125.0
+  - @akinon/pz-haso@1.125.0
+  - @akinon/pz-hepsipay@1.125.0
+  - @akinon/pz-masterpass@1.125.0
+  - @akinon/pz-masterpass-rest@1.125.0
+  - @akinon/pz-multi-basket@1.125.0
+  - @akinon/pz-one-click-checkout@1.125.0
+  - @akinon/pz-otp@1.125.0
+  - @akinon/pz-pay-on-delivery@1.125.0
+  - @akinon/pz-saved-card@1.125.0
+  - @akinon/pz-similar-products@1.125.0
+  - @akinon/pz-tabby-extension@1.125.0
+  - @akinon/pz-tamara-extension@1.125.0
 
 ## 1.124.0
 

package/app-template/docs/advanced-usage.md

@@ -42,6 +42,107 @@ const middleware: NextMiddleware = (
 };
 ```
 
+## Custom Segments
+
+The `[pz]` segment encodes `locale`, `currency`, and `url` by default. You can add custom segments via `pzSegments` in `settings.js` to encode additional values into the URL.
+
+### Configuration
+
+Define custom segments in `settings.js` with a `resolve` function that computes the segment value at request time:
+
+```js
+/** @type {import('@akinon/next/types').Settings} */
+module.exports = {
+  // ...
+  usePzSegment: true,
+  pzSegments: {
+    segments: [
+      {
+        name: 'segment',
+        resolve: (context) => context.req.cookies.get('pz-segment')?.value ?? 'default'
+      }
+    ]
+  }
+}
+```
+
+Default segments (`locale`, `currency`, `url`) are always included automatically. You only need to define your custom ones.
+
+### Resolve Context
+
+The `resolve` function receives a context object with the following properties:
+
+| Property   | Type             | Description                          |
+|------------|------------------|--------------------------------------|
+| `req`      | `PzNextRequest`  | The incoming request object (cookies, headers, middlewareParams) |
+| `event`    | `NextFetchEvent` | The Next.js fetch event (waitUntil, etc.) |
+| `url`      | `NextURL`        | Cloned URL object of the current request |
+| `locale`   | `string`         | Resolved locale value                |
+| `currency` | `string`         | Resolved currency value              |
+| `pathname` | `string`         | Pathname without locale prefix       |
+
+### Reading Segment Values
+
+In server components, use `parsePzParams` to read all segment values (both built-in and custom):
+
+```tsx
+import { parsePzParams } from '@akinon/next/utils'
+import settings from 'settings'
+
+export default function Page({ params }) {
+  const { locale, currency, url, segment } = parsePzParams(params, settings)
+  // ...
+}
+```
+
+In client components, use the `usePzParams` hook:
+
+```tsx
+'use client'
+import { usePzParams } from '@akinon/next/hooks/use-pz-params'
+
+export default function MyComponent() {
+  const { locale, currency, url, segment } = usePzParams()
+  // ...
+}
+```
+
+### Example: Cookie-based Segment
+
+A segment that reads a value from a cookie and falls back to a default:
+
+```js
+pzSegments: {
+  segments: [
+    {
+      name: 'segment',
+      resolve: (context) => context.req.cookies.get('pz-segment')?.value ?? 'default'
+    }
+  ]
+}
+```
+
+This encodes the cookie value into the `[pz]` URL parameter. The resulting URL structure becomes:
+
+```
+/tr--TL--<encoded-url>--default/page-path
+```
+
+### Migration from Legacy Structure
+
+To migrate a project using the legacy `[commerce]/[locale]/[currency]` directory structure to the new `[pz]` segment:
+
+```bash
+npx projectzero codemod --codemod=migrate-segments
+```
+
+This codemod will:
+- Detect all dynamic segments and merge them into `[pz]/`
+- Update `settings.js` with `usePzSegment: true`
+- Clean up middleware rewrite blocks
+- Update path references in `tsconfig.json`, `next.config.js`, and source files
+- Replace `params.locale` / `params.currency` / `params.url` usages with `parsePzParams`
+
 ## Enabling Browser Back/Forward Cache (bfcache)
 
 By default, dynamic pages may include `Cache-Control: no-store` headers, which prevents browsers from using the back/forward cache (bfcache). To enable bfcache support, set the `BF_CACHE` environment variable to `true`:

package/app-template/next.config.mjs

@@ -8,12 +8,12 @@ const nextConfig = {
   rewrites: async () => {
     return [
       {
-        source: '/:commerce/:locale/:currency/sitemap.xml',
-        destination: '/:commerce/:locale/:currency/xml-sitemap'
+        source: '/:pz/sitemap.xml',
+        destination: '/:pz/xml-sitemap'
       },
       {
-        source: '/:commerce/:locale/:currency/sitemap/:node',
-        destination: '/:commerce/:locale/:currency/xml-sitemap/:node'
+        source: '/:pz/sitemap/:node',
+        destination: '/:pz/xml-sitemap/:node'
       }
     ];
   }

package/app-template/package.json

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

package/app-template/src/app/{[commerce]/[locale]/[currency] → [pz]}/layout.tsx

@@ -42,17 +42,12 @@ export async function generateMetadata() {
   return result;
 }
 
-async function RootLayout({
-  params,
-  locale,
-  translations,
-  children
-}: RootLayoutProps) {
+async function RootLayout({ locale, translations, children }: RootLayoutProps) {
   return (
     <html lang={locale.isoCode} {...(locale.rtl ? { dir: 'rtl' } : {})}>
       <head />
       <body className="overflow-x-hidden">
-        <PzRoot translations={translations} {...params}>
+        <PzRoot translations={translations} locale={locale.value}>
           <ClientRoot>
             <div className="overflow-x-hidden">
               <MobileAppToggler>

package/app-template/src/settings.js

@@ -63,5 +63,6 @@ module.exports = {
     defaultExpirationTime: 900 // 15 min
   },
   customNotFoundEnabled: false,
+  usePzSegment: true,
   commerceRedirectionIgnoreList: ['/users/reset']
 };

package/app-template/tsconfig.json

@@ -5,16 +5,12 @@
     "baseUrl": "./src",
     "paths": {
       "@theme/*": ["./*"],
-      "@root/*": ["./app/[commerce]/[locale]/[currency]/*"],
-      "@product/*": ["./app/[commerce]/[locale]/[currency]/product/*"],
-      "@group-product/*": [
-        "./app/[commerce]/[locale]/[currency]/group-product/*"
-      ],
-      "@category/*": ["./app/[commerce]/[locale]/[currency]/category/*"],
-      "@special-page/*": [
-        "./app/[commerce]/[locale]/[currency]/special-page/*"
-      ],
-      "@flat-page/*": ["./app/[commerce]/[locale]/[currency]/flat-page/*"]
+      "@root/*": ["./app/[pz]/*"],
+      "@product/*": ["./app/[pz]/product/*"],
+      "@group-product/*": ["./app/[pz]/group-product/*"],
+      "@category/*": ["./app/[pz]/category/*"],
+      "@special-page/*": ["./app/[pz]/special-page/*"],
+      "@flat-page/*": ["./app/[pz]/flat-page/*"]
     },
     "allowSyntheticDefaultImports": true,
     "composite": false,

package/codemods/migrate-segments/index.js

@@ -0,0 +1,593 @@
+const fs = require('fs');
+const path = require('path');
+
+const green = (msg) => `\x1b[32m${msg}\x1b[0m`;
+const red = (msg) => `\x1b[31m${msg}\x1b[0m`;
+const yellow = (msg) => `\x1b[33m${msg}\x1b[0m`;
+const bold = (msg) => `\x1b[1m${msg}\x1b[0m`;
+
+const BUILTIN_SEGMENTS = ['commerce', 'locale', 'currency', 'url'];
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function countEntries(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    count++;
+    if (entry.isDirectory()) {
+      count += countEntries(path.join(dir, entry.name));
+    }
+  }
+  return count;
+}
+
+/**
+ * Walks down from [commerce]/ through nested dynamic segments,
+ * collecting segment names and the directories at each level.
+ *
+ * Handles intermediate content (e.g. layout.tsx at [locale]/ level)
+ * by continuing to descend as long as a single-bracket dynamic child exists.
+ *
+ * Example:
+ *   [commerce]/[locale]/[currency]/[url]/...
+ *   → segments: ['locale', 'currency', 'url']
+ *   → levels: [{ dir: '[locale]/', segmentChild: '[currency]' }, ...]
+ *   → contentDir: the deepest level with route content
+ */
+function detectSegments(commerceDir) {
+  const segments = [];
+  const levels = []; // { dir, segmentChildName } for each intermediate level
+  let currentDir = commerceDir;
+
+  while (true) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    // Find single-bracket dynamic segment dirs (not catch-all [...])
+    const dynamicDirs = entries.filter(
+      (e) =>
+        e.isDirectory() &&
+        e.name.startsWith('[') &&
+        e.name.endsWith(']') &&
+        !e.name.startsWith('[...')
+    );
+
+    if (dynamicDirs.length === 1) {
+      const segName = dynamicDirs[0].name.slice(1, -1);
+      segments.push(segName);
+      levels.push({ dir: currentDir, segmentChildName: dynamicDirs[0].name });
+      currentDir = path.join(currentDir, dynamicDirs[0].name);
+    } else {
+      // No more single dynamic segment children — this is the deepest content level
+      break;
+    }
+  }
+
+  return { segments, levels, contentDir: currentDir };
+}
+
+/**
+ * Copies non-segment content from each intermediate level into dest,
+ * then copies the deepest content level on top (deeper wins on conflict).
+ */
+function mergeContentIntoPz(levels, contentDir, pzDir) {
+  // First: copy non-segment content from each intermediate level (shallowest first)
+  for (const { dir, segmentChildName } of levels) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip the segment child directory itself
+      if (entry.name === segmentChildName) continue;
+
+      const srcPath = path.join(dir, entry.name);
+      const destPath = path.join(pzDir, entry.name);
+      if (entry.isDirectory()) {
+        copyDirRecursive(srcPath, destPath);
+      } else {
+        fs.mkdirSync(pzDir, { recursive: true });
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+
+  // Last: copy deepest content level (overwrites conflicts from shallower levels)
+  copyDirRecursive(contentDir, pzDir);
+}
+
+/**
+ * Reads middleware.ts and extracts the expression used to build
+ * the URL rewrite for each custom segment.
+ *
+ * Looks for patterns like:
+ *   url.pathname = '/' + <expression> + url.pathname
+ *   url.pathname = `/${<expression>}${url.pathname}`
+ *
+ * Then maps that expression into a resolve function.
+ */
+function analyzeMiddleware(workingDir, customSegments) {
+  const hints = {};
+
+  const middlewarePath = path.join(workingDir, 'src', 'middleware.ts');
+  if (!fs.existsSync(middlewarePath)) return hints;
+
+  const content = fs.readFileSync(middlewarePath, 'utf-8');
+
+  // Extract the rewrite expression from url.pathname assignment
+  // Pattern 1: url.pathname = '/' + <expr> + url.pathname
+  const concatMatch = content.match(
+    /url\.pathname\s*=\s*['"`]\/['"`]\s*\+\s*(.+?)\s*\+\s*url\.pathname/
+  );
+  // Pattern 2: url.pathname = `/${<expr>}${url.pathname}`
+  const templateMatch = content.match(
+    /url\.pathname\s*=\s*`\/\$\{(.+?)\}\$\{url\.pathname\}`/
+  );
+
+  const rewriteExpression = concatMatch?.[1]?.trim() || templateMatch?.[1]?.trim();
+
+  for (const seg of customSegments) {
+    // If we found a rewrite expression in middleware, use it directly
+    if (rewriteExpression) {
+      hints[seg] = {
+        source: 'middleware-rewrite',
+        code: `({ req }) => ${rewriteExpression}`
+      };
+      continue;
+    }
+
+    // Check for cookie pattern: req.cookies.get('pz-{seg}') or similar
+    const cookieRegex = new RegExp(
+      `cookies\\.get\\(['"\`](?:pz-)?${seg}['"\`]\\)`,
+      'i'
+    );
+    if (cookieRegex.test(content)) {
+      hints[seg] = {
+        source: 'cookie',
+        code: `({ req }) => req.cookies.get('pz-${seg}')?.value ?? ''`
+      };
+      continue;
+    }
+
+    // Check for header pattern: req.headers.get('x-{seg}')
+    const headerRegex = new RegExp(
+      `headers\\.get\\(['"\`](?:x-)?${seg}['"\`]\\)`,
+      'i'
+    );
+    if (headerRegex.test(content)) {
+      hints[seg] = {
+        source: 'header',
+        code: `({ req }) => req.headers.get('x-${seg}') ?? ''`
+      };
+      continue;
+    }
+
+    // No hint found
+    hints[seg] = {
+      source: 'unknown',
+      code: null
+    };
+  }
+
+  return hints;
+}
+
+/**
+ * Removes the rewrite block from middleware.ts since resolve now handles it.
+ * Strips: url clone, url.pathname assignment, NextResponse.rewrite with pz-override-response.
+ * Leaves the middleware function body empty (or with remaining custom logic).
+ */
+function cleanupMiddleware(workingDir) {
+  const middlewarePath = path.join(workingDir, 'src', 'middleware.ts');
+  if (!fs.existsSync(middlewarePath)) return false;
+
+  let content = fs.readFileSync(middlewarePath, 'utf-8');
+
+  if (!content.includes('pz-override-response')) return false;
+
+  // Remove: const url = req.nextUrl.clone();
+  content = content.replace(
+    /\n?\s*const url = req\.nextUrl\.clone\(\);\s*\n?/,
+    '\n'
+  );
+
+  // Remove: url.pathname = ... + url.pathname;
+  content = content.replace(
+    /\s*url\.pathname\s*=\s*.+?url\.pathname.*;\s*\n?/,
+    ''
+  );
+
+  // Replace NextResponse.rewrite(url, { headers: { 'pz-override-response': ... } })
+  // with empty return (or no return)
+  content = content.replace(
+    /\s*return\s+NextResponse\.rewrite\(url,\s*\{[\s\S]*?'pz-override-response'[\s\S]*?\}\s*\);\s*/,
+    '\n'
+  );
+
+  // Clean up empty lines left behind
+  content = content.replace(/\n{3,}/g, '\n\n');
+
+  fs.writeFileSync(middlewarePath, content);
+  return true;
+}
+
+/**
+ * Replaces old segment path references in project files (tsconfig, imports, etc.)
+ * e.g. ./app/[commerce]/[locale]/[currency]/[url]/ → ./app/[pz]/
+ */
+function updatePathReferences(workingDir, segments) {
+  // Build old path patterns from detected segments in different formats
+  // Bracket format: [commerce]/[locale]/[currency]/[url]
+  const bracketPath = ['[commerce]', ...segments.map((s) => `[${s}]`)].join(
+    '/'
+  );
+  // Colon format (Next.js rewrites): :commerce/:locale/:currency/:url
+  const colonPath = [':commerce', ...segments.map((s) => `:${s}`)].join('/');
+
+  const replacements = [
+    { from: bracketPath, to: '[pz]' },
+    { from: colonPath, to: ':pz' }
+  ];
+
+  const extensions = ['.json', '.js', '.mjs', '.ts', '.tsx'];
+  let updatedFiles = [];
+
+  function walkAndReplace(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      // Skip the app directory itself (already handled by directory migration)
+      if (entry.name === 'app' && dir === path.join(workingDir, 'src')) continue;
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walkAndReplace(fullPath);
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        let content;
+        try {
+          content = fs.readFileSync(fullPath, 'utf-8');
+        } catch {
+          continue;
+        }
+
+        let changed = false;
+        for (const { from, to } of replacements) {
+          if (content.includes(from)) {
+            content = content.split(from).join(to);
+            changed = true;
+          }
+        }
+
+        if (changed) {
+          fs.writeFileSync(fullPath, content);
+          updatedFiles.push(path.relative(workingDir, fullPath));
+        }
+      }
+    }
+  }
+
+  walkAndReplace(workingDir);
+  return updatedFiles;
+}
+
+function updateParamsUsage(workingDir) {
+  const extensions = ['.ts', '.tsx'];
+  const updatedFiles = [];
+
+  // Patterns to replace inline
+  const replacements = [
+    // decodeURIComponent(params.url) → parsePzParams(params, settings).url
+    {
+      pattern: /decodeURIComponent\(params\.url\)/g,
+      replacement: 'parsePzParams(params, settings).url'
+    },
+    // params.locale → parsePzParams(params, settings).locale
+    {
+      pattern: /params\.locale/g,
+      replacement: 'parsePzParams(params, settings).locale'
+    },
+    // params.currency → parsePzParams(params, settings).currency
+    {
+      pattern: /params\.currency/g,
+      replacement: 'parsePzParams(params, settings).currency'
+    },
+    // params.url (standalone, not already wrapped) → parsePzParams(params, settings).url
+    {
+      pattern: /params\.url/g,
+      replacement: 'parsePzParams(params, settings).url'
+    }
+  ];
+
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        let content;
+        try {
+          content = fs.readFileSync(fullPath, 'utf-8');
+        } catch {
+          continue;
+        }
+
+        // Check if file has any params.locale/currency/url usage
+        if (!/params\.(locale|currency|url)/.test(content)) continue;
+
+        let updated = content;
+        for (const { pattern, replacement } of replacements) {
+          updated = updated.replace(pattern, replacement);
+        }
+
+        if (updated !== content) {
+          // Add import if not already present
+          if (!updated.includes('parsePzParams')) {
+            // This shouldn't happen since we just added it, but safety check
+          }
+          if (
+            !updated.includes("from '@akinon/next/utils'") &&
+            !updated.includes("from '@akinon/next/utils/pz-segments'")
+          ) {
+            // Add import at the top after last import
+            const lastImportIdx = updated.lastIndexOf('\nimport ');
+            if (lastImportIdx !== -1) {
+              const lineEnd = updated.indexOf('\n', lastImportIdx + 1);
+              updated =
+                updated.slice(0, lineEnd + 1) +
+                "import { parsePzParams } from '@akinon/next/utils';\n" +
+                updated.slice(lineEnd + 1);
+            } else {
+              updated =
+                "import { parsePzParams } from '@akinon/next/utils';\n" +
+                updated;
+            }
+          } else {
+            // File already imports from @akinon/next/utils, add parsePzParams to existing import
+            const importRegex =
+              /import\s*\{([^}]*)\}\s*from\s*['"]@akinon\/next\/utils['"]/;
+            const match = updated.match(importRegex);
+            if (match && !match[1].includes('parsePzParams')) {
+              updated = updated.replace(
+                importRegex,
+                `import {${match[1]}, parsePzParams } from '@akinon/next/utils'`
+              );
+            }
+          }
+
+          // Ensure settings import exists
+          if (
+            !updated.includes("from 'settings'") &&
+            !updated.includes('from "settings"')
+          ) {
+            const lastImportIdx = updated.lastIndexOf('\nimport ');
+            if (lastImportIdx !== -1) {
+              const lineEnd = updated.indexOf('\n', lastImportIdx + 1);
+              updated =
+                updated.slice(0, lineEnd + 1) +
+                "import settings from 'settings';\n" +
+                updated.slice(lineEnd + 1);
+            }
+          }
+
+          fs.writeFileSync(fullPath, updated);
+          updatedFiles.push(path.relative(workingDir, fullPath));
+        }
+      }
+    }
+  }
+
+  walk(path.join(workingDir, 'src'));
+  return updatedFiles;
+}
+
+function generatePzSegmentsConfig(segments, resolveHints) {
+  const lines = segments.map((name) => {
+    const hint = resolveHints[name];
+    if (hint && hint.code) {
+      return `    { name: '${name}', resolve: ${hint.code} }`;
+    }
+    if (hint && hint.source === 'unknown') {
+      return `    { name: '${name}', resolve: ({ req }) => '' /* TODO: return ${name} value */ }`;
+    }
+    return `    { name: '${name}' }`;
+  });
+  return `pzSegments: {\n    segments: [\n${lines.join(',\n')}\n    ]\n  }`;
+}
+
+const transform = () => {
+  const workingDir = path.resolve(process.cwd());
+  const appDir = path.join(workingDir, 'src', 'app');
+  const settingsPath = path.join(workingDir, 'src', 'settings.js');
+
+  if (!fs.existsSync(appDir)) {
+    console.error(red('Error: src/app/ directory not found.'));
+    process.exit(1);
+  }
+
+  const pzDir = path.join(appDir, '[pz]');
+  if (fs.existsSync(pzDir)) {
+    console.log(
+      yellow(
+        '[pz] directory already exists. Migration may have already been done.'
+      )
+    );
+    process.exit(0);
+  }
+
+  const commerceDir = path.join(appDir, '[commerce]');
+  if (!fs.existsSync(commerceDir)) {
+    console.error(red('Error: [commerce] directory not found in src/app/.'));
+    process.exit(1);
+  }
+
+  // Detect all segments by walking down the directory tree
+  const { segments, levels, contentDir } = detectSegments(commerceDir);
+
+  const customSegments = segments.filter(
+    (s) => !BUILTIN_SEGMENTS.includes(s)
+  );
+  const segmentPath = ['[commerce]', ...segments.map((s) => `[${s}]`)].join(
+    '/'
+  );
+
+  // Count entries across all levels that will be merged
+  let totalEntries = countEntries(contentDir);
+  for (const { dir, segmentChildName } of levels) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === segmentChildName) continue;
+      totalEntries++;
+      if (entry.isDirectory()) {
+        totalEntries += countEntries(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  console.log(bold('\nPZ Segment Migration'));
+  console.log('====================\n');
+  console.log(`Detected: ${yellow(segmentPath + '/')}`);
+  console.log(`Segments: ${segments.join(', ')}`);
+  if (customSegments.length > 0) {
+    console.log(
+      `Custom:   ${yellow(customSegments.join(', '))} (will be added to pzSegments)`
+    );
+  }
+  if (levels.some(({ dir, segmentChildName }) =>
+    fs.readdirSync(dir).some((f) => f !== segmentChildName)
+  )) {
+    console.log(`Note:     Intermediate levels have content, will be merged`);
+  }
+  console.log(`Target:   ${yellow('[pz]/')}`);
+  console.log(`Entries:  ${totalEntries}\n`);
+
+  // Merge all levels into [pz]/
+  console.log('Merging content into [pz]/...');
+  mergeContentIntoPz(levels, contentDir, pzDir);
+
+  // Remove legacy [commerce]/ tree
+  console.log('Removing legacy directories...');
+  fs.rmSync(commerceDir, { recursive: true, force: true });
+
+  // Update settings.js
+  if (fs.existsSync(settingsPath)) {
+    let content = fs.readFileSync(settingsPath, 'utf-8');
+
+    // Add usePzSegment: true
+    if (!content.includes('usePzSegment')) {
+      content = content.replace(/(\n};\s*$)/, ',\n  usePzSegment: true$1');
+
+      if (!content.includes('usePzSegment')) {
+        content = content.replace(/(};\s*$)/, '  usePzSegment: true,\n$1');
+      }
+    }
+
+    // Add pzSegments config if custom segments were found
+    if (customSegments.length > 0 && !content.includes('pzSegments')) {
+      const resolveHints = analyzeMiddleware(workingDir, customSegments);
+      const orderedSegments = segments.filter((s) => s !== 'commerce');
+      const pzSegmentsBlock = generatePzSegmentsConfig(
+        orderedSegments,
+        resolveHints
+      );
+
+      content = content.replace(
+        /(\n};\s*$)/,
+        `,\n  ${pzSegmentsBlock}$1`
+      );
+
+      if (!content.includes('pzSegments')) {
+        content = content.replace(
+          /(};\s*$)/,
+          `  ${pzSegmentsBlock},\n$1`
+        );
+      }
+    }
+
+    fs.writeFileSync(settingsPath, content);
+
+    console.log('Updated settings.js:');
+    console.log('  - usePzSegment: true');
+    if (customSegments.length > 0) {
+      const resolveHints = analyzeMiddleware(workingDir, customSegments);
+      console.log(
+        `  - pzSegments with segments: [${segments.filter((s) => s !== 'commerce').join(', ')}]`
+      );
+      for (const seg of customSegments) {
+        const hint = resolveHints[seg];
+        if (hint && hint.source !== 'unknown') {
+          console.log(
+            `    ${bold(seg)}: resolve from ${hint.source}`
+          );
+        } else {
+          console.log(
+            yellow(
+              `    ${seg}: resolve source unknown — fill in the resolve function manually`
+            )
+          );
+        }
+      }
+    }
+  } else {
+    console.log(
+      yellow(
+        'Warning: settings.js not found. Add usePzSegment: true manually.'
+      )
+    );
+  }
+
+  // Clean up middleware.ts rewrite block since url is now a built-in segment
+  if (segments.includes('url') || customSegments.length > 0) {
+    const cleaned = cleanupMiddleware(workingDir);
+    if (cleaned) {
+      console.log('Cleaned middleware.ts: removed rewrite block (now handled by built-in url segment)');
+    }
+  }
+
+  // Update path references in tsconfig, imports, etc.
+  const updatedFiles = updatePathReferences(workingDir, segments);
+  if (updatedFiles.length > 0) {
+    console.log(`Updated path references in ${updatedFiles.length} file(s):`);
+    updatedFiles.forEach((f) => console.log(`  - ${f}`));
+  }
+
+  // Update params.locale/currency/url usages to parsePzParams
+  const paramsUpdated = updateParamsUsage(workingDir);
+  if (paramsUpdated.length > 0) {
+    console.log(
+      `Updated params usage in ${paramsUpdated.length} file(s):`
+    );
+    paramsUpdated.forEach((f) => console.log(`  - ${f}`));
+  }
+
+  console.log(green('\nMigration completed successfully!\n'));
+  console.log('Next steps:');
+  console.log(`  1. Review changes with ${bold('git diff')}`);
+  console.log(`  2. Build with ${bold('yarn build')}`);
+  console.log('');
+};
+
+module.exports = {
+  transform
+};

package/package.json

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