@nifrajs/web 2.0.0 → 2.2.0

package/src/bun-dev-entry.ts

@@ -0,0 +1,184 @@
+/**
+ * `@nifrajs/web/bun-dev-entry` — discovering the client-entry URL Bun's dev server assigns.
+ *
+ * ## Why this file exists at all
+ *
+ * Bun's dev server bundles an HTML route and rewrites its `<script src="./entry.tsx">` into a
+ * content-hashed URL under `/_bun/client/`. That rewrite is the whole point: the hash changes per build,
+ * so the URL cannot be predicted or hard-coded.
+ *
+ * nifra needs that URL, because nifra renders the document. Bun never sees the page it would inject the
+ * script into - `createWebApp` builds the HTML from the route's own output and needs `clientEntry` to
+ * emit `<script type="module" src=…>` and the matching `modulepreload`. So the two halves have to meet:
+ * Bun knows the URL, nifra needs it, and there is no supported API connecting them. Verified against Bun
+ * 1.3.14: the HTML import evaluates to `{}` with no keys, the `Bun.serve` instance exposes nothing
+ * asset-related, and `/_bun/manifest`, `/_bun/client/manifest.json` and `/_bun/assets` all 404.
+ *
+ * The only route is to ask the dev server for a page it *did* bundle and read the URL back out of it.
+ *
+ * ## Why it is a module instead of four lines inline
+ *
+ * A regex over another tool's output is a dependency on an unspecified format, and that is true whether
+ * it lives here or inline in the dev server. What changes is the blast radius. Isolated here it is one
+ * function with one caller, covered by tests that pin the exact tag shape Bun emits today - so a Bun
+ * upgrade that changes the format fails a test with a diff of the markup instead of producing a dev
+ * server that boots fine and serves pages whose scripts 404. And if Bun ever exposes a real accessor,
+ * this is the only body that changes.
+ *
+ * Detection is layered so a cosmetic change degrades instead of breaking: the `data-bun-dev-server-script`
+ * attribute is the precise signal, an unambiguous single module script under `/_bun/` is the fallback,
+ * and anything else is a named error that says what was searched for and what was found.
+ */
+
+/** One `<script>` tag lifted out of a served page: its raw attribute text and parsed `src`. */
+interface ScriptTag {
+  readonly attrs: string
+  readonly src: string | undefined
+}
+
+// `<script …>` open tags. Attribute text is captured raw; `src` is parsed out of it separately so the
+// two are independent of attribute ORDER (Bun emits `crossorigin src=… data-bun-dev-server-script`, but
+// nothing in HTML makes that order stable).
+const SCRIPT_OPEN = /<script\b([^>]*)>/gi
+const SRC_ATTR = /\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i
+// The attribute Bun marks its own bundled entry with. Valueless today; matched tolerantly so a future
+// `data-bun-dev-server-script="1"` still hits.
+const MARKER_ATTR = /\bdata-bun-dev-server-script\b/i
+// Bun serves every bundled client asset under this prefix.
+const BUN_CLIENT_PREFIX = "/_bun/"
+
+/** Pull every `<script>` open tag out of an HTML document, in source order. */
+function scriptTags(html: string): ScriptTag[] {
+  const tags: ScriptTag[] = []
+  SCRIPT_OPEN.lastIndex = 0
+  for (let m = SCRIPT_OPEN.exec(html); m !== null; m = SCRIPT_OPEN.exec(html)) {
+    const attrs = m[1] ?? ""
+    const src = SRC_ATTR.exec(attrs)
+    tags.push({ attrs, src: src?.[1] ?? src?.[2] ?? src?.[3] })
+  }
+  return tags
+}
+
+/** How the entry URL was found - reported so a fallback hit is visible rather than silent. */
+export type DevEntryVia = "marker" | "single-bun-script"
+
+/** A located client entry: the URL to hand nifra, its stylesheets, and which signal found it. */
+export interface DevEntryMatch {
+  readonly src: string
+  /**
+   * Stylesheet URLs Bun extracted from the entry's CSS imports.
+   *
+   * These are not a nicety. Bun's bundler pulls `import "./app.css"` out of the JS graph and links it
+   * from the HTML *it* bundled - the throwaway probe page, which nobody ever sees. nifra renders the real
+   * pages, so unless these are carried across, a Bun-pipeline dev session serves every page unstyled
+   * while the production build (which reads CSS from the build manifest) is fine. That is the worst
+   * possible shape for a bug: dev-only, silent, and looks like the app's own CSS is broken.
+   */
+  readonly styles: readonly string[]
+  readonly via: DevEntryVia
+}
+
+// `<link rel="stylesheet" href="…">`. `rel` and `href` are matched independently of order, same reason
+// as the script tags: attribute order in generated markup is not a contract.
+const LINK_OPEN = /<link\b([^>]*)>/gi
+const HREF_ATTR = /\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/i
+const REL_STYLESHEET =
+  /\brel\s*=\s*(?:"[^"]*\bstylesheet\b[^"]*"|'[^']*\bstylesheet\b[^']*'|stylesheet)/i
+
+/** Every stylesheet URL linked from a document, in source order. */
+export function parseDevStyles(html: string): string[] {
+  const hrefs: string[] = []
+  LINK_OPEN.lastIndex = 0
+  for (let m = LINK_OPEN.exec(html); m !== null; m = LINK_OPEN.exec(html)) {
+    const attrs = m[1] ?? ""
+    if (!REL_STYLESHEET.test(attrs)) continue
+    const href = HREF_ATTR.exec(attrs)
+    const url = href?.[1] ?? href?.[2] ?? href?.[3]
+    if (url !== undefined && url !== "") hrefs.push(url)
+  }
+  return hrefs
+}
+
+/**
+ * Find the bundled client-entry URL in a page Bun's dev server rendered. Pure - the whole format
+ * dependency lives in this function, which is what makes it testable against captured real output.
+ *
+ * Returns `undefined` rather than throwing so the caller can attach the context a useful error needs
+ * (which URL was probed, what the server returned).
+ */
+export function parseDevEntry(html: string): DevEntryMatch | undefined {
+  const tags = scriptTags(html)
+  const styles = parseDevStyles(html)
+  // 1. The precise signal: Bun's own marker attribute.
+  for (const tag of tags) {
+    if (MARKER_ATTR.test(tag.attrs) && tag.src !== undefined && tag.src !== "") {
+      return { src: tag.src, styles, via: "marker" }
+    }
+  }
+  // 2. Fallback: exactly one script pointing into Bun's client-asset prefix. Requiring uniqueness is what
+  //    keeps this a fallback and not a guess - with two candidates there is no basis for picking one, so
+  //    it declines and lets the caller raise a real error.
+  const bunScripts = tags.filter((t) => t.src?.startsWith(BUN_CLIENT_PREFIX))
+  const only = bunScripts.length === 1 ? bunScripts[0] : undefined
+  if (only?.src !== undefined) return { src: only.src, styles, via: "single-bun-script" }
+  return undefined
+}
+
+/** The error thrown when Bun's dev server serves a page nothing in it can be recognised as the entry. */
+export function devEntryNotFoundMessage(probeUrl: string, html: string): string {
+  const scripts = scriptTags(html)
+  const found =
+    scripts.length === 0
+      ? "the page contains no <script> tags at all"
+      : `the page's script tags are: ${scripts.map((s) => `<script${s.attrs}>`).join(", ")}`
+  return (
+    `[nifra] could not find Bun's bundled client entry in the page served at ${probeUrl}.\n` +
+    `  Looked for a <script> carrying \`data-bun-dev-server-script\`, then for a single module script ` +
+    `under \`${BUN_CLIENT_PREFIX}\`; ${found}.\n` +
+    `  This is how Bun's dev server labelled its bundled entry when this was written, so a Bun upgrade ` +
+    `that changes the markup lands here first. Run the Bun pipeline dev server's tests to see the ` +
+    `current shape, or use the Vite pipeline (\`nifra dev\`) meanwhile.`
+  )
+}
+
+/** Structural slice of a running server this needs: just the port it bound. */
+export interface ServedOn {
+  readonly port: number
+}
+
+export interface ResolveDevEntryOptions {
+  /** Path of the throwaway route serving Bun's bundled HTML (e.g. `/__nifra/entry`). */
+  readonly probePath: string
+  /** Injected for tests; defaults to global `fetch`. */
+  readonly fetchImpl?: typeof fetch
+}
+
+/**
+ * Ask Bun's dev server for the current bundled entry URL. One loopback request against a route the app
+ * never exposes.
+ *
+ * **The answer expires.** The URL is a content hash over the whole client graph, so editing any file it
+ * reaches - a route, a component, a stylesheet - re-hashes it. Caching the startup value and injecting it
+ * forever produces a spectacular failure: Bun answers a superseded chunk URL with a 104-byte
+ * `location.reload()` stub under a 405, so the page reloads, gets the same dead URL from SSR, and reloads
+ * again, forever. No console output survives the loop to explain it. Callers must re-resolve rather than
+ * remember - see how `@nifrajs/web/dev` serves a stable URL that redirects here per request.
+ */
+export async function resolveDevEntry(
+  server: ServedOn,
+  options: ResolveDevEntryOptions,
+): Promise<DevEntryMatch> {
+  const doFetch = options.fetchImpl ?? fetch
+  const probeUrl = `http://127.0.0.1:${server.port}${options.probePath}`
+  const response = await doFetch(probeUrl)
+  if (!response.ok) {
+    throw new Error(
+      `[nifra] Bun's dev server returned ${response.status} for the client-entry probe at ${probeUrl}. ` +
+        "The generated HTML route did not build - the error above this line is Bun's.",
+    )
+  }
+  const html = await response.text()
+  const match = parseDevEntry(html)
+  if (match === undefined) throw new Error(devEntryNotFoundMessage(probeUrl, html))
+  return match
+}

