@iterant/site-runtime 3.11.1 → 3.12.0

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.1._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.12.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,57 @@ 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.
+
 ### Web fonts (3.8.0)
 
 A site names its font families once, in `SITE_CONFIG.fonts`, and passes the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.11.1",
+  "version": "3.12.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/src/config/preset.ts

@@ -13,12 +13,14 @@ import {
   findFontFamily,
 } from "../fonts/catalog";
 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 +169,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 +215,11 @@ 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);
   // 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 +242,20 @@ 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,
+      ...(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, 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 +353,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,97 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { AstroIntegration } from "astro";
+
+// The platform's build-time facts, under a fixed module id: the brand's folder
+// as the preset was given it, 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 the
+// folder and none of them is called from the config.
+//
+// It is what makes the folder ONE value. The preset receives it, the assets and
+// the sitemap go under it, 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;
+  /** 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,
+  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)};\nexport const FOLDER = ${JSON.stringify(folder)};\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,16 @@
+// 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;
+}

package/src/layouts/LayoutCore.astro

@@ -1,11 +1,13 @@
 ---
 import { Font, fontData } from "astro:assets";
+import { FOLDER } from "virtual:iterant/site";
 import { getCollection, getEntry } from "astro:content";
 import type { AstroComponentFactory } from "astro/runtime/server/index.js";
 import RelatedLinks from "../components/RelatedLinks.astro";
 import { SEO, type PageType } from "../components/seo";
 import type { SeoJsonSchema } from "../components/seo-json";
 import { fontCssVariable } from "../fonts/catalog";
+import { folderPath } from "../lib/folder";
 import type { HreflangAlternate } from "../lib/hreflang";
 import { DEFAULT_LOCALE, localeFromPath } from "../lib/locales";
 import { SITE_RUNTIME_VERSION } from "../version";
@@ -215,7 +217,11 @@ const fontPreload = fonts.named ? [{ style: "normal", subset: "latin" }] : false
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link
+      rel="icon"
+      type="image/x-icon"
+      href={folderPath(FOLDER, "favicon.ico")}
+    />
     <meta name="generator" content={Astro.generator} />
     <meta name="it-site-runtime" content={SITE_RUNTIME_VERSION} />
     <meta name="it-astro-starter-version" content={SITE_RUNTIME_VERSION} />

package/src/lib/folder.ts

@@ -0,0 +1,33 @@
+// The brand's folder: the one path segment every platform file a build emits
+// lives under, so the customer's edge forwards `example.com/feed/*` and never
+// needs a second rule. Pages are untouched: they keep their public paths, and a
+// site with no folder emits exactly what it emitted before folders existed.
+//
+// The value is the backend's `brand.iterant_subfolder`, written into the repo's
+// site config beside `fonts` and handed to `iterantStarter({ folder })`. One
+// owner, one copy, never inferred from a path.
+
+// The backend's own rule, character for character (backend/brands/folder.py):
+// letters, digits and hyphens, so the folder is one level deep and can never
+// shadow a platform file name. The reserved names and the locale-shape refusal
+// stay at the door in Django, which owns the value; what a build can still be
+// handed is a bad shape, and a bad shape emits asset URLs nobody can fetch and a
+// sitemap nobody can find, so the build refuses it instead.
+const FOLDER_SEGMENT = /^[a-z0-9-]+$/;
+
+export function assertFolder(folder: string): string {
+  if (!FOLDER_SEGMENT.test(folder)) {
+    throw new Error(
+      `iterantStarter: folder must be one lower-case segment of letters, digits and hyphens, no slashes (got ${JSON.stringify(folder)})`,
+    );
+  }
+  return folder;
+}
+
+/** A platform file's public path: `/feed/favicon.ico` under a folder,
+ *  `/favicon.ico` without one. The folder is validated here too, because this is
+ *  where it becomes a URL: a value like `/evil.example` must never get that far,
+ *  wherever it was read. */
+export function folderPath(folder: string | undefined, file: string): string {
+  return folder ? `/${assertFolder(folder)}/${file}` : `/${file}`;
+}

package/src/routes/index.ts

@@ -1,7 +1,12 @@
 // Platform route handlers. Every one of these stays behind a VISIBLE file in the
-// repo's src/pages/ — existence and addressing are repo-owned, behavior rides a
-// package bump. No route is injected: a route that exists in no repo file breaks
-// the src/pages/ mental model and the debuggability contract.
+// repo's src/pages/: existence and addressing are repo-owned, behavior rides a
+// package bump. A route that exists in no repo file breaks the src/pages/ mental
+// model and the debuggability contract.
+//
+// One route is addressed by the platform, llms.txt under a brand folder
+// (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 {
   AI_ANSWER_CRAWLERS,

package/src/routes/llms-txt-injected.ts

@@ -0,0 +1,11 @@
+import { SITE_CONFIG } from "virtual:iterant/site";
+
+import { createLlmsTxtRoute } from "./llms-txt";
+
+// The body of /<folder>/llms.txt, as the preset injects it (see
+// ../config/site-module.ts). The brand's name and description come from the
+// repo's site config through the virtual module, since an injected route has no
+// repo file to import them from; the folder the handler writes into its links
+// comes from the same module.
+export const prerender = true;
+export const GET = createLlmsTxtRoute({ siteConfig: SITE_CONFIG });

package/src/routes/llms-txt.ts

@@ -1,5 +1,7 @@
 import { getCollection } from "astro:content";
+import { FOLDER } from "virtual:iterant/site";
 import { isAdvertised } from "../lib/advertised";
+import { folderPath } from "../lib/folder";
 import type { APIRoute } from "astro";
 
 // /llms.txt, generated at dev/build time with no crawler or AI step: a curated
@@ -11,6 +13,10 @@ import type { APIRoute } from "astro";
 //   ---
 //   export const prerender = true;
 //   export const GET = createLlmsTxtRoute({ siteConfig: SITE_CONFIG });
+//
+// Under a brand folder the same handler is addressed by the preset instead, at
+// /<folder>/llms.txt, because no file name the template ships can carry a
+// per-brand segment (../config/site-module.ts).
 
 export interface LlmsTxtOptions {
   /** The brand's SITE_CONFIG; name and description head the file when set. */
@@ -58,7 +64,7 @@ export function createLlmsTxtRoute({ siteConfig }: LlmsTxtOptions): APIRoute {
         : []),
       "## Discovery",
       "",
-      `- [Sitemap](${new URL("/sitemap-index.xml", origin).href}): Complete search-engine sitemap, if available.`,
+      `- [Sitemap](${new URL(folderPath(FOLDER, "sitemap-index.xml"), origin).href}): Complete search-engine sitemap, if available.`,
       `- [Robots policy](${new URL("/robots.txt", origin).href}): Crawler permissions for automated agents.`,
       "",
     ];

package/src/routes/robots-txt.ts

@@ -1,5 +1,7 @@
 import type { APIRoute } from "astro";
+import { FOLDER } from "virtual:iterant/site";
 
+import { folderPath } from "../lib/folder";
 import { normalizeSourceUrls } from "../lib/sitemap/shared";
 
 // /robots.txt: crawler permissions, the site's AI policy and the sitemap
@@ -108,11 +110,20 @@ function legacyDisallows(rules: string[] | undefined): string[] {
 export function renderRobotsTxt(
   config: RobotsSiteConfig,
   site: URL | undefined,
+  // The brand's folder (site-runtime 3.12.0). robots.txt itself stays at the
+  // root, where a crawler looks for it; its index line points into the folder,
+  // where the build writes the sitemap. Resolved against the ORIGIN, because the
+  // folder is what the customer forwards from their domain's root, while a site
+  // URL that carries a path keeps resolving relative to it without one.
+  folder: string = "",
 ): string {
   const policy = resolveAiPolicy(config.aiPolicy);
+  const indexPath = folder
+    ? folderPath(folder, "sitemap-index.xml")
+    : "sitemap-index.xml";
   const sitemap = site
     ? [
-        `Sitemap: ${new URL("sitemap-index.xml", site).href}`,
+        `Sitemap: ${new URL(indexPath, site).href}`,
         // Mirrored sitemap, only when sourceSitemapUrl is configured.
         ...(normalizeSourceUrls(config.sourceSitemapUrl ?? "").length > 0
           ? [`Sitemap: ${new URL("sitemap.xml", site).href}`]
@@ -141,7 +152,7 @@ export function createRobotsTxtRoute(options: RobotsTxtOptions): APIRoute {
   const { siteConfig, ...flat } = options;
   const config: RobotsSiteConfig = { ...flat, ...(siteConfig ?? {}) };
   return ({ site }) =>
-    new Response(renderRobotsTxt(config, site), {
+    new Response(renderRobotsTxt(config, site, FOLDER), {
       headers: { "Content-Type": "text/plain" },
     });
 }