@nifrajs/web 3.5.0 → 4.0.0

package/src/internal/server-boundary.ts

@@ -1,83 +1,20 @@
 /**
- * The server/client boundary, owned in one place.
+ * The client-build transforms that every pipeline must apply identically - the Bun client build, the
+ * Vite dev server, the Vite production build, and `nifra dev --bun`:
  *
- * 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`:
- *
- *   - `*.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.
+ * Which files may reach a browser at all is the zone classifier's job (`zones.ts`). These two get one
+ * definition here so the Bun and Vite halves emit identical bytes; a copied-then-edited second version
+ * is how a client that works in dev and 404s in production happens.
  */
 
-// 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. */
+/** Modules whose exports become client stubs: `todos.fn.ts`, `x.fn.mjs`, or the extensionless `foo.fn`. */
 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 })"
-
 import { jsStringLiteral } from "./js-string.ts"
 
-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(",")) {
-      // Collapse runs of whitespace first (linear), so the ` as ` split below needs no `\s+as\s+`
-      // regex - adjacent unbounded quantifiers around a literal backtrack quadratically on crafted
-      // all-whitespace input.
-      const item = raw
-        .trim()
-        .replace(/\s+/g, " ")
-        .replace(/^type /, "")
-      if (item === "") continue
-      const parts = item.split(" as ")
-      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.
 // ---------------------------------------------------------------------------------------------------

package/src/internal/source-map.ts

@@ -0,0 +1,256 @@
+/**
+ * Source map v3 decoding, encoding and lookup, shared by the browser-frame mapper, the dev server's
+ * SSR frame remap and the SFC plugins that join several compiler outputs into one module. Node-free.
+ */
+
+/** A source map as its v3 JSON object. */
+export interface RawSourceMap {
+  /** `3`; some compilers type it as the string. */
+  readonly version: number | string
+  readonly sources: readonly string[]
+  readonly sourcesContent?: readonly (string | null)[] | undefined
+  readonly names?: readonly string[] | undefined
+  readonly mappings: string
+  readonly file?: string | undefined
+}
+
+/** One generated line's segments, flattened: [column, source, line, column] per segment, all absolute. */
+export type MappingLine = Int32Array
+
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+const BASE64_VALUE = new Int8Array(128).fill(-1)
+for (let i = 0; i < BASE64.length; i++) BASE64_VALUE[BASE64.charCodeAt(i)] = i
+
+/** Decode a source map v3 `mappings` string. Segments without a source are dropped. */
+export function decodeMappings(mappings: string): MappingLine[] {
+  const lines: MappingLine[] = []
+  let segment: number[] = []
+  let current: number[] = []
+  let generatedColumn = 0
+  let source = 0
+  let sourceLine = 0
+  let sourceColumn = 0
+  let value = 0
+  let shift = 0
+  const endSegment = (): void => {
+    if (segment.length === 0) return
+    generatedColumn += segment[0] ?? 0
+    if (segment.length >= 4) {
+      source += segment[1] ?? 0
+      sourceLine += segment[2] ?? 0
+      sourceColumn += segment[3] ?? 0
+      current.push(generatedColumn, source, sourceLine, sourceColumn)
+    }
+    segment = []
+  }
+  for (let i = 0; i < mappings.length; i++) {
+    const code = mappings.charCodeAt(i)
+    if (code === 44 /* , */) {
+      endSegment()
+      continue
+    }
+    if (code === 59 /* ; */) {
+      endSegment()
+      lines.push(Int32Array.from(current))
+      current = []
+      generatedColumn = 0
+      continue
+    }
+    const digit = code < 128 ? (BASE64_VALUE[code] ?? -1) : -1
+    if (digit === -1) throw new Error(`invalid VLQ character at ${i}`)
+    value += (digit & 31) << shift
+    if (digit & 32) {
+      shift += 5
+      continue
+    }
+    segment.push(value & 1 ? -(value >>> 1) : value >>> 1)
+    value = 0
+    shift = 0
+  }
+  endSegment()
+  lines.push(Int32Array.from(current))
+  return lines
+}
+
+function vlq(value: number): string {
+  let rest = value < 0 ? (-value << 1) | 1 : value << 1
+  let out = ""
+  do {
+    let digit = rest & 31
+    rest >>>= 5
+    if (rest > 0) digit |= 32
+    out += BASE64[digit]
+  } while (rest > 0)
+  return out
+}
+
+/** Encode decoded lines back into a `mappings` string. */
+export function encodeMappings(lines: readonly MappingLine[]): string {
+  let source = 0
+  let sourceLine = 0
+  let sourceColumn = 0
+  return lines
+    .map((segments) => {
+      let generatedColumn = 0
+      const parts: string[] = []
+      for (let i = 0; i + 3 < segments.length; i += 4) {
+        const column = segments[i] ?? 0
+        const s = segments[i + 1] ?? 0
+        const l = segments[i + 2] ?? 0
+        const c = segments[i + 3] ?? 0
+        parts.push(
+          vlq(column - generatedColumn) +
+            vlq(s - source) +
+            vlq(l - sourceLine) +
+            vlq(c - sourceColumn),
+        )
+        generatedColumn = column
+        source = s
+        sourceLine = l
+        sourceColumn = c
+      }
+      return parts.join(",")
+    })
+    .join(";")
+}
+
+/** The source position for a 0-based generated line/column: the last segment at or before it. */
+export function lookupPosition(
+  lines: readonly (MappingLine | undefined)[],
+  line: number,
+  column: number,
+): { readonly source: number; readonly line: number; readonly column: number } | undefined {
+  const segments = lines[line]
+  if (segments === undefined || segments.length === 0) return undefined
+  let low = 0
+  let high = segments.length / 4 - 1
+  let found = -1
+  while (low <= high) {
+    const mid = (low + high) >>> 1
+    if ((segments[mid * 4] ?? 0) <= column) {
+      found = mid
+      low = mid + 1
+    } else high = mid - 1
+  }
+  if (found === -1) found = 0
+  return {
+    source: segments[found * 4 + 1] ?? 0,
+    line: (segments[found * 4 + 2] ?? 0) + 1,
+    column: (segments[found * 4 + 3] ?? 0) + 1,
+  }
+}
+
+const decoded = new WeakMap<RawSourceMap, MappingLine[]>()
+
+/** Where a 1-based generated line/column came from in `map`'s first-listed sources, 1-based. */
+export function originalPosition(
+  map: RawSourceMap,
+  line: number,
+  column: number,
+): { readonly line: number; readonly column: number } | undefined {
+  let lines = decoded.get(map)
+  if (lines === undefined) {
+    lines = decodeMappings(map.mappings)
+    decoded.set(map, lines)
+  }
+  const found = lookupPosition(lines, line - 1, column - 1)
+  return found === undefined ? undefined : { line: found.line, column: found.column }
+}
+
+const INLINE_MAP = /\/\/[#@] sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)\s*$/
+
+/** The map a module carries as a trailing base64 `sourceMappingURL` comment, when it does. */
+export function inlineSourceMap(code: string): RawSourceMap | undefined {
+  const found = INLINE_MAP.exec(code.slice(-4 * 1024 * 1024))
+  if (found === null) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(atob(found[1] ?? ""))
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== "object" || parsed === null) return undefined
+  const mappings: unknown = Reflect.get(parsed, "mappings")
+  const sources: unknown = Reflect.get(parsed, "sources")
+  if (typeof mappings !== "string" || !Array.isArray(sources)) return undefined
+  return {
+    version: 3,
+    sources: sources.map((source) => (typeof source === "string" ? source : "")),
+    mappings,
+  }
+}
+
+/**
+ * One map over parts joined with no separator, each part either mapped by its own map or unmapped
+ * (generated glue). Sources are merged by name.
+ */
+export function concatSourceMaps(
+  parts: readonly { readonly code: string; readonly map?: RawSourceMap | undefined }[],
+): RawSourceMap {
+  const sources: string[] = []
+  const sourcesContent: (string | null)[] = []
+  const out: number[][] = [[]]
+  for (const part of parts) {
+    const lineOffset = out.length - 1
+    // A part that starts mid-line shifts its first line's columns by what is already on that line.
+    const columnOffset = lastLineLength(parts, part)
+    if (part.map !== undefined) {
+      const index = part.map.sources.map((source, i) => {
+        let at = sources.indexOf(source)
+        if (at === -1) {
+          at = sources.push(source) - 1
+          sourcesContent.push(part.map?.sourcesContent?.[i] ?? null)
+        }
+        return at
+      })
+      decodeMappings(part.map.mappings).forEach((segments, line) => {
+        const target = out[lineOffset + line] ?? []
+        out[lineOffset + line] = target
+        for (let i = 0; i + 3 < segments.length; i += 4) {
+          target.push(
+            (segments[i] ?? 0) + (line === 0 ? columnOffset : 0),
+            index[segments[i + 1] ?? 0] ?? 0,
+            segments[i + 2] ?? 0,
+            segments[i + 3] ?? 0,
+          )
+        }
+      })
+    }
+    const newlines = part.code.split("\n").length - 1
+    for (let i = 0; i < newlines; i++) out[lineOffset + 1 + i] ??= []
+  }
+  return {
+    version: 3,
+    sources,
+    sourcesContent,
+    names: [],
+    mappings: encodeMappings(out.map((line) => Int32Array.from(line))),
+  }
+}
+
+function lastLineLength(
+  parts: readonly { readonly code: string }[],
+  until: { readonly code: string },
+): number {
+  let length = 0
+  for (const part of parts) {
+    if (part === until) return length
+    const newline = part.code.lastIndexOf("\n")
+    length = newline === -1 ? length + part.code.length : part.code.length - newline - 1
+  }
+  return length
+}
+
+const REGISTRY = Symbol.for("nifra.dev.ssrSourceMaps")
+
+/**
+ * The maps of modules a dev plugin compiled for SSR, by file path. Bun's runtime ignores a plugin's
+ * inline map, so a server stack names the compiled line; the dev server remaps through this.
+ */
+export function ssrSourceMaps(): Map<string, RawSourceMap> {
+  const existing: unknown = Reflect.get(globalThis, REGISTRY)
+  if (existing instanceof Map) return existing
+  const created = new Map<string, RawSourceMap>()
+  Reflect.set(globalThis, REGISTRY, created)
+  return created
+}

package/src/internal/target-compat.ts

@@ -0,0 +1,92 @@
+/**
+ * Which runtime built-ins a server bundle can load on its target. Separate from the zone rules: a
+ * backend module may import `node:fs`, but an edge worker cannot run it, and a Node server has no
+ * `bun:` modules. Same refusal and wording as the Vite edge build's guard.
+ */
+import type { ClientModuleGraph, GraphImport } from "../module-graph.ts"
+
+export type ServerBundleTarget = "browser" | "node" | "bun"
+
+/** Built-in prefixes each target cannot load. The `browser` target is the edge (workerd, edge-light). */
+const UNSUPPORTED: Readonly<Record<ServerBundleTarget, readonly string[]>> = {
+  browser: ["node:", "bun:"],
+  node: ["bun:"],
+  bun: [],
+}
+
+/**
+ * The `node:` built-ins every edge runtime nifra deploys to provides: Cloudflare Workers with
+ * `nodejs_compat` (the scaffold's wrangler.toml sets it), Vercel Edge and Deno. Svelte's server renderer
+ * imports `node:async_hooks` for AsyncLocalStorage.
+ */
+export const EDGE_NODE_BUILTINS: ReadonlySet<string> = new Set([
+  "node:assert",
+  "node:async_hooks",
+  "node:buffer",
+  "node:events",
+  "node:util",
+])
+
+/** Whether a server bundle for `target` cannot load the built-in `specifier`. */
+export function unsupportedBuiltin(specifier: string, target: ServerBundleTarget): boolean {
+  if (target === "browser" && EDGE_NODE_BUILTINS.has(specifier)) return false
+  return UNSUPPORTED[target].some((prefix) => specifier.startsWith(prefix))
+}
+
+/**
+ * The built-ins a server bundle still loads that its target cannot, each with the modules that import
+ * them. A tree-shaken library module that imports `node:fs` is not one: only what the output keeps can
+ * fail. Two kinds are kept: an import the emitted code still makes (a dynamic `import()` that survived),
+ * and a static import of a built-in the bundler left external in a module that ships, which Bun's
+ * browser target replaces with an empty object that throws on first use. A chunk without `imports`
+ * evidence falls back to every module import, so missing evidence refuses.
+ */
+export function unsupportedBuiltins(
+  graph: ClientModuleGraph,
+  target: ServerBundleTarget,
+  labelOf: (id: string) => string,
+): ReadonlyMap<string, readonly string[]> {
+  if (UNSUPPORTED[target].length === 0) return new Map()
+  const unsupported = (spec: string) => unsupportedBuiltin(spec, target)
+  const specOf = (im: GraphImport) => im.original ?? im.path ?? ""
+  const chunks = Object.values(graph.chunks)
+  const evidence = chunks.every((chunk) => chunk.imports !== undefined)
+  const shipped = evidence
+    ? new Set(chunks.flatMap((chunk) => chunk.modules))
+    : new Set(Object.keys(graph.modules))
+  const found = new Map<string, Set<string>>()
+  const keep = (builtin: string) => {
+    if (unsupported(builtin) && !found.has(builtin)) found.set(builtin, new Set())
+  }
+  for (const chunk of chunks) for (const spec of chunk.imports ?? []) keep(spec)
+  for (const id of shipped) {
+    for (const im of graph.modules[id]?.imports ?? []) {
+      if (!evidence || (im.external === true && im.dynamic !== true)) keep(specOf(im))
+    }
+  }
+  for (const id of shipped) {
+    for (const im of graph.modules[id]?.imports ?? []) found.get(specOf(im))?.add(labelOf(id))
+  }
+  return new Map([...found].map(([builtin, importers]) => [builtin, [...importers].sort()]))
+}
+
+/** The build-failing message for {@link unsupportedBuiltins}, or `undefined` when there are none. */
+export function formatUnsupportedBuiltins(
+  found: ReadonlyMap<string, readonly string[]>,
+  target: ServerBundleTarget,
+): string | undefined {
+  if (found.size === 0) return undefined
+  const builtins = [...found.keys()].sort()
+  const importers = [...new Set([...found.values()].flat())].sort().join(", ") || "unknown module"
+  if (target === "browser") {
+    return (
+      `[nifra/web] Node built-in(s) reached an edge server bundle: ${builtins.join(", ")}. ` +
+      `Imported by: ${importers}. ` +
+      "Move the import behind a Node/Bun target or replace it with an edge-compatible API."
+    )
+  }
+  return (
+    `[nifra/web] Bun built-in(s) reached a Node server bundle: ${builtins.join(", ")}. ` +
+    `Imported by: ${importers}. Build for the Bun target or replace it with a Node API.`
+  )
+}

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

@@ -22,3 +22,16 @@ export function timingSafeEqual(a: string, b: string): boolean {
   for (let i = 0; i < ba.length; i++) diff |= (ba[i] as number) ^ (bb[i] as number)
   return diff === 0
 }
+
+/**
+ * Boot-time guard for a shared bearer token checked with {@link timingSafeEqual}. A missing header or
+ * query parameter is compared as `""`, so an empty (or unset, then defaulted) secret would authorize
+ * every request that simply omits the token. Throws rather than letting that endpoint exist.
+ */
+export function assertTokenSecret(secret: unknown, label: string): asserts secret is string {
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new TypeError(
+      `[nifra] ${label} requires a non-empty secret; an empty one would accept requests that omit the token`,
+    )
+  }
+}

