@nifrajs/web 2.1.0 → 2.3.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/chunk-names.ts

@@ -1,6 +1,6 @@
 /**
  * URL-safe output chunk naming. Bun names a code-split chunk after its source file's basename, so a
- * dynamic-route file like `[slug].tsx` emits `[slug]-<hash>.js` — the `[ ]` make a URL a static server
+ * dynamic-route file like `[slug].tsx` emits `[slug]-<hash>.js` - the `[ ]` make a URL a static server
  * (server-bun, CF Pages) reject with 400, so the lazy import fails and the route silently never
  * hydrates (SSR looks perfect; all interactivity is dead). `sanitizeOutputNames` renames every output
  * whose basename isn't URL-path-safe (`[slug]` → `_slug_`) and rewrites the references to it inside the

package/src/client.ts

@@ -1,11 +1,23 @@
 /**
- * `@nifrajs/web/client` — the agnostic browser layer for client-side navigation. It wires the pure
+ * `@nifrajs/web/client` - the agnostic browser layer for client-side navigation. It wires the pure
  * router store ({@link ClientRouter}) to the browser: `pushState` on navigate, `popstate` →
  * navigate, and delegated interception of same-origin `<a>` clicks (client transition instead of
- * a full page load). DOM-only — never imported on the server, so the store stays SSR-safe.
+ * a full page load). DOM-only - never imported on the server, so the store stays SSR-safe.
  */
+import { trustedHeadAttributes } from "./internal/head-attributes.ts"
+import { EXECUTABLE_SCRIPT_TYPES, INERT_SCRIPT_TYPES } from "./internal/script-types.ts"
 import type { Meta } from "./manifest.ts"
