@nifrajs/web 0.1.0-alpha.1 → 0.1.0-alpha.2

package/src/manifest.ts

@@ -28,20 +28,92 @@ export type Loader = (ctx: LoaderContext) => unknown | Promise<unknown>
  */
 export type Action = (ctx: LoaderContext) => unknown | Promise<unknown>
 
-/** The document head a route contributes — title + `<meta>`/`<link>` tag attribute sets. */
+/**
+ * One `<link>` tag's attributes for a route/layout's `meta.link`. The common HTML `<link>` attributes
+ * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable —
+ * the previous `Record<string, string>` required *every* value to be a present string, which rejected
+ * exactly that idiomatic shape (the bug this fixes). The index signature keeps custom/`data-*` attrs
+ * (and any future standard attr) passing without a cast; `boolean` covers boolean attributes like
+ * `disabled` (rendered as a bare attribute when `true`, omitted when `false`), and `undefined` lets a
+ * caller spread in a conditionally-absent attribute. Attribute *names* are still shape-validated and
+ * values HTML-escaped at render — a widened type never widens the injection surface.
+ */
+export interface LinkDescriptor {
+  readonly rel?: string
+  readonly href?: string
+  readonly hreflang?: string
+  readonly crossorigin?: string
+  readonly media?: string
+  readonly sizes?: string
+  readonly type?: string
+  readonly as?: string
+  readonly integrity?: string
+  readonly referrerpolicy?: string
+  readonly fetchpriority?: string
+  readonly title?: string
+  readonly imagesrcset?: string
+  readonly imagesizes?: string
+  readonly color?: string
+  readonly disabled?: boolean
+  readonly [attr: string]: string | boolean | undefined
+}
+
+/** One `<script>` element a route contributes to `<head>` — for structured data (JSON-LD) and other
+ * inert, non-executable head scripts. The `content` is the script body; `type` defaults to
+ * `"application/ld+json"` (the common case). The renderer escapes `content` against an HTML breakout
+ * (`</`, `<!--`, `]]>`) — see `escapeScriptContent` — so a JSON-LD payload can never close the
+ * `<script>` element early. `content` is **JSON/text, never raw HTML**: this slot is not an XSS escape
+ * hatch for arbitrary markup. */
+export interface ScriptDescriptor {
+  /** The script's `type` attribute. Default `"application/ld+json"`. */
+  readonly type?: string
+  /** The script body (e.g. a `JSON.stringify`'d JSON-LD object). Escaped for safe `<script>` embedding. */
+  readonly content: string
+}
+
+/**
+ * The document head a route contributes — title + `<meta>`/`<link>`/`<script>` tag sets. Returned by a
+ * route/layout `meta` (statically, or from a {@link MetaArgs} function). Every value is serialized into
+ * managed (`data-nifra`) head tags: attribute *names* are shape-validated and *values* HTML-escaped at
+ * render (see `tagAttrs`/`headTags` in `@nifrajs/web`), and `script[].content` is breakout-escaped — so
+ * loader-derived strings (LLM-authored `og:*`, user content) are XSS-safe in the head by construction.
+ * Layout-chain heads merge with the page's via `mergeHeads` (arrays concat outermost→page; `title` is
+ * nearest-wins). Build `og:*`/`twitter:*` with `openGraph(...)`, canonical with `canonical(...)`, and
+ * JSON-LD with `jsonLd(...)` (all from `@nifrajs/web`) rather than hand-writing the records.
+ */
 export interface Meta {
   readonly title?: string
   readonly meta?: ReadonlyArray<Record<string, string>>
-  readonly link?: ReadonlyArray<Record<string, string>>
+  readonly link?: readonly LinkDescriptor[]
+  /** Inert head `<script>`s (JSON-LD structured data, etc.). See {@link ScriptDescriptor}. */
+  readonly script?: readonly ScriptDescriptor[]
 }
 
