@zvndev/darkmown 0.17.0 → 0.19.0

package/src/compiler.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import MarkdownIt from "markdown-it";
+import { imageSize } from "image-size";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
@@ -135,12 +136,48 @@ export function compilePage(file, context) {
   const scriptSrcs = compiled.assets.runtime ? ["/__wd/runtime.js", ...compiled.assets.scripts] : [...compiled.assets.scripts];
   const scripts = scriptSrcs.map((src) => `<script type="module" src="${src}"></script>`).join("\n");
   // Cross-document view transitions: opt in per page with `transitions: true` in
-  // frontmatter to emit the CSS-only @view-transition rule — a smooth same-origin
-  // cross-fade on navigation, with zero JavaScript. Ignored by browsers without
-  // support (graceful fade-free fallback) and only applies to same-origin
+  // frontmatter to emit a CSS-only stylesheet — a smooth same-origin transition
+  // on navigation, with zero JavaScript. Ignored by browsers without support
+  // (graceful, transition-free fallback) and only applies to same-origin
   // navigations where both the outgoing and incoming page opt in.
+  //
+  // The default UA animation cross-fades the root: outgoing opacity 1→0 while
+  // incoming 0→1, both at once. Mid-navigation that leaves the two pages
+  // superimposed at ~50% opacity — headings ghost over headings. We override it
+  // with a directional fade+slide (old lifts up and out, new rises up and in) so
+  // the pages move past each other instead of stacking. Short + eased = peppy.
   const wantTransitions = compiled.meta.transitions === true || compiled.meta.transitions === "true";
-  const transitions = wantTransitions ? `\n  <style>@view-transition { navigation: auto; }</style>` : "";
+  const transitions = wantTransitions
+    ? `\n  <style>
+    @view-transition { navigation: auto; }
+    ::view-transition-old(root) { animation: wd-nav-out 200ms cubic-bezier(0.4, 0, 1, 1) both; }
+    ::view-transition-new(root) { animation: wd-nav-in 200ms cubic-bezier(0, 0, 0.2, 1) both; }
+    @keyframes wd-nav-out { to { opacity: 0; transform: translateY(-1rem); } }
+    @keyframes wd-nav-in { from { opacity: 0; transform: translateY(1rem); } }
+    @media (prefers-reduced-motion: reduce) {
+      ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 1ms; }
+      @keyframes wd-nav-out { to { opacity: 0; } }
+      @keyframes wd-nav-in { from { opacity: 0; } }
+    }
+  </style>`
+    : "";
+
+  // The latency half of smooth navigation — and what kills the white flash. A
+  // declarative speculationrules script (the browser interprets it — not
+  // framework runtime JS, so the zero-JS invariant holds) *prerenders* the next
+  // same-origin page on hover/pointerdown. Prefetch only warms the cache, so the
+  // page still has to render on click — that render gap is the white flash. A
+  // prerender renders the whole page in a hidden tab ahead of the click, so
+  // activation is instant: no render gap, and the view transition fires on the
+  // already-painted page. Safe now that pages are light. Eagerness `moderate` =
+  // ~200ms hover / pointerdown, capped at two. Mark a link `{.no-prefetch}` to
+  // opt it out; `rel=nofollow` links are never speculated. Browsers without
+  // support (or with preloading disabled) ignore the tag and navigate normally.
+  const speculation = wantTransitions
+    ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
+    : "";
+
+  const body = enhanceImages(compiled.html, context);
 
   return {
     meta: compiled.meta,
@@ -151,10 +188,10 @@ export function compilePage(file, context) {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>${descriptionTag}
   <link rel="icon" href="${favicon}">
-  ${cssLinks}${transitions}
+  ${cssLinks}${transitions}${speculation}
 </head>
 <body>
-${compiled.html}
+${body}
 ${scripts}
 </body>
 </html>`,
@@ -163,6 +200,80 @@ ${scripts}
   };
 }
 
+/**
+ * Harden every `<img>` in the assembled page body — compile-time only, zero
+ * runtime JS. Bare markdown images reflow the page as they decode (cumulative
+ * layout shift — the literal "jump" on navigation) and load eagerly. This
+ * stamps intrinsic `width`/`height` (read from the file on disk so the browser
+ * reserves space), `decoding="async"` on all, and a load-priority split: the
+ * first image is the LCP candidate (eager + `fetchpriority="high"`), the rest
+ * lazy-load. Author-set attributes are never overwritten.
+ * @param {string} html Assembled page body HTML.
+ * @param {Paths} paths Resolved project paths.
+ * @returns {string}
+ */
+export function enhanceImages(html, paths) {
+  let index = 0;
+  return html.replace(/<img\b[^>]*?\/?>/g, (tag) => {
+    const i = index++;
+    const has = (/** @type {string} */ attr) => new RegExp(`\\b${attr}\\s*=`, "i").test(tag);
+    /** @type {string[]} */
+    const add = [];
+    // Dimensions only when the author hasn't sized it — adding one axis to a
+    // manually-sized image would distort its aspect ratio.
+    if (!has("width") && !has("height")) {
+      const dim = measureImage(srcOf(tag), paths);
+      if (dim) add.push(`width="${dim.width}"`, `height="${dim.height}"`);
+    }
+    if (!has("decoding")) add.push(`decoding="async"`);
+    if (i === 0) {
+      // First image is the LCP candidate: stays eager, gets a priority hint.
+      if (!has("fetchpriority")) add.push(`fetchpriority="high"`);
+    } else if (!has("loading")) {
+      add.push(`loading="lazy"`);
+    }
+    if (!add.length) return tag;
+    return `${tag.replace(/\s*\/?>\s*$/, "")} ${add.join(" ")}>`;
+  });
+}
+
+/**
+ * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
+ * @param {string} tag
+ * @returns {string}
+ */
+function srcOf(tag) {
+  const m = tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i);
+  return m ? m[1] : "";
+}
+
+/**
+ * Read an image's intrinsic dimensions from disk, or null when the src is
+ * remote/relative/unreadable. Resolution mirrors the asset emit: `/__wd/media/x`
+ * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
+ * @param {string} src
+ * @param {Paths} paths
+ * @returns {{ width: number, height: number } | null}
+ */
+function measureImage(src, paths) {
+  if (!src || /^(https?:)?\/\//i.test(src) || src.startsWith("data:")) return null;
+  let filePath;
+  if (src.startsWith("/__wd/media/")) {
+    filePath = path.join(paths.shelfRoot, src.slice("/__wd/media/".length));
+  } else if (src.startsWith("/")) {
+    filePath = path.join(paths.routesRoot, src.slice(1));
+  } else {
+    return null; // page-relative: the source directory is lost after assembly
+  }
+  try {
+    const { width, height } = imageSize(fs.readFileSync(filePath));
+    if (typeof width === "number" && typeof height === "number") return { width, height };
+  } catch {
+    /* missing or unreadable — degrade to no dimensions */
+  }
+  return null;
+}
+
 /**
  * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
  * @param {string} file Absolute path to the source file.
@@ -216,6 +327,7 @@ function compileFile(file, context, stack, scope, comp, sections, loopItem) {
 
   const raw = fs.readFileSync(file, "utf8");
   const { meta, body } = parseFrontmatter(raw, file);
+  warnLikelyFrontmatter(raw, file, comp);
   collectColocatedAssets(file, context, comp.assets);
 
   if (path.extname(file) === ".md") {
@@ -254,6 +366,37 @@ export function parseFrontmatter(raw, file) {
   return { meta, body };
 }
 
+/**
+ * Warn (non-fatal) when a file looks like it MEANT to open frontmatter but forgot
+ * the leading `---`: the first content line is a `key: value` pair and a bare
+ * `---` fence appears within the opening lines. Conservative — a normal markdown
+ * body whose first line happens to contain a colon (with no early `---`) is left
+ * alone, since `---` is also a valid horizontal rule.
+ * @param {string} raw
+ * @param {string} file
+ * @param {Compilation} comp
+ * @returns {void}
+ */
+function warnLikelyFrontmatter(raw, file, comp) {
+  if (raw.startsWith("---\n")) return; // a real opener: parseFrontmatter handled it
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++; // skip leading blanks
+  if (i >= lines.length || !/^[A-Za-z][\w-]*:\s*\S/.test(lines[i])) return;
+  // Only warn when the run of lines up to a bare `---` is ALL `key: value` pairs:
+  // a forgotten opener, not prose that merely contains a colon and a later rule.
+  for (let j = i; j < lines.length && j < i + 12; j++) {
+    const t = lines[j].trim();
+    if (t === "---") {
+      comp.warnings.push(
+        `${file}: this looks like frontmatter missing its opening "---". Use: a "---" line before the fields (and another "---" to close) — otherwise the block renders as page text.`
+      );
+      return;
+    }
+    if (t && !/^[A-Za-z][\w-]*:\s*\S/.test(t)) return; // hit prose → not frontmatter
+  }
+}
+
 // Frontmatter values are scalars, except an inline flow array `[a, b, c]`.
 // Block sequences (`- item` on following lines) are intentionally out of scope —
 // the parser stays single-pass and line-based.
@@ -460,6 +603,7 @@ function compileBody(lines, ctx) {
     if (/^(@endloop|:endif|:endfor|:endform|:else)\s*$/.test(line)) {
       throw new Error(`Stray "${line.trim()}" with no matching opener in ${ctx.file}`);
     }
+    warnUnknownDirective(line, ctx);
     prose.push(line);
   }
 
@@ -467,6 +611,44 @@ function compileBody(lines, ctx) {
   return out.join("\n");
 }
 
+// Lines that reached prose but LOOK like a directive (a `@word`/`:word` token at
+// the very start, followed by a space or end of line) and match no handler are
+// almost always a typo — every real directive was intercepted above. Warn, never
+// throw: prose legitimately contains `@` and `:`, so the match is deliberately
+// narrow (lowercase token + boundary; emoji shortcodes, times, and `@user`
+// followed by punctuation do not match).
+const KNOWN_DIRECTIVE =
+  /^(?:@(?:include|loop|empty|endloop)|:(?:state|store|fetch|computed|effect|form|endform|input|textarea|select|checkbox|radio|bind|submit|button|if|endif|else|try|note|sprint))(?:\s|$)/;
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+function warnUnknownDirective(line, ctx) {
+  // Catch capitalized (`:State`) and hyphenated (`:end-loop`) typos too — the
+  // known-directive whitelist stays case-sensitive, so a mis-cased real
+  // directive correctly trips the warning. Still unindented-only, to keep prose
+  // that legitimately starts lines with `@`/`:` from false-positiving.
+  const m = line.match(/^([@:][A-Za-z][A-Za-z-]*)(?:\s|$)/);
+  if (m && !KNOWN_DIRECTIVE.test(line)) {
+    ctx.comp.warnings.push(
+      `${ctx.file}: "${m[1]}" looks like a directive but matches none — it will render as literal text. Check the spelling (e.g. @loop, @include, :state, :if).`
+    );
+  }
+}
+
+/**
+ * Format a source location as `file:line` (1-based) for compile errors. Keeps the
+ * file path intact so existing message matchers still pass, while pointing at the
+ * unclosed opener's line.
+ * @param {string} file
+ * @param {number} index 0-based line index of the opener.
+ * @returns {string}
+ */
+function at(file, index) {
+  return `${file}:${index + 1}`;
+}
+
 /**
  * Capture lines from an opener until a matching close token, honoring nesting and fences.
  * @param {string[]} lines
@@ -501,7 +683,7 @@ function scanBlock(lines, start, openRe, endToken, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${at(file, start)}`);
 }
 
 /**
@@ -572,7 +754,7 @@ function scanContainer(lines, start, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing closing ::: for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing closing ::: for "${lines[start]}" in ${at(file, start)}`);
 }
 
 /**
@@ -641,7 +823,7 @@ function scanConditional(lines, start, file) {
     }
     current.push(line);
   }
-  throw new Error(`Missing :endif for "${lines[start]}" in ${file}`);
+  throw new Error(`Missing :endif for "${lines[start]}" in ${at(file, start)}`);
 }
 
 // ---------------------------------------------------------------------------
@@ -1526,6 +1708,11 @@ function handleLoop(line, bodyLines, emptyLines, ctx) {
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
       return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
     }
+    // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
+    // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
+    if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
+      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
+    }
   }
 
   throw new Error(
@@ -1800,15 +1987,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
   const templateCtx = { ...ctx, loopItem: itemName, loopKey: key ?? undefined, loopMeta: true, scope: createScope(ctx.scope) };
   const templateHtml = compileBody(bodyLines, templateCtx).trim();
 
-  let wrapperTag = "div";
-  let itemTemplate = templateHtml;
-  const listMatch = templateHtml.match(/^<(ul|ol)>\s*([\s\S]*?)\s*<\/\1>$/);
-  if (listMatch && (listMatch[2].match(/<li>/g) || []).length === 1) {
-    wrapperTag = listMatch[1];
-    itemTemplate = listMatch[2].trim();
-  } else {
-    itemTemplate = `<div data-wd-loop-piece>${templateHtml}</div>`;
-  }
+  const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
   const where = opts?.where || null;
   const sort = opts?.sort || null;
@@ -1830,27 +2009,132 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
   /** @type {Map<string, number>} */
   const counts = new Map();
   const count = rows.length;
+  // Inner ITEM-RELATIVE loop regions are filled per row by the runtime, not at
+  // build time; mask them so the outer initial-paint string fill leaves their
+  // pristine <template>/empty-out markup untouched, then restore.
+  const { masked, regions } = maskItemLoops(itemTemplate);
   const initial = rows
     .map((/** @type {unknown} */ item, i) => {
       const itemKey = loopKeyOf(item, counts);
       const meta = { index: i, number: i + 1, first: i === 0, last: i === count - 1, count };
-      return fillTemplateString(withLoopKey(itemTemplate, itemKey), item, meta);
+      return unmaskItemLoops(fillTemplateString(withLoopKey(masked, itemKey), item, meta), regions);
     })
     .join("");
 
-  const emptyTemplate = emptyLines ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>` : "";
+  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx);
   const initialOut = count === 0 && emptyLines ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim() : initial;
 
-  const attrs =
-    (where ? ` data-wd-loop-where="${escapeHtml(where.body)}"` : "") +
-    (sort ? ` data-wd-loop-sort="${escapeHtml(sort.key)}" data-wd-loop-sort-dir="${sort.dir}"` : "") +
-    (reverse ? ` data-wd-loop-reverse` : "") +
-    (offset ? ` data-wd-loop-offset="${numArgAttr(offset)}"` : "") +
-    (limit ? ` data-wd-loop-limit="${numArgAttr(limit)}"` : "") +
+  const attrs = loopClauseAttrs({ where, sort, reverse, offset, limit }) +
     (baked ? ` data-wd-loop-data="${escapeHtml(JSON.stringify(baked))}"` : "");
   return `<div data-wd-loop="${escapeHtml(key || "")}"${attrs}><template data-wd-loop-template>${itemTemplate}</template>${emptyTemplate}<${wrapperTag} data-wd-loop-out>${initialOut}</${wrapperTag}></div>`;
 }
 
+/**
+ * Unwrap a compiled row body into a wrapper tag + row template. A body that is a
+ * single-`<li>` `<ul>`/`<ol>` becomes an `<li>` row under that list wrapper;
+ * anything else is wrapped in a `<div data-wd-loop-piece>` under a `<div>`. Shared
+ * by top-level reactive loops and item-relative (nested) loops.
+ * @param {string} templateHtml
+ * @returns {{ wrapperTag: string, itemTemplate: string }}
+ */
+function wrapRowTemplate(templateHtml) {
+  const listMatch = templateHtml.match(/^<(ul|ol)>\s*([\s\S]*?)\s*<\/\1>$/);
+  if (listMatch && (listMatch[2].match(/<li>/g) || []).length === 1) {
+    return { wrapperTag: listMatch[1], itemTemplate: listMatch[2].trim() };
+  }
+  return { wrapperTag: "div", itemTemplate: `<div data-wd-loop-piece>${templateHtml}</div>` };
+}
+
+/**
+ * Compile an `@empty` branch body into a `<template data-wd-loop-empty>` (or "" when
+ * there is no empty branch). Shared by top-level and item-relative loops.
+ * @param {string[] | null} emptyLines
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function loopEmptyTemplate(emptyLines, ctx) {
+  return emptyLines ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>` : "";
+}
+
+/**
+ * Serialize the shared `where`/`sort`/`reverse`/`offset`/`limit` clause config to
+ * the `data-wd-loop-*` attribute string consumed by the runtime pipeline. Shared
+ * by top-level reactive loops and item-relative (nested) loops.
+ * @param {Pick<LoopOpts, "where" | "sort" | "reverse" | "offset" | "limit">} c
+ * @returns {string}
+ */
+function loopClauseAttrs(c) {
+  return (
+    (c.where ? ` data-wd-loop-where="${escapeHtml(c.where.body)}"` : "") +
+    (c.sort ? ` data-wd-loop-sort="${escapeHtml(c.sort.key)}" data-wd-loop-sort-dir="${c.sort.dir}"` : "") +
+    (c.reverse ? ` data-wd-loop-reverse` : "") +
+    (c.offset ? ` data-wd-loop-offset="${numArgAttr(c.offset)}"` : "") +
+    (c.limit ? ` data-wd-loop-limit="${numArgAttr(c.limit)}"` : "")
+  );
+}
+
+/**
+ * Emit ONE level of nested reactive loop: a `@loop <outerItem>.<path> into x`
+ * whose rows are read off the enclosing loop row at runtime. The region carries
+ * its own row <template> + clause config but, unlike a top-level loop, its source
+ * is the relative `path` (not a global state key) — `fillItem` resolves the rows
+ * off the current outer item and reconciles per row. The output starts empty; the
+ * runtime fills it on first render (the page already ships the runtime).
+ * @param {string} path Dotted sub-path off the outer item (e.g. `items`).
+ * @param {string} itemName Inner loop item name.
+ * @param {string[]} bodyLines Inner loop body.
+ * @param {Ctx} ctx
+ * @param {Partial<LoopOpts>} opts
+ * @returns {string}
+ */
+function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
+  /** @type {Ctx} */
+  // loopKey: undefined — an item-relative loop's source is a path off the outer
+  // row, not a top-level state key, so a per-row `remove` inside it has no valid
+  // target and must be rejected (rather than inheriting the outer loop's key).
+  const templateCtx = { ...ctx, loopItem: itemName, loopKey: undefined, loopMeta: true, scope: createScope(ctx.scope) };
+  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+
+  const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
+
+  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx);
+  const attrs = loopClauseAttrs({ where: opts.where || null, sort: opts.sort || null, reverse: opts.reverse || false, offset: opts.offset || null, limit: opts.limit || null });
+  return `<div data-wd-loop-item="${escapeHtml(path)}"${attrs}><template data-wd-loop-template>${itemTemplate}</template>${emptyTemplate}<${wrapperTag} data-wd-loop-out></${wrapperTag}></div>`;
+}
+
+/**
+ * Replace each top-level `data-wd-loop-item` region in a row template with an
+ * opaque placeholder so the outer initial-paint string fill cannot reach inside
+ * its pristine markup. Returns the masked string and the excised regions in order.
+ * @param {string} template
+ * @returns {{ masked: string, regions: string[] }}
+ */
+function maskItemLoops(template) {
+  const marker = "<div data-wd-loop-item=";
+  /** @type {string[]} */
+  const regions = [];
+  let masked = "";
+  let i = 0;
+  for (;;) {
+    const start = template.indexOf(marker, i);
+    if (start === -1) return { masked: masked + template.slice(i), regions };
+    const end = matchElement(template, start, "div");
+    masked += template.slice(i, start) + `\x00WDLI${regions.length}\x00`;
+    regions.push(template.slice(start, end));
+    i = end;
+  }
+}
+
+/**
+ * Restore the masked `data-wd-loop-item` regions into a filled row string.
+ * @param {string} str
+ * @param {string[]} regions
+ * @returns {string}
+ */
+function unmaskItemLoops(str, regions) {
+  return regions.length ? str.replace(/\x00WDLI(\d+)\x00/g, (_, n) => regions[Number(n)]) : str;
+}
+
 /**
  * @param {string} template
  * @param {string} itemKey
@@ -2396,7 +2680,13 @@ function parseSingleAction(expression, raw, ctx) {
   if (remove) {
     const operand = remove[2].trim();
     if (ctx.loopItem && operand === ctx.loopItem) {
-      if (!ctx.loopKey || resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
+      // A nested (item-relative) loop has a loop item but no top-level state key —
+      // its source is a path off the outer row, which the runtime's row-remove
+      // can't target. Fail loud with the honest workaround.
+      if (!ctx.loopKey) {
+        throw new Error(`Button action "${raw}" can't delete a row of a nested (item-relative) loop in ${ctx.file}. Per-row "remove" needs a top-level :state/:store list; carry the row into one (cart += ${ctx.loopItem}) and remove it there.`);
+      }
+      if (resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
         throw new Error(`Button action "${raw}" must target the :state list being looped (@loop ${remove[1]} into ${ctx.loopItem}) in ${ctx.file}.`);
       }
       return { op: "remove", target: ctx.loopKey };

package/src/headers.js

@@ -0,0 +1,94 @@
+/**
+ * Security headers Darkmown emits on every delivery surface — the local
+ * `darkmown serve`/preview server (`src/statics.js`), Cloudflare Pages
+ * (`dist/_headers`, written by `src/builder.js`), and Vercel (`vercel.json`).
+ *
+ * `statics.js` and the generated `_headers` derive from the values here, so they
+ * never drift. `vercel.json` is the exception: Vercel reads it BEFORE the build
+ * runs, so its CSP strings and static-route list are hand-maintained copies, not
+ * build output. The `vercel-csp-routes` test cross-checks vercel.json against the
+ * built route manifest so a new static route can't silently miss the strict CSP.
+ *
+ * The CSP is derived from what the framework's own output actually emits
+ * (verify against built `dist/` HTML):
+ *   - External script `/__wd/runtime.js` (same-origin) on reactive pages.
+ *   - Inline `<script type="application/json" data-wd-state>` (state seed) and
+ *     inline `<script type="speculationrules">` (prerender) — JSON/speculation
+ *     blocks can't be nonce'd cleanly, so `script-src 'unsafe-inline'`.
+ *   - The reactive runtime compiles validated expressions via `new Function`,
+ *     so reactive pages additionally need `script-src 'unsafe-eval'`.
+ *   - Inline `<style>` for view transitions — `style-src 'unsafe-inline'`.
+ *   - `data:` favicon and remote images — `img-src 'self' data: https:`.
+ *
+ * Static pages (zero framework JS) still emit inline `<style>` and an inline
+ * `<script type="speculationrules">`, so they keep `'unsafe-inline'`, but they
+ * never call `new Function`, so their CSP drops `'unsafe-eval'`.
+ */
+
+/**
+ * `connect-src` for the demo is `'self'`: the framework's own pages only
+ * `:fetch` same-origin endpoints. Apps whose `:fetch` targets a remote host
+ * must widen this (e.g. to `connect-src 'self' https://api.example.com` or
+ * `connect-src *`) by editing their `vercel.json` / `_headers` / serve config.
+ * @type {string}
+ */
+const CONNECT_SRC = "connect-src 'self'";
+
+/**
+ * Directives shared by both the static and reactive CSP. Order is cosmetic.
+ * @type {string[]}
+ */
+const COMMON_CSP_DIRECTIVES = [
+  "default-src 'self'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: https:",
+  "font-src 'self'",
+  CONNECT_SRC,
+  "object-src 'none'",
+  "base-uri 'self'",
+  "frame-ancestors 'self'"
+];
+
+/**
+ * Relaxed CSP for reactive pages: `new Function` needs `'unsafe-eval'`, the
+ * inline state/speculationrules JSON needs `'unsafe-inline'`.
+ * @type {string}
+ */
+export const REACTIVE_CSP = [
+  "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
+  ...COMMON_CSP_DIRECTIVES
+].join("; ");
+
+/**
+ * Stricter CSP for static pages: no runtime means no `new Function`, so
+ * `'unsafe-eval'` is dropped. Inline `<style>`/`<script type=speculationrules>`
+ * keep `'unsafe-inline'` on script/style.
+ * @type {string}
+ */
+export const STATIC_CSP = [
+  "script-src 'self' 'unsafe-inline'",
+  ...COMMON_CSP_DIRECTIVES
+].join("; ");
+
+/**
+ * Baseline security headers applied to every HTML response, independent of the
+ * CSP. CSP is added per-route (static vs reactive) by the helpers below.
+ * @type {Record<string, string>}
+ */
+export const BASE_SECURITY_HEADERS = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "X-Frame-Options": "SAMEORIGIN"
+};
+
+/**
+ * The full security-header set for one response, including the CSP variant.
+ * @param {boolean} reactive Whether the route ships the reactive runtime.
+ * @returns {Record<string, string>}
+ */
+export function securityHeaders(reactive) {
+  return {
+    ...BASE_SECURITY_HEADERS,
+    "Content-Security-Policy": reactive ? REACTIVE_CSP : STATIC_CSP
+  };
+}