-import { type BrowserNavigate, setBrowserNavigate } from "./navigation.ts"
+import {
+  type Blocker,
+  type BlockerController,
+  type BlockerFunction,
+  type BlockerLocation,
+  type BlockerState,
+  type BrowserNavigate,
+  IDLE_BLOCKER,
+  setBlockerController,
+  setBrowserNavigate,
+} from "./navigation.ts"
 import type { ClientRouter } from "./router.ts"
 
 export interface InstallHistoryOptions {
@@ -31,6 +43,22 @@ export function installHistory(
   // fragment target (`#id`) to scroll to once the cross-page navigation's content renders.
   type PendingScroll = { readonly pos: readonly [number, number] } | { readonly hash: string }
   let pendingScroll: PendingScroll | null = null
+
+  // Navigation-guard state (useBlocker). `index` is our position in the history line, stored in
+  // `history.state.nifraIndex`; it exists solely to reverse a blocked back/forward (a popstate can't be
+  // cancelled, so we read the delta from the index and `history.go(-delta)` back). `here` is the location
+  // we're currently on - after a popstate `location` is already the destination, so "where we were" has
+  // to be tracked, not read. `reversing` swallows the popstate our own restoring `history.go` fires.
+  let index = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
+  let here = location.pathname + location.search + (location.hash ?? "")
+  let reversing = false
+  type Registration = {
+    readonly shouldBlock: BlockerFunction
+    readonly emit: (blocker: Blocker) => void
+    state: BlockerState
+  }
+  // A single active guard (like react-router, one blocker at a time); the latest registration wins.
+  let registration: Registration | undefined
   const scrollOf = (state: unknown): [number, number] => {
     const saved = (state as { nifraScroll?: [number, number] } | null)?.nifraScroll
     return Array.isArray(saved) ? saved : [0, 0]
@@ -50,7 +78,7 @@ export function installHistory(
     return document.getElementById(id)
   }
 
-  // Wrap a navigation's render in a View Transition when the browser supports it — a graceful
+  // Wrap a navigation's render in a View Transition when the browser supports it - a graceful
   // enhancement (no-op elsewhere). The captured "before" is held across the data fetch, so pair
   // with link prefetch (hover/focus warms the cache) to keep most transitions instant.
   type ViewTransition = {
@@ -69,35 +97,112 @@ export function installHistory(
     }
     const vt = doc.startViewTransition(run)
     // Rapid in-app clicks supersede an in-flight transition; the browser skips it and rejects its
-    // promises. Reasons vary by engine — InvalidStateError "Transition was aborted because of
+    // promises. Reasons vary by engine - InvalidStateError "Transition was aborted because of
     // invalid state", or AbortError "Transition was skipped". The navigation still completes, so
     // we swallow these expected aborts rather than let them surface as unhandled rejections.
     for (const p of [vt.ready, vt.finished, vt.updateCallbackDone]) p.catch(() => {})
   }
 
-  const go = (path: string, mode: "push" | "replace"): void => {
+  // Parse a path into the `{ pathname, search, hash }` a `BlockerFunction` decides on.
+  const locationOf = (path: string): BlockerLocation => {
     const url = new URL(path, location.origin)
+    return { pathname: url.pathname, search: url.search, hash: url.hash }
+  }
+
+  // The single funnel every navigation asks before it commits. Returns true (navigation held) when a
+  // guard is armed and blocks; false when it may proceed. `retry` performs the navigation and is what
+  // `proceed` replays. While a prompt is already open (`blocked`) further navigations are swallowed; the
+  // replay from `proceed` (`proceeding`) is let straight through.
+  const guard = (nextPath: string, retry: () => void): boolean => {
+    const reg = registration
+    if (reg === undefined || reg.state === "proceeding") return false
+    if (reg.state === "blocked") return true
+    if (!reg.shouldBlock({ currentLocation: locationOf(here), nextLocation: locationOf(nextPath) }))
+      return false
+    reg.state = "blocked"
+    reg.emit({
+      state: "blocked",
+      proceed: () => {
+        if (reg.state !== "blocked") return
+        reg.state = "proceeding"
+        reg.emit({ state: "proceeding", proceed: undefined, reset: undefined })
+        retry()
+      },
+      reset: () => {
+        if (reg.state !== "blocked") return
+        reg.state = "unblocked"
+        reg.emit(IDLE_BLOCKER)
+      },
+    })
+    return true
+  }
+
+  // Once a proceeded navigation has committed, return the guard to idle so it can block the next one.
+  const settle = (): void => {
+    const reg = registration
+    if (reg !== undefined && reg.state === "proceeding") {
+      reg.state = "unblocked"
+      reg.emit(IDLE_BLOCKER)
+    }
+  }
+
+  // Commit a navigation only after its URL and origin are known-safe. An unmatched same-origin path
+  // becomes a hard load BEFORE history is mutated; otherwise the address bar could change while the
+  // router intentionally kept rendering the old route.
+  const parseNavigationUrl = (path: string): URL | null => {
+    try {
+      const url = new URL(path, location.origin)
+      if (url.protocol !== "http:" && url.protocol !== "https:") return null
+      if (url.origin !== location.origin) return null
+      return url
+    } catch {
+      return null
+    }
+  }
+
+  const commit = (path: string, url: URL, mode: "push" | "replace"): void => {
+    const routePath = url.pathname + url.search
+    if (router.match(routePath) === null) {
+      settle()
+      fallback(path)
+      return
+    }
     if (mode === "replace") {
-      // Replace the current entry with the new URL. The entry we're leaving is discarded, so its scroll
-      // isn't worth saving; the new route scrolls to its fragment target, else the top.
-      history.replaceState({}, "", path)
+      // Replace the current entry (same index) with the new URL. The entry we're leaving is discarded, so
+      // its scroll isn't worth saving; the new route scrolls to its fragment target, else the top.
+      history.replaceState({ nifraIndex: index }, "", path)
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     } else {
-      // Save the leaving entry's scroll, push a fresh entry (URL incl. any #hash), then scroll the new
-      // route: to the fragment target if one was given, else to the top.
+      // Save the leaving entry's scroll (spread keeps its nifraIndex), push a fresh higher-indexed entry
+      // (URL incl. any #hash), then scroll the new route: to the fragment target if given, else the top.
       history.replaceState({ ...(history.state ?? {}), nifraScroll: [scrollX, scrollY] }, "")
-      history.pushState({}, "", path)
+      index += 1
+      history.pushState({ nifraIndex: index }, "", path)
       pendingScroll = url.hash !== "" ? { hash: hashId(url.hash) } : { pos: [0, 0] }
     }
+    here = url.pathname + url.search + url.hash
     // The data layer fetches by path+search; the #hash is client-only (never sent to the server).
-    transition(() => router.navigate(url.pathname + url.search).catch(() => fallback(path)))
+    transition(() => router.navigate(routePath).catch(() => fallback(path)))
+    settle()
+  }
+
+  const go = (path: string, mode: "push" | "replace"): void => {
+    // Validate before the blocker observes the target. A blocker receives parsed locations, so letting a
+    // malformed string reach `locationOf` would make an otherwise no-throw navigate unexpectedly throw.
+    const url = parseNavigationUrl(path)
+    if (url === null) {
+      settle()
+      return
+    }
+    if (guard(path, () => commit(path, url, mode))) return
+    commit(path, url, mode)
   }
 
   // Programmatic navigation for adapter `useNavigate` bindings, published through the DOM-free bridge
   // (`@nifrajs/web`'s `getBrowserNavigate`). A string path pushes (or replaces); a number is a history
-  // delta (`-1` back / `1` forward), matching `history.go`. An off-route / cross-origin push still goes
-  // through `go`, whose `router.navigate` no-ops an unmatched path and whose fetch-failure falls back to
-  // a full load — same graceful degradation as a link click.
+  // delta (`-1` back / `1` forward), matching `history.go`. Off-route same-origin destinations hard-load
+  // without first creating a stale in-document history entry. Cross-origin and active-scheme strings are
+  // rejected; callers that intentionally leave the app use a normal `<a>`.
   const navigate: BrowserNavigate = (to, navOptions) => {
     if (typeof to === "number") {
       history.go(to)
@@ -107,6 +212,20 @@ export function installHistory(
   }
   setBrowserNavigate(navigate)
 
+  // Publish the guard registry through the DOM-free bridge (`@nifrajs/web`'s `registerBlocker`, which an
+  // adapter's `useBlocker` calls). One slot, latest registration wins; the unregister clears it only if
+  // it's still the current one (so a stale unmount doesn't wipe a newer guard).
+  const controller: BlockerController = {
+    register(shouldBlock, onChange) {
+      const reg: Registration = { shouldBlock, emit: onChange, state: "unblocked" }
+      registration = reg
+      return () => {
+        if (registration === reg) registration = undefined
+      }
+    },
+  }
+  setBlockerController(controller)
+
   // Resolve an event target to an in-app route path, or null (cross-origin, unknown route, or an
   // anchor opting out via target/download/rel=external). Shared by click + hover/focus prefetch.
   const inAppHref = (target: EventTarget | null): string | null => {
@@ -118,9 +237,9 @@ export function installHistory(
     const url = new URL(anchor.href)
     if (url.origin !== location.origin) return null
     if (router.match(url.pathname) === null) return null
-    // A same-page fragment link (`#section`, `/here#section` — only the hash differs) → null: let the
+    // A same-page fragment link (`#section`, `/here#section` - only the hash differs) → null: let the
     // browser do its native in-page anchor jump. Intercepting it would drop the fragment from the URL
-    // and force a scroll-to-top (a fresh push restores [0,0]) — i.e. break every in-page anchor (AUDIT
+    // and force a scroll-to-top (a fresh push restores [0,0]) - i.e. break every in-page anchor (AUDIT
     // H2). (A same-page link with NO hash still soft-navigates, as before.)
     if (url.pathname === location.pathname && url.search === location.search && url.hash !== "")
       return null
@@ -146,12 +265,49 @@ export function installHistory(
     void router.prefetch(url.pathname + url.search) // warm by path+search; the #hash isn't data
   }
 
-  // Back/forward: the entry exists (no push); restore its saved scroll after it renders.
+  // Back/forward: the entry already exists (no push). The URL has ALSO already changed - a popstate can't
+  // be cancelled - so a guard here can only restore-then-prompt: read the delta from our index, and if the
+  // guard holds, `history.go(-delta)` back to where we were (ignoring the popstate that reversal fires via
+  // `reversing`) while `proceed` re-issues `history.go(delta)` to redo the move. Unguarded, it's the old
+  // path: restore the entry's saved scroll after it renders.
   const onPopState = (): void => {
+    if (reversing) {
+      reversing = false
+      return
+    }
+    const newIndex = (history.state as { nifraIndex?: number } | null)?.nifraIndex ?? 0
+    const dest = location.pathname + location.search + (location.hash ?? "")
+    const delta = newIndex - index
+    if (guard(dest, () => history.go(delta))) {
+      reversing = true
+      history.go(-delta)
+      return
+    }
+    index = newIndex
+    here = dest
     pendingScroll = { pos: scrollOf(history.state) }
     transition(() =>
       router.navigate(location.pathname + location.search).catch(() => fallback(location.pathname)),
     )
+    settle()
+  }
+
+  // Close / reload / hard navigation away: no in-app destination exists, so consult the guard with the
+  // current location as both sides. A dirtiness guard (a boolean, or one that checks its own state) then
+  // triggers the browser's native "Leave site?" prompt; a purely destination-based guard won't. Browsers
+  // ignore any custom message - the string is set only because legacy engines require `returnValue`.
+  const onBeforeUnload = (event: BeforeUnloadEvent): void => {
+    const reg = registration
+    if (reg === undefined || reg.state === "proceeding") return
+    // `blocked` already proves the guard found unsaved state. Re-check only while idle; suppressing the
+    // native prompt merely because an in-app confirmation is open creates a close/reload data-loss gap.
+    if (
+      reg.state === "unblocked" &&
+      !reg.shouldBlock({ currentLocation: locationOf(here), nextLocation: locationOf(here) })
+    )
+      return
+    event.preventDefault()
+    event.returnValue = ""
   }
 
   // After a navigation settles (content rendered), apply the pending scroll target on the next frame:
@@ -177,37 +333,49 @@ export function installHistory(
   document.addEventListener("pointerover", onPrefetch)
   document.addEventListener("focusin", onPrefetch)
   window.addEventListener("popstate", onPopState)
+  window.addEventListener("beforeunload", onBeforeUnload)
   return () => {
     unsubscribe()
     setBrowserNavigate(undefined) // stop routing `useNavigate` to a torn-down router
+    setBlockerController(undefined) // stop routing `useBlocker` to a torn-down registry
     document.removeEventListener("click", onClick)
     document.removeEventListener("pointerover", onPrefetch)
     document.removeEventListener("focusin", onPrefetch)
     window.removeEventListener("popstate", onPopState)
+    window.removeEventListener("beforeunload", onBeforeUnload)
   }
 }
 
 /**
  * Intercept submissions of same-origin `<form method="post">` whose action targets an app route:
- * submit via the router (no full reload — POST the action, then revalidate the active loader). On
+ * submit via the router (no full reload - POST the action, then revalidate the active loader). On
  * failure it falls back to a native submit, so the form still works. Returns a teardown function.
  */
 /**
  * Sync the document head to a route's resolved {@link Meta} on client navigation. Sets the title
- * (when provided) and replaces the **managed** (`data-nifra`) `<meta>`/`<link>` tags — static head
+ * (when provided) and replaces the **managed** (`data-nifra`) `<meta>`/`<link>` tags - static head
  * content (charset, hand-written tags) is never touched. SSR injects the same `data-nifra` tags, so
  * the first navigation cleanly takes over from the server-rendered head.
  */
 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
+  // `true` sets the bare boolean attribute, `false`/`undefined` skip it - so a soft-nav head matches
   // the server-rendered one exactly (no hydration drift on the managed tags).
-  const add = (tag: "meta" | "link", attrs: Record<string, string | boolean | undefined>): void => {
+  const add = (tag: "meta" | "link", attrs: Readonly<object>): void => {
+    const trusted = trustedHeadAttributes(tag, attrs)
+    if (trusted === null) return
     const el = document.createElement(tag)
-    for (const [name, value] of Object.entries(attrs)) {
-      if (value === undefined || value === false) continue
+    for (const [name, value] of trusted) {
       el.setAttribute(name, value === true ? "" : value)
     }
     el.setAttribute("data-nifra", "")
@@ -215,13 +383,36 @@ export function applyHead(head: Meta): void {
   }
   for (const m of head.meta ?? []) add("meta", m)
   for (const l of head.link ?? []) add("link", l)
-  // `<script>` slot (JSON-LD etc.) — soft-nav parity with the SSR `headTags` script render. Set the body
+  // `<script>` slot (JSON-LD etc.) - soft-nav parity with the SSR `headTags` script render. Set the body
   // via `textContent`, NOT `innerHTML`: `textContent` assigns the raw string without HTML re-parsing, so
-  // a `</script>` (or `<!--`/`]]>`) payload in the JSON-LD can't break out — the DOM-native equivalent of
+  // a `</script>` (or `<!--`/`]]>`) payload in the JSON-LD can't break out - the DOM-native equivalent of
   // the server's `escapeScriptContent`. `type` defaults to `application/ld+json` (matching the SSR side).
   for (const s of head.script ?? []) {
+    const type = s.type ?? "application/ld+json"
+    if (!INERT_SCRIPT_TYPES.has(type)) {
+      throw new TypeError("[nifra/web] refusing executable content in the inert head.script slot")
+    }
+    const el = document.createElement("script")
+    el.setAttribute("type", type)
+    el.textContent = s.content
+    el.setAttribute("data-nifra", "")
+    document.head.appendChild(el)
+  }
+  for (const s of head.unsafeScript ?? []) {
+    if (s.unsafe !== true || s.nonce.trim() === "") {
+      throw new TypeError("[nifra/web] executable inline scripts require a non-empty CSP nonce")
+    }
+    // Same allowlist the server applies. `setAttribute` cannot be broken out of the way the server's
+    // template literal could, so this is not about injection here - it is about the two halves
+    // accepting the same documents, so a head that renders cannot fail on the next soft-nav.
+    if (!EXECUTABLE_SCRIPT_TYPES.has(s.type)) {
+      throw new TypeError(
+        `[nifra/web] unsupported executable script type ${JSON.stringify(s.type)}`,
+      )
+    }
     const el = document.createElement("script")
-    el.setAttribute("type", s.type ?? "application/ld+json")
+    el.setAttribute("type", s.type)
+    el.setAttribute("nonce", s.nonce)
     el.textContent = s.content
     el.setAttribute("data-nifra", "")
     document.head.appendChild(el)
@@ -242,7 +433,7 @@ export function installForms(router: ClientRouter): () => void {
     // actionData drives the update); absent or any other value keeps the default revalidation.
     const revalidate = form.dataset.nifraRevalidate !== "false"
     router.submit(url.pathname + url.search, new FormData(form), { revalidate }).catch(() => {
-      form.submit() // data submit failed — fall back to a full-page POST
+      form.submit() // data submit failed - fall back to a full-page POST
     })
   }
   document.addEventListener("submit", onSubmit)
@@ -254,7 +445,7 @@ export function installForms(router: ClientRouter): () => void {
  * and fires a one-shot `nifra:hydrated` event. The generated client entry calls this on the next frame
  * after the adapter mounts (so every framework binding gets it), letting apps gate a custom JS-only
  * interaction that would otherwise fire before its handler is attached. Idempotent. nifra's own
- * progressive-enhancement forms/links don't need it — only hand-wired onClick/onSubmit handlers with no
+ * progressive-enhancement forms/links don't need it - only hand-wired onClick/onSubmit handlers with no
  * native fallback do. See the Hydration guide.
  */
 export function signalHydrated(): void {

package/src/conformance.ts

@@ -93,8 +93,8 @@ const readHtml = async (
  * and hydration-head output is a stable string. It rejects with
  * {@link RenderAdapterConformanceError} naming the first failed check.
  *
- * Framework semantics outside the interface—Suspense scheduling, compiler plugins, DOM hydration,
- * error boundaries, and framework-specific primitives—remain the adapter package's local tests.
+ * Framework semantics outside the interface-Suspense scheduling, compiler plugins, DOM hydration,
+ * error boundaries, and framework-specific primitives-remain the adapter package's local tests.
  */
 export async function assertRenderAdapterConformance(
   adapter: RenderAdapter,
@@ -135,7 +135,7 @@ export async function assertRenderAdapterConformance(
     if (typeof buffered !== "string") fail("buffered render", "renderToString must return a string")
     const bufferedHtml = buffered as string
     if (fixture.deferred) {
-      // Deferred content differs between streaming and buffered renders — only require every marker.
+      // Deferred content differs between streaming and buffered renders - only require every marker.
       for (const marker of [
         markers.outer,
         markers.inner,