@zvndev/darkmown 1.5.0 → 2.0.0

package/src/compiler/structure.js

@@ -0,0 +1,377 @@
+// ---------------------------------------------------------------------------
+// Structure: the directives that shape a page's tree — `@include` (sub-file
+// compile + scoped-skin stamp), `::: container` sections, `:if` conditional
+// regions, the `:carousel` block — plus the documentation-demo directives
+// (`:try`/`:note`/`:sprint`). Nested block bodies recurse through
+// `ctx.compileBody` (and `@include` through `ctx.compileFile`), threaded in by
+// the per-file compile so the module graph stays an import-cycle-free DAG.
+//
+// Every handler receives the 0-based line `index` so its malformed/invalid
+// errors report `file:line` (via `at`) — matching the unclosed-block errors —
+// while keeping the message text and `Use:` hints intact.
+// ---------------------------------------------------------------------------
+
+import { at, createScope, LOOP_META, nestedCtx } from "./context.js";
+import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
+import {
+  escapeHtml,
+  getPath,
+  lookupPath,
+  lookupVar,
+  parseScalar,
+  resolveStateKey
+} from "./interpolation.js";
+import { compileWhen, evalPredicate } from "./predicates.js";
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleInclude(line, ctx, index) {
+  const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
+  if (!match) throw new Error(`Malformed @include in ${at(ctx, index)}: ${line}`);
+  const target = resolveInclude(match[1], ctx.file, ctx.context);
+  const args = parseIncludeArgs(match[2] || "", ctx);
+  const childScope = createScope(ctx.scope, args);
+  const child = ctx.compileFile(
+    target,
+    ctx.context,
+    ctx.stack,
+    childScope,
+    ctx.comp,
+    ctx.sections,
+    ctx.loopItem
+  );
+  // An include with its OWN scoped colocated skin stamps just its returned
+  // subtree — so a scoped `.card` in the include can't collide with a `.card`
+  // anywhere else on the page, and the scope never leaks to the include's
+  // siblings (only this child HTML is stamped). The CSS rewrite (builder) uses
+  // the same path-derived id, so attribute and stylesheet line up.
+  const scopedSkin = scopedSkinFor(target, ctx.context);
+  return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
+}
+
+/**
+ * @param {string} raw
+ * @param {Ctx} ctx
+ * @returns {Record<string, unknown>}
+ */
+function parseIncludeArgs(raw, ctx) {
+  /** @type {Record<string, unknown>} */
+  const args = {};
+  const re = /([A-Za-z0-9_-]+)=("[^"]*"|'[^']*'|\{[^}]*\}|\S+)/g;
+  for (const match of raw.matchAll(re)) {
+    const value = match[2];
+    if (value.startsWith("{")) {
+      const expr = value.slice(1, -1).trim();
+      const resolved = lookupPath(expr, ctx);
+      if (!resolved.found) {
+        throw new Error(
+          `@include argument ${match[1]}={ ${expr} } in ${ctx.file} does not match any value in scope`
+        );
+      }
+      args[match[1]] = resolved.value;
+    } else {
+      args[match[1]] = parseScalar(value);
+    }
+  }
+  return args;
+}
+
+/**
+ * @param {string} header
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleContainer(header, bodyLines, ctx, index) {
+  let rest = header.trim();
+  let tag = "section";
+  /** @type {string[]} Static classes baked into class="". */
+  const extraClass = [];
+  /** @type {[string, string][]} Reactive loop-item class bindings (data-wd-each-class). */
+  const eachClasses = [];
+  /** @type {[string, string][]} Global state-driven class bindings (data-wd-class). */
+  const stateClasses = [];
+  let id = "";
+  // Leading tag/name token (anything not starting with . or #). "section" keeps
+  // the <section> tag; any other name becomes a <div> and also a class.
+  const lead = rest.match(/^([^\s.#]\S*)/);
+  let nameToken = "section";
+  if (lead) {
+    nameToken = lead[1];
+    rest = rest.slice(lead[0].length).trim();
+  }
+  if (nameToken !== "section") {
+    tag = "div";
+    extraClass.push(nameToken);
+  }
+  while (rest.length) {
+    if (rest.startsWith("#")) {
+      const m = rest.match(/^#(\S+)/);
+      id = m ? m[1] : "";
+      rest = rest.slice((m ? m[0] : rest).length).trim();
+      continue;
+    }
+    const cm = rest.match(/^\.([A-Za-z_][\w-]*)/);
+    if (!cm)
+      throw new Error(
+        `Unexpected token "${rest.split(/\s+/)[0]}" in container "::: ${header}" in ${at(ctx, index)}`
+      );
+    const cls = cm[1];
+    rest = rest.slice(cm[0].length).trim();
+    // Optional `when <predicate>` makes the class reactive. The predicate runs to
+    // the next ` .`/` #` token or the end of the header.
+    const whenMatch = rest.match(/^when\s+(.+?)(?=\s+[.#]|$)/);
+    if (whenMatch) {
+      rest = rest.slice(whenMatch[0].length).trim();
+      const compiled = compileWhen(whenMatch[1].trim(), ctx);
+      if (compiled.static) {
+        if (compiled.value) extraClass.push(cls);
+      } else if (compiled.item) eachClasses.push([cls, compiled.body]);
+      else stateClasses.push([cls, compiled.body]);
+    } else {
+      extraClass.push(cls);
+    }
+  }
+  const explicitId = Boolean(id);
+  if (!id) id = `wd-s${++ctx.comp.sectionCounter}`;
+
+  ctx.sections.push(id);
+  let inner;
+  try {
+    inner = ctx.compileBody(bodyLines, nestedCtx(ctx, index + 1));
+  } finally {
+    ctx.sections.pop();
+  }
+  const idAttr = explicitId ? ` id="${escapeHtml(id)}"` : "";
+  const classAttr = extraClass.length ? ` class="${escapeHtml(extraClass.join(" "))}"` : "";
+  let classBind = "";
+  if (eachClasses.length) {
+    ctx.comp.assets.runtime = true;
+    classBind += ` data-wd-each-class="${escapeHtml(JSON.stringify(eachClasses))}"`;
+  }
+  if (stateClasses.length) {
+    ctx.comp.assets.runtime = true;
+    classBind += ` data-wd-class="${escapeHtml(JSON.stringify(stateClasses))}"`;
+  }
+  return `<${tag}${idAttr}${classAttr}${classBind}>\n${inner}\n</${tag}>`;
+}
+
+/**
+ * `:carousel [autoplay=N]` … `:endcarousel` — a horizontally scroll-snapping
+ * carousel. Contract: each DIRECT child element of the track is one slide, so put
+ * each slide in its own block (e.g. a `::: slide` container) and give that block
+ * the slide sizing in your skin — loose prose lines would each count as a slide.
+ * Registers the `carousel` behavior (prev/next, dot nav, optional autoplay, mouse
+ * drag); native CSS scroll-snap + the page skin handle layout and touch swipe.
+ * `autoplay` is suppressed under `prefers-reduced-motion`. No runtime required.
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleCarousel(line, bodyLines, ctx, index) {
+  const match = line.match(/^:carousel\s*(.*)$/);
+  const rest = (match?.[1] || "").trim();
+  let autoplayAttr = "";
+  if (rest) {
+    const auto = rest.match(/^autoplay=(\d+)$/);
+    if (!auto)
+      throw new Error(
+        `Malformed :carousel in ${at(ctx, index)}: ${line}. Use: :carousel [autoplay=3000] … :endcarousel`
+      );
+    autoplayAttr = ` data-wd-carousel-autoplay="${auto[1]}"`;
+  }
+  ctx.comp.assets.behaviors.add("carousel");
+  const inner = ctx.compileBody(bodyLines, nestedCtx(ctx, index + 1));
+  return `<div class="wd-carousel" data-wd-carousel${autoplayAttr}>\n<div class="wd-carousel-track" data-wd-carousel-track>\n${inner}\n</div>\n</div>`;
+}
+
+/**
+ * Compile-time announcements for `:fetch` lifecycle regions: a bare
+ * `:if <key>_loading` over a fetch-declared key becomes a `role="status"`
+ * (polite) live region and `:if <key>_error` a `role="alert"` one, so the
+ * runtime's existing show/hide flip is read by assistive tech with zero extra
+ * runtime JS. Author-supplied `role`/`aria-live` inside the region always wins
+ * (see handleInput) — nothing is added over it.
+ *
+ * The author-aria check reads the region's own RAW SOURCE lines, not its compiled
+ * branch HTML: in the documented chained pattern (`:if x_loading` / `:else if
+ * x_error` / `:else`) the loading region's falsy branch *contains* the nested
+ * error region's framework-added `role="alert"`, and matching that would falsely
+ * suppress the loading region's own `role="status"`. Framework-added attributes
+ * never appear in source, so only genuine author `role`/`aria-live` can match.
+ * @param {string} key Resolved state key of the `:if` region.
+ * @param {string[]} sourceLines The region's own truthy + falsy source lines.
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function fetchLiveAttr(key, sourceLines, ctx) {
+  const match = key.match(/^(.*)_(loading|error)$/);
+  if (!match || !ctx.comp.fetchKeys.has(match[1])) return "";
+  if (/\b(?:role|aria-live)\s*=/.test(sourceLines.join("\n"))) return "";
+  return match[2] === "loading" ? ' role="status" aria-live="polite"' : ' role="alert"';
+}
+
+/**
+ * @param {string} line
+ * @param {string[]} truthyLines
+ * @param {string[]} falsyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @param {number} [falsyStart] 0-based index the falsy body starts at in the
+ *   current slice, so nested errors in that branch report the true file line.
+ * @returns {string}
+ */
+export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart = index + 1) {
+  const truthyCtx = nestedCtx(ctx, index + 1);
+  const falsyCtx = nestedCtx(ctx, falsyStart);
+  const condition = line.replace(/^:if\s+/, "").trim();
+  // Fast path: a bare truthy dotted path (`:if open`, `:if item.done`). Keeps the
+  // existing markup/behavior identical. Anything with operators (`>`, `==`, `and`,
+  // `not`, …) falls through to the predicate path below.
+  const match = condition.match(/^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)$/);
+  if (match) {
+    const segs = match[1].split(".");
+    const head = segs[0];
+
+    // Per-row meta vars in :if — only valid inside a loop.
+    if (LOOP_META[head]) {
+      if (!ctx.loopMeta)
+        throw new Error(
+          `":if ${match[1]}" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Use it inside a loop body.`
+        );
+      if (ctx.loopItem) {
+        const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
+        const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
+        return `<span data-wd-each-if data-wd-meta="${LOOP_META[head]}"><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+      }
+      // static: the meta boolean is in scope — fall through to the static branch below.
+    }
+
+    const staticValue = lookupVar(ctx.scope, head);
+    if (staticValue.found) {
+      const active = Boolean(getPath(staticValue.value, segs.slice(1)));
+      return ctx.compileBody(active ? truthyLines : falsyLines, active ? truthyCtx : falsyCtx);
+    }
+
+    if (ctx.loopItem && head === ctx.loopItem) {
+      const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
+      const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
+      const rest = segs.slice(1).join(".");
+      const pathAttr = ` data-wd-path="${escapeHtml(rest)}"`;
+      return `<span data-wd-each-if${pathAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+    }
+
+    const key = resolveStateKey(head, ctx);
+    if (!key) {
+      throw new Error(
+        `:if ${match[1]} in ${ctx.file} does not match a :state or in-scope value. Declare it first.`
+      );
+    }
+    ctx.comp.assets.runtime = true;
+    const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
+    const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
+    const restPath = segs.slice(1).join(".");
+    const pathAttr = restPath ? ` data-wd-path="${escapeHtml(restPath)}"` : "";
+    const liveAttr = restPath ? "" : fetchLiveAttr(key, [...truthyLines, ...falsyLines], ctx);
+    const initialTruthy = Boolean(getPath(ctx.comp.state.get(key), segs.slice(1)));
+    const active = initialTruthy ? truthy : falsy;
+    return `<div data-wd-if="${key}"${pathAttr}${liveAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
+  }
+
+  // Predicate path: a comparison / logical condition. Compiles through the same
+  // whitelist as `@loop … where` / `.class when` (with `not`), so it folds at
+  // build when static, drives a per-row each-if when it reads the loop item, and
+  // a global if-region (evaluated each render) when it reads state. No raw eval.
+  if (!condition)
+    throw new Error(
+      `Malformed :if in ${at(ctx, index)}: ${line}. Use ":if name" or ":if a <op> b [and|or|not …]".`
+    );
+  const compiled = compileWhen(condition, ctx, '":if"');
+  if (compiled.static)
+    return ctx.compileBody(
+      compiled.value ? truthyLines : falsyLines,
+      compiled.value ? truthyCtx : falsyCtx
+    );
+  ctx.comp.assets.runtime = true;
+  const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
+  const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
+  const exprAttr = ` data-wd-if-expr="${escapeHtml(compiled.body)}"`;
+  if (compiled.item) {
+    return `<span data-wd-each-if${exprAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
+  }
+  const initialTruthy = evalPredicate(compiled.body, undefined, ctx);
+  const active = initialTruthy ? truthy : falsy;
+  return `<div data-wd-if=""${exprAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
+}
+
+/**
+ * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+export function renderDemoDirective(line, ctx) {
+  const tryMatch = line.match(/^:try\s+"([^"]+)"\s+href="([^"]+)"$/);
+  if (tryMatch) {
+    const href = validateDemoHref(tryMatch[2], ctx);
+    return `<a class="try-card" href="${escapeHtml(href)}"><span>Try</span>${escapeHtml(tryMatch[1])}</a>`;
+  }
+  const note = line.match(/^:note\s+"([^"]+)"$/);
+  if (note) return `<aside class="note">${escapeHtml(note[1])}</aside>`;
+  const sprint = line.match(/^:sprint\s+min=(\d+)\s+max=(\d+)\s+roles="([^"]+)"$/);
+  if (sprint) {
+    const roles = sprint[3]
+      .split(",")
+      .map((role) => role.trim())
+      .filter(Boolean);
+    return `<section class="sprint-board" data-min="${sprint[1]}" data-max="${sprint[2]}">${roles.map((role) => `<article><strong>${escapeHtml(role)}</strong><span>active lane</span></article>`).join("")}</section>`;
+  }
+  return "";
+}
+
+/**
+ * Validate demo-card links without adding arbitrary URL passthrough.
+ * @param {string} href
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function validateDemoHref(href, ctx) {
+  const value = href.trim();
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — rejects control characters in URLs/hrefs.
+  if (value !== href || /[\u0000-\u001F\u007F]/.test(value)) {
+    throw new Error(
+      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`
+    );
+  }
+  if (value.startsWith("//")) {
+    throw new Error(
+      `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http: or https: explicitly.`
+    );
+  }
+  if (
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith("#")
+  ) {
+    return value;
+  }
+  const scheme = value.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (scheme && ["http", "https", "mailto"].includes(scheme[1].toLowerCase())) {
+    return value;
+  }
+  throw new Error(
+    `Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`
+  );
+}

package/src/dev.js

@@ -1,6 +1,54 @@
+import { escapeHtml } from "./compiler.js";
+
 export const devClientPath = "/__wd/dev-client.js";
 export const devEventsPath = "/__wd/dev-events";
 
+/**
+ * Serialize the dev server's rebuilds: at most ONE child build runs at a time.
+ * Every build read-modify-writes the dependency map (`dist/.wd-dev-deps.json`),
+ * so overlapping children could persist a stale map missing deps a concurrent
+ * build just recorded — after which the affected routes silently stop
+ * rebuilding. Changes debounce into a batch; changes arriving MID-build
+ * accumulate into the next batch (duplicate paths coalesce via the Set, and a
+ * `null` — a `src/` change or an unattributable event, forcing a full rebuild —
+ * swallows the whole batch into one full build).
+ * @param {(changed: string[]) => Promise<void> | void} runBuild Runs one child
+ *   build over the changed `site/` paths (`[]` = full rebuild). Build failures
+ *   are its own concern (report + resolve); a rejection still frees the queue.
+ * @param {number} [debounceMs] Debounce window for batching change events.
+ * @returns {{ change: (path: string | null) => void, close: () => void }}
+ */
+export function createRebuildQueue(runBuild, debounceMs = 30) {
+  /** @type {Set<string | null>} */
+  const pending = new Set();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  let running = false;
+  const flush = () => {
+    if (running || pending.size === 0) return;
+    const changed = pending.has(null) ? [] : /** @type {string[]} */ ([...pending]);
+    pending.clear();
+    running = true;
+    Promise.resolve()
+      .then(() => runBuild(changed))
+      .catch(() => {}) // runBuild reports its own failures; never wedge the queue
+      .then(() => {
+        running = false;
+        flush(); // drain changes that arrived mid-build (already waited a build long)
+      });
+  };
+  return {
+    change(path) {
+      pending.add(path);
+      clearTimeout(timer);
+      timer = setTimeout(flush, debounceMs);
+    },
+    close() {
+      clearTimeout(timer);
+    }
+  };
+}
+
 /**
  * Inject the dev-client `<script>` before `</body>` (or append it if absent),
  * plus — for a `draft: true` page — an inline draft-banner script. Both are
@@ -42,6 +90,34 @@ document.addEventListener("DOMContentLoaded", () => document.body.prepend(banner
 `;
 }
 
+/**
+ * The page the dev server serves for a route with no dist output while the last
+ * build is FAILED — the honest alternative to the production 404 copy, which
+ * would claim the route "is hidden or has not been created" when the real cause
+ * is a compile error. The message renders inline (works without JS) and the
+ * injected dev client replays the `builderror` overlay on connect, then reloads
+ * the real page on the next successful build.
+ * @param {string} message The recorded build failure.
+ * @returns {string}
+ */
+export function buildFailedPage(message) {
+  return injectDevClient(
+    `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Darkmown build failed</title>
+</head>
+<body>
+  <h1>Darkmown build failed</h1>
+  <pre>${escapeHtml(message)}</pre>
+  <p>This route has no built output because the last build failed. Fix the file above and this page reloads on the next successful build.</p>
+</body>
+</html>`
+  );
+}
+
 /**
  * The dev-client browser script that opens the SSE channel for live reload.
  * @returns {string}

package/src/headers.js

@@ -12,11 +12,21 @@
  * 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'`.
+ *   - Inline `<script type="application/json" data-wd-state>` (state seed) —
+ *     a non-executable data block, which `script-src` does not govern, so it
+ *     needs no source at all.
+ *   - Inline `<script type="speculationrules">` (prerender, `transitions: true`)
+ *     — the one inline script `script-src` does gate. Its body is a single
+ *     build-time constant, so a `'sha256-…'` hash source authorizes exactly it
+ *     (plus the `'inline-speculation-rules'` keyword for browsers that check
+ *     that instead of the hash) and `'unsafe-inline'` is dropped entirely. A
+ *     raw `<script>` an author writes into `html: true` markdown is therefore
+ *     blocked by the shipped CSP — use a colocated `.js` file (same-origin,
+ *     covered by `'self'`) or widen `script-src` deliberately.
  *   - The reactive runtime compiles validated expressions via `new Function`,
- *     so reactive pages additionally need `script-src 'unsafe-eval'`.
+ *     so reactive pages additionally need `script-src 'unsafe-eval'`. That
+ *     keyword cannot be hashed away: it gates eval-family APIs, not inline
+ *     script elements.
  *   - Inline `<style>` for view transitions — `style-src 'unsafe-inline'`.
  *   - `data:` favicon and remote images — `img-src 'self' data: https:`.
  *   - `:video`/`:audio` allow relative or `http(s)` sources — `media-src 'self' https:`.
@@ -26,11 +36,40 @@
  *     authorizes it (and blocks a form exfiltrating to a third-party origin). Apps
  *     posting to a remote backend widen this alongside `connect-src`.
  *
- * Static pages (zero framework JS) still emit inline `<style>` and an inline
- * `<script type="speculationrules">`, so they keep `'unsafe-inline'`, but they
+ * Static pages (zero framework JS) share the same hash-based `script-src` but
  * never call `new Function`, so their CSP drops `'unsafe-eval'`.
  */
 
+import { createHash } from "node:crypto";
+
+/**
+ * The exact body of the inline `<script type="speculationrules">` block that
+ * `compilePage` emits for `transitions: true` pages. Kept in sync with
+ * `src/compiler/page.js` by a drift-guard test that hashes the block out of a
+ * real build — if the emitted rules change, that test fails before the CSP
+ * silently starts blocking prerender.
+ * @type {string}
+ */
+export const SPECULATION_RULES_JSON =
+  '{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}';
+
+/**
+ * CSP hash source for the speculationrules block — computed from the constant
+ * above at module load, never hand-maintained.
+ * @type {string}
+ */
+export const SPECULATION_RULES_HASH = `'sha256-${createHash("sha256")
+  .update(SPECULATION_RULES_JSON)
+  .digest("base64")}'`;
+
+/**
+ * The `script-src` both CSP variants share: same-origin scripts, plus the two
+ * grants for the inline speculationrules block (hash + keyword). No
+ * `'unsafe-inline'` — the state seed is a data block and needs nothing.
+ * @type {string}
+ */
+const SCRIPT_SRC = `script-src 'self' ${SPECULATION_RULES_HASH} 'inline-speculation-rules'`;
+
 /**
  * `connect-src` for the demo is `'self'`: the framework's own pages only
  * `:fetch` same-origin endpoints. Apps whose `:fetch` targets a remote host
@@ -42,6 +81,10 @@ const CONNECT_SRC = "connect-src 'self'";
 
 /**
  * Directives shared by both the static and reactive CSP. Order is cosmetic.
+ * `img-src`/`media-src` deliberately allow any `https:` host — remote images
+ * and media in markdown are legitimate everywhere. Sites that only serve their
+ * own assets can tighten both to `'self'` (plus `data:` for the favicon) in
+ * their deploy config; see SECURITY.md "Tightening the policy".
  * @type {string[]}
  */
 const COMMON_CSP_DIRECTIVES = [
@@ -59,24 +102,20 @@ const COMMON_CSP_DIRECTIVES = [
 ];
 
 /**
- * Relaxed CSP for reactive pages: `new Function` needs `'unsafe-eval'`, the
- * inline state/speculationrules JSON needs `'unsafe-inline'`.
+ * Relaxed CSP for reactive pages: `new Function` needs `'unsafe-eval'`; the
+ * inline speculationrules block rides on the shared hash source, so no
+ * `'unsafe-inline'`.
  * @type {string}
  */
-export const REACTIVE_CSP = [
-  "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
-  ...COMMON_CSP_DIRECTIVES
-].join("; ");
+export const REACTIVE_CSP = [`${SCRIPT_SRC} '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.
+ * `'unsafe-eval'` is dropped too. Inline `<style>` (view transitions) keeps
+ * `'unsafe-inline'` on style-src only.
  * @type {string}
  */
-export const STATIC_CSP = ["script-src 'self' 'unsafe-inline'", ...COMMON_CSP_DIRECTIVES].join(
-  "; "
-);
+export const STATIC_CSP = [SCRIPT_SRC, ...COMMON_CSP_DIRECTIVES].join("; ");
 
 /**
  * Baseline security headers applied to every HTML response, independent of the

package/src/router.js

@@ -101,11 +101,22 @@ export function routeFromFile(routesRoot, file) {
 
 /**
  * Map a public route to the `index.html` output path under `distRoot`.
+ *
+ * Defense in depth: routes come from `routeFromFile` walking `site/pages`, so
+ * they can't normally carry traversal segments — but any future caller passing
+ * an unvetted route must not be able to write outside the build output. The
+ * resolved path is asserted to stay inside `distRoot`.
  * @param {string} distRoot Absolute path to the build output directory.
  * @param {string} route Public route path.
  * @returns {string}
  */
 export function outputPathForRoute(distRoot, route) {
   const clean = route === "/" ? "" : route.replace(/^\/|\/$/g, "");
-  return path.join(distRoot, clean, "index.html");
+  const out = path.join(distRoot, clean, "index.html");
+  if (!path.resolve(out).startsWith(path.resolve(distRoot) + path.sep)) {
+    throw new Error(
+      `Route "${route}" resolves outside the build output directory ${distRoot} — routes must not contain traversal segments`
+    );
+  }
+  return out;
 }

package/src/runtime.js

@@ -142,6 +142,8 @@ const fmtToDate = (v) => {
 };
 /** @param {Date} d @param {any} opts @param {any} fb */
 const fmtDate = (d, opts, fb) => (Number.isNaN(d.getTime()) ? String(fb) : new Intl.DateTimeFormat(undefined, opts).format(d));
+/** Date-only strings (no time) format in UTC so the calendar date is stable. @param {any} v */
+const fmtTZ = (v) => (typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v.trim()) ? { timeZone: "UTC" } : undefined);
 
 /** @type {Record<string, (value: any, args: any[]) => any>} */
 const FMT = {
@@ -149,9 +151,9 @@ const FMT = {
   number: (v, [d]) => new Intl.NumberFormat(undefined, d == null ? {} : { minimumFractionDigits: +d, maximumFractionDigits: +d }).format(fmtNum(v)),
   percent: (v, [d = 0]) => new Intl.NumberFormat(undefined, { style: "percent", minimumFractionDigits: +d, maximumFractionDigits: +d }).format(fmtNum(v)),
   round: (v, [d = 0]) => { const p = 10 ** +d; return Math.round(fmtNum(v) * p) / p; },
-  date: (v, [s = "medium"]) => fmtDate(fmtToDate(v), { dateStyle: s }, v),
-  time: (v, [s = "short"]) => fmtDate(fmtToDate(v), { timeStyle: s }, v),
-  datetime: (v, [ds = "medium", ts = "short"]) => fmtDate(fmtToDate(v), { dateStyle: ds, timeStyle: ts }, v),
+  date: (v, [s = "medium"]) => fmtDate(fmtToDate(v), { dateStyle: s, ...fmtTZ(v) }, v),
+  time: (v, [s = "short"]) => fmtDate(fmtToDate(v), { timeStyle: s, ...fmtTZ(v) }, v),
+  datetime: (v, [ds = "medium", ts = "short"]) => fmtDate(fmtToDate(v), { dateStyle: ds, timeStyle: ts, ...fmtTZ(v) }, v),
   upper: (v) => String(v ?? "").toUpperCase(),
   lower: (v) => String(v ?? "").toLowerCase(),
   capitalize: (v) => { const s = String(v ?? ""); return s ? s[0].toUpperCase() + s.slice(1) : s; },