@iterant/site-runtime 3.12.0 → 3.13.0

package/src/lib/canonical-scope.ts

@@ -0,0 +1,108 @@
+// Which paths the origin in `astro.config.mjs` actually serves.
+//
+// The production deploy bakes the CUSTOMER's origin into `site`, and in path
+// routing the customer forwards one prefix and nothing else: `/<folder>/*`.
+// Translations live under that same prefix (`/<folder>/<locale>/x`), so the one
+// rule covers them too.
+// Every other route of the build (the brand home at `/`, the holding page,
+// anything outside the folder) lives on the platform's own host alone. A
+// canonical, an og:url or a sitemap `<loc>` that names the customer's origin
+// for one of those points at a URL their edge answers with their own site,
+// which is how a link preview sends a reader to the wrong page.
+//
+// `host` is every build that came before this one: the origin serves the whole
+// site and nothing here changes a byte of what it emits.
+
+export type CanonicalScopeName = "host" | "folder";
+
+export interface CanonicalScope {
+  name: CanonicalScopeName;
+  /** The one segment the customer forwards. Empty under `host`. */
+  folder: string;
+  /** The origin an out-of-scope path resolves against. Null under `host`. */
+  platformSite: string | null;
+}
+
+/** The default, and what every build declared before the scope existed. */
+export const HOST_SCOPE: CanonicalScope = {
+  name: "host",
+  folder: "",
+  platformSite: null,
+};
+
+/** The build's environment, where the deploy states the scope. The index
+ *  signature is what lets `process.env` be passed straight in. */
+export interface CanonicalScopeEnv {
+  ITERANT_CANONICAL_SCOPE?: string;
+  ITERANT_PLATFORM_SITE?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * The scope this build runs under, from the deploy's environment and the
+ * folder the preset was given.
+ *
+ * Folder scope with no folder, or with no platform origin to send the rest of
+ * the site to, is a deploy that would emit customer URLs for pages the customer
+ * never serves. There is no safe reading of it, so the build stops here rather
+ * than at the first crawler.
+ */
+export function readCanonicalScope(
+  env: CanonicalScopeEnv,
+  folder: string,
+): CanonicalScope {
+  const name = env.ITERANT_CANONICAL_SCOPE?.trim() || "host";
+  if (name !== "host" && name !== "folder") {
+    throw new Error(
+      `ITERANT_CANONICAL_SCOPE must be "host" or "folder" (got ${JSON.stringify(name)})`,
+    );
+  }
+  if (name === "host") return HOST_SCOPE;
+  const platformSite = env.ITERANT_PLATFORM_SITE?.trim() ?? "";
+  if (!folder) {
+    throw new Error(
+      "ITERANT_CANONICAL_SCOPE=folder needs a folder: pass the brand's folder to iterantStarter({ folder })",
+    );
+  }
+  if (!platformSite) {
+    throw new Error(
+      "ITERANT_CANONICAL_SCOPE=folder needs ITERANT_PLATFORM_SITE, the origin that serves the routes the customer's domain does not",
+    );
+  }
+  if (!URL.canParse(platformSite)) {
+    throw new Error(
+      `ITERANT_PLATFORM_SITE must be an absolute origin (got ${JSON.stringify(platformSite)})`,
+    );
+  }
+  return { name, folder, platformSite: new URL(platformSite).origin };
+}
+
+/**
+ * Whether the build's `site` origin serves this path. Always true under `host`.
+ *
+ * The folder is matched SEGMENT-wise, never as a string prefix, so `/feedback`
+ * is out of scope for the folder `feed`. The locale needs no test of its own:
+ * a translation lives under the folder like every other page.
+ */
+export function inCanonicalScope(
+  pathname: string,
+  scope: CanonicalScope,
+): boolean {
+  if (scope.name === "host") return true;
+  const segments = pathname.split("/").filter(Boolean);
+  return segments[0] === scope.folder;
+}
+
+/**
+ * The origin a path's absolute URL resolves against: the build's `site` when
+ * the path is in scope, the platform origin when it is not. Under `host` it is
+ * always `site`, so every emitter that calls this keeps emitting what it did.
+ */
+export function originForPath<T extends URL | string | undefined>(
+  pathname: string,
+  scope: CanonicalScope,
+  site: T,
+): T | string {
+  if (!scope.platformSite || inCanonicalScope(pathname, scope)) return site;
+  return scope.platformSite;
+}

package/src/lib/hreflang-derive.ts

@@ -0,0 +1,118 @@
+import { isAdvertised } from "./advertised";
+import { originForPath, type CanonicalScope } from "./canonical-scope";
+import { DEFAULT_LOCALE, normalizeBcp47, parseEntryId } from "./locales";
+
+// hreflang alternates for locale sibling pages (starter 2.9.0). A page with
+// locale siblings advertises one `<link rel="alternate" hreflang>` per
+// NON-DRAFT sibling in the group, plus exactly one `x-default` pointing at the
+// unsuffixed base entry. A page with no siblings emits nothing. Ported from the
+// legacy `derive_hreflang_set` (backend translation_group.py): published/
+// indexable rows only (starter: non-draft), one x-default = the default-locale
+// row, deduped on a normalized locale key, hreflang values in canonical BCP-47.
+//
+// The DERIVATION alone lives here, so it imports no virtual module and the
+// package's pure entry can re-export it. The scope is an argument rather than a
+// default: a caller that does not know which origin serves which path cannot
+// spell these hrefs, and a default would let it emit customer URLs for pages
+// the customer never serves. ./hreflang.ts is where that caller reads it.
+
+/** One reciprocal hreflang alternate. `hreflang` is BCP-47 or "x-default". */
+export interface HreflangAlternate {
+  hreflang: string;
+  href: string;
+}
+
+/** The minimal page-entry shape the derivation reads. */
+export interface HreflangEntry {
+  /** Collection entry id (`example`, `example.es`). */
+  id: string;
+  /** The entry's `route` field (`/example`, `/es/example`). */
+  route: string;
+  draft: boolean;
+  /** Kept out of search; never advertised as an alternate. */
+  noindex?: boolean;
+}
+
+/** A `pages` collection entry, as `pageLocaleHead` consumes it. */
+export interface PagesCollectionEntry {
+  id: string;
+  data: { route: string; draft: boolean; noindex?: boolean };
+}
+
+/**
+ * The `<html lang>` value for a page, from its entry id: base entries are the
+ * brand default (`en`); siblings carry their locale in canonical BCP-47
+ * casing (`example.pt-br` → `pt-BR`).
+ */
+export function pageLang(entryId: string): string {
+  const { locale } = parseEntryId(entryId);
+  return locale ? normalizeBcp47(locale) : DEFAULT_LOCALE;
+}
+
+function absolute(
+  route: string,
+  site: URL | string | undefined,
+  scope: CanonicalScope,
+): string {
+  if (!site) return route; // dev without a configured `site`, relative href
+  return new URL(
+    route,
+    originForPath(route, scope, site).toString(),
+  ).toString();
+}
+
+/**
+ * The reciprocal hreflang set for the group `baseName` belongs to, derived from
+ * ALL page entries (the caller passes the whole collection). Every non-draft
+ * entry in the group contributes one alternate; the base entry also seeds the
+ * single `x-default`. Draft and noindex siblings are never advertised
+ * (unpublished translations and private pages must not leak to crawlers). Deduped on the normalized locale key
+ * (first entry wins); hrefs absolute via `site` (`Astro.site`), or via the
+ * platform origin for a route that site does not serve. Returns `[]`
+ * when the group has no non-draft siblings — a lone page emits no hreflang.
+ */
+export function deriveHreflangAlternates(params: {
+  entries: HreflangEntry[];
+  baseName: string;
+  site: URL | string | undefined;
+  /** Which paths the site origin serves. */
+  scope: CanonicalScope;
+}): HreflangAlternate[] {
+  const { entries, baseName, site, scope } = params;
+
+  const byKey = new Map<
+    string,
+    { tag: string; route: string; isBase: boolean }
+  >();
+  let base: { route: string } | undefined;
+  for (const entry of entries) {
+    // Never advertise a draft or a noindex sibling or base.
+    if (!isAdvertised(entry, { includeDrafts: false })) continue;
+    const { base: entryBase, locale } = parseEntryId(entry.id);
+    if (entryBase !== baseName) continue;
+    const isBase = !locale;
+    const tag = isBase ? DEFAULT_LOCALE : normalizeBcp47(locale);
+    const key = tag.toLowerCase();
+    if (isBase) base = { route: entry.route };
+    if (!byKey.has(key)) byKey.set(key, { tag, route: entry.route, isBase });
+  }
+
+  const hasSibling = [...byKey.values()].some((alt) => !alt.isBase);
+  if (!hasSibling) return [];
+
+  const ordered = [...byKey.values()].sort((a, b) => {
+    if (a.isBase !== b.isBase) return a.isBase ? -1 : 1; // base first
+    return a.tag.localeCompare(b.tag);
+  });
+  const alternates: HreflangAlternate[] = ordered.map((alt) => ({
+    hreflang: alt.tag,
+    href: absolute(alt.route, site, scope),
+  }));
+  if (base) {
+    alternates.push({
+      hreflang: "x-default",
+      href: absolute(base.route, site, scope),
+    });
+  }
+  return alternates;
+}

package/src/lib/hreflang.ts

@@ -1,46 +1,22 @@
-import { isAdvertised } from "./advertised";
-import { DEFAULT_LOCALE, normalizeBcp47, parseEntryId } from "./locales";
-
-// hreflang alternates for locale sibling pages (starter 2.9.0). A page with
-// locale siblings advertises one `<link rel="alternate" hreflang>` per
-// NON-DRAFT sibling in the group, plus exactly one `x-default` pointing at the
-// unsuffixed base entry. A page with no siblings emits nothing. Ported from the
-// legacy `derive_hreflang_set` (backend translation_group.py): published/
-// indexable rows only (starter: non-draft), one x-default = the default-locale
-// row, deduped on a normalized locale key, hreflang values in canonical BCP-47.
-
-/** One reciprocal hreflang alternate. `hreflang` is BCP-47 or "x-default". */
-export interface HreflangAlternate {
-  hreflang: string;
-  href: string;
-}
-
-/** The minimal page-entry shape the derivation reads. */
-export interface HreflangEntry {
-  /** Collection entry id (`example`, `example.es`). */
-  id: string;
-  /** The entry's `route` field (`/example`, `/es/example`). */
-  route: string;
-  draft: boolean;
-  /** Kept out of search; never advertised as an alternate. */
-  noindex?: boolean;
-}
-
-/** A `pages` collection entry, as `pageLocaleHead` consumes it. */
-export interface PagesCollectionEntry {
-  id: string;
-  data: { route: string; draft: boolean; noindex?: boolean };
-}
-
-/**
- * The `<html lang>` value for a page, from its entry id: base entries are the
- * brand default (`en`); siblings carry their locale in canonical BCP-47
- * casing (`example.pt-br` → `pt-BR`).
- */
-export function pageLang(entryId: string): string {
-  const { locale } = parseEntryId(entryId);
-  return locale ? normalizeBcp47(locale) : DEFAULT_LOCALE;
-}
+import { CANONICAL_SCOPE, FOLDER, PLATFORM_SITE } from "virtual:iterant/site";
+
+import {
+  deriveHreflangAlternates,
+  pageLang,
+  type HreflangAlternate,
+  type PagesCollectionEntry,
+} from "./hreflang-derive";
+import { parseEntryId } from "./locales";
+
+// The locale head a page renders, as a repo calls it
+// (`@iterant/site-runtime/hreflang`). It is the derivation in
+// ./hreflang-derive.ts plus the one fact a repo cannot supply: which paths the
+// baked `site` origin actually serves. That comes from the preset, through the
+// virtual module the layout and the platform routes already read, so a page
+// under a customer's forwarded folder advertises its siblings on their domain
+// and a page outside it advertises them on ours. No repo has to know, and none
+// can get it wrong.
+export * from "./hreflang-derive";
 
 /**
  * The locale head pair every page emits (starter 2.10.0): `<html lang>` plus
@@ -65,64 +41,11 @@ export function pageLocaleHead(params: {
       })),
       baseName: parseEntryId(params.entryId).base,
       site: params.site,
+      scope: {
+        name: CANONICAL_SCOPE,
+        folder: FOLDER,
+        platformSite: PLATFORM_SITE,
+      },
     }),
   };
 }
-
-function absolute(route: string, site: URL | string | undefined): string {
-  if (!site) return route; // dev without a configured `site` — relative href
-  return new URL(route, site.toString()).toString();
-}
-
-/**
- * The reciprocal hreflang set for the group `baseName` belongs to, derived from
- * ALL page entries (the caller passes the whole collection). Every non-draft
- * entry in the group contributes one alternate; the base entry also seeds the
- * single `x-default`. Draft and noindex siblings are never advertised
- * (unpublished translations and private pages must not leak to crawlers). Deduped on the normalized locale key
- * (first entry wins); hrefs absolute via `site` (`Astro.site`). Returns `[]`
- * when the group has no non-draft siblings — a lone page emits no hreflang.
- */
-export function deriveHreflangAlternates(params: {
-  entries: HreflangEntry[];
-  baseName: string;
-  site: URL | string | undefined;
-}): HreflangAlternate[] {
-  const { entries, baseName, site } = params;
-
-  const byKey = new Map<
-    string,
-    { tag: string; route: string; isBase: boolean }
-  >();
-  let base: { route: string } | undefined;
-  for (const entry of entries) {
-    // Never advertise a draft or a noindex sibling or base.
-    if (!isAdvertised(entry, { includeDrafts: false })) continue;
-    const { base: entryBase, locale } = parseEntryId(entry.id);
-    if (entryBase !== baseName) continue;
-    const isBase = !locale;
-    const tag = isBase ? DEFAULT_LOCALE : normalizeBcp47(locale);
-    const key = tag.toLowerCase();
-    if (isBase) base = { route: entry.route };
-    if (!byKey.has(key)) byKey.set(key, { tag, route: entry.route, isBase });
-  }
-
-  const hasSibling = [...byKey.values()].some((alt) => !alt.isBase);
-  if (!hasSibling) return [];
-
-  const ordered = [...byKey.values()].sort((a, b) => {
-    if (a.isBase !== b.isBase) return a.isBase ? -1 : 1; // base first
-    return a.tag.localeCompare(b.tag);
-  });
-  const alternates: HreflangAlternate[] = ordered.map((alt) => ({
-    hreflang: alt.tag,
-    href: absolute(alt.route, site),
-  }));
-  if (base) {
-    alternates.push({
-      hreflang: "x-default",
-      href: absolute(base.route, site),
-    });
-  }
-  return alternates;
-}

package/src/lib/locales.ts

@@ -2,8 +2,9 @@ import { z } from "astro/zod";
 
 // Locale sibling entries (starter 2.8.0): a translated page is a first-class
 // content entry next to its base — `src/content/pages/<page>.<locale>.json`
-// with the lowercased locale as both the filename suffix and the root-level
-// route prefix (`/es/pricing`); the unsuffixed base stays the x-default.
+// with the lowercased locale as both the filename suffix and the route segment
+// the translation lives under (`/es/pricing`, or `/feed/es/pricing` under a
+// brand folder); the unsuffixed base stays the x-default.
 // Site chrome follows the same model (`src/content/chrome.<locale>.json`),
 // resolved per request path with fallback to the base chrome. `<html lang>`
 // and hreflang alternates are derived from the entry locale (see
@@ -62,14 +63,20 @@ export function normalizeBcp47(locale: string): string {
 }
 
 /**
- * The locale segment a request path is prefixed with, if any: `/es/pricing`
- * → `es`, `/pt-br` → `pt-br`, `/pricing` → undefined. Grammar-only — the
- * caller decides whether a matching sibling (chrome.<locale>.json) actually
- * exists and falls back to the base otherwise, so a page that merely LOOKS
- * locale-shaped costs nothing.
+ * The locale segment a request path carries, if any: `/es/pricing` → `es`,
+ * `/pt-br` → `pt-br`, `/pricing` → undefined. Under a brand folder the locale
+ * sits inside it, so `localeFromPath("/feed/es/pricing", "feed")` is `es`:
+ * that is what lets the customer forward `/feed/*` alone and still reach every
+ * translation. Grammar-only — the caller decides whether a matching sibling
+ * (chrome.<locale>.json) actually exists and falls back to the base otherwise,
+ * so a page that merely LOOKS locale-shaped costs nothing.
  */
-export function localeFromPath(pathname: string): string | undefined {
-  const [first] = pathname.split("/").filter(Boolean);
+export function localeFromPath(
+  pathname: string,
+  folder?: string,
+): string | undefined {
+  const segments = pathname.split("/").filter(Boolean);
+  const first = segments[folder && segments[0] === folder ? 1 : 0];
   return first && LOCALE_SEGMENT_RE.test(first) ? first : undefined;
 }
 

package/src/lib/sitemap/index.ts

@@ -5,6 +5,7 @@
 export { DEFAULT_PAGES_DIR } from "../content-paths";
 export { getSitemapPaths, type SitemapPathsOptions } from "./get-sitemap-paths";
 export {
+  createSitemapFilter,
   sitemapWithCustomPages,
   type SitemapWithCustomPagesOptions,
 } from "./sitemap-with-custom-pages-plugin";

package/src/lib/sitemap/sitemap-with-custom-pages-plugin.ts

@@ -2,6 +2,11 @@ import { fileURLToPath } from "node:url";
 import sitemap, { type SitemapOptions } from "@astrojs/sitemap";
 import type { AstroIntegration } from "astro";
 
+import {
+  HOST_SCOPE,
+  inCanonicalScope,
+  type CanonicalScope,
+} from "../canonical-scope";
 import { getSitemapPaths, type SitemapPathsOptions } from "./get-sitemap-paths";
 
 // The platform patches the `site:` literal at deploy time, so we emit URLs against a
@@ -14,29 +19,69 @@ const PLACEHOLDER = "https://starter.invalid";
 // names them here.
 const PLATFORM_DENY = new Set(["/under-construction"]);
 
-/** Whether a sitemap URL may be listed: neither a platform route nor a denied
- *  entry route (a draft or a noindex page), whichever way the integration
- *  found it. */
+/** Whether a sitemap URL may be listed: in the canonical scope, and neither a
+ *  platform route nor a denied entry route (a draft or a noindex page),
+ *  whichever way the integration found it. An out-of-scope path is not served
+ *  on the origin the `<loc>` would name, so listing it points a crawler at the
+ *  customer's own site. */
 export function sitemapPageAllowed(
   url: string,
   deny: ReadonlySet<string> = new Set(),
+  scope: CanonicalScope = HOST_SCOPE,
 ): boolean {
+  const pathname = sitemapPath(url);
+  if (pathname === undefined) return true;
+  return (
+    !PLATFORM_DENY.has(pathname) &&
+    !deny.has(pathname) &&
+    inCanonicalScope(pathname, scope)
+  );
+}
+
+/** A candidate's path in entry-route form, or undefined when it is not a URL
+ *  the integration can read. */
+function sitemapPath(url: string): string | undefined {
   try {
-    const pathname = new URL(url).pathname.replace(/\/+$/, "") || "/";
-    return !PLATFORM_DENY.has(pathname) && !deny.has(pathname);
+    return new URL(url).pathname.replace(/\/+$/, "") || "/";
   } catch {
-    return true;
+    return undefined;
   }
 }
 
+/**
+ * The integration's page filter: the rule above, plus first-one-wins on a
+ * repeated path.
+ *
+ * @astrojs/sitemap discovers the prerendered pages itself AND is handed the
+ * entry routes as customPages, so a bespoke page that also has a page entry
+ * arrives twice and is listed twice. One pass over the candidates, so the state
+ * is the filter's own and a new build gets a new one.
+ */
+export function createSitemapFilter(
+  deny: ReadonlySet<string> = new Set(),
+  scope: CanonicalScope = HOST_SCOPE,
+): (url: string) => boolean {
+  const listed = new Set<string>();
+  return (url) => {
+    if (!sitemapPageAllowed(url, deny, scope)) return false;
+    const pathname = sitemapPath(url) ?? url;
+    if (listed.has(pathname)) return false;
+    listed.add(pathname);
+    return true;
+  };
+}
+
 export type SitemapWithCustomPagesOptions = SitemapOptions &
-  SitemapPathsOptions;
+  SitemapPathsOptions & {
+    /** Which paths the site origin serves. Defaults to the whole host. */
+    scope?: CanonicalScope;
+  };
 
 export function sitemapWithCustomPages(
   options: SitemapWithCustomPagesOptions = {},
 ): AstroIntegration[] {
   let resolvedSite = "";
-  const { pagesDir, root, ...sitemapOptions } = options;
+  const { pagesDir, root, scope = HOST_SCOPE, ...sitemapOptions } = options;
   const userSerialize = sitemapOptions.serialize;
   const userFilter = sitemapOptions.filter;
 
@@ -47,8 +92,10 @@ export function sitemapWithCustomPages(
   // populated before anything reads it.
   const customPages: string[] = [...(sitemapOptions.customPages ?? [])];
   // Filled beside customPages: the entry routes the integration must not list
-  // from its own crawl of prerendered pages.
+  // from its own crawl of prerendered pages. The filter reads it by reference,
+  // so it sees whatever astro:config:setup put there.
   const denied = new Set<string>();
+  const allowed = createSitemapFilter(denied, scope);
 
   return [
     {
@@ -96,9 +143,7 @@ export function sitemapWithCustomPages(
     sitemap({
       ...sitemapOptions,
       customPages,
-      filter: (page) =>
-        sitemapPageAllowed(page, denied) &&
-        (userFilter ? userFilter(page) : true),
+      filter: (page) => (userFilter ? userFilter(page) : true) && allowed(page),
       serialize(item) {
         if (resolvedSite && item.url.startsWith(PLACEHOLDER)) {
           item.url = resolvedSite + item.url.slice(PLACEHOLDER.length);

package/src/routes/index.ts

@@ -7,7 +7,12 @@
 // (site-runtime 3.12.0): the folder is per-brand data, so no file name the
 // template ships can carry it, and the preset injects the same handler at
 // /<folder>/llms.txt (../config/site-module.ts).
-export { createLlmsTxtRoute, type LlmsTxtOptions } from "./llms-txt";
+export {
+  createLlmsTxtRoute,
+  renderLlmsTxt,
+  type LlmsTxtOptions,
+  type LlmsTxtPage,
+} from "./llms-txt";
 export {
   AI_ANSWER_CRAWLERS,
   AI_POLICY_PRESETS,