@nifrajs/web 2.2.0 → 2.4.0

package/src/internal/head-attributes.ts

@@ -0,0 +1,109 @@
+/**
+ * The one trust boundary for route-owned `<meta>` and `<link>` attributes.
+ *
+ * Both SSR and soft navigation consume this normalized representation. Keeping policy here prevents
+ * the two renderers from disagreeing about whether a descriptor is executable or otherwise unsafe.
+ */
+
+export type HeadTag = "meta" | "link"
+export type HeadAttributeValue = string | boolean | undefined
+export type TrustedHeadAttribute = readonly [name: string, value: string | true]
+
+const SAFE_ATTR_NAME = /^[a-z][a-z0-9-]*$/
+const DATA_ATTR_NAME = /^data-[a-z0-9-]+$/
+const EVENT_ATTR_NAME = /^on/i
+
+const META_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "charset",
+  "content",
+  "http-equiv",
+  "itemprop",
+  "media",
+  "name",
+  "property",
+  "scheme",
+])
+
+const LINK_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "as",
+  "blocking",
+  "color",
+  "crossorigin",
+  "disabled",
+  "fetchpriority",
+  "href",
+  "hreflang",
+  "imagesizes",
+  "imagesrcset",
+  "integrity",
+  "media",
+  "nonce",
+  "referrerpolicy",
+  "rel",
+  "sizes",
+  "title",
+  "type",
+])
+
+// Browsers ignore embedded ASCII whitespace/control characters while recognizing URL schemes. Remove
+// them before checking so `java\nscript:` cannot evade the scheme policy. Relative and protocol-relative
+// URLs are allowed; an explicit scheme must be HTTP(S). This rejects active and local schemes such as
+// javascript:, vbscript:, data:, blob:, and file: before a descriptor reaches either renderer.
+function hasDisallowedLinkScheme(value: string): boolean {
+  let compact = ""
+  for (const char of value) {
+    const code = char.charCodeAt(0)
+    if (code > 0x20 && code !== 0x7f) compact += char.toLowerCase()
+  }
+  const scheme = /^([a-z][a-z0-9+.-]*):/.exec(compact)?.[1]
+  return scheme !== undefined && scheme !== "http" && scheme !== "https"
+}
+
+/**
+ * Normalize one descriptor. `null` means the entire element is unsafe (currently meta refresh).
+ * Unknown attributes are dropped: future platform attributes must be reviewed and added explicitly.
+ */
+export function trustedHeadAttributes(
+  tag: HeadTag,
+  attrs: Readonly<object>,
+): readonly TrustedHeadAttribute[] | null {
+  if (typeof attrs !== "object" || attrs === null) return []
+  let entries: Array<[string, unknown]>
+  try {
+    entries = Object.entries(attrs)
+  } catch {
+    // A route can cross this runtime boundary through untyped JavaScript or a cast. A hostile Proxy/getter
+    // must not strand SSR or a soft navigation; reject the descriptor rather than partially trusting it.
+    return []
+  }
+
+  if (tag === "meta") {
+    for (const [rawName, value] of entries) {
+      if (
+        rawName.toLowerCase() === "http-equiv" &&
+        typeof value === "string" &&
+        value.trim().toLowerCase() === "refresh"
+      )
+        return null
+    }
+  }
+
+  const allowed = tag === "meta" ? META_ATTRIBUTES : LINK_ATTRIBUTES
+  const out: TrustedHeadAttribute[] = []
+  for (const [rawName, value] of entries) {
+    if (value === undefined || value === false) continue
+    if (value !== true && typeof value !== "string") continue
+    const name = rawName.toLowerCase()
+    if (!SAFE_ATTR_NAME.test(name) || EVENT_ATTR_NAME.test(name)) continue
+    if (!allowed.has(name) && !DATA_ATTR_NAME.test(name)) continue
+    if (
+      tag === "link" &&
+      name === "href" &&
+      typeof value === "string" &&
+      hasDisallowedLinkScheme(value)
+    )
+      continue
+    out.push([name, value === true ? true : value])
+  }
+  return out
+}