-/** Args for a route's `meta` function: the loader's data + the route params. */
+/**
+ * Args for a route's `meta` function: the loader's `data` + the route `params` + the request `origin`.
+ * `meta()` runs in BOTH SSR and client navigation, so it has **no `request`/`process.env`/server access** —
+ * `origin` is the only server-resolved fact it gets (so you needn't thread `siteUrl` through loader data
+ * for absolute `og:url`/`canonical`/`og:image` URLs). See {@link origin}.
+ */
 export interface MetaArgs<Data = unknown> {
   readonly data: Data
   readonly params: Record<string, string>
+  /**
+   * The site origin — scheme + host (+ port), e.g. `"https://news.example.com"`, **with no trailing
+   * slash**. The single piece of server/env knowledge `meta()` otherwise can't see: it runs in BOTH
+   * SSR and client navigation, so it has no `request`/`process.env`. The framework resolves it from the
+   * request URL during SSR and from `location.origin` on client nav — and they match, so an absolute
+   * `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.
+   */
+  readonly origin: string
 }
 
-/** A route's `meta`: a static {@link Meta}, or a function of the loader data + params. */
+/** A route's `meta`: a static {@link Meta}, or a function of the loader data + params + the request
+ * origin ({@link MetaArgs}). Use the `origin` arg for absolute `canonical`/`og:url`/`og:image` URLs —
+ * it's resolved server-side from the request and matches the client's `location.origin`. */
 export type MetaInput = Meta | ((args: MetaArgs) => Meta)
 
 /** One concrete parameterization of a dynamic route, returned by {@link GetStaticPaths}. */
@@ -104,10 +176,16 @@ export interface RouteModule {
   readonly islandScripts?: readonly string[]
 }
 
-/** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader. */
+/** A layout (or `_404`/`_error`) entry: its source file (for client codegen) + a lazy loader.
+ *
+ * A `_layout.tsx` may export `meta` (static {@link Meta} or a function of the loader data + params,
+ * same shape as a route's) to contribute sitewide `<head>` tags — `hreflang`/`preconnect`/etc. that
+ * belong on every page under the layout. The layout chain's heads merge with the page's: arrays
+ * (`meta`/`link`) concatenate outermost→innermost→page; scalars (`title`) are nearest-wins (the page
+ * overrides an inner layout, which overrides an outer one). See `mergeHeads` in `@nifrajs/web`. */
 export interface LayoutEntry {
   readonly file: string
-  readonly load: () => Promise<{ default: unknown }>
+  readonly load: () => Promise<{ default: unknown; meta?: MetaInput }>
 }
 
 /** One matched route: pattern, nested layout ids (outermost → innermost), source file, loader. */

package/src/server-only.ts

@@ -0,0 +1,25 @@
+/**
+ * `@nifrajs/web/server-only` — the **explicit, opt-in poison-import marker** (Next's `import
+ * "server-only"`). A module of PURE server logic that carries no `node:` import — a secret-bearing
+ * constant, a server-only API call — can't be caught by nifra's other two client-leak guards: the
+ * `.server` convention (which empties `*.server` modules in the client build) needs the file to be
+ * NAMED `*.server`, and the node-builtin guard only fires when a `node:` import actually reaches a
+ * client chunk. This marker closes that gap: drop a side-effect import at the top of the module —
+ *
+ *     import "@nifrajs/web/server-only"
+ *
+ * — and the CLIENT build ({@link buildClient}) FAILS LOUD, naming the import chain, if that module
+ * ever lands in a browser chunk. On the SERVER build/runtime it's a harmless no-op (this empty
+ * module), so the same file runs untouched server-side.
+ *
+ * Pair it with the type-level {@link ServerOnly} brand (from `@nifrajs/web`) on the module's exports
+ * to signal intent to readers + the compiler; this runtime import is what actually fails the build.
+ *
+ * @see ServerOnly — the type-level intent marker that complements this runtime import.
+ */
+
+// Intentionally empty. The marker is the IMPORT itself: `buildClient` detects any module that imports
+// this specifier and lands in a client chunk (via the same Bun metafile graph the node-builtin guard
+// walks) and fails the build. There is no value to export and nothing to run — on the server it's a
+// no-op so the marked module behaves normally; on the client the build never completes.
+export {}

