feat: landing pages + URL redirects + CMS root-level routing

Three interlocking bodies of work.

URL-redirect subsystem
- New url_redirect table (base) with write-time chain collapse; a
  notFound-gated middleware 302s an old path to the new one.
- Inline capture in the product/category update services: url_key renames,
  category reassignment/unassignment (incl. whole variant groups), and
  category rename AND reparent.
- Unified, unit-tested path algebra (pathRemap: buildEntityPath / remapPath /
  planSubtreeRedirects); boundary-anchored subscriber cascade (fixes the
  /shoe-sale sweep and /cat/cat-toy mangle); set-based recordRedirectsBatch.
- Delete-cascade cleanup: purge a category subtree's aliases and capture the
  nested->root move of every product it uncategorises.

CMS root-level routing
- CMS pages are served at root-level /<url_key> via url_rewrite; the
  page-builder for CMS pages reverts to route-level.

Landing pages (promotion module)
- New first-class entity: root-level URL, page-builder-only body via
  entity_urn, admin grid + CRUD + duplicate, status + publish schedule;
  wins URL collisions.
- Page-builder entity-scope registry; draft/scheduled pages preview in the
  editor via a valid changeset token (possession-based trust).

SEO / UI
- LinkPicker "Landing page" tab + a promotion:landing_page link loader.
- Live SearchSnippetPreview (SERP snippet) on the landing-page and CMS-page
  SEO forms; dropped meta_keywords from landing pages; two-column landing
  edit layout with status + schedule in the sidebar.

Verified: tsc 0 errors; jest 82 suites / 790 tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: treoden

packages/evershop/src/bin/lib/addDefaultMiddlewareFuncs.ts

@@ -238,11 +238,28 @@ export function addDefaultMiddlewareFuncs(app) {
       return next();
     }
 
-    // Find the matched rewrite rule base on the request path
-    const rewriteRule = await select()
-      .from('url_rewrite')
-      .where('request_path', '=', `/${path}`)
-      .load(pool);
+    // Find the matched rewrite rule based on the request path. url_rewrite only
+    // enforces UNIQUE(entity_uuid), so two entities (e.g. a landing page and a
+    // CMS page) can share a request_path. Resolve deterministically by
+    // entity_type PRECEDENCE — landing pages win a genuine collision, then
+    // cms_page, product, category, then oldest id (see wiki/landing-pages.md).
+    // The query-builder can't express a CASE order (its OrderBy holds a single
+    // field and mangles a CASE string), so this drops to raw SQL.
+    const rewriteResult = await pool.query(
+      `SELECT * FROM url_rewrite
+       WHERE request_path = $1
+       ORDER BY CASE entity_type
+           WHEN 'landing_page' THEN 0
+           WHEN 'cms_page' THEN 1
+           WHEN 'product' THEN 2
+           WHEN 'category' THEN 3
+           ELSE 4
+         END,
+         url_rewrite_id ASC
+       LIMIT 1`,
+      [`/${path}`]
+    );
+    const rewriteRule = rewriteResult.rows[0] ?? null;
 
     if (rewriteRule) {
       // Find the route

packages/evershop/src/bin/seed/seedBlog.ts

@@ -118,7 +118,7 @@ export async function seedBlog(): Promise<void> {
           short_description: c.short_description ?? null
         })
         .execute(connection);
