@salla.sa/twilight-theme-engine 1.0.84 → 1.0.86

package/tailwind/routes/root/head.ts.txt

@@ -0,0 +1,424 @@
+import type { HeadDescriptor, HeadResult } from '../../utils/head';
+import { mergeHead, resolveHead } from '../../utils/head';
+import { buildBaseHead } from '../../utils/baseHead';
+import { FALLBACK_LOCALE } from '../../providers/locale-constants';
+import { getTwilightContext } from '../../twilight/context';
+import type { TwilightContextMatch } from '../../twilight/ensure-context';
+import { ensureTwilightContextFromMatches } from '../../twilight/ensure-context';
+import type { StoreContext } from '../../api/store';
+import type { AppSnippet } from '../../api/apps';
+import { SettingsError } from '../../utils/errors';
+import { renderAppScopeInstallScript } from '../../utils/app-scope';
+import { renderThemeHookSlotsScript } from '../../utils/theme-hook-slots';
+import { escapeForInlineScript } from '../../utils/inline-script';
+import { readEnv, renderRuntimeEnvScript } from '../../utils/runtime-env';
+
+const SALLA_ICONS_CSS_URL = 'https://cdn.assets.salla.network/static/fonts/sallaicons.css?v=2.0.5';
+const LIT_VERSION = '3.3.3';
+const LIT_CDN_BASE = `https://cdn.assets.salla.network/static/lit/${LIT_VERSION}`;
+
+/** Bare-specifier map for the lit build the engine's `<salla-*>` web components resolve against. */
+const LIT_IMPORTS: Record<string, string> = {
+  lit: `${LIT_CDN_BASE}/lit.js`,
+  'lit/': `${LIT_CDN_BASE}/`,
+  'lit-html': `${LIT_CDN_BASE}/lit-html/lit-html.js`,
+  'lit-html/': `${LIT_CDN_BASE}/lit-html/`,
+  'lit-element': `${LIT_CDN_BASE}/lit-element/lit-element.js`,
+  'lit-element/': `${LIT_CDN_BASE}/lit-element/`,
+  '@lit/reactive-element': `${LIT_CDN_BASE}/reactive-element/reactive-element.js`,
+  '@lit/reactive-element/': `${LIT_CDN_BASE}/reactive-element/`,
+};
+
+export const TICKETING_SCRIPT_URL =
+  'https://cdn.assets.salla.network/latest/@salla.sa/ui-store-ticketing-system/ticketing-system.es.js';
+
+const TWILIGHT_RELEASE_CDN = 'https://cdn.salla.network/js/twilight';
+const TWILIGHT_DEV_CDN = 'https://cdn.assets.salla.network/dev/@salla.sa/twilight';
+// The oldest Twilight release this engine works with. Raise it whenever the engine
+// starts relying on something newer; the reason lives in that commit. Today's floor:
+// components ship their own CSS, which themes no longer compile (SallaApp/twilight#2107).
+const MIN_TWILIGHT_VERSION = '2.14.538';
+// Last resort when no override and no platform pin, and the substitute for a pin below the floor.
+const DEFAULT_TWILIGHT_VERSION = '2.14.584';
+const releaseUrl = (version: string): string =>
+  `${TWILIGHT_RELEASE_CDN}/${version}/twilight.esm.js`;
+// The head is built more than once per request (early hints, then the page); say it once.
+const warnedPins = new Set<string>();
+
+/** `x.y.z` release pins only; dev shas and other strings are loaded as given. */
+function belowMinimum(version: string): boolean {
+  return (
+    /^\d+\.\d+\.\d+$/.test(version) &&
+    version.localeCompare(MIN_TWILIGHT_VERSION, undefined, { numeric: true }) < 0
+  );
+}
+
+/** The `x.y.z` release segment of a release-CDN `.../twilight.esm.js` URL, if present. */
+function releaseVersionInUrl(url: string): string | null {
+  const match = url.match(/\/(\d+\.\d+\.\d+)\/twilight\.esm\.js(?:[?#]|$)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * `VITE_TWILIGHT_URL`/`VITE_TWILIGHT_VERSION` outrank everything below, including
+ * `theme.twilight.version`'s own `belowMinimum` guard — a stale override wins
+ * silently otherwise (TD-16375: a scaffold-time pin outlived the engine raising
+ * MIN_TWILIGHT_VERSION, so every new theme rendered without component CSS and
+ * nothing said why). Only a dev-mode nudge, not a swap: an env override is a
+ * deliberate choice, so unlike the settings-pin path below this never substitutes
+ * the engine default underneath the developer.
+ */
+function warnIfOverrideBelowMinimum(source: string, version: string): void {
+  // Worker logs in production should stay quiet -- this is a developer-directed nudge,
+  // not a user-facing or production-monitored signal. import.meta.env.DEV is a static
+  // false in production builds, so this branch (and the console.warn below) is
+  // tree-shaken out entirely, same as DevSettingsWidget / dev-settings-store.ts.
+  if (!import.meta.env.DEV) return;
+  if (!belowMinimum(version)) return;
+  const key = `${source}:${version}`;
+  if (warnedPins.has(key)) return;
+  warnedPins.add(key);
+  console.warn(
+    `[twilight] ${source}=${version} is below the engine minimum ${MIN_TWILIGHT_VERSION} — components may load without their CSS (SallaApp/twilight#2107). Unset it or bump it to ${MIN_TWILIGHT_VERSION}+.`
+  );
+}
+
+/**
+ * Which twilight.esm.js the storefront loads, in priority order:
+ * 1. `VITE_TWILIGHT_URL` — full local/deployment override.
+ * 2. `VITE_TWILIGHT_VERSION` — dev-CDN build override.
+ * 3. `theme.twilight.version` from the settings endpoint — the platform-pinned
+ *    release used when no environment override is configured.
+ * 4. The engine's default release, also used when the pin is below the engine minimum.
+ */
+export function resolveTwilightSdkUrl(settings?: StoreContext): string {
+  const urlOverride = readEnv('VITE_TWILIGHT_URL');
+  if (urlOverride) {
+    const version = releaseVersionInUrl(urlOverride);
+    if (version) warnIfOverrideBelowMinimum('VITE_TWILIGHT_URL', version);
+    return urlOverride;
+  }
+
+  const versionOverride = readEnv('VITE_TWILIGHT_VERSION');
+  if (versionOverride) {
+    warnIfOverrideBelowMinimum('VITE_TWILIGHT_VERSION', versionOverride);
+    return `${TWILIGHT_DEV_CDN}/${versionOverride}/twilight.esm.js`;
+  }
+
+  const pinnedVersion = settings?.theme?.twilight?.version;
+  if (pinnedVersion && belowMinimum(pinnedVersion)) {
+    if (!warnedPins.has(pinnedVersion)) {
+      warnedPins.add(pinnedVersion);
+      console.warn(
+        `[twilight] theme.twilight.version ${pinnedVersion} is below the engine minimum ${MIN_TWILIGHT_VERSION}; loading ${DEFAULT_TWILIGHT_VERSION} instead`
+      );
+    }
+    return releaseUrl(DEFAULT_TWILIGHT_VERSION);
+  }
+  if (pinnedVersion) return releaseUrl(pinnedVersion);
+
+  return releaseUrl(DEFAULT_TWILIGHT_VERSION);
+}
+
+// On a page that preloads its LCP image, the icon font (~270 KB) applies once the first screen's
+// priority images have painted, so it doesn't compete with them; other pages swap on load.
+const MEDIA_SWAP_SCRIPT = `
+(function(){var d=document,s=function(l){if(l.sheet||"all"===l.media)l.media="all";else l.onload=function(){this.media="all"}},f=d.getElementById("salla-theme-font"),i=d.getElementById("salla-icons-css");f&&s(f);if(!i)return;if(!d.querySelector('link[rel="preload"][as="image"]'))return s(i);var g=function(){g=function(){};s(i)},p=function(){requestAnimationFrame(function(){setTimeout(function(){g()})});setTimeout(function(){g()},100)};d.addEventListener("DOMContentLoaded",function(){var m=[].filter.call(d.querySelectorAll('img[fetchpriority="high"]'),function(x){return!x.complete}),n=m.length;if(!n)return p();m.forEach(function(x){var o=function(){--n||p()};x.addEventListener("load",o,{once:!0});x.addEventListener("error",o,{once:!0})});setTimeout(function(){g()},2500)})})();
+`.trim();
+
+const LOADING_CSS = `
+.loading-overlay{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;background:#fff;z-index:9999}
+.loading-spinner{animation:spin 1s linear infinite;border-radius:9999px;height:3rem;width:3rem;border-bottom:2px solid var(--color-primary,#000)}
+@keyframes spin{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}
+html,body{margin:0;padding:0;height:100%}
+`.trim();
+
+const SALLA_INIT_SCRIPT = `
+window.salla = window.Salla = window.Salla || window.salla || {};
+window.Salla.onReady = window.Salla.onReady || function(callback) {
+  return new Promise(function(resolve) {
+    if (window.Salla.status === 'ready') {
+      var config = window.salla && window.salla.config && window.salla.config.all();
+      resolve(callback ? callback(config) : config);
+    } else {
+      window.addEventListener('twilight::initiated', function(event) {
+        resolve(callback ? callback(event.detail) : event.detail);
+      }, { once: true });
+    }
+  });
+};
+`.trim();
+
+/**
+ * Distinct snippet-host origins to `preconnect` (warm DNS/TCP/TLS during parse). From the real
+ * URLs (dev/prod-correct), deduped and capped at 4. No `crossOrigin`: snippets are no-cors fetches.
+ */
+export function snippetPreconnectOrigins(snippets: readonly AppSnippet[] | undefined): string[] {
+  if (!snippets?.length) return [];
+  const origins = new Set<string>();
+  for (const app of snippets) {
+    if (app.status !== 'enabled') continue;
+    for (const s of app.snippets) {
+      if (!s.url) continue;
+      try {
+        origins.add(new URL(s.url).origin);
+      } catch {
+        /* skip a malformed snippet url rather than breaking the head */
+      }
+      if (origins.size >= 4) return [...origins];
+    }
+  }
+  return [...origins];
+}
+
+export function rootHead(ctx: {
+  params: Record<string, string>;
+  matches?: readonly TwilightContextMatch[];
+}): HeadResult {
+  // Re-run on the client during hydration, where the twilight module store may
+  // still be empty. Recover it from the resolved match context so the head is
+  // built from real settings instead of falling through to 'Store Unavailable'.
+  ensureTwilightContextFromMatches(ctx.matches);
+
+  let settings: StoreContext | undefined;
+  try {
+    settings = getTwilightContext().settings;
+  } catch (e) {
+    if (e instanceof SettingsError) {
+      return resolveHead({
+        title: 'Store Unavailable',
+      });
+    }
+    throw e;
+  }
+  const locale = ctx.params.locale || FALLBACK_LOCALE;
+  const parts = deriveHeadParts(settings);
+
+  return resolveHead(
+    mergeHead(buildBaseHead(settings, locale), {
+      meta: buildRootMeta(parts),
+      links: buildRootLinks(parts),
+      styles: buildRootStyles(parts),
+      importMap: [{ imports: LIT_IMPORTS }],
+      scripts: buildRootScripts(parts),
+    })
+  );
+}
+
+/** Everything the root head's tag builders read, derived once from the store settings. */
+interface RootHeadParts {
+  store: StoreContext['store'] | undefined;
+  favicon?: string;
+  primaryColor?: string;
+  fontUrl?: string;
+  fontUrlWithDisplay?: string;
+  isGoogleFont?: boolean;
+  fontFamilyName?: string;
+  customJs?: string;
+  customCss?: string;
+  isCustomCssUrl?: boolean;
+  isCustomJsUrl?: boolean;
+  twilightSdkUrl: string;
+  snippetPreconnects: Array<{ rel: 'preconnect'; href: string }>;
+  appScopeInstallScript: string;
+  themeHookSlotsScript: string | null;
+  runtimeEnvScript: string | null;
+}
+
+/** Google Fonts only honours `display=swap` as a query param; other hosts get the @font-face
+ *  override instead (see buildRootStyles). */
+function deriveFontParts(theme?: StoreContext['theme']) {
+  const font = theme?.font;
+  const fontUrl = font?.url || font?.path;
+  const isGoogleFont = fontUrl?.includes('fonts.googleapis.com');
+  const needsDisplay = Boolean(isGoogleFont && fontUrl && !fontUrl.includes('display='));
+  const separator = fontUrl?.includes('?') ? '&' : '?';
+
+  return {
+    fontUrl,
+    isGoogleFont,
+    fontFamilyName: font?.family_name,
+    fontUrlWithDisplay: needsDisplay ? `${fontUrl}${separator}display=swap` : fontUrl,
+  };
+}
+
+/** Theme customization JS/CSS, each either a URL to load or an inline blob to embed. */
+function deriveCustomizationParts(theme?: StoreContext['theme']) {
+  const customization = theme?.customization;
+  const customJs = customization?.js?.trim();
+  const customCss = customization?.css?.trim();
+  const isUrl = (value?: string): boolean =>
+    Boolean(value?.startsWith('http') || value?.startsWith('//'));
+
+  return {
+    customJs,
+    customCss,
+    isCustomCssUrl: isUrl(customCss),
+    isCustomJsUrl: isUrl(customJs),
+  };
+}
+
+function deriveHeadParts(settings?: StoreContext): RootHeadParts {
+  const store = settings?.store;
+
+  return {
+    store,
+    favicon: store?.icon,
+    primaryColor: settings?.theme?.color?.primary,
+    ...deriveFontParts(settings?.theme),
+    ...deriveCustomizationParts(settings?.theme),
+    twilightSdkUrl: resolveTwilightSdkUrl(settings),
+    // Warm the connection to the snippet host(s) during head parse, so the body's deferred
+    // `<script src>` snippet tags fetch off an already-open socket instead of DNS+TCP+TLS.
+    snippetPreconnects: snippetPreconnectOrigins(getTwilightContext().appsSnippets).map((href) => ({
+      rel: 'preconnect' as const,
+      href,
+    })),
+    // Install `Salla.appScope` inline at parse time, before the SDK is ready — else a snippet's
+    // onReady callback calls it too early and throws. Always emitted, even when the settings
+    // prefetch failed: the CDN snippet tags ship regardless (they come from the *snippets*
+    // endpoint), so the factory has to exist for them. `installAppScope` then seeds the real
+    // buckets into this install once the client query resolves.
+    appScopeInstallScript: renderAppScopeInstallScript(
+      getTwilightContext().appsSettings ?? { apps: {} }
+    ),
+    // Whitelist the theme's own hook slots at parse time too, for the same reason: apps register
+    // their `onReady` callbacks from parser-inserted snippet tags, long before React hydrates.
+    themeHookSlotsScript: renderThemeHookSlotsScript(),
+    // Env this render resolved (worker `vars` live in server-only `process.env`), handed to the
+    // client so it doesn't silently fall back to the production defaults. Re-rendered on the
+    // client during hydration, where it resolves to the same values or to nothing.
+    runtimeEnvScript: renderRuntimeEnvScript(),
+  };
+}
+
+function buildRootMeta(p: RootHeadParts): NonNullable<HeadDescriptor['meta']> {
+  return [
+    { name: 'robots', content: 'index, follow' },
+    { name: 'msapplication-TileColor', content: '#ffffff' },
+    ...(p.favicon ? [{ name: 'msapplication-TileImage', content: p.favicon }] : []),
+    ...(p.primaryColor
+      ? [
+          { name: 'theme-color', content: p.primaryColor },
+          { name: 'msapplication-navbutton-color', content: p.primaryColor },
+          { name: 'apple-mobile-web-app-status-bar-style', content: p.primaryColor },
+        ]
+      : []),
+  ];
+}
+
+function buildRootLinks(p: RootHeadParts): NonNullable<HeadDescriptor['links']> {
+  return [
+    { rel: 'preconnect', href: 'https://api.salla.dev' },
+    { rel: 'preconnect', href: 'https://cdn.salla.sa' },
+    { rel: 'preconnect', href: 'https://cdn.assets.salla.network', crossOrigin: 'anonymous' },
+    // Warm the installed apps' CDN snippet host(s) — see snippetPreconnectOrigins.
+    ...p.snippetPreconnects,
+    ...(p.fontUrl
+      ? [
+          {
+            rel: 'preconnect' as const,
+            href: 'https://fonts.gstatic.com',
+            crossOrigin: 'anonymous' as const,
+          },
+        ]
+      : []),
+    { rel: 'modulepreload', href: p.twilightSdkUrl },
+    ...(p.fontUrlWithDisplay
+      ? [
+          {
+            id: 'salla-theme-font',
+            rel: 'stylesheet',
+            href: p.fontUrlWithDisplay,
+            media: 'print',
+          },
+        ]
+      : []),
+    ...(p.fontUrlWithDisplay && !p.isGoogleFont && p.fontFamilyName
+      ? [
+          {
+            id: 'salla-font-display-override',
+            rel: 'preload',
+            as: 'style',
+            href: p.fontUrlWithDisplay,
+          },
+        ]
+      : []),
+    ...(p.favicon ? [{ rel: 'icon', href: p.favicon }] : []),
+    ...(p.favicon
+      ? [{ id: 'salla-apple-icon', rel: 'apple-touch-icon-precomposed', href: p.favicon }]
+      : []),
+    ...(p.isCustomCssUrl && p.customCss
+      ? [{ id: 'salla-custom-css', rel: 'stylesheet', href: p.customCss }]
+      : []),
+    {
+      id: 'salla-icons-css',
+      rel: 'stylesheet',
+      href: SALLA_ICONS_CSS_URL,
+      media: 'print',
+    },
+    // {
+    //   id: 'intl-tel-input-css',
+    //   rel: 'stylesheet',
+    //   href: 'https://cdn.jsdelivr.net/npm/intl-tel-input@26.8.0/build/css/intlTelInput.css',
+    // },
+    ...(p.isCustomJsUrl && p.customJs
+      ? [{ id: 'salla-custom-js-preload', rel: 'preload', as: 'script', href: p.customJs }]
+      : []),
+  ];
+}
+
+// Hoistable (href + precedence): the web components insert their own <style> near the top of
+// <head> before hydration, which a positionally hydrated <style> would be matched against.
+const hoisted = (id: string, children: string) => ({
+  id,
+  href: id,
+  precedence: 'default',
+  children,
+});
+
+function buildRootStyles(p: RootHeadParts): NonNullable<HeadDescriptor['styles']> {
+  return [
+    hoisted('twilight-loading', LOADING_CSS),
+    ...(!p.isGoogleFont && p.fontFamilyName
+      ? [
+          hoisted(
+            'salla-font-display-swap',
+            `@font-face{font-family:"${p.fontFamilyName}";font-display:swap;src:local("${p.fontFamilyName}")}`
+          ),
+        ]
+      : []),
+    ...(!p.isCustomCssUrl && p.customCss ? [hoisted('salla-custom-css', p.customCss)] : []),
+  ];
+}
+
+function buildRootScripts(p: RootHeadParts): NonNullable<HeadDescriptor['scripts']> {
+  return [
+    // First: the API base / store identifier this render used, so the hydrated client
+    // resolves the same ones (worker `vars` never reach the browser bundle on their own).
+    ...(p.runtimeEnvScript ? [{ id: 'salla-runtime-env', children: p.runtimeEnvScript }] : []),
+    { id: 'twilight-init', children: SALLA_INIT_SCRIPT },
+    // After twilight-init (which defines window.Salla) and before the SDK module, so the
+    // appScope factory exists ahead of any snippet's onReady callback firing.
+    { id: 'salla-app-scope', children: p.appScopeInstallScript },
+    // Arms the hook-slot whitelist push here, so its `twilight::initiated` listener is
+    // registered before any app snippet's — listeners fire in registration order.
+    ...(p.themeHookSlotsScript
+      ? [{ id: 'salla-theme-hook-slots', children: p.themeHookSlotsScript }]
+      : []),
+    { id: 'salla-async-css', children: MEDIA_SWAP_SCRIPT },
+    // The SDK and ticketing modules are rendered at the end of <body> (SallaSdkScripts).
+    ...(p.customJs ? [buildCustomJsScript(p.customJs, Boolean(p.isCustomJsUrl))] : []),
+  ];
+}
+
+/** A URL customization is loaded after SDK init; an inline one is wrapped so a syntax/runtime
+ *  error in partner JS warns instead of taking the page down. */
+function buildCustomJsScript(customJs: string, isUrl: boolean) {
+  return {
+    id: 'salla-custom-js',
+    children: isUrl
+      ? `window.addEventListener('twilight::initiated',function(){var s=document.createElement('script');s.src=${escapeForInlineScript(JSON.stringify(customJs))};s.async=true;document.head.appendChild(s)},{once:true});`
+      : `try { ${customJs} } catch(e) { console.warn("[ThemeCustomization] Custom JS error:", e); }`,
+  };
+}

package/tailwind/routes/root/index.ts.txt

@@ -0,0 +1,2 @@
+export { rootHead } from './head';
+export { rootBeforeLoad, type BeforeLoadResult } from './beforeLoad';

package/tailwind/routes/seo-redirects.ts.txt

@@ -0,0 +1,82 @@
+import { useEffect } from 'react';
+import { redirect } from '../providers/NavigationProvider';
+import { FALLBACK_LOCALE } from '../providers/locale-constants';
+import { clearAuthTokenCookie } from '../utils/cookies';
+
+export interface SlugBrandParams {
+  /** SEO slug segment (ignored — only here to match the route pattern). */
+  slug: string;
+  /** Brand numeric ID to redirect to. */
+  id: string;
+  /** Active locale from the `/$locale` parent layout (e.g. `'ar'`, `'en'`). */
+  locale?: string;
+}
+
+export async function slugBrandRedirectLoader(ctx: { params: SlugBrandParams }): Promise<never> {
+  const locale = ctx.params.locale || FALLBACK_LOCALE;
+  throw redirect(`/${locale}/brands/${ctx.params.id}`);
+}
+
+export interface PendingOrdersRedirectParams {
+  /** Active locale from the `/$locale` parent layout (e.g. `'ar'`, `'en'`). */
+  locale?: string;
+}
+
+export async function pendingOrdersRedirectLoader(
+  ctx: { params: PendingOrdersRedirectParams } = { params: {} }
+): Promise<never> {
+  const locale = ctx.params.locale || FALLBACK_LOCALE;
+  throw redirect(`/${locale}/account/orders?status=pending`);
+}
+
+/** `/account/rating`: the loyalty "rate your orders" link. Twig Raed has no rating page and sends it to the orders list. */
+export async function ratingRedirectLoader(
+  ctx: { params: PendingOrdersRedirectParams } = { params: {} }
+): Promise<never> {
+  const locale = ctx.params.locale || FALLBACK_LOCALE;
+  throw redirect(`/${locale}/account/orders`);
+}
+
+/** A Twig customer URL (`/profile`, `/orders`, …) kept working as its `/account/…` page. */
+export async function accountRedirectLoader(ctx: {
+  params: PendingOrdersRedirectParams;
+  page: string;
+  /** The incoming query string (`?status=pending`), kept on the account page. */
+  search?: string;
+}): Promise<never> {
+  // No locale in the URL stays without one: the locale layout adds it only where the store has several.
+  const prefix = ctx.params.locale ? `/${ctx.params.locale}` : '';
+  throw redirect(`${prefix}/account/${ctx.page}${ctx.search ?? ''}`, { statusCode: 301 });
+}
+
+/** `/latest-products`, `/most-sales-products` and `/offers` now live at `/products?source=`. */
+export async function productsSourceRedirectLoader(ctx: {
+  params: PendingOrdersRedirectParams;
+  source: 'latest' | 'sales' | 'offers';
+  search?: string;
+}): Promise<never> {
+  const prefix = ctx.params.locale ? `/${ctx.params.locale}` : '';
+  const query = new URLSearchParams(ctx.search);
+  query.delete('source');
+  const rest = query.toString();
+  throw redirect(`${prefix}/products?source=${ctx.source}${rest ? `&${rest}` : ''}`, {
+    statusCode: 301,
+  });
+}
+
+/**
+ * `/logout` — where the SDK sends the browser once `salla.auth.logout()` has run
+ * (`salla.url.get('logout?from=…')`). The Twig storefront serves that URL server-side. Here
+ * it renders nothing and, in the browser, removes the theme's own `token` cookie (the SDK's
+ * `cookie.clearAll()` leaves it) and then does a full navigation home. It has to be a
+ * component, not a loader redirect: a loader runs during server rendering, where the cookie
+ * can't be cleared, so the redirect would leave the visitor signed in on the next request.
+ */
+export function LogoutRedirect(): null {
+  useEffect(() => {
+    clearAuthTokenCookie();
+    // `/{store base}/{locale}/logout?from=…` → `/{store base}/{locale}`
+    window.location.replace(window.location.href.replace(/\/logout\/?(\?[^#]*)?(#.*)?$/, ''));
+  }, []);
+  return null;
+}

package/tailwind/routes/testimonials/ReviewsPage.tsx.txt

@@ -0,0 +1,12 @@
+import { SallaReviewsPage } from '@salla.sa/twilight-components-react/reviews-page';
+import type { ReviewsPageProps } from './types';
+import { Breadcrumb } from '../../components/common';
+
+export function ReviewsPage({ page }: ReviewsPageProps) {
+  return (
+    <div className="container mb-20">
+      <Breadcrumb page={page} />
+      <SallaReviewsPage />
+    </div>
+  );
+}

package/tailwind/routes/testimonials/TestimonialsPage.tsx.txt

@@ -0,0 +1,80 @@
+import { useState, useEffect } from 'react';
+import { SallaComments } from '@salla.sa/twilight-components-react/comments';
+import { useTranslation } from '../../providers/I18nProvider';
+import { useComments } from '../../hooks/useComments';
+import type { TestimonialsPageProps } from './types';
+import { Breadcrumb } from '../../components/common';
+
+const buildSortOptions = (t: (key: string, fb: string) => string) => [
+  { id: 'latest', label: t('pages.testimonials.sort_by_date_desc', 'Latest') },
+  { id: 'oldest', label: t('pages.testimonials.sort_by_date_asc', 'Oldest') },
+  {
+    id: 'top_rating',
+    label: t('pages.testimonials.sort_by_rating_desc', 'Top rated'),
+  },
+  {
+    id: 'bottom_rating',
+    label: t('pages.testimonials.sort_by_rating_asc', 'Low rated'),
+  },
+];
+
+export function TestimonialsPage({ page }: TestimonialsPageProps) {
+  const { t } = useTranslation();
+  const { commentsKey } = useComments();
+
+  // Sync sort state with URL
+  const [selectedSort, setSelectedSort] = useState(() => {
+    const params = new URLSearchParams(window.location.search);
+    return params.get('sort') || 'latest';
+  });
+
+  // Update URL when sort changes
+  useEffect(() => {
+    const url = new URL(window.location.href);
+    url.searchParams.set('sort', selectedSort);
+    window.history.replaceState(null, '', url.toString());
+  }, [selectedSort]);
+
+  return (
+    <div className="container">
+      <Breadcrumb page={page} />
+
+      <div className="flex justify-center">
+        <div className="w-full lg:w-10/12 bg-white rounded p-6 lg:p-8 mt-4 lg:mt-12">
+          <div className="mb-4 sm:mb-6 flex justify-between items-center">
+            <h1 className="font-bold text-2xl">{page.title}</h1>
+            <div className="flex items-center">
+              <label
+                className="hidden sm:block rtl:ml-3 ltr:mr-3 whitespace-nowrap"
+                htmlFor="testimonials-filter"
+              >
+                {t('pages.categories.sorting', 'Sort by')}
+              </label>
+              <select
+                id="testimonials-filter"
+                className="form-input pt-0 pb-1 rtl:pl-10 ltr:pr-10 bg-white text-gray-900"
+                value={selectedSort}
+                onChange={(e) => setSelectedSort(e.target.value)}
+              >
+                {buildSortOptions(t).map((opt) => (
+                  <option key={opt.id} value={opt.id}>
+                    {opt.label}
+                  </option>
+                ))}
+              </select>
+            </div>
+          </div>
+
+          {/* Key prop forces reload when sort changes or new comment added */}
+          <SallaComments
+            key={`${selectedSort}-${commentsKey}`}
+            testimonials
+            // drifted wrapper types require itemId; testimonials mode has none
+            itemId={undefined as never}
+            sort={selectedSort as any}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/tailwind/routes/testimonials/index.tsx.txt

@@ -0,0 +1,80 @@
+import type { HeadDescriptor } from '../../utils/head';
+import { buildHreflangAlternates } from '../../utils/baseHead';
+import { lazy } from 'react';
+import { reviewsLoader, testimonialsLoader } from './loader';
+import type { ReviewsPageProps, TestimonialsPageProps } from './types';
+import type { TwilightContext } from '../../twilight/context';
+import { RouteId } from '../../router/route-ids';
+
+// Lazy-load component for code-splitting
+const LazyTestimonialsPage = lazy(() =>
+  import('./TestimonialsPage').then((m) => ({ default: m.TestimonialsPage }))
+);
+
+const LazyReviewsPage = lazy(() =>
+  import('./ReviewsPage').then((m) => ({ default: m.ReviewsPage }))
+);
+
+export const TestimonialsPage = LazyTestimonialsPage;
+export const ReviewsPage = LazyReviewsPage;
+export { reviewsLoader, testimonialsLoader } from './loader';
+export type { ReviewsPageProps, TestimonialsPageProps } from './types';
+
+async function loader(
+  ctx: { locale?: string },
+  extend?: (
+    data: TestimonialsPageProps,
+    ctx: { params: Record<string, never> }
+  ) => Promise<Record<string, unknown>> | Record<string, unknown>
+): Promise<TestimonialsPageProps> {
+  const data = await testimonialsLoader({ locale: ctx.locale ?? 'ar' });
+
+  if (extend) {
+    const extra = await extend(data, { params: {} });
+    return { ...data, ...extra } as TestimonialsPageProps;
+  }
+  return data;
+}
+
+function head(ctx: TwilightContext, data: TestimonialsPageProps): HeadDescriptor {
+  const base: HeadDescriptor = {
+    title: data.page.title,
+    description: data.page.description,
+    alternateLanguages: buildHreflangAlternates(ctx.settings, ctx.location.pathname),
+  };
+
+  return base;
+}
+
+export const Testimonials = {
+  id: RouteId.TESTIMONIALS,
+  loader,
+  head,
+  Component: LazyTestimonialsPage,
+} as const;
+
+async function loadReviews(
+  _ctx?: { locale?: string },
+  extend?: (
+    data: ReviewsPageProps,
+    ctx: { params: Record<string, never> }
+  ) => Promise<Record<string, unknown>> | Record<string, unknown>
+): Promise<ReviewsPageProps> {
+  const data = await reviewsLoader();
+
+  if (extend) {
+    const extra = await extend(data, { params: {} });
+    return { ...data, ...extra } as ReviewsPageProps;
+  }
+  return data;
+}
+
+export const Reviews = {
+  id: RouteId.REVIEWS,
+  loader: loadReviews,
+  head: (ctx: TwilightContext, data: ReviewsPageProps): HeadDescriptor => ({
+    title: data.page.title,
+    alternateLanguages: buildHreflangAlternates(ctx.settings, ctx.location.pathname),
+  }),
+  Component: LazyReviewsPage,
+} as const;