@sarimarcus/content-sites-core 0.6.1 → 0.7.0-rc.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.7.0-rc.0 (2026-09-30)
+
+- Ships compiled `dist/` (ESM + declarations) for every subpath, so code Node loads directly (factory tests, `astro.config.mjs`) can import core.
+- `./url`: `url`, `normalizePagePath`, `toAbsoluteSiteUrl`, `normalizeSiteUrl` (`basePath` defaults to `'/'`), `getOgImagePath`, `normalizeHref`, `extractProseHrefs`, `dedupRelated`, `buildImageMap` / `keyBySlug`. `./dom`: `deterministicId`. New `./text`: `slugify`, `fitWithinLength` (SLA-2747).
+
 ## 0.6.1 (2026-09-30)
 
 - Stable release of 0.6.1-rc.0, unchanged: the Blockquote caption change reviewed by screenshot on Córdoba; every other page identical (SLA-2821).

package/README.md

@@ -4,9 +4,14 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
 and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
 today's ui components import from tourism code).
 
-Named entry points: `url`, `dates`, `dom`, `config` and `types` (`src/internal` is never exported). No `.astro`
+Named entry points: `url`, `dates`, `dom`, `text`, `config` and `types` (`src/internal` is never exported). No `.astro`
 files. Lowest layer: imports nothing from the other packages. Ownership per path is in
 `.planning/platform/catalogue.json` (owner `core`).
 
 Code Node loads directly (config builders imported by `astro.config.mjs`) ships compiled to `dist/` with
-type declarations. Node will not strip types from files under `node_modules`.
+type declarations. Node will not strip types from files under `node_modules`. So every entry point resolves to
+`dist/`: `npm run build -w packages/core` compiles it (`tsconfig.build.json`), and `release-check.mjs` refuses a
+missing or stale `dist/`.
+
+Core code never imports `astro:content`, never reads `import.meta.env` or `import.meta.glob` (values and glob
+results come in as parameters), and never names a site or vertical. `validate-packages.mjs` enforces all three.

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/index.js

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/config. Components land here from SLA-2742 on.
+export {};

package/dist/dates/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dates/index.js

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/dates. Components land here from SLA-2742 on.
+export {};

package/dist/dom/deterministicId.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Stable per-instance DOM id. Replaces `Math.random()`, which made rebuilds
+ * non-byte-identical (SLA-2428). The id only has to be unique within one page,
+ * so hash the caller's stable inputs (djb2) and suffix a counter for a genuine
+ * same-page collision.
+ */
+export declare function deterministicId(prefix: string, ...parts: (string | null | undefined)[]): string;

package/dist/dom/deterministicId.js

@@ -0,0 +1,20 @@
+// Anchored on globalThis, not module scope: the module can be instantiated more
+// than once per build, and the collision counter must not restart when it is.
+const g = globalThis;
+g.__domIdSeen ??= new Map();
+const seen = g.__domIdSeen;
+/**
+ * Stable per-instance DOM id. Replaces `Math.random()`, which made rebuilds
+ * non-byte-identical (SLA-2428). The id only has to be unique within one page,
+ * so hash the caller's stable inputs (djb2) and suffix a counter for a genuine
+ * same-page collision.
+ */
+export function deterministicId(prefix, ...parts) {
+    const seed = `${prefix}|${parts.map((p) => p ?? '').join('|')}`;
+    let h = 5381;
+    for (let i = 0; i < seed.length; i++)
+        h = ((h * 33) ^ seed.charCodeAt(i)) >>> 0;
+    const n = seen.get(seed) ?? 0;
+    seen.set(seed, n + 1);
+    return `${prefix}-${h.toString(36)}${n ? `-${n}` : ''}`;
+}

package/dist/dom/index.d.ts

@@ -0,0 +1 @@
+export { deterministicId } from './deterministicId.ts';

package/dist/dom/index.js

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/dom.
+export { deterministicId } from "./deterministicId.js";

