@nifrajs/web 2.14.1 → 3.2.0

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

package/src/plugins/stylex.ts

@@ -0,0 +1,298 @@
+/**
+ * StyleX integration for Nifra's Bun and Vite pipelines.
+ *
+ * The StyleX compiler stays an optional peer owned by the StyleX project. This module owns only the
+ * Nifra boundary: transform route/component modules in both pipelines, emit client CSS through the
+ * existing virtual stylesheet seam, and run the same transform without CSS for SSR.
+ */
+import type { BunPlugin } from "bun"
+import {
+  createStylesheetEmitter,
+  devServerCompile,
+  hash8,
+  normalizeFilePath,
+  reproduciblePath,
+  requirePeer,
+} from "./kit.ts"
+
+const STYLE_NS = "nifra-stylex"
+const JS_FILTER = /\.[cm]?[jt]sx?(\?|$)/
+
+/** StyleX's module resolution option, kept structural so the compiler remains an optional peer. */
+export interface StylexModuleResolution {
+  readonly type: "commonJS" | "haste"
+  readonly rootDir: string
+}
+
+/** Structural slice of `@babel/core` used by the adapter. */
+export interface StylexBabelCompiler {
+  transformAsync(
+    source: string,
+    options: Readonly<Record<string, unknown>>,
+  ): Promise<StylexBabelResult | null | undefined>
+}
+
+/** Structural slice of the StyleX Babel plugin used by the adapter. */
+export interface StylexCompiler {
+  withOptions(options: Readonly<Record<string, unknown>>): unknown
+  processStylexRules(rules: readonly unknown[], options: Readonly<Record<string, unknown>>): string
+}
+
+/** Optional peer injection and compiler configuration shared by Bun and Vite adapters. */
+export interface StylexPluginOptions {
+  /** Inject `@babel/core` in tests or advanced integrations. Defaults to the optional peer. */
+  readonly babel?: StylexBabelCompiler
+  /** Inject `@stylexjs/babel-plugin` in tests or advanced integrations. */
+  readonly compiler?: StylexCompiler
+  /** Inject Babel syntax plugins. Defaults to the three official syntax peers. */
+  readonly syntaxPlugins?: {
+    readonly flow: unknown
+    readonly jsx: unknown
+    readonly typescript: unknown
+  }
+  /** StyleX import sources to transform. Defaults to `stylex` and `@stylexjs/stylex`. */
+  readonly importSources?: readonly string[]
+  /** StyleX development transform mode. Defaults to Nifra's dev-server signal. */
+  readonly dev?: boolean
+  /** StyleX CSS layer output. Defaults to `true` for deterministic precedence. */
+  readonly useCSSLayers?: boolean
+  /** StyleX's module resolution policy. */
+  readonly unstable_moduleResolution?: StylexModuleResolution
+  /** Extra Babel plugins and presets merged before the StyleX plugin. */
+  readonly babelConfig?: {
+    readonly plugins?: readonly unknown[]
+    readonly presets?: readonly unknown[]
+  }
+}
+
+interface StylexBabelResult {
+  readonly code?: unknown
+  readonly metadata?: unknown
+}
+
+interface StylexTransformedModule {
+  readonly code: string
+  readonly css: string
+}
+
+interface StylexDependencies {
+  readonly babel: StylexBabelCompiler
+  readonly compiler: StylexCompiler
+  readonly syntax: Required<StylexPluginOptions>["syntaxPlugins"]
+}
+
+interface RecordLike {
+  readonly [key: string]: unknown
+}
+
+const isRecord = (value: unknown): value is RecordLike =>
+  (typeof value === "object" && value !== null) || typeof value === "function"
+
+const unwrapDefault = (value: unknown): unknown => {
+  if (!isRecord(value)) return value
+  return value.default ?? value
+}
+
+const isBabelCompiler = (value: unknown): value is StylexBabelCompiler =>
+  isRecord(value) && typeof value.transformAsync === "function"
+
+const isStylexCompiler = (value: unknown): value is StylexCompiler =>
+  isRecord(value) &&
+  typeof value.withOptions === "function" &&
+  typeof value.processStylexRules === "function"
+
+const syntaxPeer = async (specifier: string, feature: string): Promise<unknown> =>
+  unwrapDefault(
+    await requirePeer<unknown>(specifier, {
+      feature,
+      install: `bun add -d ${specifier}`,
+    }),
+  )
+
+const loadBabelCompiler = async (options: StylexPluginOptions): Promise<StylexBabelCompiler> => {
+  if (options.babel !== undefined) return options.babel
+  const loaded = await requirePeer<unknown>("@babel/core", {
+    feature: "StyleX compilation",
+    install: "bun add -d @babel/core",
+  })
+  const compiler = unwrapDefault(loaded)
+  if (!isBabelCompiler(compiler)) {
+    throw new Error("[nifra/web] the installed @babel/core does not expose transformAsync")
+  }
+  return compiler
+}
+
+const loadStylexCompiler = async (options: StylexPluginOptions): Promise<StylexCompiler> => {
+  if (options.compiler !== undefined) return options.compiler
+  const loaded = await requirePeer<unknown>("@stylexjs/babel-plugin", {
+    feature: "StyleX compilation",
+    install: "bun add -d @stylexjs/babel-plugin",
+  })
+  const compiler = unwrapDefault(loaded)
+  if (!isStylexCompiler(compiler)) {
+    throw new Error(
+      "[nifra/web] the installed @stylexjs/babel-plugin does not expose the StyleX compiler API",
+    )
+  }
+  return compiler
+}
+
+const loadSyntaxPlugins = async (
+  options: StylexPluginOptions,
+): Promise<Required<StylexPluginOptions>["syntaxPlugins"]> => {
+  if (options.syntaxPlugins !== undefined) return options.syntaxPlugins
+  const [flow, jsx, typescript] = await Promise.all([
+    syntaxPeer("@babel/plugin-syntax-flow", "StyleX Flow syntax parsing"),
+    syntaxPeer("@babel/plugin-syntax-jsx", "StyleX JSX syntax parsing"),
+    syntaxPeer("@babel/plugin-syntax-typescript", "StyleX TypeScript syntax parsing"),
+  ])
+  return { flow, jsx, typescript }
+}
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+const containsStylexImport = (source: string, importSources: readonly string[]): boolean =>
+  importSources.some((specifier) => {
+    const escaped = escapeRegExp(specifier)
+    return new RegExp(
+      `(?:from\\s*['"]${escaped}['"]|import\\s*\\(\\s*['"]${escaped}['"]\\s*\\)|require\\s*\\(\\s*['"]${escaped}['"]\\s*\\))`,
+      "m",
+    ).test(source)
+  })
+
+const loaderFor = (path: string): "js" | "jsx" | "ts" | "tsx" => {
+  const clean = path.split("?", 1)[0] ?? path
+  if (clean.endsWith(".tsx")) return "tsx"
+  if (clean.endsWith(".jsx")) return "jsx"
+  if (clean.endsWith(".ts") || clean.endsWith(".mts") || clean.endsWith(".cts")) return "ts"
+  return "js"
+}
+
+const moduleResolution = (options: StylexPluginOptions): StylexModuleResolution =>
+  options.unstable_moduleResolution ?? { type: "commonJS", rootDir: process.cwd() }
+
+const transformModule = async (
+  source: string,
+  filename: string,
+  options: StylexPluginOptions,
+  dependencies: Promise<StylexDependencies>,
+): Promise<StylexTransformedModule | undefined> => {
+  if (!containsStylexImport(source, options.importSources ?? ["stylex", "@stylexjs/stylex"])) {
+    return undefined
+  }
+
+  const { babel, compiler, syntax } = await dependencies
+  const result = await babel.transformAsync(source, {
+    babelrc: false,
+    filename,
+    presets: [...(options.babelConfig?.presets ?? [])],
+    plugins: [
+      ...((options.babelConfig?.plugins ?? []) as readonly unknown[]),
+      /\.jsx?$/.test(filename) ? syntax.flow : [syntax.typescript, { isTSX: true }],
+      syntax.jsx,
+      compiler.withOptions({
+        dev: options.dev ?? devServerCompile(),
+        importSources: options.importSources ?? ["stylex", "@stylexjs/stylex"],
+        treeshakeCompensation: true,
+        unstable_moduleResolution: moduleResolution(options),
+      }),
+    ],
+  })
+  const code = typeof result?.code === "string" ? result.code : undefined
+  if (code === undefined) return undefined
+
+  const metadata = isRecord(result?.metadata) ? result.metadata : undefined
+  const rules = Array.isArray(metadata?.stylex) ? metadata.stylex : []
+  const css =
+    rules.length === 0
+      ? ""
+      : compiler.processStylexRules(rules, {
+          useCSSLayers: options.useCSSLayers ?? true,
+        })
+  return { code, css }
+}
+
+const dependenciesFor = (options: StylexPluginOptions): (() => Promise<StylexDependencies>) => {
+  let dependencies: Promise<StylexDependencies> | undefined
+  return (): Promise<StylexDependencies> => {
+    dependencies ??= Promise.all([
+      loadBabelCompiler(options),
+      loadStylexCompiler(options),
+      loadSyntaxPlugins(options),
+    ]).then(([babel, compiler, syntax]) => ({ babel, compiler, syntax }))
+    return dependencies
+  }
+}
+
+/** Build a Bun plugin that transforms StyleX and emits CSS for the browser or class maps for SSR. */
+export function stylexBunPlugin(
+  generate: "dom" | "ssr",
+  options: StylexPluginOptions = {},
+): BunPlugin {
+  return {
+    name: `nifra-stylex-${generate}`,
+    setup(build) {
+      const stylesheet = generate === "dom" ? createStylesheetEmitter(build, STYLE_NS) : undefined
+      const dependencies = dependenciesFor(options)
+      build.onLoad({ filter: JS_FILTER }, async (args) => {
+        const path = normalizeFilePath(args.path)
+        const source = await Bun.file(path).text()
+        const transformed = await transformModule(source, path, options, dependencies())
+        if (transformed === undefined) return
+        const contents =
+          generate === "dom" && stylesheet !== undefined && transformed.css !== ""
+            ? `${transformed.code}\n${stylesheet.emit(path, transformed.css)}`
+            : transformed.code
+        return { contents, loader: loaderFor(path) }
+      })
+    },
+  }
+}
+
+/** Structural Vite plugin return type. Vite remains an optional peer of `@nifrajs/web`. */
+export interface StylexVitePlugin {
+  readonly name: string
+  transform(
+    source: string,
+    id: string,
+  ): Promise<{ readonly code: string; readonly map?: null } | undefined>
+  resolveId(id: string): string | undefined
+  load(id: string): string | undefined
+}
+
+/** Build a Vite plugin that maps each transformed StyleX module to a virtual CSS asset. */
+export function stylexVitePlugin(
+  generate: "dom" | "ssr",
+  options: StylexPluginOptions = {},
+): StylexVitePlugin {
+  const cssById = new Map<string, string>()
+  const dependencies = dependenciesFor(options)
+  const virtualIdFor = (id: string): string =>
+    `virtual:nifra-stylex/${hash8(reproduciblePath(normalizeFilePath(id)))}.css`
+
+  return {
+    name: `nifra-stylex-${generate}`,
+    async transform(source, id) {
+      const path = normalizeFilePath(id)
+      const transformed = await transformModule(source, path, options, dependencies())
+      if (transformed === undefined) return undefined
+      if (generate === "ssr" || transformed.css === "") return { code: transformed.code, map: null }
+      const cssId = virtualIdFor(path)
+      cssById.set(cssId, transformed.css)
+      return {
+        code: `${transformed.code}\nimport ${JSON.stringify(cssId)}`,
+        map: null,
+      }
+    },
+    resolveId(id) {
+      return cssById.has(id) ? id : undefined
+    },
+    load(id) {
+      return cssById.get(id)
+    },
+  }
+}
+
+/** Convenience alias for apps that configure only a browser Vite build. */
+export const stylexVite = (options: StylexPluginOptions = {}): StylexVitePlugin =>
+  stylexVitePlugin("dom", options)

