orionplace-svelte 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionplace-svelte",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "SvelteKit 2 storefront for your Orionplace marketplace: setup CLI, server API gateway, typed store and ready-made catalog, cart, checkout and account components in English and Russian, plus an Android app build.",
   "type": "module",
   "license": "MIT",

package/runtime/marketplace.d.mts

@@ -37,6 +37,18 @@ export declare function marketplacePublicOrigin(
   tenantDomain?: string,
 ): string;
 
+export declare function noindexPathPrefixes(value?: string): string[];
+
+export declare function marketplaceNoindexPath(
+  pathname: string,
+  value?: string,
+): boolean;
+
+export declare function sitemapIndexedPages(
+  pages: MarketplaceSitemapPage[],
+  value?: string,
+): MarketplaceSitemapPage[];
+
 export declare function marketplaceRobots(origin: string): string;
 
 export declare function marketplaceRobotsResponse(

package/runtime/marketplace.mjs

@@ -329,6 +329,7 @@ export async function forwardMarketplace(request, configuration = {}) {
 // node_modules/.cache/orionplace/sitemaps/<domain>.json (ORIONPLACE_CACHE_DIR
 // moves it). "orionplace-<framework> sitemap rebuild" rebuilds that file at
 // once; the running storefront serves the new file without a restart.
+// Paths in ORIONPLACE_NOINDEX_PATHS are left out when the sitemap is served.
 
 export const SITEMAP_LIFETIME = 60 * 60 * 1000;
 const sitemapPageSize = 100;
@@ -353,6 +354,34 @@ export function marketplacePublicOrigin(request, tenantDomain = '') {
   return local || !tenantDomain ? url.origin : `https://${tenantDomain}`;
 }
 
+/**
+ * Pages kept out of search engines: ORIONPLACE_NOINDEX_PATHS lists path
+ * prefixes separated by spaces or commas, for example "/catalog /category
+ * /product" on a demo or staging storefront. Those pages answer with
+ * `X-Robots-Tag: noindex, follow` and the sitemap leaves them out. Empty
+ * (the default) keeps every public page indexable.
+ */
+export function noindexPathPrefixes(value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  return String(value ?? '')
+    .split(/[\s,]+/)
+    .map((item) => item.trim().replace(/\/+$/, ''))
+    .filter((item) => /^\/[A-Za-z0-9._~\/-]+$/.test(item));
+}
+
+/** Whether a page path is kept out of search engines (see noindexPathPrefixes). */
+export function marketplaceNoindexPath(pathname, value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  const path = String(pathname ?? '');
+  return noindexPathPrefixes(value)
+    .some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+
+/** The sitemap pages search engines may index. */
+export function sitemapIndexedPages(pages, value = environment.ORIONPLACE_NOINDEX_PATHS) {
+  return noindexPathPrefixes(value).length
+    ? pages.filter((page) => !marketplaceNoindexPath(page.path, value))
+    : pages;
+}
+
 /** @param {string} origin */
 export function marketplaceRobots(origin) {
   return `User-agent: *\nDisallow: /api/\nAllow: /\n\nSitemap: ${origin}/sitemap.xml\n`;
@@ -618,7 +647,7 @@ async function buildMarketplaceSitemap(tenant) {
 /** How many <url> entries a built sitemap has. */
 export function sitemapUrlCount(sitemap) {
   let count = 0;
-  for (const page of sitemap.pages) {
+  for (const page of sitemapIndexedPages(sitemap.pages)) {
     const own = page.locales
       ? sitemap.locales.filter((code) => page.locales.includes(code))
       : sitemap.locales;
@@ -776,7 +805,7 @@ export async function marketplaceSitemapResponse(request, configuration = {}) {
     }
   }
   const origin  = marketplacePublicOrigin(request, tenant.domain);
-  return new Response(marketplaceSitemapXml(origin, sitemap.pages, sitemap.locales), {
+  return new Response(marketplaceSitemapXml(origin, sitemapIndexedPages(sitemap.pages), sitemap.locales), {
     headers: {
       'Content-Type': 'application/xml; charset=utf-8',
       'Cache-Control': 'public, max-age=3600',

package/src/project-readme.mjs

@@ -397,6 +397,12 @@ npx orionplace-svelte sitemap rebuild shop.example.com  # one domain
 npx orionplace-svelte sitemap status                  # when each was built
 \`\`\`
 
+To keep a demo or staging storefront's shop pages out of search engines, set
+\`ORIONPLACE_NOINDEX_PATHS\` in \`.env\` to path prefixes separated by spaces,
+for example \`ORIONPLACE_NOINDEX_PATHS="/catalog /category /product"\`. Those
+pages answer with \`X-Robots-Tag: noindex, follow\` and the sitemap leaves them
+out; the journal and other pages stay indexable. Leave it empty on a live shop.
+
 This setup does not add analytics.
 
 ## Android app

package/templates/src/hooks.server.ts

@@ -1,4 +1,6 @@
 import type { Handle } from '@sveltejs/kit';
+import { env } from '$env/dynamic/private';
+import { marketplaceNoindexPath } from '@orionplace-runtime/marketplace.mjs';
 
 function escapeAttribute(value: string) {
   return value
@@ -30,6 +32,12 @@ export const handle: Handle = async ({ event, resolve }) => {
     response.headers.set('Cache-Control', 'private, no-store');
     response.headers.set('Vary', 'Host, X-Forwarded-Host, X-Front-Domain');
   }
+  // Pages under ORIONPLACE_NOINDEX_PATHS stay out of search engines.
+  if (
+    marketplaceNoindexPath(event.url.pathname, env.ORIONPLACE_NOINDEX_PATHS)
+  ) {
+    response.headers.set('X-Robots-Tag', 'noindex, follow');
+  }
   // A page rendered while Application Load failed is the 503 error page.
   if (
     event.locals.orionplaceUnavailable &&

package/templates/src/lib/components/orionplace/catalog/StorefrontCatalog.svelte

@@ -171,7 +171,7 @@
               onclick={() => openBranch(item.id)}
               class={['op-feature-button px-3!']}
             >
-              {labels.value.categories} →
+              {labels.value.categories} <span aria-hidden="true">→</span>
             </button>
           {/if}
           <a
@@ -184,7 +184,7 @@
               'op-feature-link op-feature-button op-feature-primary px-3!',
             ]}
           >
-            {labels.value.products} →
+            {labels.value.products} <span aria-hidden="true">→</span>
           </a>
         </li>
       {/each}

package/templates/src/lib/composables/useOrionplacePageSeo.svelte.ts

@@ -1,7 +1,14 @@
+import { page as currentPage } from '$app/state';
+import { browser } from '$app/environment';
 import { computed, toValue } from '@/lib/orionplace/reactivity.svelte';
 import type { MaybeRefOrGetter } from '@/lib/orionplace/reactivity.svelte';
-import { useSeoMeta } from '@/lib/orionplace/navigation.svelte';
-import { storefrontPageMetadata } from '@/lib/utils/orionplace/pageSeo';
+import { useHead, useSeoMeta } from '@/lib/orionplace/navigation.svelte';
+import {
+  storefrontAbsoluteUrl,
+  storefrontCanonicalUrl,
+  storefrontPageMetadata,
+  storefrontPublicOrigin,
+} from '@/lib/utils/orionplace/pageSeo';
 import type { StorefrontSeoPage } from '@/lib/utils/orionplace/pageSeo';
 
 export function useOrionplacePageSeo(
@@ -15,24 +22,42 @@ export function useOrionplacePageSeo(
     image?: MaybeRefOrGetter<string | undefined>;
   } = {},
 ) {
-  const metadata = computed(() =>
+  // The address the visitor used: the proxy's host during the server render.
+  const origin    = browser
+    ? window.location.origin
+    : storefrontPublicOrigin(currentPage.url.host);
+  const metadata  = computed(() =>
     storefrontPageMetadata(toValue(page), toValue(locale), {
       title: toValue(values.title),
       description: toValue(values.description),
       keywords: toValue(values.keywords),
     }),
   );
+  const canonical = computed(() =>
+    storefrontCanonicalUrl(
+      origin,
+      currentPage.url.pathname,
+      currentPage.url.search,
+      toValue(locale),
+      toValue(values.robots),
+    ),
+  );
 
   // Link previews use the same title and description as the page; the
-  // image is the record's first picture when the page has one.
-  const seo      = {
+  // image is the record's first picture when the page has one, as a
+  // complete address.
+  const seo       = {
     title: () => metadata.value.title,
     description: () => metadata.value.description,
     keywords: () => metadata.value.keywords,
     robots: () => toValue(values.robots),
     ogTitle: () => metadata.value.title,
     ogDescription: () => metadata.value.description,
-    ogImage: () => toValue(values.image) || undefined,
+    ogImage: () => storefrontAbsoluteUrl(toValue(values.image), origin),
+    ogUrl: () => canonical.value,
   };
   useSeoMeta(seo);
+  useHead(() => ({
+    link: canonical.value ? [{ rel: 'canonical', href: canonical.value }] : [],
+  }));
 }

package/templates/src/lib/composables/useOrionplaceProductSearch.svelte.ts

@@ -6,6 +6,10 @@ import {
   watch,
 } from '@/lib/orionplace/reactivity.svelte';
 import type { MaybeRefOrGetter } from '@/lib/orionplace/reactivity.svelte';
+import { browser } from '$app/environment';
+import { replaceState } from '$app/navigation';
+import { page as currentPage } from '$app/state';
+import { routeHref } from '@/lib/orionplace/navigation.svelte';
 import { useOrionplaceStore } from '@/lib/stores/orionplace.svelte';
 import { useOrionplaceApi } from '@/lib/composables/useOrionplaceApi.svelte';
 import { useOrionplaceProgress } from '@/lib/composables/useOrionplaceProgress.svelte';
@@ -25,6 +29,12 @@ import type {
 } from '@/lib/interfaces/orionplace/products/IProduct';
 import type { IProductSearchFacets } from '@/lib/interfaces/orionplace/products/IProductSearchFacets';
 import type { OrionplaceFeatureApi } from '@/lib/composables/useOrionplaceFeature.svelte';
+import {
+  productListLocationFromQuery,
+  productListLocationQuery,
+  sameProductListLocation,
+} from '@/lib/utils/orionplace/productListLocation';
+import type { ProductListLocation } from '@/lib/utils/orionplace/productListLocation';
 
 export type ProductSearchData = IProductSearchFacets & {
   products: { data: IProduct[]; rpag?: IProductPagination };
@@ -42,10 +52,28 @@ export type ProductSearchContext = ProductSearchScope & { categoryId?: number };
  */
 export interface ProductSearchSnapshot {
   scope: string;
+  // The page and filters it was loaded with; see productListLocation.
+  list?: string;
   productIds: number[];
   rpag?: IProductPagination;
 }
 
+const firstListPage: ProductListLocation = { page: 1, filters: {} };
+
+function listSignature(location: ProductListLocation) {
+  return JSON.stringify(productListLocationQuery({}, location));
+}
+
+// The browser reads the address bar: a shallow replaceState (below) does not
+// update `page.url`.
+function addressQuery(): Record<string, string> {
+  return Object.fromEntries(
+    browser
+      ? new URL(window.location.href).searchParams
+      : currentPage.url.searchParams,
+  );
+}
+
 type OrionplaceStore = ReturnType<typeof useOrionplaceStore>;
 
 /**
@@ -57,6 +85,7 @@ export function productSearchBody(
   store: OrionplaceStore,
   scope: ProductSearchContext,
   page: number,
+  filters = store.searchFilters,
 ) {
   const category =
     scope.categoryId === undefined
@@ -72,7 +101,7 @@ export function productSearchBody(
 
   if (scope.categoryId !== undefined) {
     return category
-      ? categorySearchRequest(category, store.searchFilters, page)
+      ? categorySearchRequest(category, filters, page)
       : undefined;
   }
 
@@ -80,7 +109,35 @@ export function productSearchBody(
     return undefined;
   }
 
-  return scopedSearchRequest(scope, store.searchFilters, page);
+  return scopedSearchRequest(scope, filters, page);
+}
+
+/**
+ * A list opened from its URL (Back, a reload) on a later page or with
+ * filters gets only the filtered choices, or none after the first page.
+ * Without stored choices for the scope this also asks for the unfiltered
+ * first page, so the filter panel keeps every seller, price and option to
+ * choose from. The extra request is only for the panel: when it fails the
+ * panel shows the choices of the result.
+ */
+async function preserveFullSearchFacets(
+  store: OrionplaceStore,
+  scope: ProductSearchContext,
+  page: number,
+  requestData: (body: Record<string, unknown>) => Promise<ProductSearchData>,
+) {
+  const needed = page > 1 || Object.keys(store.searchFilters).length > 0;
+  const body   = needed && !store.searchFacets
+    ? productSearchBody(store, scope, 1, {})
+    : undefined;
+
+  if (!body) {
+    return;
+  }
+  const full = await requestData(body).catch(() => undefined);
+  if (full && !store.searchFacets) {
+    store.preserveSearchFacets(full);
+  }
 }
 
 /** Stores the returned products and keeps the scope's first filter choices. */
@@ -98,24 +155,34 @@ export function storeProductSearchPage(
 }
 
 /**
- * Loads the first result page during a server render, with the filters
- * currently in the store. Returns null when the scope cannot be searched.
+ * Loads a result page during a server render: the page and filters of the
+ * address (`location`, the first page by default), so a reload shows the
+ * list the visitor left. Returns null when the scope cannot be searched.
  */
 export async function loadProductSearchSnapshot(
   api: Pick<OrionplaceFeatureApi, 'request'>,
   store: OrionplaceStore,
   scope: ProductSearchContext,
+  location: ProductListLocation = firstListPage,
 ): Promise<ProductSearchSnapshot | null> {
-  const body = productSearchBody(store, scope, 1);
+  store.setSearchFilters(location.filters);
+  const body = productSearchBody(store, scope, location.page);
 
   if (!body) {
     return null;
   }
 
-  const data = await api.request<ProductSearchData>('products_search', body);
+  // Both requests run together; the full choices are kept first.
+  const [data] = await Promise.all([
+    api.request<ProductSearchData>('products_search', body),
+    preserveFullSearchFacets(store, scope, location.page, (full) =>
+      api.request<ProductSearchData>('products_search', full),
+    ),
+  ]);
 
   return {
     scope: JSON.stringify(scope),
+    list: listSignature(location),
     productIds: storeProductSearchPage(store, data),
     rpag: data.products.rpag,
   };
@@ -131,24 +198,40 @@ export function useOrionplaceProductSearch(
     scrollToTop?: boolean;
     // The first page from the server render; see useOrionplaceServerData.
     initial?: ProductSearchSnapshot | null;
+    // `false` keeps the page and filters out of the URL.
+    rememberInAddress?: boolean;
   } = {},
 ) {
   const store       = useOrionplaceStore();
+  const remember    = options.rememberInAddress !== false;
   const api         = options.request ? undefined : useOrionplaceApi();
   const requestData =
     options.request ??
     ((body, signal) =>
       api!.request<ProductSearchData>('products_search', body, signal));
-  // The server result is used only for the scope it was loaded for.
+  // The page and filters in the URL: Back from a product or a reload opens
+  // the list the visitor left.
+  function addressLocation(): ProductListLocation {
+    return remember ? productListLocationFromQuery(addressQuery()) : firstListPage;
+  }
+  const opening     = addressLocation();
+  // The server result is used only for the scope and the page and filters
+  // it was loaded for.
   const initial     =
-    options.initial?.scope === JSON.stringify(toValue(context))
+    options.initial?.scope === JSON.stringify(toValue(context)) &&
+    (options.initial.list ?? listSignature(firstListPage)) ===
+      listSignature(opening)
       ? options.initial
       : undefined;
+  if (initial) {
+    // The filter panel shows the filters this result was loaded with.
+    store.setSearchFilters(opening.filters);
+  }
   const productIds  = ref<number[]>(initial ? [...initial.productIds] : []);
   const pagination  = ref<IProductPagination>(
     initial ? mergeCategoryPagination({}, initial.rpag) : {},
   );
-  const page        = ref(1);
+  const page        = ref(initial ? opening.page : 1);
   const pending     = ref(!initial);
   const failed      = ref(false);
   const loaded      = ref(Boolean(initial));
@@ -157,6 +240,28 @@ export function useOrionplaceProductSearch(
 
   useOrionplaceProgress(() => pending.value);
 
+  // Replaces the URL without a new load, so Back from the list still leaves
+  // it in one step.
+  function rememberLocation() {
+    const next  = { page: page.value, filters: store.searchFilters };
+    const query = addressQuery();
+    if (
+      !remember ||
+      !browser ||
+      sameProductListLocation(productListLocationFromQuery(query), next)
+    ) {
+      return;
+    }
+    replaceState(
+      routeHref({
+        path: window.location.pathname,
+        query: productListLocationQuery(query, next),
+        hash: window.location.hash,
+      }),
+      currentPage.state,
+    );
+  }
+
   function cancel() {
     request?.abort();
     request       = undefined;
@@ -178,11 +283,20 @@ export function useOrionplaceProductSearch(
       pending.value    = !mounted;
       return;
     }
+    rememberLocation();
     const current = new AbortController();
     request       = current;
     pending.value = true;
     try {
-      const data       = await requestData(body, current.signal);
+      const [data]     = await Promise.all([
+        requestData(body, current.signal),
+        preserveFullSearchFacets(
+          store,
+          toValue(context),
+          page.value,
+          (full) => requestData(full, current.signal),
+        ),
+      ]);
       if (current.signal.aborted) {
         return;
       }
@@ -209,11 +323,16 @@ export function useOrionplaceProductSearch(
     store.setSearchFilters({});
     void load(true);
   }
+  // A new scope starts from the page and filters of its URL: none after a
+  // link, the ones the visitor left after Back or a reload.
   function reset() {
+    const location   = addressLocation();
     pagination.value = {};
     productIds.value = [];
     store.setSearchFacets(null);
-    clearFilters();
+    store.setSearchFilters(location.filters);
+    page.value       = location.page;
+    void load();
   }
   function turnPage(value: number) {
     if (

package/templates/src/lib/layouts/StorefrontPageHead.svelte

@@ -22,4 +22,13 @@
       {/if}
     {/if}
   {/each}
+
+  {#each metadata.link ?? [] as link (link.rel)}
+    {#if link.href}
+      <link
+        rel={link.rel}
+        href={link.href}
+      />
+    {/if}
+  {/each}
 </svelte:head>

package/templates/src/lib/orionplace/navigation.svelte.ts

@@ -103,12 +103,15 @@ const headKey = Symbol('orionplace-head');
 export interface PageHead {
   title?: string;
   meta?: Record<string, any>[];
+  // <link> tags, one per `rel` (the canonical address).
+  link?: { rel: string; href: string }[];
 }
 type HeadReader = () => PageHead;
 
 function collectHead(readers: HeadReader[]): PageHead {
   let title: string | undefined;
   const meta = new Map<string, Record<string, any>>();
+  const link = new Map<string, { rel: string; href: string }>();
   for (const read of readers) {
     const head = read();
     title      = head.title ?? title;
@@ -118,8 +121,11 @@ function collectHead(readers: HeadReader[]): PageHead {
         meta.set(key, tag);
       }
     }
+    for (const tag of head.link ?? []) {
+      link.set(tag.rel, tag);
+    }
   }
-  return { title, meta: [...meta.values()] };
+  return { title, meta: [...meta.values()], link: [...link.values()] };
 }
 
 interface HeadRegistry {
@@ -178,7 +184,9 @@ export function useSeoMeta(source: Record<string, any>) {
               ? 'og:description'
               : name === 'ogImage'
                 ? 'og:image'
-                : name,
+                : name === 'ogUrl'
+                  ? 'og:url'
+                  : name,
         content: typeof value === 'function' ? value() : value,
       })),
   }));

package/templates/src/lib/orionplace/pageLoad.ts

@@ -3,6 +3,7 @@ import { OrionplaceStore } from '@/lib/orionplace/store.svelte';
 import { snapshotPageState } from '@/lib/orionplace/pageState';
 import { loadProductSearchSnapshot } from '@/lib/composables/useOrionplaceProductSearch.svelte';
 import { requestProductPage } from '@/lib/utils/orionplace/productPage';
+import { productListLocationFromQuery } from '@/lib/utils/orionplace/productListLocation';
 import { requestTariffPage } from '@/lib/utils/orionplace/tariffPage';
 import {
   blogPageNumber,
@@ -81,6 +82,8 @@ export async function loadStorefrontPageData(
   // A request failure retains the component's own Retry state. Only a
   // successful response without the record produces a missing-page response.
   if (store.isReady) {
+    // A list opens on the page and filters of its URL (Back, reload).
+    const listLocation = productListLocationFromQuery(Object.fromEntries(query));
     try {
       if (path === '/browse') {
         const scope                                        = {
@@ -91,18 +94,25 @@ export async function loadStorefrontPageData(
         };
         store.searchQuery                                  = scope.query;
         data[`orionplace:search:${JSON.stringify(scope)}`] =
-          await loadProductSearchSnapshot(api, store.facade, scope);
+          await loadProductSearchSnapshot(
+            api,
+            store.facade,
+            scope,
+            listLocation,
+          );
       } else if (path === '/featured') {
         data['orionplace:featured'] = await loadProductSearchSnapshot(
           api,
           store.facade,
           { featured: true },
+          listLocation,
         );
       } else if (path.startsWith('/category/')) {
         data[`orionplace:category:${id}`] = await loadProductSearchSnapshot(
           api,
           store.facade,
           { categoryId: id },
+          listLocation,
         );
       } else if (path.startsWith('/product/') && id) {
         const { product, sellers }       = await requestProductPage(

package/templates/src/lib/utils/orionplace/pageSeo.ts

@@ -282,3 +282,71 @@ export function storefrontPageMetadata(
     keywords: plainText(values.keywords ?? '') || `${title}, ${copy[2]}`,
   };
 }
+
+/*
+ * Addresses for search engines and link previews. The public origin is the
+ * storefront host the visitor used (the proxy's Host or X-Forwarded-Host),
+ * over HTTPS; a local host keeps HTTP for development.
+ */
+export function storefrontPublicOrigin(host: string | null | undefined): string {
+  const name  = (host ?? '').split(',')[0]!.trim().toLowerCase();
+  if (!/^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*|\[[0-9a-f:]+\])(?::\d{1,5})?$/.test(name)) {
+    return '';
+  }
+  const local = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::\d+)?$/.test(name);
+  return `${local ? 'http' : 'https'}://${name}`;
+}
+
+/**
+ * A complete address for a link preview image: a storefront path such as
+ * `/ps3/blog/posts/images/5` gets the public origin; without an origin it is
+ * left out, since a relative og:image is not loaded by link previews.
+ */
+export function storefrontAbsoluteUrl(
+  value: string | null | undefined,
+  origin: string,
+): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  try {
+    const url = origin ? new URL(value, `${origin}/`) : new URL(value);
+    return /^https?:$/.test(url.protocol) ? url.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The pages the sitemap lists (runtime/marketplace.mjs), plus plan pages.
+const indexedPage = /^\/(?:|catalog|journal|tariffs|manufacturers|sellers|stores|contact|privacy|(?:category|product|journal)\/\d+|tariffs\/[^/]+\/\d+)$/;
+
+/**
+ * The canonical address of a page: the sitemap's address for it, the page in
+ * the language it shows (`?locale=`). Pages that are not listed, pages with
+ * other query parameters (filters, page numbers, private keys) and noindex
+ * pages get none.
+ */
+export function storefrontCanonicalUrl(
+  origin: string,
+  pathname: string,
+  search: string,
+  locale: string,
+  robots?: string,
+): string | undefined {
+  const path  = pathname.replace(/\/+$/, '') || '/';
+  const query = new URLSearchParams(search);
+  query.delete('locale');
+  if (
+    !origin ||
+    /noindex/i.test(robots ?? '') ||
+    !indexedPage.test(path) ||
+    [...query.keys()].length
+  ) {
+    return undefined;
+  }
+  const url   = new URL(path, `${origin}/`);
+  if (locale) {
+    url.searchParams.set('locale', locale);
+  }
+  return url.toString();
+}

package/templates/src/lib/utils/orionplace/productListLocation.ts

@@ -0,0 +1,130 @@
+import type { ProductFacetSelection } from '@/lib/interfaces/orionplace/products/IProductSearchFacets';
+
+// Where a product list is: its result page and the chosen filters. Category,
+// search, seller and featured lists keep it in the URL as `?page&filters`, so
+// a reload and the browser's Back button from a product return to the same
+// list. `filters` is the filter selection as JSON; the address is visitor
+// input, so only plain filter values within the limits below are read.
+export interface ProductListLocation {
+  page: number;
+  filters: ProductFacetSelection;
+}
+
+type QueryValue = string | null | undefined | readonly (string | null)[];
+
+const locationKeys    = ['page', 'filters'];
+const maxPage         = 10000;
+const maxFiltersText  = 4000;
+const maxFilterKeys   = 40;
+const maxFilterIds    = 200;
+const maxFilterString = 100;
+const filterKey       = /^[a-z][a-z0-9_]{0,63}$/;
+
+function first(value: QueryValue) {
+  return Array.isArray(value) ? value[0] : (value as string | null | undefined);
+}
+
+function filterValue(value: unknown): ProductFacetSelection[string] {
+  if (Array.isArray(value)) {
+    const ids = value.filter(
+      (id): id is number => Number.isSafeInteger(id) && id >= 0,
+    );
+
+    return ids.length === value.length && ids.length && ids.length <= maxFilterIds
+      ? ids
+      : undefined;
+  }
+  if (typeof value === 'string') {
+    return value && value.length <= maxFilterString ? value : undefined;
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+
+  // `false` chooses nothing, as an empty list or text.
+  return value === true ? true : undefined;
+}
+
+export function productListFiltersFromText(
+  text: string | null | undefined,
+): ProductFacetSelection {
+  if (!text || text.length > maxFiltersText) {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {};
+  }
+  const result: ProductFacetSelection = {};
+  for (const [key, value] of Object.entries(parsed).slice(0, maxFilterKeys)) {
+    const checked = filterKey.test(key) ? filterValue(value) : undefined;
+    if (checked !== undefined) {
+      result[key] = checked;
+    }
+  }
+
+  return result;
+}
+
+// The filters as URL text, or undefined when nothing is chosen.
+// Keys are sorted, so the same choice always gives the same text.
+export function productListFiltersText(filters: ProductFacetSelection) {
+  const chosen = productListFiltersFromText(JSON.stringify(filters));
+  const keys   = Object.keys(chosen).sort();
+
+  return keys.length
+    ? JSON.stringify(Object.fromEntries(keys.map((key) => [key, chosen[key]])))
+    : undefined;
+}
+
+export function productListLocationFromQuery(
+  query: Record<string, QueryValue>,
+): ProductListLocation {
+  const page = Number(first(query.page));
+
+  return {
+    page: Number.isSafeInteger(page) && page > 0 && page <= maxPage ? page : 1,
+    filters: productListFiltersFromText(first(query.filters)),
+  };
+}
+
+// Compares the URL form, so the same choice in another key order is equal.
+export function sameProductListLocation(
+  left: ProductListLocation,
+  right: ProductListLocation,
+) {
+  return (
+    left.page === right.page &&
+    productListFiltersText(left.filters) === productListFiltersText(right.filters)
+  );
+}
+
+// The query of `next`: other parameters such as `locale` or `q` stay, and the
+// first page without filters adds nothing.
+export function productListLocationQuery(
+  query: Record<string, QueryValue>,
+  next: ProductListLocation,
+) {
+  const result: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    const text = first(value);
+    if (typeof text === 'string' && !locationKeys.includes(key)) {
+      result[key] = text;
+    }
+  }
+  if (next.page > 1) {
+    result.page = String(next.page);
+  }
+  const filters = productListFiltersText(next.filters);
+  if (filters) {
+    result.filters = filters;
+  }
+
+  return result;
+}

package/templates/src/routes/browse/+page.svelte

@@ -14,6 +14,7 @@
   import { directoryLabels } from '@/lib/utils/orionplace/directoryLabels';
   import { storeAddress, storePhoneLink } from '@/lib/utils/orionplace/storeDirectory';
   import { browseLabels } from '@/lib/utils/orionplace/browseLabels';
+  import { productListLocationFromQuery } from '@/lib/utils/orionplace/productListLocation';
   import {
     fixedScopeFilters,
     hasFixedSearchScope,
@@ -68,7 +69,13 @@
   // browser.
   const serverResults          = useOrionplaceServerData(
     `orionplace:search:${JSON.stringify(scope.value)}`,
-    (api) => loadProductSearchSnapshot(api, store, scope.value),
+    (api) =>
+      loadProductSearchSnapshot(
+        api,
+        store,
+        scope.value,
+        productListLocationFromQuery(route.query),
+      ),
   );
   const results                = useOrionplaceProductSearch(scope, {
     initial: serverResults.value,

package/templates/src/routes/category/[id]/+page.svelte

@@ -11,6 +11,7 @@
   import { useOrionplaceCategoryProducts } from '@/lib/composables/useOrionplaceCategoryProducts.svelte';
   import { useOrionplaceServerData } from '@/lib/composables/useOrionplaceServerData.svelte';
   import { loadProductSearchSnapshot } from '@/lib/composables/useOrionplaceProductSearch.svelte';
+  import { productListLocationFromQuery } from '@/lib/utils/orionplace/productListLocation';
   import { useOrionplaceStorefront } from '@/lib/composables/useOrionplaceStorefront.svelte';
   import {
     getAvailableNestedValueFromObject,
@@ -31,12 +32,19 @@
     /^\d+$/.test(String(route.params.id)) ? Number(route.params.id) : 0,
   );
   const category                         = computed(() => store.getCatalogCategory(id.value));
-  // The server render loads the first result page with the visitor's
-  // cookies, so the page HTML lists the category's products and prices.
-  // Filters and further pages load in the browser.
+  // The server render loads the result page of the URL (page and filters,
+  // the first page by default) with the visitor's cookies, so the page HTML
+  // lists the category's products and prices. Later changes load in the
+  // browser.
   const serverResults                    = useOrionplaceServerData(
     `orionplace:category:${id.value}`,
-    (api) => loadProductSearchSnapshot(api, store, { categoryId: id.value }),
+    (api) =>
+      loadProductSearchSnapshot(
+        api,
+        store,
+        { categoryId: id.value },
+        productListLocationFromQuery(route.query),
+      ),
   );
   const results                          = useOrionplaceCategoryProducts(id, serverResults.value);
   const { actions, variants, selection } = useOrionplaceStorefront();

package/templates/src/routes/featured/+page.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { routeHref } from '@/lib/orionplace/navigation.svelte';
   import { computed } from '@/lib/orionplace/reactivity.svelte';
-  import { navigateTo } from '@/lib/orionplace/navigation.svelte';
+  import { navigateTo, useRoute } from '@/lib/orionplace/navigation.svelte';
   import { useOrionplacePageSeo } from '@/lib/composables/useOrionplacePageSeo.svelte';
   import { useOrionplaceStore } from '@/lib/stores/orionplace.svelte';
   import { useOrionplaceFeaturedProducts } from '@/lib/composables/useOrionplaceFeaturedProducts.svelte';
@@ -10,6 +10,7 @@
   import { useOrionplaceStorefront } from '@/lib/composables/useOrionplaceStorefront.svelte';
   import { featuredLabels } from '@/lib/utils/orionplace/featuredLabels';
   import { browseLabels } from '@/lib/utils/orionplace/browseLabels';
+  import { productListLocationFromQuery } from '@/lib/utils/orionplace/productListLocation';
   import ProductSearchResults from '@/lib/components/orionplace/search/ProductSearchResults.svelte';
   import OrionplaceEmptyState from '@/lib/components/orionplace/shared/OrionplaceEmptyState.svelte';
 
@@ -19,10 +20,16 @@
   let { ...attributes }: Props = $props();
 
   const store                  = useOrionplaceStore();
+  const route                  = useRoute();
   // Featured products depend on the signed-in customer's searches: the
-  // server render loads the first page with the visitor's cookies.
+  // server render loads the page of the URL with the visitor's cookies.
   const serverResults          = useOrionplaceServerData('orionplace:featured', (api) =>
-    loadProductSearchSnapshot(api, store, { featured: true }),
+    loadProductSearchSnapshot(
+      api,
+      store,
+      { featured: true },
+      productListLocationFromQuery(route.query),
+    ),
   );
   const results                = useOrionplaceFeaturedProducts(serverResults.value);
   const { actions, variants }  = useOrionplaceStorefront();