package/src/vite.ts

@@ -19,7 +19,7 @@ import {
 import { relative, resolve as resolvePath } from "node:path"
 import { renderDevErrorOverlay } from "./dev-error.ts"
 import { discoverRoutes } from "./fs.ts"
-import { generateClientEntry } from "./index.ts"
+import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
 
 /** Minimal app surface — `createWebApp(...)` satisfies it. */
 interface FetchApp {
@@ -36,6 +36,8 @@ interface ViteLike {
 }
 interface ViteModule {
   createServer(config: Record<string, unknown>): Promise<ViteLike>
+  // Present only on rolldown-vite (Vite 8+); used to gate the optimizeDeps.jsx-key normalization below.
+  readonly rolldownVersion?: string
 }
 
 // `node:http` server type the request handler runs on (also the HMR WebSocket host — see below).
@@ -66,7 +68,7 @@ export interface ViteDevServerOptions {
   readonly define?: Readonly<Record<string, string>>
   /** Vite project root (default `process.cwd()`). */
   readonly root?: string
-  /** Port (default 3000). */
+  /** Port (default {@link DEFAULT_DEV_PORT}). */
   readonly port?: number
   /**
    * Use polling for the file watcher. Native fs events (fsevents/inotify) are unreliable inside
@@ -111,6 +113,68 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
   return new Request(url, init as unknown as ConstructorParameters<typeof Request>[1])
 }
 
+// A Vite plugin's `config` hook — the only hook we wrap. Typed structurally (no `vite` type dep): it
+// takes the user config + env and may return a partial config (possibly a promise). Everything else on
+// the plugin object is preserved by spread, so wrapping is transparent to Vite.
+interface VitePluginLike {
+  readonly name?: string
+  config?: (config: unknown, env: unknown) => unknown
+  readonly [key: string]: unknown
+}
+
+/**
+ * Strip `optimizeDeps.rollupOptions.jsx` from a plugin's `config` hook output when running under
+ * rolldown-vite — the source of the scary, harmless `Warning: Invalid input options … "jsx" Invalid
+ * key: Expected never but received "jsx"` on `nifra dev`.
+ *
+ * Why it happens: `@vitejs/plugin-react@4.x` (and peers) target an *older* rolldown-vite optimizeDeps
+ * API — they inject `optimizeDeps.rollupOptions.jsx` to tell the dep pre-bundler to transform JSX. Vite
+ * 8's rolldown dep-optimizer renamed that surface to `optimizeDeps.rolldownOptions` (and moved jsx under
+ * `transform.jsx`), so the stale `rollupOptions.jsx` is an unrecognized input option → the warning. It's
+ * a version-skew artifact, not a real misconfig: the route source JSX transform runs through the
+ * plugin's own `transform` hook (untouched here), and node_modules deps that get pre-bundled almost
+ * never contain raw JSX — so dropping the dead key changes no behavior and keeps HMR/Fast Refresh
+ * intact. We *strip* (rather than translate to `rolldownOptions`) so the fix is version-agnostic: a
+ * plugin already emitting the correct `rolldownOptions` is left untouched, and a future plugin bump that
+ * stops emitting `rollupOptions.jsx` makes this a no-op.
+ *
+ * Scoped narrowly: only the `optimizeDeps.rollupOptions.jsx` key is removed, only under rolldown-vite,
+ * and only from the value a plugin's `config` hook returns. Non-rolldown Vite is passed through verbatim.
+ */
+export function normalizeRolldownPlugins(
+  plugins: readonly unknown[],
+  isRolldown: boolean,
+): readonly unknown[] {
+  if (!isRolldown) return plugins
+  const stripJsxKey = (returned: unknown): unknown => {
+    // Only touch a plain-object config carrying optimizeDeps.rollupOptions.jsx; leave anything else as-is.
+    if (returned === null || typeof returned !== "object") return returned
+    const cfg = returned as { optimizeDeps?: { rollupOptions?: Record<string, unknown> } }
+    const rollupOptions = cfg.optimizeDeps?.rollupOptions
+    if (rollupOptions === undefined || !("jsx" in rollupOptions)) return returned
+    // Clone the affected branch (never mutate the plugin's own return value) and drop the dead key.
+    const { jsx: _dropped, ...restRollup } = rollupOptions
+    return {
+      ...cfg,
+      optimizeDeps: { ...cfg.optimizeDeps, rollupOptions: restRollup },
+    }
+  }
+  return plugins.map((plugin) => {
+    if (plugin === null || typeof plugin !== "object") return plugin
+    const p = plugin as VitePluginLike
+    if (typeof p.config !== "function") return plugin
+    const originalConfig = p.config
+    return {
+      ...p,
+      config: (config: unknown, env: unknown) => {
+        const returned = originalConfig(config, env)
+        // The hook may return a promise — normalize both shapes.
+        return returned instanceof Promise ? returned.then(stripJsxKey) : stripJsxKey(returned)
+      },
+    }
+  })
+}
+
 /**
  * Start the Vite-backed dev server: Vite serves/HMRs the client; nifra SSRs each request and Vite
  * injects its HMR client + the framework refresh preamble via `transformIndexHtml`.
@@ -118,7 +182,7 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
 export async function createViteDevServer(options: ViteDevServerOptions): Promise<ViteDevServer> {
   const root = resolvePath(options.root ?? process.cwd())
   const routesDir = resolvePath(options.routesDir)
-  const port = options.port ?? 3000
+  const port = options.port ?? DEFAULT_DEV_PORT
 
   // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
   const manifest = discoverRoutes(routesDir)
@@ -172,7 +236,14 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
   // `conditions: ["bun"]` makes Vite resolve nifra's workspace packages (`@nifrajs/web-react/client`, …) to
   // their TS **source** — so the dev server needs no prior `dist` build of the adapter packages.
   const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
-  const { createServer } = (await import("vite")) as unknown as ViteModule
+  const viteModule = (await import("vite")) as unknown as ViteModule
+  const { createServer } = viteModule
+  // Under rolldown-vite (Vite 8+), strip the stale `optimizeDeps.rollupOptions.jsx` some framework
+  // plugins still emit — it triggers a noisy "Invalid key … jsx" warning but does nothing useful here.
+  const plugins = normalizeRolldownPlugins(
+    options.plugins ?? [],
+    viteModule.rolldownVersion !== undefined,
+  )
   vite = await createServer({
     root,
     appType: "custom",
@@ -182,9 +253,15 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
       // Explicit watch config; poll when native fs events aren't delivered (containers/sandboxes).
       watch: usePolling ? { usePolling: true, interval: 80 } : {},
     },
-    plugins: [...(options.plugins ?? [])],
+    plugins: [...plugins],
     resolve: {
       conditions: [...(options.conditions ?? []), "bun", "module", "browser", "development"],
+      // Dedupe React to ONE copy. In a multi-root workspace a shared package can pull react/react-dom
+      // from a SIBLING app's node_modules, so the dev server loads two React cores → a second hook
+      // dispatcher → `resolveDispatcher().useState` null on any hook-using route (the error points at the
+      // component, not the resolution — brutal to diagnose). Mirrors the build-time reactDedupePlugin so
+      // dev matches prod. No-op for non-React apps (the package simply isn't present to dedupe).
+      dedupe: ["react", "react-dom"],
     },
     ...(options.define ? { define: options.define } : {}),
   })