package/dist/text/fitWithinLength.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Pick the longest candidate that still fits within maxLen, falling back to the last (shortest) one if
+ * none fit. Candidates must be ordered longest/most-descriptive to shortest/most-terse.
+ */
+export declare function fitWithinLength(candidates: string[], maxLen: number): string;

package/dist/text/fitWithinLength.js

@@ -0,0 +1,7 @@
+/**
+ * Pick the longest candidate that still fits within maxLen, falling back to the last (shortest) one if
+ * none fit. Candidates must be ordered longest/most-descriptive to shortest/most-terse.
+ */
+export function fitWithinLength(candidates, maxLen) {
+    return candidates.find((c) => c.length <= maxLen) ?? candidates[candidates.length - 1];
+}

package/dist/text/index.d.ts

@@ -0,0 +1,2 @@
+export { slugify } from './slugify.ts';
+export { fitWithinLength } from './fitWithinLength.ts';

package/dist/text/index.js

@@ -0,0 +1,3 @@
+// Public surface of @sarimarcus/content-sites-core/text.
+export { slugify } from "./slugify.js";
+export { fitWithinLength } from "./fitWithinLength.js";

package/dist/text/slugify.d.ts

@@ -0,0 +1 @@
+export declare function slugify(value: string): string;

package/dist/text/slugify.js

@@ -0,0 +1,8 @@
+export function slugify(value) {
+    return value
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}

package/dist/types/index.d.ts

@@ -0,0 +1,48 @@
+/** Version of the site and vertical definition schemas. The factory validator refuses any other value. */
+export declare const DEFINITION_SCHEMA_VERSION = 1;
+export type CityPlaces = {
+    mode: 'city';
+    cityName: string;
+    lat: number;
+    lng: number;
+    regionCode: string;
+};
+export type WorldwidePlaces = {
+    mode: 'worldwide';
+};
+/**
+ * A site's identity, as generated into `src/config/site.generated.ts` from its `sites.json` entry.
+ * Only fields a site renders from belong here; factory-only registry keys stay in `sites.json`.
+ */
+export interface SiteConfig {
+    schemaVersion: typeof DEFINITION_SCHEMA_VERSION;
+    key: string;
+    siteName: string;
+    /** Absolute origin, no trailing slash: `https://<domain>`. */
+    url: string;
+    language: string;
+    locale: string;
+    /** The vertical this site belongs to, or null for a one-off site. */
+    vertical: string | null;
+    analytics: {
+        gtmId: string;
+    };
+    social: {
+        twitterHandle?: string;
+    };
+    places: CityPlaces | WorldwidePlaces;
+}
+/** A vertical manifest, `verticals/<id>/vertical.json` in the factory. Never published. */
+export interface VerticalDefinition {
+    schemaVersion: typeof DEFINITION_SCHEMA_VERSION;
+    /** Equal to the manifest's directory name. */
+    id: string;
+    /** The vertical's npm package, or null when it has none yet. */
+    package: string | null;
+    /** Collections the vertical owns; each must be in every member site's `content_types`. */
+    contentTypes: string[];
+    /** Dotted paths into a site's `sites.json` entry that every member site must set, e.g. `places.cityName`. */
+    requires: string[];
+    /** Reserved for SLA-2744; empty until then. */
+    routes: [];
+}

package/dist/types/index.js

@@ -0,0 +1,3 @@
+// Public surface of @sarimarcus/content-sites-core/types.
+/** Version of the site and vertical definition schemas. The factory validator refuses any other value. */
+export const DEFINITION_SCHEMA_VERSION = 1;

package/dist/url/imageMap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Key an eager `import.meta.glob` result by file basename: `/src/assets/x/<slug>.webp` → `<slug>`.
+ * The glob itself must stay a literal at the call site (Vite requires it).
+ */
+export declare function buildImageMap<T>(mods: Record<string, {
+    default: T;
+}>): Record<string, T>;
+export declare const keyBySlug: typeof buildImageMap;