package/src/internal/vitals-runtime.ts

@@ -0,0 +1,53 @@
+/** `@nifrajs/web/vitals` with the metric library passed in, so tests can use a fake. */
+import type { MetricType, ReportOpts } from "web-vitals"
+import { getBrowserRouter } from "../navigation.ts"
+import type { ReportWebVitalsOptions, WebVitalsMetric } from "../vitals.ts"
+
+type OnMetric = (report: (metric: MetricType) => void, options?: ReportOpts) => void
+
+/** The `web-vitals` functions the reporter registers with. */
+export interface VitalsLibrary {
+  readonly onCLS: OnMetric
+  readonly onFCP: OnMetric
+  readonly onINP: OnMetric
+  readonly onLCP: OnMetric
+  readonly onTTFB: OnMetric
+}
+
+/** The route id a measured URL matches, through the router `installHistory` registered. A metric of a
+ * client navigation names that navigation's URL; any other names the document's, and a library that
+ * names none falls back to the current one. */
+function routeOf(url: string | undefined): string | undefined {
+  const router = getBrowserRouter()
+  if (router === undefined) return undefined
+  const target = new URL(url ?? location.href, location.href)
+  if (target.origin !== location.origin) return undefined
+  return router.match(target.pathname + target.search)?.routeId
+}
+
+/** Register `report` with every metric `library` measures. Each report is a fresh object, so a metric
+ * kept by the caller does not change when the library updates its own copy. On the server there is
+ * nothing to measure, and the returned stop function is a no-op. */
+export function reportWith(
+  library: VitalsLibrary,
+  report: (metric: WebVitalsMetric) => void,
+  options: ReportWebVitalsOptions,
+): () => void {
+  if (typeof document === "undefined") return () => {}
+  let active = true
+  const opts: ReportOpts = {
+    reportAllChanges: options.reportAllChanges === true,
+    reportSoftNavs: options.softNavigations === true,
+  }
+  const forward = (metric: MetricType): void => {
+    if (active) report({ ...metric, route: routeOf(metric.navigationURL) })
+  }
+  library.onCLS(forward, opts)
+  library.onFCP(forward, opts)
+  library.onINP(forward, opts)
+  library.onLCP(forward, opts)
+  library.onTTFB(forward, opts)
+  return () => {
+    active = false
+  }
+}