@nifrajs/web 3.1.0 → 3.3.0

package/src/islands.ts

@@ -34,6 +34,28 @@ export type IslandCleanup = () => void
 // 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
 
+/**
+ * Author a typed enhancer. Pure identity at runtime (zero cost, tree-shaken away) - its only job is
+ * to pin the `data-props` shape so `el` and `props` are typed inside the body and the enhancer is
+ * assignable to `mountIslands`. Prefer this over an inline arrow whenever an island reads props:
+ *
+ *   const counter = defineIsland<{ start: number }>((el, props) => {
+ *     let n = props.start                       // props typed, no cast
+ *     const out = el.querySelector("output")!
+ *     const onClick = () => { out.textContent = String(++n) }
+ *     el.querySelector("button")?.addEventListener("click", onClick)
+ *     return () => el.querySelector("button")?.removeEventListener("click", onClick)
+ *   })
+ *   mountIslands({ counter })
+ *
+ * The props type is a contract, not a validator - `data-props` is JSON authored by your own SSR, so
+ * it is trusted framing, not user input. Keep the enhancer body imperative: read the DOM, wire
+ * listeners, return cleanup. No hidden reactivity to get wrong.
+ */
+export function defineIsland<P = unknown>(enhancer: IslandEnhancer<P>): IslandEnhancer<P> {
+  return enhancer
+}
+
 /** Parse an island's inline `data-props` JSON; malformed/absent → `undefined` (never throws). */
 function readProps(el: HTMLElement): unknown {
   const raw = el.dataset.props
@@ -100,3 +122,66 @@ export function mountIslands(
     }
   }
 }
+
+/** Unsubscribe one bus handler; calling twice is a no-op. Also returned so an enhancer can hand it
+ * straight back as its `IslandCleanup`. */
+export type IslandBusUnsubscribe = () => void
+
+/**
+ * A typed publish/subscribe channel for coordinating islands that must talk to each other without a
+ * shared reactive store - a cart badge reacting to an "add to cart" island, a filter island driving
+ * a results island. Create ONE bus in your mount entry and close over it in each enhancer; there is
+ * no implicit global, so concurrent renders and tests never cross-talk.
+ *
+ *   type Events = { "cart:add": { sku: string }; "cart:count": number }
+ *   const bus = createIslandBus<Events>()
+ *   mountIslands({
+ *     addBtn: defineIsland((el) => {
+ *       const onClick = () => bus.emit("cart:add", { sku: el.dataset.sku! })
+ *       el.addEventListener("click", onClick)
+ *       return () => el.removeEventListener("click", onClick)
+ *     }),
+ *     badge: defineIsland((el) => bus.on("cart:count", (n) => { el.textContent = String(n) })),
+ *   })
+ *
+ * `on` returns its own unsubscribe, so an enhancer whose only job is to listen can `return bus.on(...)`
+ * directly as its cleanup. A handler that throws is isolated - it never blocks the other subscribers
+ * or the `emit` caller. Synchronous, in-memory, no DOM dependency (safe to construct under SSR); it
+ * carries no history, so a subscriber only sees events emitted after it subscribed.
+ */
+export function createIslandBus<
+  Events extends Record<string, unknown> = Record<string, unknown>,
+>(): {
+  emit<K extends keyof Events>(type: K, detail: Events[K]): void
+  on<K extends keyof Events>(type: K, handler: (detail: Events[K]) => void): IslandBusUnsubscribe
+} {
+  const channels = new Map<keyof Events, Set<(detail: never) => void>>()
+  return {
+    emit(type, detail) {
+      const handlers = channels.get(type)
+      if (handlers === undefined) return
+      // Snapshot so a handler that (un)subscribes mid-dispatch cannot corrupt this iteration.
+      for (const handler of [...handlers]) {
+        try {
+          ;(handler as (d: Events[typeof type]) => void)(detail)
+        } catch (err) {
+          console.error(`[nifra/islands] bus handler for "${String(type)}" failed:`, err)
+        }
+      }
+    },
+    on(type, handler) {
+      let handlers = channels.get(type)
+      if (handlers === undefined) {
+        handlers = new Set()
+        channels.set(type, handlers)
+      }
+      handlers.add(handler as (detail: never) => void)
+      return () => {
+        const set = channels.get(type)
+        if (set === undefined) return
+        set.delete(handler as (detail: never) => void)
+        if (set.size === 0) channels.delete(type)
+      }
+    },
+  }
+}

package/src/module-graph.ts

