@nifrajs/web 3.3.0 → 4.0.0

package/src/module-graph.ts

@@ -23,6 +23,11 @@ export interface GraphImport {
   readonly path?: string
   /** The specifier as written in source - the only form that survives an unresolved import. */
   readonly original?: string
+  /** The bundler left this import in the emitted code instead of bundling its target. Bun does this
+   * for a dynamic `import("node:fs")` in a browser build: the import ships, the module does not. */
+  readonly external?: boolean
+  /** A dynamic `import()`. A bundler can drop one in dead code while the module around it ships. */
+  readonly dynamic?: boolean
 }
 
 export interface GraphModule {
@@ -34,6 +39,13 @@ export interface GraphChunk {
   readonly entryPoint?: string
   /** Module ids that landed in this chunk. */
   readonly modules: readonly string[]
+  /** The names this chunk exports, when the bundler reports them (entry chunks). */
+  readonly exports?: readonly string[]
+  /**
+   * What the emitted code itself imports: another output by its key in `chunks`, anything else as
+   * written. Module-level edges cannot say this - a bundler drops some and keeps others.
+   */
+  readonly imports?: readonly string[]
 }
 
 /** What a client build looks like to the guards, whichever bundler produced it. */
@@ -52,12 +64,26 @@ const normalizeModuleId = (id: string): string => id.replaceAll("\\", "/")
 /** The slice of Bun's metafile this seam consumes. Not yet in `@types/bun`; shape per the docs. */
 export interface BunMetafileLike {
   readonly inputs?: Readonly<
-    Record<string, { readonly imports?: ReadonlyArray<{ path?: string; original?: string }> }>
+    Record<
+      string,
+      {
+        readonly imports?: ReadonlyArray<{
+          path?: string
+          original?: string
+          external?: boolean
+          kind?: string
+        }>
+      }
+    >
   >
   readonly outputs?: Readonly<
     Record<
       string,
-      { readonly entryPoint?: string; readonly inputs?: Readonly<Record<string, unknown>> }
+      {
+        readonly entryPoint?: string
+        readonly inputs?: Readonly<Record<string, unknown>>
+        readonly exports?: readonly string[]
+      }
     >
   >
 }
@@ -65,29 +91,37 @@ export interface BunMetafileLike {
 /**
  * Adapt a `Bun.build` metafile to the neutral graph.
  *
- * A total function: an absent or partial metafile yields an empty graph rather than throwing, because
- * a guard that crashes on an unexpected build shape fails the build for the wrong reason. An empty
- * graph reports no findings, which matches the existing behaviour when the metafile is missing.
+ * Fails closed: the graph is the evidence that nothing backend reached the browser, so a build that
+ * produced no metafile, or one without inputs or outputs, is an error rather than an empty graph that
+ * would report nothing.
  */
 export function fromBunMetafile(meta: BunMetafileLike | undefined): ClientModuleGraph {
+  if (meta?.inputs === undefined || meta.outputs === undefined) {
+    throw new Error(
+      "[nifra/web] the client build produced no module graph (metafile), so nifra cannot prove what reached the browser. Refusing to write the bundle",
+    )
+  }
   const modules: Record<string, GraphModule> = {}
-  for (const [rawId, input] of Object.entries(meta?.inputs ?? {})) {
+  for (const [rawId, input] of Object.entries(meta.inputs)) {
     const id = normalizeModuleId(rawId)
     modules[id] = {
       imports: (input.imports ?? []).map((im) => ({
         ...(im.path === undefined ? {} : { path: normalizeModuleId(im.path) }),
         ...(im.original === undefined ? {} : { original: im.original }),
+        ...(im.external === true ? { external: true } : {}),
+        ...(im.kind === "dynamic-import" ? { dynamic: true } : {}),
       })),
     }
   }
   const chunks: Record<string, GraphChunk> = {}
-  for (const [rawPath, output] of Object.entries(meta?.outputs ?? {})) {
+  for (const [rawPath, output] of Object.entries(meta.outputs)) {
     const path = normalizeModuleId(rawPath)
     chunks[path] = {
       ...(output.entryPoint !== undefined
         ? { entryPoint: normalizeModuleId(output.entryPoint) }
         : {}),
       modules: Object.keys(output.inputs ?? {}).map(normalizeModuleId),
+      ...(output.exports !== undefined ? { exports: output.exports } : {}),
     }
   }
   return { modules, chunks }
@@ -105,6 +139,12 @@ export interface RollupChunkLike {
   readonly facadeModuleId?: string | null
   /** Every module id that landed in this chunk. Rollup's `moduleIds`. */
   readonly moduleIds?: readonly string[]
+  /** The names this chunk exports. Rollup's `exports`. */
+  readonly exports?: readonly string[]
+  /** Outputs and externals this chunk imports statically / dynamically. Rollup's `imports` and
+   * `dynamicImports`. */
+  readonly imports?: readonly string[]
+  readonly dynamicImports?: readonly string[]
 }
 export type RollupBundleLike = Readonly<Record<string, RollupChunkLike>>
 
@@ -118,8 +158,8 @@ export type RollupBundleLike = Readonly<Record<string, RollupChunkLike>>
  * guards read the resolved `path` as their fallback (a `node:` prefix, the `server-only` basename), so
  * detection is unaffected; only the human-readable chain shows resolved paths instead of as-written ones.
  *
- * Total, like {@link fromBunMetafile}: an empty bundle yields an empty graph (no findings), never a throw
- * that would fail a build for the wrong reason.
+ * An empty bundle yields an empty graph; the Rollup output always carries its own graph, so there is
+ * no missing-evidence case to fail on here.
  */
 export function fromRollupBundle(
   bundle: RollupBundleLike,
@@ -154,6 +194,10 @@ export function fromRollupBundle(
       // how a non-entry Bun output omits `entryPoint`, so the guards' entry set stays the real entries.
       ...(output.facadeModuleId ? { entryPoint: normalizeModuleId(output.facadeModuleId) } : {}),
       modules: chunkModules,
+      ...(output.exports !== undefined ? { exports: output.exports } : {}),
+      ...(output.imports !== undefined
+        ? { imports: [...output.imports, ...(output.dynamicImports ?? [])] }
+        : {}),
     }
   }
   return { modules, chunks }

package/src/navigation.ts

@@ -12,6 +12,7 @@
  * native `<a href>` full-page navigation - progressive enhancement, no throw.
  */
 
+import type { ClientRouter } from "./router.ts"
 import { serializeSearch } from "./search.ts"
 
 /** Options for a programmatic navigation. */
@@ -102,6 +103,18 @@ export function resolveNavigate(
   return { to: to.to + query, options: resolved }
 }
 
+/**
+ * When a link warms its route's chunk and loader data ahead of a click. Set it with the
+ * `data-nifra-prefetch` attribute on the link or on any ancestor (the nearest wins):
+ * - `intent` (the default) - on hover or keyboard focus.
+ * - `viewport` - once the link scrolls into view.
+ * - `render` - as soon as a page shows the link.
+ * - `none` - never; the route loads when the link is followed.
+ *
+ * A warmed route is used by a click within 30 seconds; after that the click loads it again.
+ */
+export type PrefetchMode = "intent" | "viewport" | "render" | "none"
+
 /**
  * A history-aware navigate. A **string** `to` is a same-origin path (`/users/7?tab=a`) navigated to
  * (push, or replace with `{ replace: true }`); a **number** is a history delta (`-1` back, `1`
@@ -109,14 +122,24 @@ export function resolveNavigate(
  */
 export type BrowserNavigate = (to: string | number, options?: NavigateOptions) => void
 
-// The active browser navigate (set by `installHistory`, cleared on teardown). Module-scoped: one app
-// per page; absent on the server and before hydration.
+// The active browser navigate and the router behind it (set by `installHistory`, cleared on
+// teardown). Module-scoped: one app per page; absent on the server and before hydration.
 let browserNavigate: BrowserNavigate | undefined
-
-/** Register (or clear, with `undefined`) the browser navigate - called by `installHistory`. Not for
- * app use. */
-export function setBrowserNavigate(navigate: BrowserNavigate | undefined): void {
+let browserRouter: ClientRouter | undefined
+
+/** Register (or clear, with `undefined`) the browser navigate and its router - called by
+ * `installHistory`. Not for app use. */
+export function setBrowserNavigate(
+  navigate: BrowserNavigate | undefined,
+  router?: ClientRouter,
+): void {
   browserNavigate = navigate
+  browserRouter = router
+}
+
+/** The mounted client router, or `undefined` on the server / before `installHistory` has run. */
+export function getBrowserRouter(): ClientRouter | undefined {
+  return browserRouter
 }
 
 /** The active browser navigate, or `undefined` on the server / before `installHistory` has run. A

package/src/nonce.ts

@@ -0,0 +1,104 @@
+/** Context supplied while resolving a document's CSP nonce. */
+export interface NonceContext<Env = unknown> {
+  readonly request: Request
+  readonly env: Env
+}
+
+/** Generate a nonce for one request, or return `undefined` to keep the document nonce-free. */
+export type NonceGenerator<Env = unknown> = (
+  context: NonceContext<Env>,
+) => string | undefined | Promise<string | undefined>
+
+/** Context supplied to the optional Content-Security-Policy header callback. */
+export interface NonceHeaderContext {
+  readonly nonce: string
+  readonly request: Request
+  readonly response: Response
+}
+
+/** Return the complete Content-Security-Policy value for a nonce-bearing document. */
+export type NonceHeader = (context: NonceHeaderContext) => string | undefined
+
+/**
+ * A request-aware nonce resolver. It is callable so existing `createWebApp({ nonce })` code can pass
+ * it directly. When created with a `header` callback, `createWebApp` also installs its response hook
+ * automatically and applies that callback's CSP value to the same request that received the nonce.
+ */
+export interface NonceResolver<Env = unknown> extends NonceGenerator<Env> {
+  /** Read the currently resolved nonce for a request, if one has been generated. */
+  readonly get?: (request: Request) => string | undefined
+  /** Internal integration seam used by `createWebApp` when a header callback was supplied. */
+  readonly onResponse?: (response: Response, request: Request) => Response
+}
+
+export interface CreateNonceResolverOptions<Env = unknown> {
+  /** Custom nonce generator. The default is a fresh CSP base64-compatible nonce per request. */
+  readonly generate?: NonceGenerator<Env>
+  /** Build the complete CSP value. App-specific sources remain the caller's responsibility. */
+  readonly header?: NonceHeader
+}
+
+/**
+ * Create a request-memoized CSP nonce resolver for `createWebApp`.
+ *
+ * ```ts
+ * const nonce = createNonceResolver({
+ *   header: ({ nonce }) => `default-src 'self'; script-src 'self' 'nonce-${nonce}'`,
+ * })
+ * const app = createWebApp({ adapter, manifest, clientEntry, nonce })
+ * ```
+ *
+ * A nonce is generated only when the page executor asks for one. Data-mode/API responses never ask,
+ * so the response hook has no value to attach and leaves those responses without a CSP nonce header.
+ */
+export function createNonceResolver<Env = unknown>(
+  options: CreateNonceResolverOptions<Env> = {},
+): NonceResolver<Env> {
+  const values = new WeakMap<Request, string>()
+  const pending = new WeakMap<Request, Promise<string | undefined>>()
+  // CSP nonce-source values use the base64-value grammar. A UUID contains hyphens, so remove them
+  // before emitting it; the remaining 122 random bits are sufficient for a per-response nonce and
+  // stay valid across browsers and all fetch runtimes without a Node-only encoder.
+  const generate = options.generate ?? (() => crypto.randomUUID().replaceAll("-", ""))
+
+  const resolve = (context: NonceContext<Env>): string | Promise<string | undefined> => {
+    const existing = values.get(context.request)
+    if (existing !== undefined) return existing
+    const ongoing = pending.get(context.request)
+    if (ongoing !== undefined) return ongoing
+    const generated = (async (): Promise<string | undefined> => {
+      const value = await generate(context)
+      if (value === undefined) return undefined
+      if (value.trim() === "") {
+        throw new TypeError("[nifra/web] createNonceResolver generated an empty CSP nonce")
+      }
+      values.set(context.request, value)
+      return value
+    })()
+    pending.set(context.request, generated)
+    generated.then(
+      () => pending.delete(context.request),
+      () => pending.delete(context.request),
+    )
+    return generated
+  }
+
+  const get = (request: Request): string | undefined => values.get(request)
+  if (options.header === undefined) return Object.assign(resolve, { get })
+
+  const onResponse = (response: Response, request: Request): Response => {
+    const nonce = values.get(request)
+    values.delete(request)
+    if (nonce === undefined) return response
+    const value = options.header?.({ nonce, request, response })
+    if (value === undefined) return response
+    const headers = new Headers(response.headers)
+    headers.set("content-security-policy", value)
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+  return Object.assign(resolve, { get, onResponse })
+}

package/src/plugins/css-modules.ts

@@ -51,9 +51,11 @@ function scopedKeyframeName(filePath: string, name: string): string {
 
 /** Matches `@keyframes name` / `@-webkit-keyframes name` (etc.); captures the leading keyword and name. */
 const KEYFRAMES_PRELUDE = /(@(?:-\w+-)?keyframes\s+)([A-Za-z_][\w-]*)/i
-/** An `animation` / `animation-name` declaration: capture the `prop:` head + the value (which holds the
- * keyframe-name token(s) to remap). */
-const ANIMATION_DECL = /^(\s*animation(?:-name)?\s*:\s*)([\s\S]*)$/i
+/** An `animation` / `animation-name` declaration, vendor-prefixed or after a comment: capture the
+ * `prop:` head + the value (which holds the keyframe-name token(s) to remap). A comment cannot hold its
+ * own closing delimiter, so each one matches one way - no backtracking across them. */
+const ANIMATION_DECL =
+  /^((?:\s|\/\*(?:[^*]|\*(?!\/))*\*\/)*(?:-[a-z]+-)?animation(?:-name)?\s*:\s*)([\s\S]*)$/i
 const isKeyframesAt = (at: string): boolean => at === "keyframes" || at.endsWith("-keyframes")
 
 /** `s[i]` is a quote: return the index just past the matching close quote (honoring `\` escapes). */

package/src/plugins/kit.ts

@@ -8,6 +8,7 @@ import { existsSync } from "node:fs"
 import { dirname, join, relative } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import type { BunPlugin } from "bun"
+import { type RawSourceMap, ssrSourceMaps } from "../internal/source-map.ts"
 
 /** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
@@ -123,6 +124,29 @@ export function devServerCompile(): boolean {
   return process.env[DEV_HMR_ENV] === "1"
 }
 
+export { concatSourceMaps, type RawSourceMap } from "../internal/source-map.ts"
+
+/**
+ * A compiled module carrying its map back to the file it came from, during a dev server only. The client
+ * half gets it inline: Bun's bundler keeps a plugin's output as the bundle map's source, and the dev
+ * server's frame mapper follows the inline map from there. The SSR half goes in the process registry
+ * instead, because Bun's runtime ignores a plugin's inline map when it reports a stack.
+ */
+export function withDevSourceMap(
+  code: string,
+  map: RawSourceMap | undefined,
+  path: string,
+  generate: "dom" | "ssr",
+): string {
+  if (map === undefined || !devServerCompile()) return code
+  if (generate === "ssr") {
+    ssrSourceMaps().set(portablePath(path), map)
+    return code
+  }
+  const encoded = Buffer.from(JSON.stringify(map)).toString("base64")
+  return `${code}\n//# sourceMappingURL=data:application/json;base64,${encoded}\n`
+}
+
 /**
  * The app root and the routes directory of the running dev server, for plugins that need to tell one of
  * the app's own components from a dependency or a route module. Set alongside {@link DEV_HMR_ENV}; read

package/src/plugins/svg.ts

@@ -11,9 +11,10 @@
  * is untouched - only the `?component` marker is intercepted.
  *
  * Optimization is optional: pass `svgo` (or install the `svgo` peer) to minify/clean the SVG first.
- * The transform is regex-based and targets the common icon-set shape (well-formed, self-closed tags);
- * it camelCases hyphenated + `xlink:`/`xmlns:` attributes, maps `class` → `className`, parses an inline
- * `style="..."` into an object, and drops XML declarations/comments so the result is valid JSX.
+ * The file must be one well-formed `<svg>` element; anything else is refused rather than guessed at.
+ * Its text reaches JSX as text - a brace in a `<style>` rule or a `<title>` is a character, never an
+ * expression. The transform camelCases hyphenated + `xlink:`/`xmlns:` attributes, maps `class` →
+ * `className`, parses an inline `style="..."` into an object, and drops XML declarations/comments.
  */
 import type { BunPlugin } from "bun"
 import { normalizeFilePath, requirePeer } from "./kit.ts"
@@ -113,10 +114,140 @@ export function stripSvgPreamble(xml: string): string {
   return parts.join("").trim()
 }
 
+/** How a framework's template must spell an SVG file's text and names, for {@link svgTemplateMarkup}. */
+export interface SvgMarkupRules {
+  /** Text content as the template must spell it; `cdata` text arrives as a CDATA section held it. */
+  readonly text: (text: string, cdata: boolean) => string
+  /** An attribute value (without its quotes) as the template must spell it. Default as written. */
+  readonly attributeValue?: (value: string) => string
+  /** Why the template would read an element or attribute name as more than markup, or `undefined`. */
+  readonly refuse?: (name: string, kind: "element" | "attribute") => string | undefined
+  /** Elements whose content the template reads as raw text, copied as it is. */
+  readonly rawText?: ReadonlySet<string>
+}
+
+const svgMarkupError = (detail: string): Error =>
+  new Error(`[nifra/web] an SVG component must be plain SVG markup: ${detail}`)
+
+const TAG_NAME = /[A-Za-z_:][\w:.-]*/y
+const SPACE = /\s*/y
+
+/**
+ * An SVG file's markup rewritten for a framework template: one `<svg>` root, its text and attribute
+ * values put through `rules` so none of it reads as template syntax. Markup a well-formed SVG cannot
+ * hold is refused rather than passed on - a brace, a bare name or an unquoted value in a tag, content
+ * after the root - since each is a way for the file to reach the template as code.
+ */
+export function svgTemplateMarkup(xml: string, rules: SvgMarkupRules): string {
+  const svg = stripSvgPreamble(xml)
+  if (!/^<svg[\s/>]/.test(svg)) throw svgMarkupError("it does not start with an <svg> element")
+  let out = ""
+  let depth = 0
+  let i = 0
+  while (i < svg.length) {
+    if (svg.startsWith("<![CDATA[", i)) {
+      const close = svg.indexOf("]]>", i + 9)
+      if (close === -1) throw svgMarkupError("a CDATA section is not closed")
+      out += rules.text(svg.slice(i + 9, close), true)
+      i = close + 3
+      continue
+    }
+    if (svg[i] !== "<") {
+      const next = svg.indexOf("<", i)
+      const end = next === -1 ? svg.length : next
+      out += rules.text(svg.slice(i, end), false)
+      i = end
+      continue
+    }
+    const tag = readSvgTag(svg, i, rules)
+    out += tag.markup
+    i = tag.end
+    if (tag.closing) depth--
+    else if (!tag.selfClosing) {
+      depth++
+      if (rules.rawText?.has(tag.name) === true) {
+        // Wherever the template's own reading ends this element, in any case, raw text ends here too.
+        const close = svg.toLowerCase().indexOf(`</${tag.name.toLowerCase()}`, i)
+        const end = close === -1 ? svg.length : close
+        out += svg.slice(i, end)
+        i = end
+      }
+    }
+    if (depth === 0) {
+      if (svg.slice(i).trim() !== "") throw svgMarkupError("there is content after the root </svg>")
+      return out
+    }
+  }
+  throw svgMarkupError("the root <svg> element is not closed")
+}
+
+/** One tag of {@link svgTemplateMarkup}'s input, rebuilt with each attribute value through `rules`. */
+function readSvgTag(
+  svg: string,
+  start: number,
+  rules: SvgMarkupRules,
+): { markup: string; end: number; name: string; closing: boolean; selfClosing: boolean } {
+  const closing = svg[start + 1] === "/"
+  let i = start + (closing ? 2 : 1)
+  TAG_NAME.lastIndex = i
+  const name = TAG_NAME.exec(svg)?.[0]
+  if (name === undefined) throw svgMarkupError(`a "<" at offset ${start} opens no tag`)
+  const refused = rules.refuse?.(name, "element")
+  if (refused !== undefined) throw svgMarkupError(refused)
+  i += name.length
+  let markup = `<${closing ? "/" : ""}${name}`
+  for (;;) {
+    SPACE.lastIndex = i
+    const space = SPACE.exec(svg)?.[0] ?? ""
+    i += space.length
+    if (svg[i] === ">")
+      return { markup: `${markup}>`, end: i + 1, name, closing, selfClosing: false }
+    if (!closing && svg.startsWith("/>", i)) {
+      return { markup: `${markup}/>`, end: i + 2, name, closing, selfClosing: true }
+    }
+    if (i >= svg.length) throw svgMarkupError(`the tag <${name}> is not closed`)
+    TAG_NAME.lastIndex = i
+    const attribute = closing || space === "" ? undefined : TAG_NAME.exec(svg)?.[0]
+    if (attribute === undefined) {
+      throw svgMarkupError(`<${name}> holds ${JSON.stringify(svg[i])} where an attribute belongs`)
+    }
+    const refusedAttribute = rules.refuse?.(attribute, "attribute")
+    if (refusedAttribute !== undefined) throw svgMarkupError(refusedAttribute)
+    i += attribute.length
+    SPACE.lastIndex = i
+    i += SPACE.exec(svg)?.[0].length ?? 0
+    if (svg[i] !== "=") throw svgMarkupError(`the attribute ${attribute} on <${name}> has no value`)
+    SPACE.lastIndex = i + 1
+    i += 1 + (SPACE.exec(svg)?.[0].length ?? 0)
+    const quote = svg[i]
+    const close = quote === '"' || quote === "'" ? svg.indexOf(quote, i + 1) : -1
+    if (close === -1) {
+      throw svgMarkupError(`the value of ${attribute} on <${name}> is not a quoted string`)
+    }
+    const value = svg.slice(i + 1, close)
+    markup += ` ${attribute}=${quote}${rules.attributeValue?.(value) ?? value}${quote}`
+    i = close + 1
+  }
+}
+
+/** Text as JSX text: a brace, `>` or `=` as a character reference, so none of it is an expression. */
+const jsxText = (text: string, cdata: boolean): string =>
+  (cdata ? text.replaceAll("&", "&amp;").replaceAll("<", "&lt;") : text).replace(
+    /[{}>=]/g,
+    (char) => `&#${char.charCodeAt(0)};`,
+  )
+
+/** JSX reads `<a.b>` and `<Name>` as a value in scope, called as a component - never an SVG element. */
+const jsxRefuse = (name: string, kind: "element" | "attribute"): string | undefined =>
+  kind === "element" && (name.includes(".") || /^[A-Z]/.test(name))
+    ? `JSX reads the element <${name}> as a value in scope, not an SVG element`
+    : undefined
+
 /** Convert an SVG XML string into a JSX-safe `<svg>…</svg>` element with `{...props}` spread on the root. */
 export function svgToJsx(xml: string, options: SvgToJsxOptions = {}): string {
   const classProp = options.classProp ?? "className"
-  let out = stripSvgPreamble(xml)
+  // Text is escaped first, `=` included, so the attribute rewrites below match inside tags only.
+  let out = svgTemplateMarkup(xml, { text: jsxText, refuse: jsxRefuse })
 
   // Namespaced attributes → camelCase (xlink:href → xlinkHref, xmlns:xlink → xmlnsXlink).
   out = out.replace(/\b([a-z]+):([a-z]+)=/gi, (_m, ns: string, name: string) => {