@iterant/site-runtime 3.11.2 → 3.13.0

package/bin/site-runtime.mjs

@@ -5,6 +5,7 @@
  * brand repo root.
  *
  *   site-runtime verify                    # the gate: fonts, islands, lint, check, tests, build, bespoke siblings, editor bytes
+ *   site-runtime verify --lint <path...>   # the same gate, linting only those paths (none: skip the lint step)
  *   site-runtime scan-copy [files...]      # hardcoded visible copy in component code
  *   site-runtime scan-island-imports [dir] # island-grade ui primitives imported by registered sections
  *   site-runtime scan-bespoke-siblings     # bespoke locale-sibling hydration contract (after a build)

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.11.2._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.13.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -526,9 +526,11 @@ platform and must remain a string literal, so the sitemap helper emits against a
 placeholder host and swaps it at emit time.
 
 Platform routes stay VISIBLE files in `src/pages/`, each a shim over a package
-handler. Nothing is injected: existence and addressing stay repo-owned so the
-`src/pages/` mental model holds, while the behavior rides the bump. A repo
-carries FOUR of them, all four unconditionally:
+handler: existence and addressing stay repo-owned so the `src/pages/` mental
+model holds, while the behavior rides the bump. One route is addressed by the
+platform instead, llms.txt under a brand folder (see The brand folder), because
+no file name a template ships can carry a per-brand path segment. A repo carries
+FOUR of them, all four unconditionally:
 
 | File                                   | Handler                     | `prerender` |
 | -------------------------------------- | --------------------------- | ----------- |
@@ -569,6 +571,141 @@ extends rather than ejects: extra integrations and vite plugins append through
 `overrides`, and any other key it needs it writes in its own `defineConfig`
 object after the spread.
 