package/src/internal/script-types.ts

@@ -0,0 +1,18 @@
+/**
+ * The `type` values each head-script slot accepts, owned in one place because both halves enforce it:
+ * the server's `headTags` and the client's `applyHead` on a soft navigation. A head that renders and
+ * then throws on the next navigation is worse than one that never rendered.
+ *
+ * Allowlists rather than escaping. Both slots interpolate `type` into an attribute, and a value
+ * outside these sets is a mistake - emitting an escaped version of it would produce a `<script>` the
+ * browser treats as inert data under a name nobody meant. Escaping is for values; this is a keyword.
+ */
+
+/** Data, never executed by the browser. */
+export const INERT_SCRIPT_TYPES: ReadonlySet<string> = new Set([
+  "application/ld+json",
+  "application/json",
+])
+
+/** Executed. Only reachable through `unsafeScript`, which additionally requires a CSP nonce. */
+export const EXECUTABLE_SCRIPT_TYPES: ReadonlySet<string> = new Set(["module", "text/javascript"])

package/src/internal/server-boundary.ts

@@ -0,0 +1,187 @@
+/**
+ * The server/client boundary, owned in one place.
+ *
+ * The client build must never ship server-only code, or server-only config, to a browser. Three
+ * conventions enforce that, and each has to mean the SAME thing in every pipeline that builds the client
+ * - the Bun client build, the Vite dev server, the Vite production build, and `nifra dev --bun`'s refusal
+ * (which cannot transform, so it refuses to start instead):
+ *
+ *   - `*.server` modules - emptied, so a secret / `node:` / native import subtree never reaches the client.
+ *   - `*.fn` modules     - replaced with HTTP stubs, so the function bodies (and their imports) stay server-side.
+ *   - public-env prefix  - which environment variables the client bundle is allowed to inline.
+ *
+ * When each pipeline re-encoded one of these rules, they drifted. A hand-written glob
+ * `**\/*.server.{ts,tsx,js,jsx}` missed the extensionless `db.server` and the `.mts`/`.cts`/`.mjs`/`.cjs`
+ * forms the regex matches, waving a module the build empties straight into the browser. So the matchers,
+ * the replacement bodies, and the env mapping get exactly one definition here; every pipeline imports it,
+ * and parity tests assert the Bun and Vite halves emit identical bytes. A matcher that decides whether a
+ * secret can reach a browser gets one owner, not four.
+ */
+
+// Both module conventions match a filename SUFFIX with the identical optional source-extension tail -
+// `.ts`, `.tsx`, `.mts`, `.cts`, `.mjs`, `.cjs`, `.js`, `.jsx`, or none (the extensionless `db.server` /
+// `todos.fn`). Kept adjacent so the shared shape is visible, and a parity test pins that the two never
+// diverge on which extensions count - a copied-then-edited second tail is exactly how the old glob drifted.
+
+/** Matches `db.server.ts`, `auth.server.tsx`, `x.server.mjs`, and the extensionless `foo.server`. */
+export const SERVER_ONLY_MODULE = /\.server(\.[cm]?[jt]sx?)?$/
+/** Modules whose exports become client stubs. Mirrors the `.server` convention's shape. */
+export const SERVER_FN_MODULE = /\.fn(\.[cm]?[jt]sx?)?$/
+
+// ---------------------------------------------------------------------------------------------------
+// `.server` - empty a server-only module in the client build.
+// ---------------------------------------------------------------------------------------------------
+
+/**
+ * The replacement body for an emptied module. A Proxy rather than `export {}` so any named OR default
+ * import resolves to `undefined` instead of failing the bundle with a missing-export error - the client
+ * degrades at the call site it wrote, not at link time in a file it never named.
+ *
+ * Shared so the Bun and Vite pipelines emit the same bytes; a parity test asserts it.
+ */
+export const SERVER_ONLY_REPLACEMENT = "module.exports = new Proxy({}, { get: () => undefined })"
+
+const EXPORTED_DECLARATION =
+  /\bexport\s+(?:declare\s+)?(?:async\s+)?(?:const|let|var|function|class|enum)\s+([A-Za-z_$][\w$]*)/g
+const EXPORTED_LIST = /\bexport\s*\{([^}]*)\}(?:\s*from\s*["'][^"']+["'])?/g
+
+/**
+ * Vite dev serves native ESM, so the Bun/CommonJS proxy above is invalid there. Emit inert ESM
+ * bindings derived from the source's public names while discarding the implementation and imports.
+ * An unsupported exotic export fails closed at ESM link time; server code is never served as fallback.
+ */
+export function viteServerOnlyReplacement(source: string): string {
+  const names = new Set<string>()
+  let hasDefault = /\bexport\s+default\b/.test(source)
+
+  for (const match of source.matchAll(EXPORTED_DECLARATION)) names.add(match[1] as string)
+  for (const match of source.matchAll(EXPORTED_LIST)) {
+    for (const raw of (match[1] ?? "").split(",")) {
+      const item = raw.trim().replace(/^type\s+/, "")
+      if (item === "") continue
+      const parts = item.split(/\s+as\s+/)
+      const exported = (parts[1] ?? parts[0] ?? "").trim()
+      if (exported === "default") hasDefault = true
+      else if (/^[A-Za-z_$][\w$]*$/.test(exported)) names.add(exported)
+    }
+  }
+
+  const bindings = [...names].sort().map((name) => `export const ${name} = undefined`)
+  if (hasDefault) bindings.push("export default undefined")
+  return `// Generated by @nifrajs/web: server-only implementation removed from the browser.\n${bindings.join("\n")}\n`
+}
+
+// ---------------------------------------------------------------------------------------------------
+// `.fn` - turn a server-function module into the client stubs that call it.
+// ---------------------------------------------------------------------------------------------------
+
+/**
+ * The server half of a server function must never reach a browser: it closes over database handles,
+ * secrets and everything else the module imports. So the CLIENT build does not bundle these modules at
+ * all - it replaces each one with a stub per export that POSTs to the route the server mounted.
+ *
+ * The generation is pure on purpose. The Bun and Vite pipelines both need this transform and must
+ * produce byte-identical stubs, so it lives here and each bundler contributes only its own plugin shell.
+ * A divergence between the two would be a client that works in dev and 404s in production.
+ *
+ * The exports are found by scanning the SOURCE rather than importing it - importing would execute the
+ * module, which is precisely what must not happen in a client build - and the declaration form is fixed:
+ *
+ *     export const addTodo = serverFn({ … }, async (input, c) => { … })
+ *
+ * Anything else is refused rather than skipped: a server function the scanner cannot see would be absent
+ * from the client and fail as `addTodo is not a function` at runtime, far from the cause.
+ */
+
+/** `export const NAME = serverFn(` at the start of a line - the one declaration form. */
+const DECLARATION = /^[\t ]*export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*serverFn\s*\(/gm
+/** Any mention of `serverFn(` as a call, used to prove nothing was missed. */
+const ANY_CALL = /\bserverFn\s*\(/g
+/** Line comments and block comments, stripped before scanning so prose cannot register as code. */
+const COMMENTS = /\/\*[\s\S]*?\*\/|(^|[^:])\/\/.*$/gm
+
+/**
+ * The namespace a `*.fn.ts` module is mounted under: its filename without the `.fn` suffix.
+ *
+ * Deriving it from the filename rather than the full path keeps the build machine's directory layout
+ * out of a public URL, and keeps the route readable in logs. It also means the mount on the server -
+ * `serverFunctions("todos", …)` - has to use the same word, which is the one thing a reader must check
+ * by eye today; {@link SERVER_FN_MODULE} files are named for it precisely to make that obvious.
+ */
+export function serverFnNamespace(filePath: string): string {
+  const base = filePath.replaceAll("\\", "/").split("/").pop() ?? ""
+  return base.replace(SERVER_FN_MODULE, "")
+}
+
+/** The server functions a module declares, in source order. */
+export function scanServerFnExports(source: string): string[] {
+  const code = source.replaceAll(COMMENTS, "$1")
+  const names = [...code.matchAll(DECLARATION)].map((m) => m[1] as string)
+  const calls = [...code.matchAll(ANY_CALL)].length
+  if (calls > names.length) {
+    throw new Error(
+      "[nifra/fn] a server function is declared in a form the client transform cannot read. Use " +
+        "`export const name = serverFn(…)` at the top level: the client build scans the source rather " +
+        "than importing it (importing would run your server code during a browser build), so a " +
+        "declaration it cannot see would be missing from the client and fail as `name is not a function`.",
+    )
+  }
+  return names
+}
+
+/**
+ * The client replacement for a `*.fn.ts` module: one stub per export, and none of the original code.
+ *
+ * `credentials: "same-origin"` is explicit rather than relied upon - the server refuses a cross-origin
+ * call, and stating it here means the browser never sends cookies somewhere that would reject them.
+ * The content type is not decoration either: it is what makes a cross-origin form unable to forge one
+ * of these calls, so the stub and the server guard have to agree on it.
+ */
+export function generateServerFnStub(source: string, namespace: string): string {
+  const names = scanServerFnExports(source)
+  const calls = names
+    .map((name) => `export const ${name} = (input) => __nifraCall(${JSON.stringify(name)}, input)`)
+    .join("\n")
+  return `// Generated by @nifrajs/web: the server half of this module never reaches the browser.
+const __nifraBase = ${JSON.stringify(`/_nifra/fn/${namespace}`)}
+
+async function __nifraCall(name, input) {
+  const response = await fetch(\`\${__nifraBase}/\${name}\`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input === undefined ? {} : input),
+    credentials: "same-origin",
+  })
+  if (response.status === 404) {
+    throw new Error(
+      \`[nifra/fn] \${name} is not mounted at \${__nifraBase}. The client derives that path from this \` +
+        \`file's name, so the server's serverFunctions(...) namespace has to match it.\`,
+    )
+  }
+  if (!response.ok) {
+    let detail = ""
+    try {
+      detail = JSON.stringify(await response.json())
+    } catch {
+      // A non-JSON error body is not worth a second failure; the status carries enough.
+    }
+    throw new Error(\`[nifra/fn] \${name} failed: \${response.status}\${detail ? \` \${detail}\` : ""}\`)
+  }
+  return response.status === 204 ? undefined : await response.json()
+}
+
+${calls}
+`
+}
+
+// ---------------------------------------------------------------------------------------------------
+// public-env - which environment variables the client bundle may inline.
+// ---------------------------------------------------------------------------------------------------
+
+/** Translate Nifra's public-env contract to Vite's `envPrefix` option. */
+export function vitePublicEnvPrefix(prefix: string | undefined): string {
+  const configured = prefix ?? "PUBLIC_"
+  // Vite rejects an empty prefix. Environment-variable names cannot contain NUL, so this sentinel
+  // cannot match an ambient key and faithfully represents Nifra's "expose nothing" setting.
+  return configured === "" ? "\0nifra-public-env-disabled" : configured
+}

package/src/internal/timing-safe-equal.ts

@@ -2,7 +2,7 @@
  * Constant-time string equality, shared by every secret check in `@nifrajs/web`. Internal: no
  * `exports` entry points here, so it never becomes public API.
  *
- * One owner per package rather than a copy per call site — this is the primitive whose whole value
+ * One owner per package rather than a copy per call site - this is the primitive whose whole value
  * lies in a detail (no early exit) that a well-meaning "simplification" silently removes, and a bug
  * in it is invisible in review and in tests, since a timing-unsafe compare returns the same answers.
  */

package/src/internal/vite-import.ts

@@ -0,0 +1,92 @@
+/**
+ * The one place nifra imports Vite from.
+ *
+ * ## Why this is a module and not two `await import("vite")` calls
+ *
+ * Vite must not be imported before {@link relaxCaptureStackTrace} has run, and that requirement is
+ * invisible at the call site. It was invisible in exactly the way that matters: the production build
+ * relaxed first, the dev server did not, and the dev server's import ran earlier in the test process.
+ * ESM caches a module that throws while EVALUATING, so once vite failed there it kept failing - every
+ * later `loadVite` re-threw the cached error, with its shim correctly installed and no longer able to
+ * help. One unguarded import poisons vite for the whole process.
+ *
+ * So the import lives here and the guard is not optional. A caller cannot get the module without it.
+ */
+
+/** Marks the shim as installed, so repeated imports do not wrap a wrapper. */
+const RELAXED: unique symbol = Symbol.for("@nifrajs/web/relaxed-capture-stack-trace")
+
+/**
+ * Restore V8's `Error.captureStackTrace` contract on a runtime that is stricter than it.
+ *
+ * `captureStackTrace` is a V8 API and V8 decorates ANY object handed to it. Some runtimes require a
+ * real Error - one with the internal slot - and throw "First argument must be an Error object".
+ *
+ * That breaks importing vite outright. Vite bundles `follow-redirects`, which builds its error types
+ * the pre-class way:
+ *
+ *   function CustomError(props) { Error.captureStackTrace(this, this.constructor); … }
+ *   CustomError.prototype = new (baseClass || Error)()
+ *
+ * The last line CONSTRUCTS `baseClass` while defining the subclass, so `this` inherits from Error but
+ * was never built by it - and the throw lands during module evaluation, before vite exports anything.
+ *
+ * Decorating a stack is best-effort by definition, so swallowing the refusal loses nothing: the shim
+ * delegates and suppresses only that. Installed once and deliberately not restored, since the strict
+ * behaviour is the deviation and a library evaluated later meets the same wall.
+ *
+ * ## Why it does not probe first
+ *
+ * It used to construct an object like follow-redirects' and install the shim only if the runtime
+ * refused it. That shipped and CI still failed, because the probe was not the same shape as the real
+ * call: it passed `Object.create(Error.prototype)` and no `constructorOpt`, while follow-redirects
+ * passes an object whose prototype is an Error INSTANCE plus `this.constructor`. One Bun build accepts
+ * the former and rejects the latter, so the probe reported "permissive" and installed nothing.
+ *
+ * A probe has to predict every caller's construction pattern to be right, and is silently wrong when
+ * it guesses short. Installing unconditionally cannot fail that way.
+ */
+export function relaxCaptureStackTrace(): void {
+  const strict = Error.captureStackTrace
+  if (typeof strict !== "function") return
+  if ((Error as unknown as Record<PropertyKey, unknown>)[RELAXED] === true) return
+  try {
+    Error.captureStackTrace = ((target: object, constructorOpt?: unknown) => {
+      try {
+        ;(strict as (t: object, c?: unknown) => void).call(Error, target, constructorOpt)
+      } catch {
+        // The runtime refused to decorate this object. A missing `.stack` is not worth failing over.
+      }
+    }) as typeof Error.captureStackTrace
+    Object.defineProperty(Error, RELAXED, { value: true, configurable: true })
+  } catch {
+    // The property is frozen or non-writable. Nothing can be done about the import that follows, but
+    // failing HERE would replace vite's own error with an assignment error - strictly less
+    // informative than letting the import fail and be reported by the caller.
+  }
+}
+
+/**
+ * Import the project's Vite, with the stack-trace contract restored first.
+ *
+ * Callers keep their own error message - the dev server and the production build fail for the same
+ * reasons but need to say different things - so this deliberately lets the cause through untouched.
+ * Use {@link isViteUnresolved} to tell "vite is not installed" from "vite failed to load".
+ */
+export async function importVite<T>(): Promise<T> {
+  relaxCaptureStackTrace()
+  return (await import("vite")) as unknown as T
+}
+
+/**
+ * Whether a failed {@link importVite} means vite is absent rather than broken.
+ *
+ * `vite` is an OPTIONAL peer, so a project without it fails to RESOLVE - the common case, and the one
+ * worth naming. But vite can also resolve and fail while EVALUATING, which is not a missing dependency
+ * at all: vite 8 loads rolldown's native binding on import, and a binding that will not load surfaces
+ * the same way. Telling that user to install what they already installed sends them the wrong way.
+ */
+export function isViteUnresolved(cause: unknown): boolean {
+  const message = cause instanceof Error ? cause.message : String(cause)
+  return /cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)
+}

package/src/islands.ts

@@ -1,16 +1,16 @@
 /**
- * @nifrajs/web/islands — the framework-agnostic islands client runtime.
+ * @nifrajs/web/islands - the framework-agnostic islands client runtime.
  *
  * An "island" is a server-rendered `<nifra-island>` element whose interactivity is mounted by a small
  * **plain-DOM** enhancer instead of a framework runtime. On a route that opts out of full-document
  * hydration (`export const hydrate = false`), the page ships **zero** framework JS; only the island
  * bundle (this runtime + your enhancers) loads. This variant ships ~99% less client JS than full
- * React hydration on a mostly-static page — the framework runtime is the cost, and islands skip it
+ * React hydration on a mostly-static page - the framework runtime is the cost, and islands skip it
  * entirely here.
  *
  * Server side: render the marker with `@nifrajs/web-react`'s `<Island>` (or any framework's host element
  * `<nifra-island data-id data-strategy data-props>`). Props are JSON-encoded inline in `data-props`
- * (attribute-escaped by the framework) — no central registry, so concurrent SSR renders never share
+ * (attribute-escaped by the framework) - no central registry, so concurrent SSR renders never share
  * state. Client side: bundle one entry that calls `mountIslands({ <id>: enhancer })` and load it via
  * the route's `islandScripts`.
  */
@@ -23,10 +23,10 @@ export type IslandCleanup = () => void
 
 /**
  * Enhances one island element with its (typed) props. Return a cleanup function to tear down on
- * `dispose()` (listeners, observers) — optional; an enhancer with nothing to clean up returns nothing.
+ * `dispose()` (listeners, observers) - optional; an enhancer with nothing to clean up returns nothing.
  * The `void` member is the no-cleanup case, the same shape as React's `EffectCallback`.
  */
-// biome-ignore lint/suspicious/noConfusingVoidType: `void` = "no cleanup returned", like React's EffectCallback — cleanup is optional.
+// biome-ignore lint/suspicious/noConfusingVoidType: `void` = "no cleanup returned", like React's EffectCallback - cleanup is optional.
 export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandCleanup | void
 
 const NOOP = (): void => {}
@@ -79,7 +79,7 @@ function whenStrategy(el: HTMLElement, strategy: IslandStrategy, run: () => void
 /**
  * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
  * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
- * inert SSR HTML (forward-compatible). An enhancer that throws is isolated — it never blocks the
+ * inert SSR HTML (forward-compatible). An enhancer that throws is isolated - it never blocks the
  * others (each island is independent). Returns a disposer that cancels pending triggers and runs every
  * enhancer's cleanup (call it on soft-nav teardown; harmless if your app never navigates).
  */
@@ -114,7 +114,7 @@ export function mountIslands(
       try {
         dispose()
       } catch {
-        // best-effort teardown — a failing cleanup must not block the rest
+        // best-effort teardown - a failing cleanup must not block the rest
       }
     }
   }

package/src/isr.ts

@@ -9,7 +9,7 @@
 import { isDraftEnabled } from "./draft.ts"
 import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
 
-/** A cached SSR response — the bytes + metadata a {@link CacheStore} persists. */
+/** A cached SSR response - the bytes + metadata a {@link CacheStore} persists. */
 export interface CachedResponse {
   /** The rendered document (UTF-8 HTML, fully buffered). */
   readonly body: string
@@ -38,7 +38,7 @@ export interface CacheStore {
 }
 
 export interface MemoryCacheStoreOptions {
-  /** Allow the in-memory store in production. Off by default — per-instance caching means revalidation
+  /** Allow the in-memory store in production. Off by default - per-instance caching means revalidation
    * won't propagate across instances and each instance caches separately. */
   readonly allowInProduction?: boolean
   /** Hard cap on entries; the least-recently-used is evicted past it (default 500). */
@@ -47,7 +47,7 @@ export interface MemoryCacheStoreOptions {
 
 /**
  * In-process ISR cache. Refuses to run in production unless explicitly allowed (mirrors the
- * rate-limit `MemoryStore` — a per-instance cache is unsafe across instances). Bounded **LRU**: a
+ * rate-limit `MemoryStore` - a per-instance cache is unsafe across instances). Bounded **LRU**: a
  * read or write bumps the entry, so the least-recently-used evicts past `max` (a hot, frequently-read
  * page survives a burst of new pages).
  */
@@ -70,7 +70,7 @@ export class MemoryCacheStore implements CacheStore {
   get(key: string): Promise<CachedResponse | undefined> {
     const value = this.cache.get(key)
     // LRU: a read bumps the entry to the tail so the bounded evict drops the LEAST-RECENTLY-USED,
-    // not the oldest-written — otherwise a burst of new pages would evict a hot, frequently-read one.
+    // not the oldest-written - otherwise a burst of new pages would evict a hot, frequently-read one.
     if (value !== undefined) {
       this.cache.delete(key)
       this.cache.set(key, value)
@@ -96,7 +96,7 @@ export class MemoryCacheStore implements CacheStore {
 }
 
 /**
- * Minimal structural shape of a Cloudflare Workers **KV namespace** binding — just the three methods
+ * Minimal structural shape of a Cloudflare Workers **KV namespace** binding - just the three methods
  * {@link KVCacheStore} uses. Structural (not a dependency on `@cloudflare/workers-types`) so any
  * KV-like binding satisfies it and tests can pass an in-memory double.
  */
@@ -112,9 +112,9 @@ export interface KVNamespaceLike {
 export interface KVCacheStoreOptions {
   /**
    * GC backstop (**seconds**) written as the KV entry's `expirationTtl`, so abandoned entries
-   * eventually evict. MUST exceed your longest `revalidate` window — otherwise KV expiry turns a
+   * eventually evict. MUST exceed your longest `revalidate` window - otherwise KV expiry turns a
    * stale-while-revalidate into a *blocking* miss (the entry vanishes instead of being served stale
-   * while it regenerates) — and be ≥ 60 (Cloudflare KV's minimum). Omit ⇒ entries persist until
+   * while it regenerates) - and be ≥ 60 (Cloudflare KV's minimum). Omit ⇒ entries persist until
    * overwritten on regeneration or purged via `revalidateEndpoint`.
    */
   readonly expirationTtl?: number
@@ -146,7 +146,7 @@ const isCachedResponse = (value: unknown): value is CachedResponse => {
 
 /**
  * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
- * binding) — the production-grade shared/durable store ISR wants: cached pages and on-demand purges
+ * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
  * hold *across* worker instances (unlike the per-instance {@link MemoryCacheStore}). Entries serialize
  * to JSON; every read is validated before it's trusted (a malformed/version-skewed entry is treated as
  * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`.
@@ -191,13 +191,13 @@ export class KVCacheStore implements CacheStore {
   }
 }
 
-/** Minimal platform shape `withISR` needs — just `waitUntil` (edge runtimes extend the response
+/** Minimal platform shape `withISR` needs - just `waitUntil` (edge runtimes extend the response
  * lifetime so background regeneration finishes). Off-edge it's absent and regen runs fire-and-forget. */
 export interface ISRPlatform {
   readonly waitUntil?: (promise: Promise<unknown>) => void
 }
 
-/** The app `withISR` wraps — anything with a `fetch(req, platform?)` (a `createWebApp` result). */
+/** The app `withISR` wraps - anything with a `fetch(req, platform?)` (a `createWebApp` result). */
 export interface ISRApp {
   fetch(req: Request, platform?: ISRPlatform): Response | Promise<Response>
 }
@@ -208,7 +208,7 @@ export const ISR_STATUS_HEADER = "x-nifra-isr"
 
 /**
  * Response header a route uses to advertise its ISR freshness (**seconds**) to a {@link withISR}
- * wrapper — `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
+ * wrapper - `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
  * from the action-revalidation `x-nifra-revalidate` header (a CSV path list the *client* parses to
  * refetch): this one is an integer TTL the *wrapper* reads, so the two channels never alias.
  */
@@ -220,14 +220,14 @@ export interface ISROptions {
    * behind). A route overrides it per-page via `export const revalidate` (surfaced as the
    * `x-nifra-isr-revalidate` response header). */
   readonly revalidate: number
-  /** Monotonic clock (ms) — injected for testability; production passes `() => Date.now()`. */
+  /** Monotonic clock (ms) - injected for testability; production passes `() => Date.now()`. */
   readonly now: () => number
   /** Cache key for a request. Default: `origin + pathname + search` so host-routed apps do not share
    * entries across tenants. Return `null` to bypass the cache for this request (it goes straight to the
    * app, uncached). */
   readonly key?: (req: Request) => string | null
   /** Draft/preview secret (the same one given to `createWebApp({ draftSecret })` + `enableDraft`). When
-   * set, a request carrying a valid signed draft cookie **bypasses the cache** — editors always render
+   * set, a request carrying a valid signed draft cookie **bypasses the cache** - editors always render
    * fresh, and a draft render is never written to the store (it can't poison the public cache). */
   readonly draftSecret?: string
 }
@@ -307,7 +307,7 @@ function sanitizeCachedHeaders(headers: Readonly<Record<string, string>>): Recor
  * Wrap a nifra app with **Incremental Static Regeneration**: a cacheable page is served from
  * {@link CacheStore} when fresh, served **stale while a fresh copy regenerates in the background**
  * (`platform.waitUntil` on edge), or rendered + stored on a miss. Framework-agnostic (it caches the
- * rendered bytes). Returns a `fetch(req, platform?)` handler — hand it to `Bun.serve`/the Workers
+ * rendered bytes). Returns a `fetch(req, platform?)` handler - hand it to `Bun.serve`/the Workers
  * `export default`, etc. Regeneration is single-flight per key (no stampede on a hot stale page).
  *
  * Each route's freshness comes from the `revalidate` header the app sets (per-route
@@ -352,7 +352,7 @@ export function withISR(
     })
   }
 
-  // Background regeneration (single-flight per key) — a failed regen keeps the stale entry; the next
+  // Background regeneration (single-flight per key) - a failed regen keeps the stale entry; the next
   // stale hit retries. Never throws (it runs detached / under waitUntil).
   const regenerate = async (
     req: Request,
@@ -413,13 +413,13 @@ export interface RevalidateEndpointOptions {
   readonly secret: string
   /** Header carrying the secret. Default `x-nifra-revalidate-token`. */
   readonly tokenHeader?: string
-  /** Map a to-purge path → its cache key — MUST match the `withISR` `key` fn. The default uses the
+  /** Map a to-purge path → its cache key - MUST match the `withISR` `key` fn. The default uses the
    * revalidation request's origin plus the purged path, matching `withISR`'s default host-aware key. */
   readonly key?: (path: string, req: Request) => string
 }
 
 /**
- * An **on-demand revalidation** (purge) endpoint — a `fetch` handler that drops a path's cached entry
+ * An **on-demand revalidation** (purge) endpoint - a `fetch` handler that drops a path's cached entry
  * so the next request re-renders. `POST` with the secret in the token header and the path as `?path=`
  * or a JSON `{ "path": "/blog/x" }` body. The token is checked in **constant time** (wrong/missing →
  * `401`); a missing/relative path → `400`; non-POST → `405`. Mount it on a nifra route, e.g.