@jxsuite/compiler 1.5.0 → 2.0.0

package/src/site/context-injection.ts

@@ -6,7 +6,11 @@
  *
  * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
  * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
- * title $page.params — dynamic route parameters (if any)
+ * title $page.params — dynamic route parameters (if any) $page.locale/$page.dir — the route's
+ * language and writing direction (§13.4) $page.alternates — this page in every language it exists
+ * in (§13.5)
+ *
+ * @docs framework/site/i18n
  */
 
 import { dirname, relative, resolve } from "node:path";
@@ -16,6 +20,9 @@ import type {
   JxStateDefinition,
   ProjectConfig,
 } from "@jxsuite/schema/types";
+import { localeDirection, localeLabel } from "@jxsuite/schema/locale";
+import { localeOfRoute } from "./i18n.ts";
+import type { ResolvedI18n, TranslationMember } from "./i18n.ts";
 import type { SiteRoute } from "../types.ts";
 
 /**
@@ -25,6 +32,9 @@ import type { SiteRoute } from "../types.ts";
  * @param {ProjectConfig} projectConfig - Loaded project configuration
  * @param {SiteRoute} route - The resolved route for this page
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
+ * @param {ResolvedI18n | null} [i18n] - Validated locale config, when the project declares one
+ * @param {readonly TranslationMember[]} [translations] - This route's translation set, itself
+ *   included
  * @returns {JxDocument} The mutated document
  */
 export function injectContext(
@@ -32,6 +42,8 @@ export function injectContext(
   projectConfig: ProjectConfig,
   route: SiteRoute,
   projectRoot: string | null = null,
+  i18n: ResolvedI18n | null = null,
+  translations: readonly TranslationMember[] = [],
 ) {
   if (!doc.state) {
     doc.state = {};
@@ -41,14 +53,45 @@ export function injectContext(
   doc.state.$site = {
     name: projectConfig.name ?? "Jx Site",
     url: projectConfig.url ?? "",
+    ...(i18n === null ? {} : { defaultLocale: i18n.defaultLocale, locales: i18n.locales }),
     ...projectConfig.state,
   };
 
-  // $page context — read-only page-level data
+  /*
+   * $page context — read-only page-level data.
+   *
+   * The locale lives here rather than as a top-level `$locale` because that is what it is: a
+   * property of the route, not a third ambient namespace beside $site and $page. A document's own
+   * `$lang` still wins over the route's locale, so this is the resolved answer, not the prefix.
+   */
+  const pageLang =
+    (typeof doc.$lang === "string" ? doc.$lang : undefined) ??
+    localeOfRoute(route.urlPattern, i18n) ??
+    projectConfig.defaults?.lang;
+  /*
+   * The same translation set `<head>` advertises, in the shape a template can render: a language
+   * switcher is the one part of a multilingual site the framework cannot write for the author, and
+   * without this it could only be hand-maintained — a hardcoded list of URLs that goes stale the
+   * moment a page gains or loses a translation, silently, in the one place a reader would use it.
+   *
+   * Site-absolute URLs, not the absolute hrefs `<head>` needs: a switcher is an internal link, and
+   * it has to work before `url` is configured. `current` marks the member this route *is*, taken
+   * from the route rather than from `$page.locale`, because a document whose `$lang` disagrees with
+   * its directory is still served from that directory.
+   */
+  const alternates = translations.map((member) => ({
+    code: member.locale,
+    current: member.urlPattern === route.urlPattern,
+    dir: localeDirection(member.locale),
+    label: localeLabel(member.locale),
+    url: member.urlPattern,
+  }));
   doc.state.$page = {
     params: route._pathParams ?? {},
     title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
     url: route.urlPattern,
+    ...(alternates.length > 0 && { alternates }),
+    ...(pageLang === undefined ? {} : { dir: localeDirection(pageLang), locale: pageLang }),
   };
 
   // Merge project-level state into page state (page wins on conflicts)

package/src/site/csp.ts

@@ -0,0 +1,224 @@
+/**
+ * Content-Security-Policy, derived from the pages the build actually produced.
+ *
+ * A static site cannot use nonces — a nonce has to be fresh per response, and these responses are
+ * files — so hashes are the only route to a strict `script-src`. That works here because the inline
+ * scripts Jx emits are **constants**: the colour-scheme pre-paint script is one fixed IIFE, and the
+ * import map is the same two-entry object on every page of a build. A handful of hashes therefore
+ * covers a whole site, which matters because Cloudflare Pages caps a `_headers` file at roughly a
+ * hundred rules — a per-page policy would be unusable past a small site.
+ *
+ * Sources are collected by **scanning finished HTML** rather than by asking each emission site what
+ * it emitted. There are seven places that can put a `<script>` on a page and a hash that does not
+ * match the shipped bytes is worse than no policy at all, so the scan runs on the exact string
+ * about to be written to disk.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { createHash } from "node:crypto";
+import type { CspConfig, HeadersConfig } from "@jxsuite/schema/types";
+
+/** Everything a page contributed to the policy. Accumulated across the whole build. */
+export interface CspSources {
+  /** `'sha256-…'` for each distinct inline script. */
+  scriptHashes: Set<string>;
+  scriptOrigins: Set<string>;
+  styleOrigins: Set<string>;
+  imgOrigins: Set<string>;
+  fontOrigins: Set<string>;
+  frameOrigins: Set<string>;
+}
+
+export function emptyCspSources(): CspSources {
+  return {
+    fontOrigins: new Set(),
+    frameOrigins: new Set(),
+    imgOrigins: new Set(),
+    scriptHashes: new Set(),
+    scriptOrigins: new Set(),
+    styleOrigins: new Set(),
+  };
+}
+
+/**
+ * Script `type` values the browser executes, and therefore the ones `script-src` governs.
+ *
+ * An empty or absent type is classic JavaScript. Everything else — `application/ld+json` above all
+ * — is a _data block_: the browser never executes it, CSP never checks it, and hashing it would add
+ * a hash that authorizes nothing. Verified in Chrome against an enforced policy.
+ */
+const EXECUTABLE_TYPES = new Set(["", "module", "importmap", "text/javascript", "module-shim"]);
+
+const SCRIPT_TAG = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+const LINK_TAG = /<link\b([^>]*)>/gi;
+const IMG_TAG = /<img\b([^>]*)>/gi;
+const SOURCE_TAG = /<source\b([^>]*)>/gi;
+const IFRAME_TAG = /<iframe\b([^>]*)>/gi;
+const FONT_EXTENSION = /\.(woff2?|ttf|otf|eot)(\?|#|$)/i;
+
+/** Read one double- or single-quoted attribute out of a raw tag attribute string. */
+function attr(attrs: string, name: string): string | undefined {
+  return new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i")
+    .exec(attrs)
+    ?.slice(2)
+    .find((v) => v !== undefined);
+}
+
+/** The origin of an absolute http(s) URL, or null for anything relative, `data:` or malformed. */
+export function originOf(url: string | undefined): string | null {
+  if (url === undefined || !/^https?:\/\//i.test(url)) {
+    return null;
+  }
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** The CSP source expression for an inline script's exact bytes. */
+export function hashOf(source: string): string {
+  return `'sha256-${createHash("sha256").update(source, "utf8").digest("base64")}'`;
+}
+
+/**
+ * Scan one finished page and add what it needs to the accumulated sources.
+ *
+ * @param {string} html - The exact bytes about to be written
+ * @param {CspSources} into
+ */
+export function collectCspSources(html: string, into: CspSources): void {
+  for (const match of html.matchAll(SCRIPT_TAG)) {
+    const attrs = match[1] ?? "";
+    const src = attr(attrs, "src");
+    const type = (attr(attrs, "type") ?? "").trim().toLowerCase();
+    if (src !== undefined) {
+      const origin = originOf(src);
+      if (origin) {
+        into.scriptOrigins.add(origin);
+      }
+      continue;
+    }
+    if (EXECUTABLE_TYPES.has(type)) {
+      into.scriptHashes.add(hashOf(match[2] ?? ""));
+    }
+  }
+
+  for (const match of html.matchAll(LINK_TAG)) {
+    const attrs = match[1] ?? "";
+    const rel = (attr(attrs, "rel") ?? "").toLowerCase();
+    const href = attr(attrs, "href");
+    const origin = originOf(href);
+    if (!origin) {
+      continue;
+    }
+    if (rel.includes("stylesheet")) {
+      into.styleOrigins.add(origin);
+    }
+    if (FONT_EXTENSION.test(href ?? "") || (attr(attrs, "as") ?? "") === "font") {
+      into.fontOrigins.add(origin);
+    }
+  }
+
+  for (const [tag, group] of [
+    [IMG_TAG, into.imgOrigins],
+    [SOURCE_TAG, into.imgOrigins],
+    [IFRAME_TAG, into.frameOrigins],
+  ] as const) {
+    for (const match of html.matchAll(tag)) {
+      const attrs = match[1] ?? "";
+      for (const value of [attr(attrs, "src"), ...srcsetUrls(attr(attrs, "srcset"))]) {
+        const origin = originOf(value);
+        if (origin) {
+          group.add(origin);
+        }
+      }
+    }
+  }
+}
+
+/** The URLs in a `srcset`, without their descriptors. */
+function srcsetUrls(srcset: string | undefined): string[] {
+  return srcset === undefined
+    ? []
+    : srcset
+        .split(",")
+        .map((candidate) => candidate.trim().split(/\s+/)[0] ?? "")
+        .filter(Boolean);
+}
+
+/** Normalize the config's three spellings into one shape, or null when CSP is off. */
+export function normalizeCspConfig(security: HeadersConfig["security"]): CspConfig | null {
+  const csp = security?.csp;
+  if (csp === undefined || csp === false) {
+    return null;
+  }
+  if (csp === true) {
+    return {};
+  }
+  if (csp === "report-only") {
+    return { mode: "report-only" };
+  }
+  return csp;
+}
+
+/**
+ * Build the policy. Returns the headers to add, which is more than one when reporting is on:
+ * `report-to` names an endpoint group that `Reporting-Endpoints` has to define.
+ *
+ * `style-src` carries `'unsafe-inline'` and always will until the style pipeline changes. Every
+ * page has a generated `<style>` block whose content is per-page, so hashing them would put one
+ * hash per page into a site-wide header, and per-element `style=` attributes have no hash form at
+ * all. Both are recorded as a divergence rather than papered over — and note that a hash and
+ * `'unsafe-inline'` in the same directive cancel: the browser ignores the keyword, so a partial job
+ * here would be worse than an honest one.
+ *
+ * @param {CspSources} sources
+ * @param {CspConfig} config
+ * @returns {Record<string, string>}
+ */
+export function buildCspHeaders(sources: CspSources, config: CspConfig): Record<string, string> {
+  const list = (fixed: string[], origins: Set<string>) => [...fixed, ...origins].join(" ");
+
+  const directives: Record<string, string | false> = {
+    "base-uri": "'self'",
+    "default-src": "'self'",
+    "font-src": list(["'self'"], sources.fontOrigins),
+    "form-action": "'self'",
+    // Matches the `X-Frame-Options: SAMEORIGIN` emitted beside it; two headers disagreeing about
+    // Framing is a worse outcome than either answer.
+    "frame-ancestors": "'self'",
+    "frame-src": list(["'self'"], sources.frameOrigins),
+    "img-src": list(["'self'", "data:"], sources.imgOrigins),
+    "object-src": "'none'",
+    "script-src": list(["'self'", ...[...sources.scriptHashes].toSorted()], sources.scriptOrigins),
+    "style-src": list(["'self'", "'unsafe-inline'"], sources.styleOrigins),
+  };
+
+  if (config.reportUri !== undefined && config.reportUri !== "") {
+    directives["report-to"] = "csp-endpoint";
+    // Deprecated in CSP3 and still the only one some browsers implement, so both are emitted.
+    directives["report-uri"] = config.reportUri;
+  }
+
+  for (const [name, value] of Object.entries<string | false>(config.directives ?? {})) {
+    directives[name] = value;
+  }
+
+  const policy = Object.entries(directives)
+    .filter(([, value]) => value !== false && value !== "")
+    .toSorted(([a], [b]) => (a < b ? -1 : 1))
+    .map(([name, value]) => `${name} ${String(value)}`)
+    .join("; ");
+
+  const headerName =
+    config.mode === "report-only"
+      ? "Content-Security-Policy-Report-Only"
+      : "Content-Security-Policy";
+  const headers: Record<string, string> = { [headerName]: policy };
+  if (config.reportUri !== undefined && config.reportUri !== "") {
+    headers["Reporting-Endpoints"] = `csp-endpoint="${config.reportUri}"`;
+  }
+  return headers;
+}

package/src/site/head-merger.ts

@@ -59,10 +59,23 @@ export function mergeHead(
   // Add canonical URL if provided
   if (context.pageUrl && context.siteUrl) {
     const canonical = new URL(context.pageUrl, context.siteUrl).href;
-    merged.set("link:canonical", {
-      attributes: { href: canonical, rel: "canonical" },
-      tagName: "link",
-    });
+    /*
+     * An author-supplied canonical wins, like every other auto-injected entry (§8.4). This used a
+     * hand-written `link:canonical` key that `headEntryKey` never produces, so the author's entry
+     * and this one landed under different keys and the page got BOTH — which is the one thing a
+     * canonical link must not be.
+     */
+    const hasAuthored = [...merged.values()].some(
+      (e) =>
+        e && typeof e === "object" && e.tagName === "link" && e.attributes?.rel === "canonical",
+    );
+    if (!hasAuthored) {
+      const entry: JxHeadEntry = {
+        attributes: { href: canonical, rel: "canonical" },
+        tagName: "link",
+      };
+      merged.set(headEntryKey(entry), entry);
+    }
     // Auto OpenGraph identity (site-architecture §8.4) — author-supplied values win.
     if (!merged.has("meta:og:url")) {
       merged.set("meta:og:url", {
@@ -78,6 +91,26 @@ export function mergeHead(
     });
   }
 
+  /*
+   * Locale alternates (site-architecture.md §13.5). Keyed through `headEntryKey` like everything
+   * else, which is what keeps a set of them from collapsing: they share `rel="alternate"` and
+   * differ only in `hreflang`, and `x-default` conventionally shares its `href` with the default
+   * locale's entry. Before the key accounted for the qualifying attribute this whole feature was
+   * impossible — the set became one link.
+   *
+   * An author-supplied alternate for the same `hreflang` wins, like every other auto entry.
+   */
+  for (const alternate of context.alternates ?? []) {
+    const entry: JxHeadEntry = {
+      attributes: { href: alternate.href, hreflang: alternate.hreflang, rel: "alternate" },
+      tagName: "link",
+    };
+    const key = headEntryKey(entry);
+    if (!merged.has(key)) {
+      merged.set(key, entry);
+    }
+  }
+
   return [...merged.values()];
 }
 
@@ -116,9 +149,17 @@ function headEntryKey(entry: JxHeadEntry) {
     return `meta:${attrs.property}`;
   }
 
-  // <link rel="..." href="..."> — keyed by rel+href
+  /*
+   * <link> — keyed by rel + href + the attribute that distinguishes two links sharing both.
+   *
+   * `rel` + `href` alone is not identity, and the cases where it fails are the ones a site actually
+   * needs: `hreflang="x-default"` conventionally points at the SAME href as the default locale's
+   * alternate, and an RSS and an Atom feed are both `rel="alternate"` differing only in `type`.
+   * `icon` differs by `sizes` and `stylesheet` by `media` for the same reason.
+   */
   if (tag === "link" && attrs.rel) {
-    return `link:${attrs.rel}:${attrs.href ?? ""}`;
+    const qualifier = attrs.hreflang ?? attrs.type ?? attrs.media ?? attrs.sizes ?? "";
+    return `link:${attrs.rel}:${attrs.href ?? ""}:${String(qualifier)}`;
   }
 
   // <script src="..."> — keyed by src
@@ -128,9 +169,8 @@ function headEntryKey(entry: JxHeadEntry) {
 
   // <style> — unique per content hash
   if (tag === "style") {
-    const content = Array.isArray(entry.children)
-      ? entry.children.join("")
-      : (entry.textContent ?? "");
+    const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
+    const content = typeof raw === "object" && raw !== null ? JSON.stringify(raw) : (raw ?? "");
     return `style:${simpleHash(content)}`;
   }
 
@@ -191,10 +231,14 @@ function renderHeadEntry(entry: JxHeadEntry) {
     return open;
   }
 
-  // Elements with content
-  const content = Array.isArray(entry.children)
-    ? entry.children.join("")
-    : (entry.textContent ?? "");
+  /*
+   * Elements with content. `textContent` may be an OBJECT: that is how a JSON-LD block is authored
+   * (§8.5), and serializing it here is what the spec has always promised. Left as-is it reached the
+   * page as the string "[object Object]".
+   */
+  const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
+  const content =
+    raw !== null && typeof raw === "object" ? JSON.stringify(raw, null, 2) : (raw ?? "");
   return `${open}${content}</${tag}>`;
 }
 

package/src/site/headers-emitter.ts

@@ -0,0 +1,232 @@
+/**
+ * Emits `dist/_headers` — the response headers the build knows and the host does not.
+ *
+ * Cacheability in particular is something only the build can decide: it is the thing that chose the
+ * filenames, so it is the only party that knows which of them embed a content hash and are
+ * therefore safe to cache forever. Left unsaid, every host applies its own default to output whose
+ * lifetime it cannot see (RFC 9111).
+ *
+ * Pure except for `writeHeaders`, which is the one function that touches disk.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildCspHeaders, normalizeCspConfig } from "./csp.ts";
+import type { CspSources } from "./csp.ts";
+import type { HeadersConfig, ProjectConfig } from "@jxsuite/schema/types";
+
+/** One `_headers` stanza: a path pattern and the headers it sets. */
+export interface HeaderRule {
+  pattern: string;
+  headers: Record<string, string>;
+}
+
+/**
+ * The only content-addressed output the build produces. `variantFilename()` embeds an 8-character
+ * digest of the source bytes, so a changed image is a changed URL and the old one can be cached
+ * forever (RFC 8246).
+ */
+export const IMMUTABLE_PATTERN = "/images/_optimized/*";
+
+/** A year, the conventional ceiling for `max-age`. */
+const IMMUTABLE_MAX_AGE = 31_536_000;
+
+/**
+ * Paths that must NEVER be marked immutable, asserted by a test.
+ *
+ * `/components/<tag>.js` and `/assets/<slug>.js` are named after the thing they contain, not after
+ * its content — editing a component reuses the URL. Marking either immutable is a year-long cache
+ * poisoning bug that only appears for visitors who came before the edit, which is the worst
+ * possible shape for one. Making them cacheable means content-hashing them first.
+ */
+export const NEVER_IMMUTABLE = ["/components/*", "/assets/*"] as const;
+
+const BANNER = "# Generated by @jxsuite/compiler — configure via build.headers in project.json.";
+const AUTHOR_BANNER =
+  "# ─── public/_headers (hand-authored; these rules override the block above) ───";
+
+/**
+ * The generated rules, general first. Order matters: on both Cloudflare and Netlify a later
+ * matching rule wins for a duplicate header name, so the specific `immutable` stanza must follow
+ * the catch-all that revalidates.
+ */
+export function buildHeaderRules(
+  build: ProjectConfig["build"],
+  cspSources?: CspSources,
+): {
+  rules: HeaderRule[];
+  errors: string[];
+} {
+  const cfg: HeadersConfig = build?.headers ?? {};
+  const errors: string[] = [];
+  if (cfg.enabled === false) {
+    return { errors, rules: [] };
+  }
+
+  const security = cfg.security ?? {};
+  const wide: Record<string, string> = {};
+
+  if (security.contentTypeOptions !== false) {
+    wide["X-Content-Type-Options"] = "nosniff";
+  }
+  if (security.referrerPolicy !== false) {
+    wide["Referrer-Policy"] = security.referrerPolicy ?? "strict-origin-when-cross-origin";
+  }
+  if (security.permissionsPolicy !== false) {
+    wide["Permissions-Policy"] =
+      security.permissionsPolicy ?? "camera=(), microphone=(), geolocation=()";
+  }
+  if (security.frameOptions !== false) {
+    wide["X-Frame-Options"] = security.frameOptions ?? "SAMEORIGIN";
+  }
+
+  const { hsts } = security;
+  if (hsts) {
+    const opts = hsts === true ? {} : hsts;
+    const maxAge = opts.maxAge ?? IMMUTABLE_MAX_AGE;
+    const includeSubDomains = opts.includeSubDomains ?? true;
+    const preload = opts.preload ?? false;
+    if (preload && !includeSubDomains) {
+      /*
+       * Submission to the preload list REQUIRES includeSubDomains. Emitting the header anyway
+       * produces something that looks submitted and is not, which is worse than not emitting it.
+       */
+      errors.push(
+        "build.headers.security.hsts: `preload` requires `includeSubDomains` — the preload list " +
+          "will not accept the header without it.",
+      );
+    } else {
+      wide["Strict-Transport-Security"] = [
+        `max-age=${maxAge}`,
+        includeSubDomains ? "includeSubDomains" : null,
+        preload ? "preload" : null,
+      ]
+        .filter(Boolean)
+        .join("; ");
+    }
+  }
+
+  /*
+   * One policy for the whole site, from the inline scripts and external origins the build actually
+   * emitted. It goes in the `/*` stanza rather than per page because the hashes are constants —
+   * and because a per-page policy would exhaust the host's rule budget on any real site.
+   */
+  const cspConfig = normalizeCspConfig(security);
+  if (cspConfig) {
+    if (cspSources === undefined) {
+      errors.push(
+        "build.headers.security.csp is set, but no page was scanned for inline scripts — the " +
+          "policy would block every one of them.",
+      );
+    } else {
+      Object.assign(wide, buildCspHeaders(cspSources, cspConfig));
+    }
+  }
+
+  const cache = cfg.cache ?? "auto";
+  if (cache === "auto") {
+    /*
+     * Everything else — HTML at `/about/`, component JS and CSS, the sitemap, the feed — revalidates
+     * every time. The ETag makes that cheap, and it is the only correct default for output whose URL
+     * does not change when its content does.
+     */
+    wide["Cache-Control"] = "public, max-age=0, must-revalidate";
+  }
+
+  const rules: HeaderRule[] = [];
+  if (Object.keys(wide).length > 0) {
+    rules.push({ headers: wide, pattern: "/*" });
+  }
+  if (cache === "auto") {
+    rules.push({
+      headers: { "Cache-Control": `public, max-age=${IMMUTABLE_MAX_AGE}, immutable` },
+      pattern: IMMUTABLE_PATTERN,
+    });
+  }
+  for (const [pattern, headers] of Object.entries(cfg.rules ?? {})) {
+    rules.push({ headers, pattern });
+  }
+  return { errors, rules };
+}
+
+/**
+ * Content-Type rules for output whose extension no host maps.
+ *
+ * `.xml` is served as `application/xml` and `.json` as `application/json` by default, which is not
+ * wrong but is not what a feed reader looks for. Only files that actually exist get a rule, so the
+ * emitted block never describes output this build did not produce.
+ */
+export function contentTypeRules(outDir: string): HeaderRule[] {
+  const known: [string, string][] = [
+    ["feed.xml", "application/atom+xml; charset=utf-8"],
+    ["feed.json", "application/feed+json; charset=utf-8"],
+    ["manifest.webmanifest", "application/manifest+json; charset=utf-8"],
+    [".well-known/security.txt", "text/plain; charset=utf-8"],
+  ];
+  const rules: HeaderRule[] = [];
+  for (const [name, type] of known) {
+    if (existsSync(join(outDir, name))) {
+      rules.push({ headers: { "Content-Type": type }, pattern: `/${name}` });
+    }
+  }
+  // The RFC 5005 archives share the feed's type.
+  if (existsSync(join(outDir, "feed", "archive"))) {
+    rules.push({
+      headers: { "Content-Type": "application/atom+xml; charset=utf-8" },
+      pattern: "/feed/archive/*",
+    });
+  }
+  return rules;
+}
+
+/** Render rules in the Netlify / Cloudflare Pages `_headers` format. */
+export function renderHeaders(rules: readonly HeaderRule[]): string {
+  const blocks = rules.map((rule) => {
+    const lines = Object.entries(rule.headers).map(([name, value]) => `  ${name}: ${value}`);
+    return [rule.pattern, ...lines].join("\n");
+  });
+  return `${[BANNER, "", ...blocks].join("\n")}\n`;
+}
+
+/**
+ * Write `dist/_headers`, preserving a hand-authored `public/_headers` **below** the generated
+ * block.
+ *
+ * `ensureRobotsSitemap` appends for the same reason this prepends: both run after the `public/`
+ * copy so they edit the deployed file, but a later `_headers` rule wins for a duplicate header
+ * name, so the author's block has to come last to override.
+ *
+ * The author's file is concatenated verbatim rather than merged. Both platforms have removal (`!
+ * Header-Name`) and conditional (`Language=`, `Country=`) extensions, and a structural merge would
+ * silently drop whatever it could not parse — deferring to each platform's own documented
+ * precedence is both simpler and more correct.
+ */
+export function writeHeaders(outDir: string, rules: readonly HeaderRule[]): number {
+  if (rules.length === 0) {
+    return 0;
+  }
+  const path = join(outDir, "_headers");
+  const authored = existsSync(path) ? readFileSync(path, "utf8").trim() : "";
+  const generated = renderHeaders(rules);
+  const body = authored === "" ? generated : `${generated}\n${AUTHOR_BANNER}\n${authored}\n`;
+  writeFileSync(path, body, "utf8");
+  return 1;
+}
+
+/**
+ * Write `dist/.nojekyll`.
+ *
+ * GitHub Pages runs Jekyll, which excludes every `_`-prefixed path — which is `_headers`,
+ * `_redirects`, `_worker.js`, `_routes.json` and `_islands/`. One empty file closes the whole class
+ * of "works locally, half-broken on Pages", so it is unconditional rather than an adapter option.
+ */
+export function writeNoJekyll(outDir: string): number {
+  const path = join(outDir, ".nojekyll");
+  if (existsSync(path)) {
+    return 0;
+  }
+  writeFileSync(path, "", "utf8");
+  return 1;
+}