+### The brand folder (3.12.0)
+
+Every platform file a build emits can live under one path segment, the brand's
+folder:
+
+```js
+import { SITE_CONFIG } from "./src/site-config";
+
+export default defineConfig({
+  site: "https://example.com",
+  ...iterantStarter({ folder: SITE_CONFIG.folder }),
+});
+```
+
+It exists for the customer's own domain. A brand served in a subfolder is
+reached through one forwarding rule, `example.com/feed/*`, and anything a page
+asks for outside that prefix 404s on the customer's site. So with
+`folder: "feed"` set:
+
+| What                           | Where it lands                                   |
+| ------------------------------ | ------------------------------------------------ |
+| hashed assets (`build.assets`) | `/feed/_astro/*`, fonts included                 |
+| immutable `Cache-Control` rule | `/feed/_astro/*`, written by the adapter         |
+| sitemap index and its children | `/feed/sitemap-index.xml`, `/feed/sitemap-0.xml` |
+| llms.txt                       | `/feed/llms.txt`, injected by the preset         |
+| the head's icon link           | `/feed/favicon.ico`                              |
+| robots.txt                     | the root, with its `Sitemap:` line in the folder |
+| the mirrored legacy sitemaps   | the root, the URLs the old site advertised       |
+
+**Pages do not move.** A page keeps the public path it is authored at, in every
+serving mode, and every `<loc>` in the sitemap is that same path. The folder is
+where the platform's own files live, not a prefix for the site.
+
+The value is the backend's `brand.iterant_subfolder`, written into
+`SITE_CONFIG.folder` beside the fonts, and `astro.config.mjs` hands it to the
+preset. The PRESET is then the only source: it places the hashed assets and the
+sitemap, and it publishes the folder to the package's own code through a virtual
+module, which is where the layout's icon link, `robots.txt` and llms.txt read
+it. Nothing reads `SITE_CONFIG.folder` a second time, so the value cannot
+disagree with itself. It must be one lower-case segment of letters, digits and
+hyphens, the shape Django validates (`backend/brands/folder.py`), which also
+refuses the reserved names and anything shaped like a language code. Absent or
+empty, everything stays at the root, byte-identical to a build before this
+option existed.
+
+Two repo-side consequences: `public/favicon.ico` moves to
+`public/<folder>/favicon.ico`, and the root `src/pages/llms.txt.ts` goes away,
+since the preset addresses that route. A repo that keeps the root file still
+builds and still serves `/llms.txt`, at a URL the customer's domain does not
+forward; the build warns until the file is deleted.
+
+### What 3.13.0 changes in every scope
+
+Three things differ from 3.12.0 even with the scope left at its default:
+
+- The BreadcrumbList folds the brand folder and the locale into its root crumb
+  (`/feed/es` for a translated page under the folder, `/feed` for a plain one),
+  so no crumb points at `/` and no crumb is named after the folder. A page that
+  is the folder index alone emits no BreadcrumbList.
+- The sitemap lists a route once when a prerendered page and a content entry
+  share it; the first one the plugin sees wins.
+- The package root no longer exports `pageLocaleHead`: it reads the virtual
+  site module, and the root stays importable outside an Astro build. Pages
+  import it from `@iterant/site-runtime/hreflang`, as the starter always did.
+  The pure `deriveHreflangAlternates` takes the scope as a required argument.
+- `verify` accepts exactly one option, `--lint <path...>`; any other option,
+  including `--lint=path`, is refused with exit 2.
+
+### The canonical scope (3.13.0)
+
+A production deploy bakes the CUSTOMER's origin into `site`, and in path routing
+the customer forwards one prefix: `/<folder>/*`, translations included, since a
+translated page lives under the folder (`/<folder>/<locale>/x`). Every other
+route of the build (the brand home at `/`, `/under-construction`, anything
+outside the folder) is served on the platform's own host alone. Spelling those
+against `site` points a crawler, and every link preview, at the customer's real
+homepage.
+
+The deploy states the scope in the build environment, not in the repo, because
+the same tree builds for both:
+
+| Variable                  | Value                                   |
+| ------------------------- | --------------------------------------- |
+| `ITERANT_CANONICAL_SCOPE` | `host` (the default) or `folder`        |
+| `ITERANT_PLATFORM_SITE`   | the platform origin, under folder scope |
+
+`folder` with no folder, or with no platform origin, fails the build: there is
+no safe reading of a deploy that would spell customer URLs for pages the
+customer never serves. `host` is what every build before this one declared, and
+under it every emitter below writes exactly the bytes it wrote then.
+
+Under `folder`, a path is IN scope when its first segment is the folder. The
+folder matches a whole segment, so `/feedback` is out of scope for the folder
+`feed`. Then:
+
+| Emitter                             | In scope                                    | Out of scope                    |
+| ----------------------------------- | ------------------------------------------- | ------------------------------- |
+| canonical, `og:url`, `og:image`     | the `site` origin                           | the platform origin             |
+| `<meta name="robots">`              | the page's own setting                      | `noindex, nofollow`             |
+| JSON-LD page `url` and `@id`        | the `site` origin                           | no graph at all (it is noindex) |
+| JSON-LD breadcrumb ancestors        | crumbs above the folder are DROPPED         | n/a                             |
+| hreflang alternates                 | the `site` origin                           | the platform origin             |
+| sitemap `<loc>`                     | listed                                      | left out                        |
+| llms.txt links                      | listed, `site` origin                       | left out                        |
+| robots.txt `Sitemap:` index line    | always, `{site}/<folder>/sitemap-index.xml` | n/a                             |
+| robots.txt mirrored `Sitemap:` line | n/a                                         | not advertised                  |
+
+Breadcrumb ancestors are dropped rather than relinked: `/` and the folder's
+locale root on the customer's domain lead to the customer's own homepage, and a
+crumb naming it would put the brand's trail on a page the brand does not own. A
+page whose only surviving crumb is itself emits no `BreadcrumbList`, the way a
+home page does.
+
+**llms.txt names no second host.** The file is read on whichever host served it,
+so a link to our origin inside the customer's copy advertises it to every
+assistant that reads the file. Under folder scope it carries only paths the
+customer serves: the pages inside the folder and the generated sitemap index.
+The Home line and the Robots policy line are at the root, so they go, and a
+section left with no lines goes with its heading.
+
+**robots.txt does not move.** It is a host-level file, read at the root of
+whichever host serves it. Its index line keeps naming
+`{site}/<folder>/sitemap-index.xml`, which is where the build writes the index.
+The MIRRORED sitemap (`sourceSitemapUrl`) is a root URL, so under folder scope
+it is not advertised at all; host scope advertises it exactly as before.
+
+**hreflang reads the scope itself.** `pageLocaleHead`
+(`@iterant/site-runtime/hreflang`) takes no scope argument: it reads it from the
+preset through the same virtual module the layout uses, so a page inside the
+folder advertises its siblings on the customer's domain and a page outside it
+advertises them on ours, with nothing for a repo to pass or get wrong. The pure
+derivation underneath, `deriveHreflangAlternates`, takes the scope as a required
+argument and is re-exported from the package root for callers outside an Astro
+build.
+
 ### Web fonts (3.8.0)
 
 A site names its font families once, in `SITE_CONFIG.fonts`, and passes the same