@@ -44,6 +44,11 @@ export interface ClientModuleGraph {
   readonly chunks: Readonly<Record<string, GraphChunk>>
 }
 
+/** Module ids are graph identifiers, not filesystem paths exposed to an OS API. Bun uses `\\` on
+ * Windows, while Rollup and the guards use `/` for suffix matching and stable diagnostics. Normalize at
+ * each adapter boundary so every consumer sees one graph shape. */
+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<
@@ -66,14 +71,23 @@ export interface BunMetafileLike {
  */
 export function fromBunMetafile(meta: BunMetafileLike | undefined): ClientModuleGraph {
   const modules: Record<string, GraphModule> = {}
-  for (const [id, input] of Object.entries(meta?.inputs ?? {})) {
-    modules[id] = { imports: input.imports ?? [] }
+  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 }),
+      })),
+    }
   }
   const chunks: Record<string, GraphChunk> = {}
-  for (const [path, 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: output.entryPoint } : {}),
-      modules: Object.keys(output.inputs ?? {}),
+      ...(output.entryPoint !== undefined
+        ? { entryPoint: normalizeModuleId(output.entryPoint) }
+        : {}),
+      modules: Object.keys(output.inputs ?? {}).map(normalizeModuleId),
     }
   }
   return { modules, chunks }