package/dist/url/imageMap.js

@@ -0,0 +1,11 @@
+/**
+ * Key an eager `import.meta.glob` result by file basename: `/src/assets/x/<slug>.webp` → `<slug>`.
+ * The glob itself must stay a literal at the call site (Vite requires it).
+ */
+export function buildImageMap(mods) {
+    return Object.fromEntries(Object.entries(mods).map(([path, mod]) => {
+        const slug = path.split('/').pop().replace('.webp', '');
+        return [slug, mod.default];
+    }));
+}
+export const keyBySlug = buildImageMap;

package/dist/url/index.d.ts

@@ -0,0 +1,4 @@
+export { url, normalizePagePath, toAbsoluteSiteUrl, normalizeSiteUrl } from './url.ts';
+export { getOgImagePath } from './ogImage.ts';
+export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.ts';
+export { buildImageMap, keyBySlug } from './imageMap.ts';

package/dist/url/index.js

@@ -0,0 +1,5 @@
+// Public surface of @sarimarcus/content-sites-core/url.
+export { url, normalizePagePath, toAbsoluteSiteUrl, normalizeSiteUrl } from "./url.js";
+export { getOgImagePath } from "./ogImage.js";
+export { normalizeHref, extractProseHrefs, dedupRelated } from "./relatedDedup.js";
+export { buildImageMap, keyBySlug } from "./imageMap.js";

package/dist/url/ogImage.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The og:image path for a content item: /images/og/{type}/{slug}.jpg.
+ * The images are pre-generated by `npm run images:og` into public/images/og/ (factory scripts/og-images).
+ */
+export declare function getOgImagePath(type: string, slug: string): string;

package/dist/url/ogImage.js

@@ -0,0 +1,7 @@
+/**
+ * The og:image path for a content item: /images/og/{type}/{slug}.jpg.
+ * The images are pre-generated by `npm run images:og` into public/images/og/ (factory scripts/og-images).
+ */
+export function getOgImagePath(type, slug) {
+    return `/images/og/${type}/${slug}.jpg`;
+}

package/dist/url/relatedDedup.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeHref(href: string, basePath?: string): string | null;
+export declare function extractProseHrefs(htmlChunks: (string | undefined | null)[], basePath?: string): Set<string>;
+export declare function dedupRelated<T extends {
+    href: string;
+}>(items: T[], proseHrefs: Set<string>, basePath?: string): T[];

package/dist/url/relatedDedup.js

@@ -0,0 +1,41 @@
+// `null` = skip dedup (external/anchor hrefs are always kept as-is).
+// Exported because callers build taken-href Sets from mixed inputs (prose HTML, cards, url()-applied hrefs)
+// and every member must be in THIS normal form or dedupRelated() silently never matches it.
+// `basePath` must arrive with its trailing slash already stripped.
+export function normalizeHref(href, basePath = '') {
+    if (!href)
+        return null;
+    let h = href;
+    if (basePath && h.startsWith(basePath))
+        h = h.slice(basePath.length);
+    if (!h.startsWith('/'))
+        return null;
+    h = h.split('#')[0].split('?')[0];
+    h = h.replace(/\/+$/, '') || '/';
+    return h;
+}
+export function extractProseHrefs(htmlChunks, basePath = '') {
+    const hrefs = new Set();
+    const re = /<a\b[^>]*\bhref=["']([^"']+)["']/gi;
+    const normalizedBase = basePath.replace(/\/+$/, '');
+    for (const html of htmlChunks) {
+        if (!html)
+            continue;
+        let m;
+        while ((m = re.exec(html))) {
+            const n = normalizeHref(m[1], normalizedBase);
+            if (n)
+                hrefs.add(n);
+        }
+    }
+    return hrefs;
+}
+export function dedupRelated(items, proseHrefs, basePath = '') {
+    if (items.length === 0 || proseHrefs.size === 0)
+        return items;
+    const normalizedBase = basePath.replace(/\/+$/, '');
+    return items.filter((it) => {
+        const n = normalizeHref(it.href, normalizedBase);
+        return n === null || !proseHrefs.has(n);
+    });
+}