@@ -818,7 +955,12 @@ change is broken. In order:
 3. **island imports**: no island-grade ui primitive is imported under
    `src/components/sections/`.
 4. **eslint**, then **astro check**, then the repo's own unit tests, then
-   **astro build**.
+   **astro build**. `site-runtime verify --lint <path...>` lints those paths
+   instead of the whole repo, and `--lint` with no paths skips the lint step:
+   the runtime bump runs this gate after a mechanical rewrite, and a replica
+   carrying a lint error in a file the bump never touched would otherwise block
+   every future bump. It narrows the LINT alone, so the check, the tests and the
+   build still cover the whole repo.
 5. **bespoke siblings**: every non-draft bespoke page satisfies the two
    hydration conventions, checked against the fresh `dist/`, plus a pin on the
    Astro runtime directive contract they rely on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.11.2",
+  "version": "3.13.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/scripts/verify.mjs

@@ -32,6 +32,10 @@
  * Run from the repo root via `bun run verify` / `npm run verify` (which map to
  * `site-runtime verify`). Every path below resolves against process.cwd(), the
  * repo being verified — the gates themselves live in node_modules.
+ *
+ * One option: `--lint <path...>` lints those paths instead of the whole repo,
+ * and `--lint` with no paths skips the lint step. See the comment on the step
+ * list for why.
  */
 
 import { spawn } from "node:child_process";
@@ -234,9 +238,29 @@ if (islandProblems.length > 0) {
   exit(1);
 }
 