-      await insertOnUpdate('url_rewrite', ['entity_uuid', 'language'])
+      await insertOnUpdate('url_rewrite', ['entity_uuid'])
         .given({
           entity_type: 'blog_category',
           entity_uuid: cat.uuid,
@@ -145,7 +145,7 @@ export async function seedBlog(): Promise<void> {
       const tag = await insert('blog_tag')
         .given({ name: t.name, url_key: t.url_key })
         .execute(connection);
-      await insertOnUpdate('url_rewrite', ['entity_uuid', 'language'])
+      await insertOnUpdate('url_rewrite', ['entity_uuid'])
         .given({
           entity_type: 'blog_tag',
           entity_uuid: tag.uuid,
@@ -199,7 +199,7 @@ export async function seedBlog(): Promise<void> {
           meta_description: p.meta_description ?? null
         })
         .execute(connection);
-      await insertOnUpdate('url_rewrite', ['entity_uuid', 'language'])
+      await insertOnUpdate('url_rewrite', ['entity_uuid'])
         .given({
           entity_type: 'blog_post',
           entity_uuid: post.uuid,

packages/evershop/src/components/common/page-builder/index.ts

@@ -55,5 +55,6 @@ export { CategoryPicker } from './pickers/CategoryPicker.js';
 export { ProductPicker } from './pickers/ProductPicker.js';
 export { CollectionPicker } from './pickers/CollectionPicker.js';
 export { PagePicker } from './pickers/PagePicker.js';
+export { LandingPagePicker } from './pickers/LandingPagePicker.js';
 export { LinkPicker } from './pickers/LinkPicker.js';
 export { EntitySearchList } from './pickers/EntitySearchList.js';

packages/evershop/src/components/common/page-builder/pickers/LandingPagePicker.tsx

@@ -0,0 +1,111 @@
+import { EntitySearchList } from '@components/common/page-builder/pickers/EntitySearchList.js';
+import React, { useEffect, useState } from 'react';
+import { useQuery } from 'urql';
+
+/**
+ * Search-and-pick a landing page. Mirrors PagePicker but queries the promotion
+ * `landingPages` collection (admin schema — the page-builder editor runs in
+ * admin context). Stores the page's `url` for display; the LinkPicker turns the
+ * pick into a `promotion:landing_page` URN, resolved to the live URL at request
+ * time by the loader registered in the promotion bootstrap.
+ */
+
+const SEARCH_QUERY = `
+  query LandingPagePickerSearch($filters: [FilterInput]) {
+    landingPages(filters: $filters) {
+      items {
+        uuid
+        name
+        urlKey
+        url
+        status
+      }
+      total
+    }
+  }
+`;
+
+export interface LandingPagePickResult {
+  url: string;
+  name: string;
+  uuid: string;
+}
+
+export interface LandingPagePickerProps {
+  selectedUrl?: string | null;
+  /** Highlight the item whose uuid matches this — preferred over selectedUrl. */
+  selectedUuid?: string | null;
+  onPick: (result: LandingPagePickResult) => void;
+  limit?: number;
+}
+
+export function LandingPagePicker({
+  selectedUrl,
+  selectedUuid,
+  onPick,
+  limit = 10
+}: LandingPagePickerProps) {
+  const [search, setSearch] = useState('');
+  const [debounced, setDebounced] = useState('');
+
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(search), 300);
+    return () => clearTimeout(t);
+  }, [search]);
+
+  const filters = debounced
+    ? [
+        { key: 'name', operation: 'like', value: debounced },
+        { key: 'limit', operation: 'eq', value: String(limit) }
+      ]
+    : [{ key: 'limit', operation: 'eq', value: String(limit) }];
+
+  const [result] = useQuery({ query: SEARCH_QUERY, variables: { filters } });
+  const items = (result.data?.landingPages?.items ?? []).map(
+    (p: {
+      uuid: string;
+      name: string;
+      url?: string | null;
+      urlKey?: string | null;
+      status: boolean;
+    }) => ({
+      id: p.url || `/${p.urlKey ?? p.uuid}`,
+      primary: p.name,
+      // Drafts shouldn't link from a public storefront (they 404 until
+      // published), so mark them — same convention as PagePicker.
+      secondary: p.status ? p.url ?? null : 'Draft',
+      _uuid: p.uuid
+    })
+  );
+
+  // When selecting by uuid (URN storage), look up the item.id whose backing
+  // _uuid matches; otherwise fall back to selectedUrl.
+  const selectedIdByUuid = selectedUuid
+    ? items.find(
+        (it) => (it as unknown as { _uuid: string })._uuid === selectedUuid
+      )?.id ?? null
+    : null;
+
+  return (
+    <EntitySearchList
+      items={items}
+      selectedId={selectedIdByUuid ?? selectedUrl ?? null}
+      search={search}
+      onSearchChange={setSearch}
+      loading={result.fetching}
+      onSelect={(id, item) =>
+        onPick({
+          url: id,
+          name: item.primary,
+          uuid: (item as unknown as { _uuid: string })._uuid
+        })
+      }
+      caption="Pick a landing page to link to."
+      emptyHint={
+        debounced
+          ? `No landing pages match "${debounced}".`
+          : 'No landing pages yet.'
+      }
+    />
+  );
+}

packages/evershop/src/components/common/page-builder/pickers/LinkPicker.tsx

@@ -2,13 +2,15 @@
 import { drawerInputClass } from '@components/common/page-builder/drawer/index.js';
 import { BlogPicker } from '@components/common/page-builder/pickers/BlogPicker.js';
 import { CategoryPicker } from '@components/common/page-builder/pickers/CategoryPicker.js';
+import { LandingPagePicker } from '@components/common/page-builder/pickers/LandingPagePicker.js';
 import { PagePicker } from '@components/common/page-builder/pickers/PagePicker.js';
 import { ProductPicker } from '@components/common/page-builder/pickers/ProductPicker.js';
 import { _ } from '@evershop/evershop/lib/locale/translate/_';
 import {
   BlogUrn,
   CatalogUrn,
   CmsUrn,
+  PromotionUrn,
   UrnService
 } from '@evershop/evershop/lib/urn';
 import React, { useState } from 'react';
@@ -40,6 +42,8 @@ function parseUrn(value: string | undefined | null): ParsedLinkUrn | null {
   if (service === 'catalog' && type === 'product') return { kind: 'product', id: uuid };
   if (service === 'catalog' && type === 'category') return { kind: 'category', id: uuid };
   if (service === 'cms' && type === 'page') return { kind: 'page', id: uuid };
+  if (service === 'promotion' && type === 'landing_page')
+    return { kind: 'landingPage', id: uuid };
   if (service === 'blog' && type === 'post')
     return { kind: 'blogPost', id: uuid };
   if (service === 'blog' && type === 'category')
@@ -51,6 +55,7 @@ function parseUrn(value: string | undefined | null): ParsedLinkUrn | null {
 
 export type LinkKind =
   | 'page'
+  | 'landingPage'
   | 'category'
   | 'product'
   | 'blogPost'
@@ -60,6 +65,7 @@ export type LinkKind =
 
 const TABS: { value: LinkKind; label: string }[] = [
   { value: 'page', label: _('Page') },
+  { value: 'landingPage', label: _('Landing page') },
   { value: 'category', label: _('Category') },
   { value: 'product', label: _('Product') },
   { value: 'blogPost', label: _('Blog post') },
@@ -127,6 +133,19 @@ export function LinkPicker({
           }
         />
       )}
+      {tab === 'landingPage' && (
+        <LandingPagePicker
+          selectedUuid={parsed?.kind === 'landingPage' ? parsed.id : null}
+          selectedUrl={parsed ? null : value || null}
+          onPick={(r) =>
+            onChange({
+              url: PromotionUrn.landingPage(r.uuid),
+              kind: 'landingPage',
+              label: r.name
+            })
+          }
+        />
+      )}
       {tab === 'category' && (
         <CategoryPicker
           selectedUuid={parsed?.kind === 'category' ? parsed.id : null}

packages/evershop/src/lib/urn/index.ts

@@ -33,7 +33,12 @@ import { UrnService } from './services/UrnService.js';
   { service: 'customer', type: 'customer', description: 'Customer account' },
   { service: 'blog', type: 'post', description: 'Blog post' },
   { service: 'blog', type: 'category', description: 'Blog category' },
-  { service: 'blog', type: 'tag', description: 'Blog tag' }
+  { service: 'blog', type: 'tag', description: 'Blog tag' },
+  {
+    service: 'promotion',
+    type: 'landing_page',
+    description: 'Promotion landing page'
+  }
 ].forEach(registerUrnSchema);
 
 export const CatalogUrn = {
@@ -63,6 +68,11 @@ export const CustomerUrn = {
   customer: (uuid: string) => UrnService.build('customer', 'customer', uuid)
 };
 
+export const PromotionUrn = {
+  landingPage: (uuid: string) =>
+    UrnService.build('promotion', 'landing_page', uuid)
+};
+
 export { UrnService };
 export { registerUrnSchema, getUrnSchema, hasUrnSchema, listUrnSchemas };
 export type { UrnSchema } from './services/UrnRegistry.js';

packages/evershop/src/lib/util/entityScopeRegistry.ts

@@ -0,0 +1,59 @@
+/**
+ * Page-builder entity-scope registry.
+ *
+ * A route registered here gains per-entity page-builder editing: the editor
+ * surfaces an entity selector (populated by `list`) and scopes widget placements
+ * to `entity_urn` (built from `resolve`). Modules register their entity-scoped
+ * routes from their own `bootstrap` — the page-builder never hardcodes or imports
+ * a domain module. See wiki/landing-pages.md.
+ *
+ * This is a plain module-level registry (not the hook/processor registry), so it
+ * is not subject to the post-bootstrap lock; by convention, registration happens
+ * at bootstrap time only.
+ */
+
+export interface EntityScopeEntity {
+  uuid: string;
+  name: string;
+  urlKey: string;
+  urn: string;
+  /**
+   * Published flag, when the entity type has one. The editor's scope selector
+   * badges `false` as a draft. Optional/nullable so entity types without a
+   * publish concept simply omit it (no badge).
+   */
+  status?: boolean | null;
+}
+
+export interface EntityScopeConfig {
+  /** The page-builder route id this scope applies to (e.g. `'landingPageView'`). */
+  routeId: string;
+  /** The entity type in URN vocabulary (e.g. `'landing_page'`). */
+  entityType: string;
+  /**
+   * Resolve a single entity uuid → its `entity_urn` + the storefront preview path
+   * the editor iframe should load. Returns null when the uuid doesn't resolve.
+   */
+  resolve: (
+    uuid: string,
+    pool: any
+  ) => Promise<{ urn: string; previewPath: string } | null>;
+  /** List all selectable entities for the editor's scope selector. */
+  list: (pool: any) => Promise<EntityScopeEntity[]>;
+}
+
+const registry = new Map<string, EntityScopeConfig>();
+
+export function registerEntityScope(config: EntityScopeConfig): void {
+  registry.set(config.routeId, config);
+}
+
+export function getEntityScope(
+  routeId: string | undefined | null
+): EntityScopeConfig | undefined {
+  return routeId ? registry.get(routeId) : undefined;
+}
+
+export function getAllEntityScopes(): EntityScopeConfig[] {
+  return Array.from(registry.values());
+}

packages/evershop/src/lib/widget/linkResolver.ts

@@ -1,4 +1,5 @@
 import { Pool } from 'pg';
+import { localizeUrl } from '../locale/localeContext.js';
 import { select } from '../postgres/query.js';
 import { buildUrl } from '../router/buildUrl.js';
 import { UrnService } from '../urn/index.js';
@@ -143,10 +144,7 @@ const pageLoader: LinkLoaderFactory = linkLoaderFromBatch(
       .where('uuid', 'IN', [...uuids])
       .execute(pool);
     const m = new Map<string, string>(
-      rows.map((r: any) => [
-        r.uuid,
-        buildUrl('cmsPageView', { url_key: r.url_key })
-      ])
+      rows.map((r: any) => [r.uuid, localizeUrl(`/${r.url_key}`)])
     );
     return uuids.map((u) => m.get(u) ?? null);
   }

packages/evershop/src/modules/base/graphql/types/Route/Route.admin.graphql

@@ -29,6 +29,13 @@ type Route {
   (product list, category page) where the URL serves many entities.
   """
   assignedEntity: AssignedEntity
+  """
+  Non-null when this route serves many entities of one type that the
+  page builder can scope widget placements to (e.g. `cmsPageView` serves
+  every CMS page). Drives the topbar "entity scope" selector so the client
+  need not hardcode `cmsPageView`. Null for routes with no entity dimension.
+  """
+  entityScope: EntityScope
 }
 
 """
@@ -41,6 +48,16 @@ type AssignedEntity {
   label: String
 }
 
+"""
+Describes a route's entity dimension for the page builder: the entity
+`type` (matches the URN service/type vocabulary, e.g. `cms_page`) and the
+GraphQL `listQuery` the selector calls to enumerate selectable entities.
+"""
+type EntityScope {
+  type: String!
+  listQuery: String!
+}
+
 extend type Query {
   routes: [Route!]!
   route(id: String!): Route