package/dist/url/url.d.ts

@@ -0,0 +1,5 @@
+/** Prepend the site base path to a path, without doubling slashes. */
+export declare function url(path: string, basePath?: string): string;
+export declare function normalizePagePath(pathname: string, basePath?: string): string;
+export declare function toAbsoluteSiteUrl(pathname: string, siteUrl: string, basePath?: string): string;
+export declare function normalizeSiteUrl(input: string, siteUrl: string, basePath?: string): string;

package/dist/url/url.js

@@ -0,0 +1,59 @@
+/** Prepend the site base path to a path, without doubling slashes. */
+export function url(path, basePath = '/') {
+    const cleanBase = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    const cleanPath = path.startsWith('/') ? path : `/${path}`;
+    return `${cleanBase}${cleanPath}`;
+}
+function normalizeBasePath(basePath) {
+    if (!basePath || basePath === '/')
+        return '';
+    return basePath.replace(/\/$/, '');
+}
+export function normalizePagePath(pathname, basePath = '/') {
+    const cleanBase = normalizeBasePath(basePath);
+    let normalized = pathname || '/';
+    if (!normalized.startsWith('/')) {
+        normalized = `/${normalized}`;
+    }
+    normalized = normalized.replace(/\/index\.html$/, '/');
+    if (cleanBase && normalized === `${cleanBase}.html`) {
+        normalized = `${cleanBase}/`;
+    }
+    else {
+        normalized = normalized.replace(/\.html$/, '');
+    }
+    const isHomepage = normalized === '/' ||
+        normalized === cleanBase ||
+        normalized === `${cleanBase}/`;
+    if (isHomepage) {
+        return cleanBase ? `${cleanBase}/` : '/';
+    }
+    return normalized.replace(/\/$/, '');
+}
+export function toAbsoluteSiteUrl(pathname, siteUrl, basePath = '/') {
+    return new URL(normalizePagePath(pathname, basePath), siteUrl.endsWith('/') ? siteUrl : `${siteUrl}/`).toString();
+}
+export function normalizeSiteUrl(input, siteUrl, basePath = '/') {
+    if (!input)
+        return input;
+    if (input.startsWith('/')) {
+        const relativeUrl = new URL(`https://internal${input}`);
+        const normalizedPath = normalizePagePath(relativeUrl.pathname, basePath);
+        return `${normalizedPath}${relativeUrl.search}${relativeUrl.hash}`;
+    }
+    if (!/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(input)) {
+        return input;
+    }
+    try {
+        const parsedUrl = new URL(input);
+        const parsedSiteUrl = new URL(siteUrl);
+        if (parsedUrl.origin !== parsedSiteUrl.origin) {
+            return input;
+        }
+        parsedUrl.pathname = normalizePagePath(parsedUrl.pathname, basePath);
+        return parsedUrl.toString();
+    }
+    catch {
+        return input;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.6.1",
+  "version": "0.7.0-rc.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -24,13 +24,35 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json"
+  },
   "exports": {
     "./package.json": "./package.json",
-    "./url": "./src/url/index.ts",
-    "./dates": "./src/dates/index.ts",
-    "./dom": "./src/dom/index.ts",
-    "./config": "./src/config/index.ts",
-    "./types": "./src/types/index.ts"
+    "./url": {
+      "types": "./dist/url/index.d.ts",
+      "default": "./dist/url/index.js"
+    },
+    "./dates": {
+      "types": "./dist/dates/index.d.ts",
+      "default": "./dist/dates/index.js"
+    },
+    "./dom": {
+      "types": "./dist/dom/index.d.ts",
+      "default": "./dist/dom/index.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "default": "./dist/text/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "default": "./dist/config/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/types/index.js"
+    }
   },
   "peerDependencies": {
     "astro": "^7.0.6"

package/src/dom/deterministicId.ts

@@ -0,0 +1,25 @@
+type SeenMap = Map<string, number>;
+
+// Anchored on globalThis, not module scope: the module can be instantiated more
+// than once per build, and the collision counter must not restart when it is.
+const g = globalThis as typeof globalThis & { __domIdSeen?: SeenMap };
+g.__domIdSeen ??= new Map();
+const seen: SeenMap = g.__domIdSeen;
+
+/**
+ * Stable per-instance DOM id. Replaces `Math.random()`, which made rebuilds
+ * non-byte-identical (SLA-2428). The id only has to be unique within one page,
+ * so hash the caller's stable inputs (djb2) and suffix a counter for a genuine
+ * same-page collision.
+ */
+export function deterministicId(
+  prefix: string,
+  ...parts: (string | null | undefined)[]
+): string {
+  const seed = `${prefix}|${parts.map((p) => p ?? '').join('|')}`;
+  let h = 5381;
+  for (let i = 0; i < seed.length; i++) h = ((h * 33) ^ seed.charCodeAt(i)) >>> 0;
+  const n = seen.get(seed) ?? 0;
+  seen.set(seed, n + 1);
+  return `${prefix}-${h.toString(36)}${n ? `-${n}` : ''}`;
+}

package/src/dom/index.ts

@@ -1,2 +1,2 @@
-// Public surface of @sarimarcus/content-sites-core/dom. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-core/dom.
+export { deterministicId } from './deterministicId.ts';

package/src/text/fitWithinLength.ts

@@ -0,0 +1,7 @@
+/**
+ * Pick the longest candidate that still fits within maxLen, falling back to the last (shortest) one if
+ * none fit. Candidates must be ordered longest/most-descriptive to shortest/most-terse.
+ */
+export function fitWithinLength(candidates: string[], maxLen: number): string {
+  return candidates.find((c) => c.length <= maxLen) ?? candidates[candidates.length - 1];
+}

package/src/text/index.ts

@@ -0,0 +1,3 @@
+// Public surface of @sarimarcus/content-sites-core/text.
+export { slugify } from './slugify.ts';
+export { fitWithinLength } from './fitWithinLength.ts';

package/src/text/slugify.ts

@@ -0,0 +1,8 @@
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/src/url/imageMap.ts

@@ -0,0 +1,14 @@
+/**
+ * Key an eager `import.meta.glob` result by file basename: `/src/assets/x/<slug>.webp` → `<slug>`.
+ * The glob itself must stay a literal at the call site (Vite requires it).
+ */
+export function buildImageMap<T>(mods: Record<string, { default: T }>): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(mods).map(([path, mod]) => {
+      const slug = path.split('/').pop()!.replace('.webp', '');
+      return [slug, mod.default];
+    })
+  );
+}
+
+export const keyBySlug = buildImageMap;