+// `--lint <path...>` narrows the lint step to those paths, and `--lint` with
+// none skips it. The runtime bump runs this gate in a brand sandbox after a
+// mechanical rewrite, and a replica that carries a lint error in a file the
+// bump never touched (a vendored analytics snippet, say) would otherwise block
+// every future bump on a fault the bump did not introduce. It narrows the LINT
+// alone: the check, the tests and the build still cover the whole repo, so
+// nothing the rewrite broke can hide behind it.
+const argv = process.argv.slice(2);
+const unknown = argv.find((arg) => arg.startsWith("-") && arg !== "--lint");
+if (unknown !== undefined) {
+  process.stderr.write(
+    `verify: unknown option ${unknown}; the only option is --lint <path...>\n`,
+  );
+  exit(2);
+}
+const lintIndex = argv.indexOf("--lint");
+const lintPaths = lintIndex === -1 ? ["."] : argv.slice(lintIndex + 1);
+/** @type {Array<[string, string[]]>} */
+const lintStep = lintPaths.length > 0 ? [["eslint", lintPaths]] : [];
+
 /** @type {Array<[string, string[]]>} */
 const steps = [
-  ["eslint", ["."]],
+  ...lintStep,
   ["astro", ["check"]],
   // The repo's own unit tests (bun:test). The content grammar's own suite ships
   // with this package; what runs here is whatever the brand repo keeps under

package/src/components/seo.tsx

@@ -1,3 +1,8 @@
+import {
+  HOST_SCOPE,
+  inCanonicalScope,
+  type CanonicalScope,
+} from "../lib/canonical-scope";
 import { localeFromPath } from "../lib/locales";
 import {
   SeoJson,
@@ -42,6 +47,9 @@ interface SEOProps {
   siteName?: string;
   organization?: OrganizationInfo;
   jsonLd?: SeoJsonSchema | SeoJsonSchema[];
+  /** Which paths this site's origin serves. Breadcrumb ancestors outside it
+   *  are dropped rather than linked. Defaults to the whole host. */
+  scope?: CanonicalScope;
 }
 
 export function SEO({
@@ -58,6 +66,7 @@ export function SEO({
   siteName,
   organization,
   jsonLd,
+  scope = HOST_SCOPE,
 }: SEOProps) {
   const resolvedSiteName = siteName ?? title;
   const fullTitle =
@@ -82,6 +91,7 @@ export function SEO({
         siteName: resolvedSiteName,
         organization,
         extras: jsonLd,
+        scope,
       });
 
   return (
@@ -121,6 +131,7 @@ export interface BuildGraphArgs {
   siteName: string;
   organization?: OrganizationInfo;
   extras?: SeoJsonSchema | SeoJsonSchema[];
+  scope?: CanonicalScope;
 }
 
 // Deterministic schema.org graph for every indexable page. Emitted nodes:
@@ -142,12 +153,13 @@ export function buildJsonLdGraph({
   siteName,
   organization,
   extras,
+  scope = HOST_SCOPE,
 }: BuildGraphArgs): SeoJsonSchema[] {
   const siteUrl = canonicalUrl ? new URL(canonicalUrl).origin : undefined;
   const organizationId = siteUrl ? `${siteUrl}/#organization` : undefined;
   const websiteId = siteUrl ? `${siteUrl}/#website` : undefined;
   const breadcrumb = canonicalUrl
-    ? buildBreadcrumbList({ canonicalUrl, title, siteName })
+    ? buildBreadcrumbList({ canonicalUrl, title, siteName, scope })
     : undefined;
 
   const pageNode = {
@@ -230,39 +242,58 @@ interface BreadcrumbArgs {
   canonicalUrl: string;
   title: string;
   siteName: string;
+  scope: CanonicalScope;
 }
 
 // BreadcrumbList from the canonical path. The root crumb is the site (or the
 // locale home for localized paths), intermediate crumbs are titleized
 // segments, and the last crumb is the page's own title without a link (per
-// Google's guidance the current page needs no item URL). The locale segment
-// itself is never a crumb; it only shifts where the root points. Home pages
-// (no segments) emit no breadcrumb.
+// Google's guidance the current page needs no item URL). Neither the brand
+// folder nor the locale is ever a crumb: both are platform addressing, not
+// something a reader navigated through, so they only shift where the root
+// points, to `/feed`, `/es` or `/feed/es`. Home pages (no segments) emit no
+// breadcrumb.
+//
+// An ancestor outside the canonical scope is DROPPED, not relinked (3.13.0):
+// under folder scope the site root and the locale root are the customer's own
+// homepage, and a crumb naming it would put the brand's trail on a page the
+// brand does not own. What is left can be the current page alone, which is no
+// trail at all, so that emits nothing the way a home page does.
 function buildBreadcrumbList({
   canonicalUrl,
   title,
   siteName,
+  scope,
 }: BreadcrumbArgs) {
   const url = new URL(canonicalUrl);
   const segments = url.pathname.split("/").filter(Boolean);
-  const locale = localeFromPath(url.pathname);
-  const crumbSegments = locale ? segments.slice(1) : segments;
+  const locale = localeFromPath(url.pathname, scope.folder);
+  const rootDepth =
+    (scope.folder && segments[0] === scope.folder ? 1 : 0) + (locale ? 1 : 0);
+  const crumbSegments = segments.slice(rootDepth);
   if (crumbSegments.length === 0) return undefined;
 
-  const rootPath = locale ? `/${locale}` : "/";
-  const items = [
-    { name: siteName, item: new URL(rootPath, url.origin).toString() },
-    ...crumbSegments.map((segment, index) => {
-      const isLast = index === crumbSegments.length - 1;
-      const path = `${rootPath === "/" ? "" : rootPath}/${crumbSegments
+  const rootPath = rootDepth
+    ? `/${segments.slice(0, rootDepth).join("/")}`
+    : "/";
+  const ancestors = [
+    { name: siteName, path: rootPath },
+    ...crumbSegments.slice(0, -1).map((segment, index) => ({
+      name: titleizeSegment(segment),
+      path: `${rootPath === "/" ? "" : rootPath}/${crumbSegments
         .slice(0, index + 1)
-        .join("/")}`;
-      return {
-        name: isLast ? title : titleizeSegment(segment),
-        ...(isLast ? {} : { item: new URL(path, url.origin).toString() }),
-      };
-    }),
+        .join("/")}`,
+    })),
+  ].filter((crumb) => inCanonicalScope(crumb.path, scope));
+
+  const items = [
+    ...ancestors.map((crumb) => ({
+      name: crumb.name,
+      item: new URL(crumb.path, url.origin).toString(),
+    })),
+    { name: title },
   ];
+  if (items.length < 2) return undefined;
 
   return {
     "@context": SCHEMA_CONTEXT,

package/src/config/preset.ts

@@ -12,13 +12,16 @@ import {
   fontCssVariable,
   findFontFamily,
 } from "../fonts/catalog";
+import { readCanonicalScope } from "../lib/canonical-scope";
 import { DEFAULT_CHROME_DIR, DEFAULT_PAGES_DIR } from "../lib/content-paths";
+import { assertFolder } from "../lib/folder";
 import devServerSignals from "../integrations/dev-server-signals.mjs";
 import iterantPlugins from "../integrations/iterant-plugins.mjs";
 import newFileReload from "../integrations/new-file-reload.mjs";
 import previewErrorShell from "../integrations/preview-error-shell.mjs";
 import siteConfigWatch from "../integrations/site-config-watch.mjs";
 import { sitemapWithCustomPages } from "../lib/sitemap";
+import { siteModule } from "./site-module";
 
 /**
  * The browser floor every brand site's CSS is compiled for, stated rather than
@@ -167,6 +170,19 @@ export interface IterantStarterOptions {
    * `catalogFontFamilies` measures.
    */
   fonts?: readonly string[] | "catalog";
+  /**
+   * The one path segment this brand's platform files live under (`"feed"`), the
+   * backend's `brand.iterant_subfolder` as the repo's site config carries it.
+   * A repo passes `SITE_CONFIG.folder`, the same way it passes the fonts.
+   *
+   * Set, the hashed assets, the sitemap index and llms.txt all move under it,
+   * so the customer's edge forwards `example.com/feed/*` and every file a page
+   * needs arrives. PAGES DO NOT MOVE: they keep the public paths they are
+   * authored at, here and in every serving mode. Absent or empty is the root,
+   * byte-identical to a build before folders existed, so a repo that has not
+   * taken the upgrade keeps building.
+   */
+  folder?: string;
   /**
    * The repo's site config module, relative to the project root. In list mode
    * it is watched, so a change to `SITE_CONFIG.fonts` restarts the dev server
@@ -200,9 +216,16 @@ export function iterantStarter({
   pagesDir = DEFAULT_PAGES_DIR,
   chromeDir = DEFAULT_CHROME_DIR,
   fonts = [],
+  folder = "",
   siteConfigPath = "src/site-config.ts",
   overrides,
 }: IterantStarterOptions = {}) {
+  const siteFolder = folder === "" ? "" : assertFolder(folder);
+  // Which paths the baked `site` origin serves (3.13.0). It is a deploy
+  // decision, not a repo one: the same tree builds for the platform host and
+  // for a customer domain that forwards the folder alone, so it arrives in the
+  // environment rather than in astro.config.mjs.
+  const scope = readCanonicalScope(process.env, siteFolder);
   // A repo's own wrangler config, when it has one. The template checks in a
   // wrangler.jsonc and its compatibility_date decides how the adapter's workerd
   // prerender behaves, so passing configPath is not a detail; the lookup stays
@@ -225,7 +248,21 @@ export function iterantStarter({
   const integrations: NonNullable<AstroUserConfig["integrations"]> = [
     react(),
     // For SSR-only dynamic routes, the page entries' routes are read from disk.
-    ...sitemapWithCustomPages({ pagesDir }),
+    // Under a folder the index and its children land in it; every <loc> stays a
+    // public path, because the pages did not move. @astrojs/sitemap creates
+    // dist/client and nothing below it, so the folder directory is there because
+    // `build.assets` below wrote the hashed assets into it first: a site that
+    // emitted no assets at all would ENOENT here rather than skip the sitemap.
+    ...sitemapWithCustomPages({
+      pagesDir,
+      scope,
+      ...(siteFolder && { filenameBase: `${siteFolder}/sitemap` }),
+    }),
+    // The folder and the site config, as a module the package's own layout and
+    // routes can read. Always registered: those readers do not care whether this
+    // site has a folder, and with none they read `""` and address the root.
+    // With one, it also injects /<folder>/llms.txt.
+    siteModule({ folder: siteFolder, scope, siteConfigPath }),
     // Dev-only: platform visual editor, gated on ?editor=1 in an iframe.
     iterantPlugins(),
     // Dev-only: swap 5xx error pages for the branded in-progress shell.
@@ -323,6 +360,11 @@ export function iterantStarter({
     ...(site !== undefined && { site }),
     output: "server" as const,
     trailingSlash: "never" as const,
+    // Hashed assets under the brand's folder, so one forwarding rule on the
+    // customer's domain covers every stylesheet, script and image a page asks
+    // for. The Cloudflare adapter reads this key too and writes its immutable
+    // Cache-Control rule for the same prefix into _headers.
+    ...(siteFolder && { build: { assets: `${siteFolder}/_astro` } }),
     // No Astro sessions: the in-memory driver stops the Cloudflare adapter from
     // auto-provisioning a KV namespace per deploy.
     session: {

package/src/config/site-module.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { AstroIntegration } from "astro";
+
+import type { CanonicalScope } from "../lib/canonical-scope";
+
+// The platform's build-time facts, under a fixed module id: the brand's folder
+// as the preset was given it, the canonical scope the deploy chose, and the
+// repo's site config. A repo never imports this, its own files import
+// `@/site-config` directly; package code does, because the layout, robots.txt
+// and the injected llms.txt route all need them and none of them is called from
+// the config.
+//
+// It is what makes each of those ONE value. The preset receives or reads it,
+// places what it places, and every other reader takes it from here, so there is
+// no second copy for a repo to set differently.
+const SITE_ID = "virtual:iterant/site";
+const RESOLVED_SITE_ID = `\0${SITE_ID}`;
+
+export interface SiteModuleOptions {
+  /** The folder, already validated. Empty means the site serves from the root. */
+  folder: string;
+  /** Which paths the baked `site` origin serves, already validated. */
+  scope: CanonicalScope;
+  /** The repo's site config module, relative to the project root. */
+  siteConfigPath: string;
+}
+
+/**
+ * The virtual module above, and the one route this package addresses itself.
+ *
+ * llms.txt has to move under a folder, and no file name the template ships can
+ * carry a per-brand path segment, so with a folder set the preset injects the
+ * handler the repo used to mount at the root. A repo that still has the root
+ * src/pages/llms.txt.ts keeps serving /llms.txt too, at a different URL, so
+ * nothing collides; the file is dead weight on the customer's domain, where only
+ * the folder is forwarded, and the starter upgrade deletes it. The warning below
+ * says so on every build until it does.
+ */
+export function siteModule({
+  folder,
+  scope,
+  siteConfigPath,
+}: SiteModuleOptions): AstroIntegration {
+  return {
+    name: "iterant-site",
+    hooks: {
+      "astro:config:setup": ({ config, injectRoute, logger, updateConfig }) => {
+        const siteConfigFile = fileURLToPath(
+          new URL(siteConfigPath, config.root),
+        );
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "iterant-site-module",
+                resolveId: (id: string) =>
+                  id === SITE_ID ? RESOLVED_SITE_ID : null,
+                load: (id: string) =>
+                  id === RESOLVED_SITE_ID
+                    ? `export { SITE_CONFIG } from ${JSON.stringify(siteConfigFile)};\n` +
+                      `export const FOLDER = ${JSON.stringify(folder)};\n` +
+                      `export const CANONICAL_SCOPE = ${JSON.stringify(scope.name)};\n` +
+                      `export const PLATFORM_SITE = ${JSON.stringify(scope.platformSite)};\n`
+                    : null,
+              },
+            ],
+          },
+        });
+        if (!folder) return;
+        injectRoute({
+          pattern: `/${folder}/llms.txt`,
+          entrypoint: new URL(
+            "../routes/llms-txt-injected.ts",
+            import.meta.url,
+          ),
+          prerender: true,
+        });
+        if (
+          existsSync(
+            fileURLToPath(new URL("src/pages/llms.txt.ts", config.root)),
+          )
+        ) {
+          logger.warn(
+            `src/pages/llms.txt.ts still serves /llms.txt; delete it so llms.txt lives under /${folder} alone`,
+          );
+        }
+      },
+      // The module's TYPES, into the repo's .astro/ where its tsconfig already
+      // reads them. Without this a consumer's `astro check` has no declaration
+      // for the id and reports TS2307 in three package files it type-checks
+      // through their imports. The text is the declaration this package ships
+      // and checks itself against, read rather than repeated, so the two
+      // readings cannot drift.
+      "astro:config:done": ({ injectTypes }) => {
+        injectTypes({
+          filename: "site.d.ts",
+          content: readFileSync(
+            new URL("./virtual-modules.d.ts", import.meta.url),
+            "utf8",
+          ),
+        });
+      },
+    },
+  };
+}

package/src/config/virtual-modules.d.ts

@@ -0,0 +1,22 @@
+// The platform's build-time facts, served by the vite plugin in ./site-module.ts
+// and read by the package's own routes and layout. A repo imports its site
+// config directly; this id exists because that code is not called from the
+// config and cannot be handed the folder any other way.
+//
+// This file is BOTH the package's own declaration and the one every consumer
+// gets: the integration reads it and injects it into the repo's .astro/ at
+// astro:config:done, so a brand's `astro check` resolves the id too.
+declare module "virtual:iterant/site" {
+  export const SITE_CONFIG: {
+    name: string;
+    description: string;
+  };
+  /** The brand's folder, `""` when the site serves from the root. */
+  export const FOLDER: string;
+  /** Which paths the baked `site` origin serves: the whole host, or the brand
+   *  folder alone on a customer domain that forwards only that prefix. */
+  export const CANONICAL_SCOPE: "host" | "folder";
+  /** The origin an out-of-scope path resolves against under `folder` scope.
+   *  Null under `host`, where every path is in scope. */
+  export const PLATFORM_SITE: string | null;
+}

package/src/index.ts

@@ -5,7 +5,8 @@
 // an Astro build (the platform agent validates brand content through it).
 //
 // Astro-bound surfaces have their own entries: `/content` (collections),
-// `/layout`, `/seo`, `/routes`, `/sitemap`, `/config`, `/integrations/*`.
+// `/layout`, `/seo`, `/routes`, `/sitemap`, `/config`, `/integrations/*`, and
+// `/hreflang`, whose `pageLocaleHead` reads the canonical scope off the preset.
 export * from "./content/schema";
 export * from "./fonts/catalog";
 export * from "./layouts/layout-core";
@@ -14,7 +15,7 @@ export * from "./lib/chrome-schemas";
 export * from "./lib/content-paths";
 export * from "./lib/content-values";
 export * from "./lib/database";
-export * from "./lib/hreflang";
+export * from "./lib/hreflang-derive";
 export * from "./lib/locales";
 export * from "./version";
 export type {