package/src/plugins/svg.ts

@@ -16,7 +16,7 @@
  * `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"
+import { normalizeFilePath, requirePeer } from "./kit.ts"
 
 /** The subset of the `svgo` API this plugin uses (structural, so no hard dependency on its types). */
 export interface SvgOptimizer {
@@ -168,7 +168,7 @@ export function svgComponentBunPlugin(
       }
 
       build.onLoad({ filter: SVG_FILTER }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         let xml = await Bun.file(path).text()
         const svgo = await getOptimizer()
         if (svgo !== undefined) {

package/src/render-seam.ts

@@ -6,6 +6,8 @@
  * without importing the document renderer through the root module. The singleton is stored on
  * globalThis because the Bun and Vite dev pipelines can evaluate two copies in one process.
  */
+
+import type { BoundaryStates } from "./boundary.ts"
 import type { Submission } from "./router.ts"
 
 /** The data handed to a route component. */
@@ -26,6 +28,8 @@ export interface RenderProps {
   readonly path?: string
   /** The route's typed, validated search params. */
   readonly search?: Record<string, unknown>
+  /** Neutral named-boundary states; adapters choose how each boundary's `render` UI is mounted. */
+  readonly boundaries?: BoundaryStates
 }
 
 /**
@@ -72,5 +76,7 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
 /** Global the server serializes an action's data return into (absent on GETs); the client reads it
  * so hydration after a native form POST matches the server-rendered markup. */
 export const ACTION_GLOBAL = "__NIFRA_ACTION__"
+/** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
+export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
 /** Marker attribute used to find a non-default hydration container. */
 export const ROOT_ATTRIBUTE = "data-nifra-root"