package/src/url/index.ts

@@ -1,2 +1,5 @@
-// Public surface of @sarimarcus/content-sites-core/url. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-core/url.
+export { url, normalizePagePath, toAbsoluteSiteUrl, normalizeSiteUrl } from './url.ts';
+export { getOgImagePath } from './ogImage.ts';
+export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.ts';
+export { buildImageMap, keyBySlug } from './imageMap.ts';

package/src/url/ogImage.ts

@@ -0,0 +1,7 @@
+/**
+ * The og:image path for a content item: /images/og/{type}/{slug}.jpg.
+ * The images are pre-generated by `npm run images:og` into public/images/og/ (factory scripts/og-images).
+ */
+export function getOgImagePath(type: string, slug: string): string {
+  return `/images/og/${type}/${slug}.jpg`;
+}

package/src/url/relatedDedup.ts

@@ -0,0 +1,41 @@
+// `null` = skip dedup (external/anchor hrefs are always kept as-is).
+// Exported because callers build taken-href Sets from mixed inputs (prose HTML, cards, url()-applied hrefs)
+// and every member must be in THIS normal form or dedupRelated() silently never matches it.
+// `basePath` must arrive with its trailing slash already stripped.
+export function normalizeHref(href: string, basePath = ''): string | null {
+  if (!href) return null;
+  let h = href;
+  if (basePath && h.startsWith(basePath)) h = h.slice(basePath.length);
+  if (!h.startsWith('/')) return null;
+  h = h.split('#')[0].split('?')[0];
+  h = h.replace(/\/+$/, '') || '/';
+  return h;
+}
+
+export function extractProseHrefs(htmlChunks: (string | undefined | null)[], basePath = ''): Set<string> {
+  const hrefs = new Set<string>();
+  const re = /<a\b[^>]*\bhref=["']([^"']+)["']/gi;
+  const normalizedBase = basePath.replace(/\/+$/, '');
+  for (const html of htmlChunks) {
+    if (!html) continue;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(html))) {
+      const n = normalizeHref(m[1], normalizedBase);
+      if (n) hrefs.add(n);
+    }
+  }
+  return hrefs;
+}
+
+export function dedupRelated<T extends { href: string }>(
+  items: T[],
+  proseHrefs: Set<string>,
+  basePath = '',
+): T[] {
+  if (items.length === 0 || proseHrefs.size === 0) return items;
+  const normalizedBase = basePath.replace(/\/+$/, '');
+  return items.filter((it) => {
+    const n = normalizeHref(it.href, normalizedBase);
+    return n === null || !proseHrefs.has(n);
+  });
+}