package/src/client.ts

@@ -200,6 +200,14 @@ export function installHistory(
  */
 export function applyHead(head: Meta): void {
   if (head.title !== undefined) document.title = head.title
+  // `<html lang>`/`<html dir>` — applied AUTHORITATIVELY (unlike `title`, which is left alone when the
+  // route omits it), mirroring the SSR shell's defaulting exactly: `lang` falls back to `"en"`, `dir` is
+  // removed when unset. Anything laxer drifts on a multilingual site — navigating /ur → /en would leave
+  // `dir="rtl"` behind and lay the English page out right-to-left, a bug a hard reload would not show.
+  const root = document.documentElement
+  root.setAttribute("lang", head.lang ?? "en")
+  if (head.dir === undefined) root.removeAttribute("dir")
+  else root.setAttribute("dir", head.dir)
   for (const el of document.head.querySelectorAll("[data-nifra]")) el.remove()
   // Values follow the same HTML attribute conventions as the SSR `tagAttrs`: a string sets the value,
   // `true` sets the bare boolean attribute, `false`/`undefined` skip it — so a soft-nav head matches

package/src/deferred.ts

@@ -5,6 +5,7 @@
  * protocol — the marker, the resolved/deferred split, and the tiny client registry that streamed
  * resolution scripts settle. The per-adapter `<Await>` lives in `@nifrajs/web-{solid,react}/client`.
  */
+import { plainJsonCodec, type TransportCodec } from "@nifrajs/core/transport-codec"
 
 /**
  * A loader value marked to stream in after the shell. The component consumes it with the adapter's
@@ -161,21 +162,22 @@ const NDJSON_ENCODER = new TextEncoder()
 export function ndjsonStream(
   forClient: unknown,
   deferred: ReadonlyArray<{ readonly id: number; readonly promise: Promise<unknown> }>,
+  codec: TransportCodec = plainJsonCodec,
 ): ReadableStream<Uint8Array> {
   return new ReadableStream({
     async start(controller) {
-      controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify(forClient)}\n`))
+      controller.enqueue(NDJSON_ENCODER.encode(`${codec.encode(forClient)}\n`))
       await Promise.all(
         deferred.map(async (d) => {
           try {
             const value = await d.promise
-            controller.enqueue(NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, v: value })}\n`))
+            controller.enqueue(NDJSON_ENCODER.encode(`${codec.encode({ i: d.id, v: value })}\n`))
           } catch (err) {
             // Redact: stream a stable opaque code, never the raw error text; log the real reason
             // server-side. The client's <Await> errorFallback receives this code.
             console.error("[nifra/web] deferred value rejected:", err)
             controller.enqueue(
-              NDJSON_ENCODER.encode(`${JSON.stringify({ i: d.id, e: DEFERRED_ERROR_CODE })}\n`),
+              NDJSON_ENCODER.encode(`${codec.encode({ i: d.id, e: DEFERRED_ERROR_CODE })}\n`),
             )
           }
         }),
@@ -259,7 +261,11 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
       return marker
     }
     if (Array.isArray(value)) return value.map(walk)
-    if (value !== null && typeof value === "object") {
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+    ) {
       const out: Record<string, unknown> = {}
       for (const [key, v] of Object.entries(value)) out[key] = walk(v)
       return out
@@ -279,6 +285,7 @@ function markersFromPlaceholders(data: unknown, pending: Pending): unknown {
 export async function parseNdjsonData(
   stream: ReadableStream<Uint8Array>,
   signal?: AbortSignal,
+  codec: TransportCodec = plainJsonCodec,
 ): Promise<unknown> {
   const reader = stream.getReader()
   const dec = new TextDecoder()
@@ -308,7 +315,7 @@ export async function parseNdjsonData(
 
   const pending: Pending = new Map()
   const first = await readLine()
-  const data = markersFromPlaceholders(first === null ? null : JSON.parse(first), pending)
+  const data = markersFromPlaceholders(first === null ? null : codec.decode(first), pending)
 
   void (async () => {
     try {
@@ -316,7 +323,7 @@ export async function parseNdjsonData(
         const line = await readLine()
         if (line === null) break
         if (line === "") continue
-        const msg = JSON.parse(line) as { i: number; v?: unknown; e?: string }
+        const msg = codec.decode(line) as { i: number; v?: unknown; e?: string }
         const entry = pending.get(msg.i)
         if (entry === undefined) continue
         pending.delete(msg.i)

package/src/dev-port.ts

@@ -0,0 +1,63 @@
+/**
+ * `@nifrajs/web/dev-port` — what a dev server says when it cannot bind.
+ *
+ * Both pipelines need this and neither should own it: the Vite server binds through Node's `http`
+ * (asynchronous `error` event), the Bun server binds through `Bun.serve` (synchronous throw). Two very
+ * different failure mechanics, one thing the developer has to be told.
+ *
+ * That message is worth this much care because the visible symptom is not the real one. When the port is
+ * taken, the EARLIER dev server is still answering on it, still serving the build it started with. Every
+ * subsequent edit appears to do nothing. What reaches the developer is "my changes stopped reaching SSR",
+ * which reads as broken HMR or a stale module graph and sends them into the module graph - not to the one
+ * process that never started. Naming the cause here is the entire fix.
+ *
+ * This module deliberately imports nothing: it is shared by a Node-http path and a Bun path, and the
+ * structural `ListenTarget` keeps it free of either runtime's types.
+ */
+
+/** The `EADDRINUSE` explanation. Exported so tests pin the exact text a user will read. */
+export function portInUseMessage(port: number): string {
+  return (
+    `[nifra] dev server can't start: port ${port} is already in use.\n` +
+    `  Most likely an earlier \`nifra dev\` is still running. It keeps serving the PREVIOUS build, so ` +
+    `every edit will look like it stops reaching SSR while the browser shows stale output.\n` +
+    `  Free the port:  lsof -ti:${port} | xargs kill\n` +
+    `  Or use another: nifra dev --port ${port + 1}`
+  )
+}
+
+/** True when an unknown thrown value carries the "address already in use" errno. */
+export const isAddressInUse = (err: unknown): boolean =>
+  (err as { code?: unknown } | null)?.code === "EADDRINUSE"
+
+const asError = (err: unknown): Error => (err instanceof Error ? err : new Error(String(err)))
+
+/** Map a bind failure to the port-collision explanation, leaving every other failure as itself. */
+export const explainBindFailure = (err: unknown, port: number): Error =>
+  isAddressInUse(err) ? new Error(portInUseMessage(port)) : asError(err)
+
+/** The bits of a Node server {@link listenOrExplain} touches — structural, so a test can fake it. */
+export interface ListenTarget {
+  listen(port: number, cb: () => void): void
+  once(event: "error", cb: (err: unknown) => void): void
+  removeListener(event: "error", cb: (err: unknown) => void): void
+}
+
+/**
+ * `listen`, but a bind failure becomes a readable nifra error instead of Node's raw internal throw.
+ *
+ * Without an `error` listener attached, Node throws from deep inside `node:events`, the new process dies
+ * in the background, and nothing connects that death to the stale page in front of you.
+ */
+export function listenOrExplain(server: ListenTarget, port: number): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const onError = (err: unknown): void => reject(explainBindFailure(err, port))
+    server.once("error", onError)
+    server.listen(port, () => {
+      // Drop the guard once we're listening: leaving it attached would funnel a LATER server error into
+      // an already-settled promise, silently swallowing it instead of surfacing it.
+      server.removeListener("error", onError)
+      resolve()
+    })
+  })
+}