@@ -117,11 +131,11 @@ export function fromRollupBundle(
     // Assets (CSS, copied files) have no module graph; `type` is absent only on hand-built test inputs,
     // which are always chunks, so treat "not explicitly an asset" as a chunk.
     if (output.type === "asset") continue
-    const moduleIds = output.moduleIds ?? []
+    const moduleIds = (output.moduleIds ?? []).map(normalizeModuleId)
     // Start from the real modules; `node:` builtins get appended below.
     const chunkModules: string[] = [...moduleIds]
     for (const id of moduleIds) {
-      const imports = importsOf(id).map((path) => ({ path }))
+      const imports = importsOf(id).map((path) => ({ path: normalizeModuleId(path) }))
       if (modules[id] === undefined) modules[id] = { imports }
       // The guards locate a leak by finding the builtin IN a chunk's module list - Bun BUNDLES the `node:`
       // polyfill, so the builtin appears there as an input. Rollup EXTERNALIZES `node:`, so it never lands
@@ -135,10 +149,10 @@ export function fromRollupBundle(
         if (modules[im.path] === undefined) modules[im.path] = { imports: [] }
       }
     }
-    chunks[fileName] = {
+    chunks[normalizeModuleId(fileName)] = {
       // `facadeModuleId` is null for a shared/common chunk (no single entry) - omit it then, matching
       // how a non-entry Bun output omits `entryPoint`, so the guards' entry set stays the real entries.
-      ...(output.facadeModuleId ? { entryPoint: output.facadeModuleId } : {}),
+      ...(output.facadeModuleId ? { entryPoint: normalizeModuleId(output.facadeModuleId) } : {}),
       modules: chunkModules,
     }
   }

package/src/nano.ts

@@ -0,0 +1,246 @@
+/**
+ * `@nifrajs/web/nano` - the smallest state layer that still lets an island drive a keyed list.
+ *
+ * The islands lane (`@nifrajs/web/islands`) is imperative and correct-by-construction, but it has no
+ * state primitive: every DOM update is hand-written, and a list means rebuilding the whole container.
+ * nano adds a small, closed set of primitives and stops:
+ *
+ *   - `signal(v)`  - a current-value cell you read with `.get()` and write with `.set()`.
+ *   - `computed(fn, [deps])` - a derived cell. Its dependencies are DECLARED, never auto-tracked.
+ *   - `resource(fetcher, [deps])` - an async cell with an explicit pending/error/ready value. This is
+ *     nano's answer to "suspense": no thrown promise, no magic boundary, just a value you can bind.
+ *   - `bind` / `bindList` / `bindResource` - explicit, one-directional DOM bindings that each return
+ *     their teardown.
+ *
+ * The design rule is the whole point: every reactive edge is a call you can see - a `bind(...)` or a
+ * `computed(fn, [deps])`. There is no re-render scope, no VDOM, no template compiler, and no effect
+ * that silently subscribes to whatever it happened to read. That is what removes the three failure
+ * modes an AI (or a human) hits in a framework - stale closures, wrong effect deps, hydration
+ * mismatch - and, just as importantly, it is what makes every remaining mistake STATICALLY
+ * detectable: a missing dep is `[deps]` that doesn't list a signal the body reads; a leak is a `bind`
+ * whose cleanup isn't returned. A framework's reactivity can't be linted like that; nano's can.
+ *
+ * Where nano stops: no client router and no nested/composable view state (a component tree that mounts
+ * and unmounts its own children). When an app needs those, it has outgrown a vanilla page - reach for
+ * a framework adapter (`@nifrajs/web-preact`), not more nano.
+ *
+ * Browser code: it touches the DOM and is meant to run in an island enhancer, never under SSR.
+ */
+
+/** A value you can read now and be told about later. Both `signal` and `computed` are `Readable`, so
+ * `bind`/`bindList` accept either. */
+export interface Readable<T> {
+  get(): T
+  subscribe(listener: (value: T) => void): () => void
+}
+
+/** A writable cell. `set` notifies subscribers only when the value actually changes (`Object.is`), so
+ * a redundant write costs nothing. */
+export interface Signal<T> extends Readable<T> {
+  set(value: T): void
+}
+
+/** Notify a snapshot of the current listeners, so a listener that (un)subscribes mid-dispatch does not
+ * corrupt the walk. A throwing listener is isolated - it never blocks the others. */
+function notify<T>(listeners: Set<(value: T) => void>, value: T): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener(value)
+    } catch (error) {
+      console.error("[nifra/nano] a subscriber threw:", error)
+    }
+  }
+}
+
+/** A current-value cell. `signal(0)` -> `.get()` reads, `.set(1)` writes and notifies. */
+export function signal<T>(initial: T): Signal<T> {
+  let value = initial
+  const listeners = new Set<(value: T) => void>()
+  return {
+    get: () => value,
+    set(next: T) {
+      if (Object.is(next, value)) return
+      value = next
+      notify(listeners, value)
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/**
+ * A derived cell. `computed(() => a.get() + b.get(), [a, b])` recomputes whenever a declared
+ * dependency changes and notifies its own subscribers when the derived value changes.
+ *
+ * The `deps` array is mandatory and explicit ON PURPOSE - it is the contract a linter checks against
+ * the signals the body reads (`NF-C023`). Auto-tracking would remove the array but reintroduce the
+ * exact "why didn't this update" bug that makes framework reactivity hard to get right.
+ */
+export function computed<T>(compute: () => T, deps: readonly Readable<unknown>[]): Readable<T> {
+  let value = compute()
+  const listeners = new Set<(value: T) => void>()
+  const recompute = (): void => {
+    const next = compute()
+    if (Object.is(next, value)) return
+    value = next
+    notify(listeners, value)
+  }
+  // A computed with a live subscriber must itself be subscribed to its deps; to keep the prototype
+  // simple it subscribes eagerly for its whole life (fine for the island-scoped, few-signal case).
+  for (const dep of deps) dep.subscribe(recompute)
+  return {
+    get: () => value,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** The three states of an async cell. A discriminated union on `status` so a consumer must handle
+ * every branch - there is no "value that might secretly be loading", the failure mode of ad-hoc
+ * `isLoading` booleans. `value`/`error` are narrowed by `status`. */
+export type ResourceState<T> =
+  | { readonly status: "pending"; readonly value: undefined; readonly error: undefined }
+  | { readonly status: "ready"; readonly value: T; readonly error: undefined }
+  | { readonly status: "error"; readonly value: undefined; readonly error: unknown }
+
+/** An async cell: a `Readable` of `ResourceState<T>` plus `refetch()`. This is nano's answer to
+ * "suspense" - an explicit pending/error/ready value, never a thrown promise or a magic boundary. */
+export interface Resource<T> extends Readable<ResourceState<T>> {
+  refetch(): void
+}
+
+/**
+ * An async derived cell. `resource(fetcher, [deps])` runs `fetcher` immediately and again whenever a
+ * declared dependency changes, exposing the result as an explicit `{ status, value, error }`.
+ *
+ * Two footguns are handled here so they cannot be got wrong by hand:
+ *   - Races: each run holds a generation; a stale run's resolution is dropped, and its `AbortSignal` is
+ *     aborted, so an earlier-started-later-finishing fetch never overwrites a newer one.
+ *   - Deps: like `computed`, dependencies are DECLARED (`NF-C023` checks the fetcher's `.get()` reads
+ *     against the array). A `resource` that reads a signal its deps omit won't refetch when it changes.
+ */
+export function resource<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly Readable<unknown>[] = [],
+): Resource<T> {
+  const state = signal<ResourceState<T>>({ status: "pending", value: undefined, error: undefined })
+  let generation = 0
+  let controller: AbortController | undefined
+  const run = (): void => {
+    const mine = ++generation
+    controller?.abort()
+    controller = new AbortController()
+    const active = controller
+    state.set({ status: "pending", value: undefined, error: undefined })
+    fetcher(active.signal).then(
+      (value) => {
+        if (mine === generation) state.set({ status: "ready", value, error: undefined })
+      },
+      (error) => {
+        // A stale run (superseded) or one we aborted must not surface as an error state.
+        if (mine === generation && !active.signal.aborted)
+          state.set({ status: "error", value: undefined, error })
+      },
+    )
+  }
+  for (const dep of deps) dep.subscribe(run)
+  run()
+  return {
+    get: () => state.get(),
+    subscribe: (listener) => state.subscribe(listener),
+    refetch: run,
+  }
+}
+
+/**
+ * Bind one element to a source: `apply(el, value)` runs once immediately and again on every change.
+ * Returns the unsubscribe - hand it back as the island's cleanup (or collect several).
+ *
+ *   bind(count, remaining, (el, n) => { el.textContent = String(n) })
+ */
+export function bind<T>(
+  el: HTMLElement,
+  source: Readable<T>,
+  apply: (el: HTMLElement, value: T) => void,
+): () => void {
+  apply(el, source.get())
+  return source.subscribe((value) => apply(el, value))
+}
+
+/** How a `bindList` turns items into keyed DOM. `key` MUST be stable and unique per item (never the
+ * array index) - it is what lets add/remove/reorder touch only the changed rows. */
+export interface BindListOptions<T> {
+  key(item: T): string | number
+  create(item: T): HTMLElement
+  update?(el: HTMLElement, item: T): void
+}
+
+/**
+ * Bind a list signal to a container with keyed reconciliation: new items are `create`d, surviving
+ * items are `update`d in place (keeping focus, scroll, and selection), removed items are detached,
+ * and the children are ordered to match the array. Returns the unsubscribe.
+ *
+ * This is the one imperative task too error-prone to hand-write each time - it is why nano exists on
+ * top of islands rather than leaving you to rebuild the container on every change.
+ */
+export function bindList<T>(
+  source: Readable<readonly T[]>,
+  container: HTMLElement,
+  options: BindListOptions<T>,
+): () => void {
+  let nodes = new Map<string | number, HTMLElement>()
+  const render = (items: readonly T[]): void => {
+    const next = new Map<string | number, HTMLElement>()
+    for (const item of items) {
+      const key = options.key(item)
+      const el = nodes.get(key) ?? options.create(item)
+      options.update?.(el, item)
+      next.set(key, el)
+    }
+    for (const [key, el] of nodes) if (!next.has(key)) el.remove()
+    // Append in item order; appending an already-attached node MOVES it, so the final order matches.
+    for (const item of items) container.appendChild(next.get(options.key(item)) as HTMLElement)
+    nodes = next
+  }
+  render(source.get())
+  return source.subscribe(render)
+}
+
+/** How a `bindResource` maps each async state to the DOM. `ready` is required (there is always a
+ * success shape to render); `pending`/`error` are optional. Every branch is explicit - no hidden
+ * "still loading" state can slip through as a rendered `undefined`. */
+export interface BindResourceHandlers<T> {
+  ready(el: HTMLElement, value: T): void
+  pending?(el: HTMLElement): void
+  error?(el: HTMLElement, error: unknown): void
+}
+
+/**
+ * Bind an element to a `resource`, dispatching on `status`. Like `bind`, it applies immediately and
+ * on every change and returns the unsubscribe - collect it (a discarded disposer is `NF-C021`).
+ *
+ *   bindResource(el, user, {
+ *     pending: (n) => { n.textContent = "Loading…" },
+ *     ready: (n, u) => { n.textContent = u.name },
+ *     error: (n) => { n.textContent = "Failed to load" },
+ *   })
+ */
+export function bindResource<T>(
+  el: HTMLElement,
+  source: Readable<ResourceState<T>>,
+  handlers: BindResourceHandlers<T>,
+): () => void {
+  return bind(el, source, (node, state) => {
+    if (state.status === "pending") handlers.pending?.(node)
+    else if (state.status === "error") handlers.error?.(node, state.error)
+    else handlers.ready(node, state.value)
+  })
+}

package/src/plugins/css-modules.ts

@@ -20,7 +20,7 @@
  * Not handled: the bare `:global`/`:local` *switch* form and `composes:` - out of scope by design.
  */
 import type { BunPlugin } from "bun"
-import { createStylesheetEmitter, hash8, reproduciblePath } from "./kit.ts"
+import { createStylesheetEmitter, hash8, normalizeFilePath, reproduciblePath } from "./kit.ts"
 
 const STYLE_NS = "nifra-css-module"
 
@@ -425,7 +425,7 @@ export function cssModulesBunPlugin(generate: "dom" | "ssr"): BunPlugin {
     setup(build) {
       const stylesheet = createStylesheetEmitter(build, STYLE_NS)
       build.onLoad({ filter: /\.module\.css(\?|$)/ }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         const source = await Bun.file(path).text()
         // Hash scoped names off the cwd-relative path so they're reproducible across machines/CI.
         const { exports, css } = transformCssModule(source, reproduciblePath(path))

package/src/plugins/kit.ts

@@ -5,7 +5,8 @@
  * `@nifrajs/web` (imported by the sibling plugin modules); not a public subpath.
  */
 import { existsSync } from "node:fs"
-import { dirname, relative } from "node:path"
+import { dirname, join, relative } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
 import type { BunPlugin } from "bun"
 
 /** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
@@ -23,6 +24,38 @@ export { rewriteSsrImports } from "../dev-ssr-graph.ts"
 
 const packageRootCache = new Map<string, string>()
 
+/**
+ * Convert a plugin/runtime path into a path the host filesystem can open.
+ *
+ * Bun and URL-based test/build APIs can hand a Windows path to a plugin as `/D:/…` (the
+ * `pathname` form of a file URL). Node's filesystem APIs correctly treat the native form as
+ * `D:\…`, but do not reinterpret that URL pathname. Keep this conversion at the boundary so
+ * generated module specifiers can remain slash-normalized without making filesystem reads
+ * platform-dependent.
+ */
+export function normalizeFilePath(path: string): string {
+  let value = path.split("?", 1)[0] ?? path
+  if (value.startsWith("file://")) {
+    try {
+      value = fileURLToPath(value)
+    } catch {
+      // Preserve malformed URL-shaped input. Converting it with Windows slash rules would turn
+      // `file://%` into a plausible-looking local path (`file:\\%`) and hide the actual bad specifier.
+      return value
+    }
+  }
+  if (process.platform === "win32") {
+    if (/^\/[A-Za-z]:[\\/]/.test(value)) value = value.slice(1)
+    return value.replaceAll("/", "\\")
+  }
+  return value
+}
+
+/** A stable slash-separated path for generated imports, virtual module IDs, and diagnostics. */
+export function portablePath(path: string): string {
+  return normalizeFilePath(path).replaceAll("\\", "/")
+}
+
 /** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root),
  * cached. Falls back to `startDir` if none is found, so it never throws. */
 function packageRootOf(startDir: string): string {
@@ -30,7 +63,7 @@ function packageRootOf(startDir: string): string {
   if (cached !== undefined) return cached
   let dir = startDir
   for (;;) {
-    if (existsSync(`${dir}/package.json`)) break
+    if (existsSync(join(dir, "package.json"))) break
     const parent = dirname(dir)
     if (parent === dir) {
       dir = startDir // reached the filesystem root with no package.json - anchor on the file's own dir
@@ -52,8 +85,9 @@ function packageRootOf(startDir: string): string {
  * cwd-relative path would silently desync if the SSR server started from a non-project-root cwd.)
  */
 export function reproduciblePath(absolutePath: string): string {
-  const root = packageRootOf(dirname(absolutePath))
-  return relative(root, absolutePath).replaceAll("\\", "/")
+  const filePath = normalizeFilePath(absolutePath)
+  const root = packageRootOf(dirname(filePath))
+  return relative(root, filePath).replaceAll("\\", "/")
 }
 
 /**
@@ -100,7 +134,14 @@ export const DEV_ROUTES_ENV = "NIFRA_DEV_ROUTES"
 const under = (path: string, dir: string | undefined): boolean =>
   dir !== undefined &&
   dir !== "" &&
-  (path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`))
+  (() => {
+    const normalizedPath = portablePath(path)
+    const normalizedDir = portablePath(dir)
+    return (
+      normalizedPath === normalizedDir ||
+      normalizedPath.startsWith(normalizedDir.endsWith("/") ? normalizedDir : `${normalizedDir}/`)
+    )
+  })()
 
 /**
  * Whether a dev compile of `path` may wrap the module in component-level hot-patching - i.e. whether it
@@ -124,7 +165,7 @@ const under = (path: string, dir: string | undefined): boolean =>
 export function devHotComponent(path: string): boolean {
   const root = process.env[DEV_ROOT_ENV]
   if (!under(path, root)) return false
-  if (path.includes("/node_modules/")) return false
+  if (portablePath(path).includes("/node_modules/")) return false
   return !under(path, process.env[DEV_ROUTES_ENV])
 }
 
@@ -151,17 +192,20 @@ export function createStylesheetEmitter(
   const cssByPath = new Map<string, string>()
   // `\?${namespace}$`: namespaces are plain identifiers, so no regex metachars to escape.
   build.onResolve({ filter: new RegExp(`\\?${namespace}$`) }, (args) => ({
-    path: args.path,
+    // Bun may hand this hook a native Windows path while the emitter stores portable module IDs.
+    // Normalize the path portion but preserve the virtual namespace suffix.
+    path: `${portablePath(args.path.slice(0, -suffix.length))}${suffix}`,
     namespace,
   }))
   build.onLoad({ filter: /.*/, namespace }, (args) => ({
-    contents: cssByPath.get(args.path.slice(0, -suffix.length)) ?? "",
+    contents: cssByPath.get(portablePath(args.path.slice(0, -suffix.length))) ?? "",
     loader: "css",
   }))
   return {
     emit(path, css) {
-      cssByPath.set(path, css)
-      return `import ${JSON.stringify(path + suffix)}\n`
+      const filePath = portablePath(path)
+      cssByPath.set(filePath, css)
+      return `import ${JSON.stringify(filePath + suffix)}\n`
     },
   }
 }
@@ -175,13 +219,22 @@ export async function requirePeer<T>(
   specifier: string,
   hint: { readonly feature: string; readonly install: string },
 ): Promise<T> {
+  const isPathSpecifier =
+    specifier.startsWith("file://") ||
+    /^\/[A-Za-z]:[\\/]/.test(specifier) ||
+    /^[A-Za-z]:[\\/]/.test(specifier)
   try {
-    return (await import(specifier)) as T
+    // Dynamic import treats a Windows URL pathname (`/D:/…`) as a POSIX root. Convert local path
+    // seams to a file URL so the runtime, regardless of platform, receives an unambiguous module ID.
+    const importPath = isPathSpecifier
+      ? pathToFileURL(normalizeFilePath(specifier)).href
+      : specifier
+    return (await import(importPath)) as T
   } catch (err) {
     // Only a genuine resolution failure means "not installed" - surface anything else (a corrupt
     // install, a native-binding error, a throw at module top-level) as the real error rather than
     // masking it behind a misleading "please install it" hint.
-    if ((err as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {
+    if (!isPathSpecifier && (err as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {
       throw new Error(
         `[nifra/web] ${hint.feature} requires the optional peer "${specifier}". Install it: ${hint.install}`,
       )

package/src/plugins/postcss.ts

@@ -18,7 +18,7 @@
  */
 import type { BunPlugin } from "bun"
 import { transformCssModule } from "./css-modules.ts"
-import { createStylesheetEmitter, reproduciblePath, requirePeer } from "./kit.ts"
+import { createStylesheetEmitter, normalizeFilePath, reproduciblePath, requirePeer } from "./kit.ts"
 
 const STYLE_NS = "nifra-postcss"
 
@@ -93,7 +93,7 @@ export function postcssBunPlugin(
       }
 
       build.onLoad({ filter: CSS_FILTER }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         const source = await Bun.file(path).text()
         const postcss = await getProcessor()
         const plugins = await getPlugins()

package/src/plugins/scss.ts

@@ -17,7 +17,7 @@ import { dirname } from "node:path"
 import { pathToFileURL } from "node:url"
 import type { BunPlugin } from "bun"
 import { transformCssModule } from "./css-modules.ts"
-import { createStylesheetEmitter, reproduciblePath, requirePeer } from "./kit.ts"
+import { createStylesheetEmitter, normalizeFilePath, reproduciblePath, requirePeer } from "./kit.ts"
 
 const STYLE_NS = "nifra-scss"
 
@@ -65,7 +65,7 @@ export function scssBunPlugin(generate: "dom" | "ssr", options: ScssPluginOption
       }
 
       build.onLoad({ filter: /\.s[ac]ss(\?|$)/ }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         const source = await Bun.file(path).text()
         const sass = await getCompiler()
         let css: string