package/src/url/url.ts

@@ -0,0 +1,74 @@
+/** Prepend the site base path to a path, without doubling slashes. */
+export function url(path: string, basePath = '/'): string {
+  const cleanBase = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  return `${cleanBase}${cleanPath}`;
+}
+
+function normalizeBasePath(basePath: string): string {
+  if (!basePath || basePath === '/') return '';
+  return basePath.replace(/\/$/, '');
+}
+
+export function normalizePagePath(pathname: string, basePath = '/'): string {
+  const cleanBase = normalizeBasePath(basePath);
+  let normalized = pathname || '/';
+
+  if (!normalized.startsWith('/')) {
+    normalized = `/${normalized}`;
+  }
+
+  normalized = normalized.replace(/\/index\.html$/, '/');
+
+  if (cleanBase && normalized === `${cleanBase}.html`) {
+    normalized = `${cleanBase}/`;
+  } else {
+    normalized = normalized.replace(/\.html$/, '');
+  }
+
+  const isHomepage =
+    normalized === '/' ||
+    normalized === cleanBase ||
+    normalized === `${cleanBase}/`;
+
+  if (isHomepage) {
+    return cleanBase ? `${cleanBase}/` : '/';
+  }
+
+  return normalized.replace(/\/$/, '');
+}
+
+export function toAbsoluteSiteUrl(pathname: string, siteUrl: string, basePath = '/'): string {
+  return new URL(
+    normalizePagePath(pathname, basePath),
+    siteUrl.endsWith('/') ? siteUrl : `${siteUrl}/`,
+  ).toString();
+}
+
+export function normalizeSiteUrl(input: string, siteUrl: string, basePath = '/'): string {
+  if (!input) return input;
+
+  if (input.startsWith('/')) {
+    const relativeUrl = new URL(`https://internal${input}`);
+    const normalizedPath = normalizePagePath(relativeUrl.pathname, basePath);
+    return `${normalizedPath}${relativeUrl.search}${relativeUrl.hash}`;
+  }
+
+  if (!/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(input)) {
+    return input;
+  }
+
+  try {
+    const parsedUrl = new URL(input);
+    const parsedSiteUrl = new URL(siteUrl);
+
+    if (parsedUrl.origin !== parsedSiteUrl.origin) {
+      return input;
+    }
+
+    parsedUrl.pathname = normalizePagePath(parsedUrl.pathname, basePath);
+    return parsedUrl.toString();
+  } catch {
+    return input;
+  }
+}