@nifrajs/web 1.13.0 → 2.0.0

package/src/client.ts

@@ -44,16 +44,10 @@ export function installHistory(
       return raw
     }
   }
-  // Resolve a fragment id to its element — by `id`, then a legacy `<a name>` — or null if absent.
+  // Resolve a fragment id to its element by `id`, or null if absent.
   const findAnchor = (id: string): Element | null => {
     if (id === "") return null
-    const byId = document.getElementById(id)
-    if (byId !== null) return byId
-    try {
-      return document.querySelector(`a[name="${CSS.escape(id)}"]`)
-    } catch {
-      return null // CSS/CSS.escape unavailable or an exotic id → no named-anchor match
-    }
+    return document.getElementById(id)
   }
 
   // Wrap a navigation's render in a View Transition when the browser supports it — a graceful

package/src/deferred.ts

@@ -28,6 +28,9 @@ export interface Deferred<T> {
  * component knows to `<Await>` it. The `id` is a placeholder until the server assigns the real one.
  */
 export function defer<T>(promise: Promise<T>): Deferred<T> {
+  // Claim the promise immediately: an eager rejection may otherwise be reported as unhandled before
+  // the SSR/NDJSON consumer attaches. Keep the original promise so consumers observe its rejection.
+  void promise.catch(() => {})
   return { __nifra_deferred: true, id: -1, promise }
 }
 

package/src/draft.ts

@@ -14,7 +14,7 @@
  *   createWebApp({ ..., draftSecret: env.DRAFT_SECRET })   // → loaders get ctx.draft
  *   withISR(app, { ..., draftSecret: env.DRAFT_SECRET })   // → editors bypass the cache
  */
-import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core"
+import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core/server"
 
 /** The cookie name nifra uses for draft/preview mode. */
 export const DRAFT_COOKIE = "__nifra_draft"

package/src/forms.ts

@@ -18,7 +18,7 @@
  * runtime is a trivial pass-through — all the work is in the types. It checks the field KEY, never the
  * MEANING (a `field("email")` collecting a phone is still valid here); that stays an app/AI concern.
  */
-import type { RouteInfo, Server } from "@nifrajs/core"
+import type { RouteInfo, Server } from "@nifrajs/core/server"
 
 // Derived from `FormData` itself (not the `FormDataEntryValue` global) so this file stays DOM-lib-free:
 // `@nifrajs/web`'s server surface is typechecked by the root config, which has no DOM lib.

package/src/index.ts

@@ -7,12 +7,13 @@
  * the adapter interprets them. That keeps this package both framework-agnostic and free
  * of DOM types: it is pure server orchestration + string building.
  */
-import { server } from "@nifrajs/core"
+
 import {
   type BackendMount,
   type BackendMountHandler,
   NIFRA_BACKEND_MOUNT,
 } from "@nifrajs/core/mount"
+import { server } from "@nifrajs/core/server"
 import {
   DEFERRED_ERROR_CODE,
   DEFERRED_RUNTIME,
@@ -86,7 +87,6 @@ export {
 export {
   type Action,
   buildManifest,
-  enumeratePrerenderedPaths,
   enumerateStaticRoutes,
   filePathToPattern,
   filePathToPatterns,
@@ -201,6 +201,9 @@ export interface RenderProps {
   readonly actionData?: unknown
   /** True while a client navigation or submit is in flight (client-only; absent/false on SSR). */
   readonly pending?: boolean
+  /** The path a client navigation is transitioning TO while `pending` (client-only; absent on SSR and
+   * when idle). Lets an adapter tell a `NavLink` whether its own target is the one loading. */
+  readonly pendingPath?: string
   /** The in-flight client submit, for optimistic UI (client-only; absent on SSR + when idle). */
   readonly submission?: Submission
   /** The matched route's decoded path params (`/users/:id` → `{ id: "7" }`). Threaded identically on
@@ -687,21 +690,17 @@ function isSameOriginPath(location: string): boolean {
 /**
  * Build a redirect `Response` — return it from a route `action` for the Post/Redirect/Get
  * pattern (POST mutates, 303 sends the browser to a fresh GET, so a reload doesn't re-submit).
- * Defaults to 303 (See Other); pass `307`/`308` (or `{ status }`) to preserve the method.
+ * Defaults to 303 (See Other); pass `{ status: 307 }` or `{ status: 308 }` to preserve the method.
  *
  * **Secure by default:** `location` must be a same-origin path (begins with `/`, not `//`). An
  * off-origin/absolute destination throws unless you pass `{ external: true }` — this closes the
  * open-redirect footgun of `return redirect(formData.get("next"))` on the no-JS (native-form) path,
  * which returns the action's `Response` verbatim.
  *
- * @param statusOrOptions a status number (back-compat) or `{ status?, external? }`.
+ * @param options redirect status and whether an off-origin destination is intentional.
  */
-export function redirect(
-  location: string,
-  statusOrOptions: number | RedirectOptions = 303,
-): Response {
-  const opts = typeof statusOrOptions === "number" ? { status: statusOrOptions } : statusOrOptions
-  if (opts.external !== true && !isSameOriginPath(location)) {
+export function redirect(location: string, options: RedirectOptions = {}): Response {
+  if (options.external !== true && !isSameOriginPath(location)) {
     throw new Error(
       `[nifra/web] redirect(${JSON.stringify(location)}) is not a same-origin path. Use a path beginning with "/" (not "//"), or redirect(location, { external: true }) for a deliberate off-origin redirect. This guards against open redirects from unvalidated input.`,
     )
@@ -715,7 +714,7 @@ export function redirect(
       `[nifra/web] redirect location contains a CR/LF character — refusing to emit a header-injecting redirect.`,
     )
   }
-  return new Response(null, { status: opts.status ?? 303, headers: { location } })
+  return new Response(null, { status: options.status ?? 303, headers: { location } })
 }
 
 /** The wrapper `revalidate()` returns: the action's `data` plus the paths it changed. A plain tagged
@@ -967,15 +966,14 @@ export interface CreateWebAppOptions {
    * mount interface from `@nifrajs/core/mount`; `createWebApp` also serves that backend over HTTP at
    * {@link apiPrefix} (default `/api`): a request whose pathname starts with the prefix is dispatched
    * before page routing with the same `env`/`waitUntil` platform context, and the backend's `Response`
-   * is returned untouched. Legacy custom `.fetch(url, init)` bridges remain mountable but cannot
-   * receive platform context. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
+   * is returned untouched. The mount runs in `nifra dev` too. Pass `apiPrefix: ""` to disable it. */
   readonly api?: unknown
   /** HTTP path prefix the {@link api} backend is auto-mounted at (default `"/api"`). A request whose
    * pathname is exactly the prefix or starts with `prefix + "/"` is dispatched to the backend before
    * page routing; the backend therefore defines its routes at the **full** path (`server().post("/api/
    * sync", …)`), matching the in-process `inProcessClient` call sites. Set to `""` to disable the
    * auto-mount entirely (the app serves pages only and `api` stays a loader-only `ctx.api`). Mounting
-   * is also a no-op when `api` has neither the symbol mount nor a legacy callable `.fetch`. */
+   * is also a no-op when `api` does not expose the symbol mount. */
   readonly apiPrefix?: string
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
    * signed `__nifra_draft` cookie gets `ctx.draft === true` in loaders/actions (else always `false`).
@@ -994,7 +992,7 @@ export interface CreateWebAppOptions {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
-  /** SSG: the prerendered-path set (e.g. from `enumeratePrerenderedPaths` or the build's
+  /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
    * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
    * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
   readonly prerenderedPaths?: readonly string[]
@@ -1027,24 +1025,15 @@ interface RouteContext {
   readonly env: unknown
 }
 
-/** Legacy pre-symbol mount bridge. Kept for custom integrations; it cannot receive platform context. */
-interface LegacyMountableApi {
-  readonly fetch: (url: string, init?: RequestInit) => Response | Promise<Response>
-}
-
 /**
- * Resolve the explicit backend mount interface, then fall back to the released `.fetch(url, init)`
- * convention. The symbol seam forwards platform context without making web depend on client.
+ * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
+ * context without making web depend on client.
  */
 function backendMountOf(api: unknown): BackendMountHandler | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
   const explicit = (api as Partial<BackendMount>)[NIFRA_BACKEND_MOUNT]
-  if (typeof explicit === "function") {
-    return (request, platform) => explicit.call(api, request, platform)
-  }
-  const legacy = (api as Partial<LegacyMountableApi>).fetch
-  if (typeof legacy !== "function") return undefined
-  return (request) => legacy.call(api, request.url, request)
+  if (typeof explicit !== "function") return undefined
+  return (request, platform) => explicit.call(api, request, platform)
 }
 
 /**
@@ -1095,13 +1084,8 @@ export function createWebApp<Env = unknown>(
   // surfaces as the backend's own response, never the page 404. We dispatch the SAME `Request` object
   // (its body unread) so streamed/large bodies pass through untouched; the backend defines its routes
   // at the full prefixed path (`server().post("/api/sync", …)`), matching the `inProcessClient` call
-  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no `.fetch`) is left pages-only. The hook
+  // sites. `apiPrefix: ""` opts out; a non-mountable `api` (no symbol mount) is left pages-only. The hook
   // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
-  //
-  // Backward-compat: an app that still hand-dispatches `/api/*` in its server entry (the old
-  // `if (pathname.startsWith("/api/")) return backend.fetch(req)`) intercepts BEFORE `app.fetch` is
-  // ever called, so that branch returns first and this hook never sees the request — no double
-  // handling. Apps that drop the hand-dispatch now rely on this mount instead (dev + prod alike).
   const apiPrefix = options.apiPrefix ?? "/api"
   const mountedApi = backendMountOf(api)
   if (apiPrefix !== "" && mountedApi !== undefined) {

package/src/manifest.ts

@@ -108,7 +108,7 @@ export interface MetaArgs<Data = unknown> {
    * `og:url`/`canonical`/`og:image` built from it never drifts between the server-rendered `<head>` and
    * a soft-nav. Use it for absolute URLs (`origin + "/posts/" + slug`) instead of threading `siteUrl`
    * through loader data. Empty string (`""`) when the origin is unknown (e.g. a hand-built test render
-   * with no request URL) — back-compat-safe: a `meta()` that ignores `origin` is unchanged.
+   * with no request URL). A `meta()` that ignores `origin` is unchanged.
    */
   readonly origin: string
 }
@@ -381,7 +381,7 @@ const encodeRouteParam = (value: string): string => {
  * Substitute a route pattern's `:param` segments with concrete values: `/users/:id` + `{id:"7"}` →
  * `/users/7`. Returns the filled path plus any params that had no value (a `getStaticPaths` bug) so
  * the caller can skip rather than emit a path with a literal `:name`. Shared by the SSG driver and
- * {@link enumeratePrerenderedPaths}.
+ * {@link enumerateStaticRoutes}.
  */
 export function fillRoutePattern(
   pattern: string,
@@ -438,9 +438,3 @@ export async function enumerateStaticRoutes(routes: readonly RouteEntry[]): Prom
   }
   return { paths, fallbacks }
 }
-
-/** The prerendered-path subset of {@link enumerateStaticRoutes} — kept for callers that only need the
- * paths (e.g. injecting `window.__NIFRA_PRERENDERED__`). */
-export async function enumeratePrerenderedPaths(routes: readonly RouteEntry[]): Promise<string[]> {
-  return (await enumerateStaticRoutes(routes)).paths
-}

package/src/plugins/postcss.ts

@@ -0,0 +1,129 @@
+/**
+ * `@nifrajs/web/plugins/postcss` - a PostCSS (`*.css`, `*.pcss`, `*.postcss`) Bun plugin, in its OWN
+ * module so the SSR preload registers it BEFORE any CSS file loads. Mirrors `@nifrajs/web/plugins/scss`:
+ * pass `"dom"` for the client bundle (`buildClient({ plugins: [...] })`) and preload `"ssr"` for the
+ * server (`bun --preload`).
+ *
+ * PostCSS (`postcss`) is an **optional peer**, not a hard dependency: it's loaded on the first CSS file
+ * and fails loud with an install hint if absent. The plugin list comes from an explicit `plugins`
+ * option, or - when omitted - from the project's `postcss.config.js`, loaded via the optional
+ * `postcss-load-config` peer. This is the Tailwind v4 path: a config with `@tailwindcss/postcss` runs
+ * inside PostCSS, so `app.css` importing `tailwindcss` is compiled during `Bun.build` with no
+ * framework-specific code (v4 bundles its own Lightning CSS, so no separate autoprefixer step).
+ *
+ * Composes with CSS Modules: a `*.module.css` / `*.module.pcss` file is processed and then run through
+ * the same scoped-class transform as `@nifrajs/web/plugins/css-modules`, so `import styles` yields the
+ * `{ original: scoped }` map (SSR/dom class-map parity). A plain CSS file is a side-effect import - its
+ * CSS is bundled (dom) and it resolves to an empty module (ssr).
+ */
+import type { BunPlugin } from "bun"
+import { transformCssModule } from "./css-modules.ts"
+import { createStylesheetEmitter, reproduciblePath, requirePeer } from "./kit.ts"
+
+const STYLE_NS = "nifra-postcss"
+
+/** The subset of the `postcss` API this plugin uses (structural, so no hard dependency on its types). */
+export type PostcssProcessor = (plugins?: readonly unknown[]) => {
+  process(
+    css: string,
+    options: { readonly from?: string; readonly to?: string },
+  ): PromiseLike<{ readonly css: string }>
+}
+
+/** The subset of `postcss-load-config` this plugin uses when no explicit `plugins` are given. */
+export type PostcssConfigLoader = (
+  ctx?: Record<string, unknown>,
+  path?: string,
+) => Promise<{ readonly plugins?: readonly unknown[]; readonly options?: Record<string, unknown> }>
+
+export interface PostcssPluginOptions {
+  /** Inject the `postcss` function (default: the optional peer, loaded lazily). Pass a stub in tests. */
+  readonly postcss?: PostcssProcessor
+  /** PostCSS plugins to run. When omitted, the project's `postcss.config.js` is loaded instead. */
+  readonly plugins?: readonly unknown[]
+  /** Directory (or file) to load `postcss.config.js` from, when `plugins` is omitted. Default: cwd. */
+  readonly config?: string
+  /** Inject the config loader (default: the `postcss-load-config` optional peer). */
+  readonly loadConfig?: PostcssConfigLoader
+}
+
+const CSS_FILTER = /\.(css|pcss|postcss)(\?|$)/
+const isModuleRequest = (cleanPath: string): boolean =>
+  /\.module\.(css|pcss|postcss)$/.test(cleanPath)
+
+/**
+ * The PostCSS Bun plugin. `"dom"` → bundles the processed CSS (and, for `*.module.*`, exports the
+ * scoped class map); `"ssr"` → the class map only for `*.module.*`, an empty module for plain CSS.
+ * Tolerates a trailing `?query` (dev servers append one to bust Bun's import cache).
+ */
+export function postcssBunPlugin(
+  generate: "dom" | "ssr",
+  options: PostcssPluginOptions = {},
+): BunPlugin {
+  return {
+    name: `nifra-postcss-${generate}`,
+    setup(build) {
+      const stylesheet = createStylesheetEmitter(build, STYLE_NS)
+      let processor = options.postcss
+      let pluginList: readonly unknown[] | undefined = options.plugins
+
+      const getProcessor = async (): Promise<PostcssProcessor> => {
+        processor ??= (
+          await requirePeer<{ default: PostcssProcessor }>("postcss", {
+            feature: "PostCSS/Tailwind support",
+            install: "bun add -d postcss",
+          })
+        ).default
+        return processor
+      }
+
+      const getPlugins = async (): Promise<readonly unknown[]> => {
+        if (pluginList !== undefined) return pluginList
+        const load =
+          options.loadConfig ??
+          (
+            await requirePeer<{ default: PostcssConfigLoader }>("postcss-load-config", {
+              feature: "loading postcss.config.js (or pass `plugins` explicitly)",
+              install: "bun add -d postcss-load-config",
+            })
+          ).default
+        const loaded = await load({}, options.config)
+        pluginList = loaded.plugins ?? []
+        return pluginList
+      }
+
+      build.onLoad({ filter: CSS_FILTER }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        const source = await Bun.file(path).text()
+        const postcss = await getProcessor()
+        const plugins = await getPlugins()
+        let css: string
+        try {
+          css = (await postcss(plugins).process(source, { from: path })).css
+        } catch (err) {
+          throw new Error(
+            `[nifra/web] failed to process ${path}: ${(err as Error)?.message ?? err}`,
+            { cause: err },
+          )
+        }
+
+        if (isModuleRequest(path)) {
+          // *.module.css → process, then scope class names through the shared CSS-modules transform.
+          // Scope off the cwd-relative path so names are reproducible across machines/CI.
+          const { exports, css: scopedCss } = transformCssModule(css, reproduciblePath(path))
+          const js = `export default ${JSON.stringify(exports)}\n`
+          return {
+            contents: generate === "dom" ? js + stylesheet.emit(path, scopedCss) : js,
+            loader: "js",
+          }
+        }
+
+        // Plain CSS → side-effect import: bundle the CSS on dom, an empty module on ssr.
+        return {
+          contents: generate === "dom" ? stylesheet.emit(path, css) : "",
+          loader: "js",
+        }
+      })
+    },
+  }
+}

package/src/plugins/svg.ts

@@ -0,0 +1,156 @@
+/**
+ * `@nifrajs/web/plugins/svg` - import an SVG as a component: `import Icon from "./icon.svg?component"`,
+ * then `<Icon className="w-6 h-6 text-blue-500" />`. Props spread onto the root `<svg>`, matching the
+ * standard Vite `svgr` workflow. In its OWN module so the SSR preload registers it before any SVG
+ * loads; pass `"dom"` for the client bundle and preload `"ssr"` for the server (both emit the same
+ * isomorphic component).
+ *
+ * SCOPE: emits an **automatic-JSX-runtime** component, so it works out of the box for the frameworks
+ * whose build supplies a `jsxImportSource` - **React and Preact**. Solid (needs `babel-preset-solid`),
+ * Svelte, and Vue are not JSX and are intentionally out of v1; a plain `import "./icon.svg"` (asset URL)
+ * 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.
+ */
+import type { BunPlugin } from "bun"
+import { requirePeer } from "./kit.ts"
+
+/** The subset of the `svgo` API this plugin uses (structural, so no hard dependency on its types). */
+export interface SvgOptimizer {
+  optimize(input: string, options?: Record<string, unknown>): { readonly data: string }
+}
+
+export interface SvgPluginOptions {
+  /** Optimize each SVG first. `true` loads the `svgo` peer; pass an optimizer to inject one (or a stub). */
+  readonly svgo?: boolean | SvgOptimizer
+}
+
+/** SVG/HTML attribute names that JSX expects camelCased (the common subset on icons). */
+const CAMEL_ATTRS = new Map(
+  [
+    "clip-path",
+    "clip-rule",
+    "fill-opacity",
+    "fill-rule",
+    "stroke-width",
+    "stroke-linecap",
+    "stroke-linejoin",
+    "stroke-opacity",
+    "stroke-dasharray",
+    "stroke-dashoffset",
+    "stroke-miterlimit",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "text-anchor",
+    "stop-color",
+    "stop-opacity",
+    "color-interpolation-filters",
+    "flood-color",
+    "flood-opacity",
+    "vector-effect",
+  ].map((name) => [name, name.replace(/-([a-z])/g, (_m, c) => (c as string).toUpperCase())]),
+)
+
+function styleToObject(style: string): string {
+  const entries = style
+    .split(";")
+    .map((decl) => decl.trim())
+    .filter(Boolean)
+    .map((decl) => {
+      const idx = decl.indexOf(":")
+      const prop = decl
+        .slice(0, idx)
+        .trim()
+        .replace(/-([a-z])/g, (_m, c) => (c as string).toUpperCase())
+      const value = decl.slice(idx + 1).trim()
+      return `${JSON.stringify(prop)}:${JSON.stringify(value)}`
+    })
+  return `{{${entries.join(",")}}}`
+}
+
+export interface SvgToJsxOptions {
+  /** The JSX prop name for `class`. `"className"` for React/Preact; `"class"` for Solid. */
+  readonly classProp?: string
+}
+
+/** 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 = xml
+    .replace(/<\?xml[\s\S]*?\?>/g, "") // XML declaration
+    .replace(/<!--[\s\S]*?-->/g, "") // comments
+    .replace(/<!DOCTYPE[^>]*>/gi, "")
+    .trim()
+
+  // Namespaced attributes → camelCase (xlink:href → xlinkHref, xmlns:xlink → xmlnsXlink).
+  out = out.replace(/\b([a-z]+):([a-z]+)=/gi, (_m, ns: string, name: string) => {
+    return `${ns.toLowerCase()}${name.charAt(0).toUpperCase()}${name.slice(1)}=`
+  })
+  // Known hyphenated attributes → camelCase.
+  for (const [kebab, camel] of CAMEL_ATTRS) {
+    out = out.replace(new RegExp(`\\b${kebab}=`, "g"), `${camel}=`)
+  }
+  // class → the framework's prop (className for React/Preact, class for Solid).
+  if (classProp !== "class") out = out.replace(/\bclass=/g, `${classProp}=`)
+  // Inline style string → JSX object.
+  out = out.replace(/\bstyle="([^"]*)"/g, (_m, css: string) => `style=${styleToObject(css)}`)
+  // Spread props onto the root <svg> tag (after the tag name, before its attributes).
+  out = out.replace(/^<svg\b/, "<svg {...props}")
+  return out
+}
+
+/** Emit the component module source for a `?component` SVG import. Identical on dom + ssr (isomorphic). */
+export function svgComponentSource(xml: string, options: SvgToJsxOptions = {}): string {
+  return `export default function SvgComponent(props){return (${svgToJsx(xml, options)})}\n`
+}
+
+/** The Bun `onLoad` filter every adapter's SVG-component plugin matches: `*.svg?component`. */
+export const SVG_COMPONENT_FILTER = /\.svg\?component(&|$)/
+const SVG_FILTER = SVG_COMPONENT_FILTER
+
+/**
+ * The SVG-as-component Bun plugin (React/Preact). `generate` is accepted for parity with the other
+ * plugin pairs; the emitted component is the same on `"dom"` and `"ssr"`.
+ */
+export function svgComponentBunPlugin(
+  _generate: "dom" | "ssr",
+  options: SvgPluginOptions = {},
+): BunPlugin {
+  return {
+    name: "nifra-svg-component",
+    setup(build) {
+      let optimizer: SvgOptimizer | undefined =
+        typeof options.svgo === "object" ? options.svgo : undefined
+      const wantOptimize = options.svgo !== undefined && options.svgo !== false
+      const getOptimizer = async (): Promise<SvgOptimizer | undefined> => {
+        if (!wantOptimize) return undefined
+        optimizer ??= await requirePeer<SvgOptimizer>("svgo", {
+          feature: "SVG optimization (svgo)",
+          install: "bun add -d svgo",
+        })
+        return optimizer
+      }
+
+      build.onLoad({ filter: SVG_FILTER }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        let xml = await Bun.file(path).text()
+        const svgo = await getOptimizer()
+        if (svgo !== undefined) {
+          try {
+            xml = svgo.optimize(xml, { path }).data
+          } catch (err) {
+            throw new Error(
+              `[nifra/web] failed to optimize ${path}: ${(err as Error)?.message ?? err}`,
+              { cause: err },
+            )
+          }
+        }
+        return { contents: svgComponentSource(xml), loader: "jsx" }
+      })
+    },
+  }
+}

package/src/router.ts

@@ -64,6 +64,9 @@ export interface RouterState {
   readonly actionData?: unknown
   /** True while a navigation or submit is in flight (drives loading UI). */
   readonly pending: boolean
+  /** The path a navigation is transitioning TO while `pending` (cleared when it settles). Lets a
+   * `NavLink` know whether its own `to` is the one loading; `undefined` when idle. */
+  readonly pendingPath?: string | undefined
   /** The in-flight submit (set during a `submit`, cleared when it settles) — for optimistic UI. */
   readonly submission?: Submission
 }
@@ -480,7 +483,7 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
       navAbort?.abort() // abandon any in-flight navigation's stream
       const ac = new AbortController()
       navAbort = ac
-      state = { ...state, pending: true }
+      state = { ...state, pending: true, pendingPath: path }
       emit()
       try {
         // Use prefetched data when present (one-shot — drop it); else fetch. The chunk is loaded
@@ -503,10 +506,10 @@ export function createClientRouter(options: ClientRouterOptions): ClientRouter {
         }
         emit()
       } catch (err) {
-        // Clear our pending flag (only if still current) and rethrow — the caller decides how to
-        // recover (the history layer falls back to a full-page navigation).
+        // Clear our pending flag + target (only if still current) and rethrow — the caller decides how
+        // to recover (the history layer falls back to a full-page navigation).
         if (mine === token) {
-          state = { ...state, pending: false }
+          state = { ...state, pending: false, pendingPath: undefined }
           emit()
         }
         throw err