@barefootjs/router 0.14.0

package/src/router.ts

@@ -0,0 +1,450 @@
+/**
+ * The router controller: event interception, programmatic navigation, prefetch.
+ *
+ * One router is active at a time (`active`). `startRouter` installs all the
+ * seams itself (correct by default — no opt-in step), delegates events on
+ * `document`/`window`, and returns a `Router` handle. A navigation swaps only
+ * the `[bf-region]` children, disposing the outgoing islands and re-hydrating
+ * the incoming ones, with last-wins semantics across overlapping navigations.
+ */
+
+import { BF_REGION } from '@barefootjs/shared'
+import { loadPage } from './cache.ts'
+import {
+  captureRegionBaselines,
+  collectModuleScripts,
+  collectRegionModuleSrcs,
+  importRegionChildren,
+  isRootRegion,
+  loadNewModules,
+  parseDocument,
+  planRegionSwaps,
+  type RegionSwap,
+} from './region.ts'
+import { buildMorphedContent } from './morph.ts'
+import {
+  defaultDispose,
+  defaultRehydrate,
+  hardNavigate,
+  pushSearchSeam,
+} from './seams.ts'
+import { announceNavigation, focusRegion } from './a11y.ts'
+import type {
+  NavigateOptions,
+  PageSnapshot,
+  Router,
+  RouterOptions,
+  RouterState,
+} from './types.ts'
+
+let active: RouterState | null = null
+
+export function startRouter(options: RouterOptions = {}): Router {
+  // SSR / non-DOM: a no-op handle, never throws.
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    return { stop() {}, navigate: async () => {}, prefetch() {} }
+  }
+
+  // Replacing the active router is idempotent — tear the old one down first.
+  if (active) active.stop()
+
+  const state: RouterState = {
+    regionSelector: options.region ?? `[${BF_REGION}]`,
+    rehydrate: options.rehydrate ?? defaultRehydrate,
+    dispose: options.dispose ?? defaultDispose,
+    loadModule: options.loadModule ?? ((src) => import(src)),
+    // Bind through a wrapper so a default `fetch` keeps its global `this`.
+    fetchFn: options.fetch ?? ((input, init) => fetch(input, init)),
+    // Seed with modules already on the page so we never re-import them. The
+    // live document's srcs resolve against the current location.
+    loadedModules: collectModuleScripts(document, window.location.href),
+    prefetchEnabled: options.prefetch ?? true,
+    prefetchDelay: options.prefetchDelay ?? 65,
+    cacheFreshMs: options.cacheFreshMs ?? 15_000,
+    cacheStaleMs: options.cacheStaleMs ?? 60_000,
+    cacheCap: options.cacheCap ?? 30,
+    cache: new Map(),
+    preloaded: new Set(),
+    shouldIntercept: options.shouldIntercept ?? defaultShouldIntercept,
+    scrollToTop: options.scrollToTop ?? true,
+    manageFocus: options.manageFocus ?? true,
+    morph: options.morph ?? true,
+    // Seed the per-region baselines from the initial document's server render
+    // (captured before islands mutate the DOM). Refreshed after each navigation.
+    regionBaselines: captureRegionBaselines(document, options.region ?? `[${BF_REGION}]`),
+    currentPath: window.location.pathname,
+    inflight: null,
+    hoverTimer: null,
+    hoverAnchor: null,
+    stop: () => {},
+  }
+
+  document.addEventListener('click', onClick)
+  window.addEventListener('popstate', onPopState)
+  if (state.prefetchEnabled) {
+    document.addEventListener('mouseover', onPointerOver)
+    document.addEventListener('mouseout', onPointerOut)
+    document.addEventListener('focusin', onFocusIn)
+    document.addEventListener('pointerdown', onPointerDown)
+  }
+  // Anchor the entry so a later back-navigation lands here, preserving any
+  // existing history.state a framework/scroll lib may have stored.
+  commitHistory('replace', window.location.href)
+
+  state.stop = () => {
+    document.removeEventListener('click', onClick)
+    window.removeEventListener('popstate', onPopState)
+    document.removeEventListener('mouseover', onPointerOver)
+    document.removeEventListener('mouseout', onPointerOut)
+    document.removeEventListener('focusin', onFocusIn)
+    document.removeEventListener('pointerdown', onPointerDown)
+    clearHoverTimer(state)
+    state.inflight?.abort()
+    if (active === state) active = null
+  }
+
+  active = state
+  return { stop: state.stop, navigate, prefetch: (url) => prefetch(url) }
+}
+
+/** Collect nodes into a fragment (the non-morph swap path). */
+function toFragment(nodes: Node[]): DocumentFragment {
+  const frag = document.createDocumentFragment()
+  for (const node of nodes) frag.appendChild(node)
+  return frag
+}
+
+// --- History --------------------------------------------------------------
+
+/**
+ * Commit a history entry while **preserving existing `history.state`**
+ * (spec step 6). `replaceState` overwrites the current entry's state, so we
+ * merge rather than clobber — a scroll-restoration lib or framework state
+ * survives a router-driven replace. A `push` starts a fresh entry (there is no
+ * prior state to keep), tagged so `popstate` can recognise router-owned entries.
+ */
+function commitHistory(mode: 'push' | 'replace', url: string): void {
+  if (mode === 'push') {
+    window.history.pushState({ bfRouter: true }, '', url)
+  } else {
+    const prev = (window.history.state ?? {}) as Record<string, unknown>
+    window.history.replaceState({ ...prev, bfRouter: true }, '', url)
+  }
+}
+
+// --- Click / navigation interception --------------------------------------
+
+function onClick(event: MouseEvent): void {
+  if (!active) return
+  if (event.defaultPrevented) return
+  // Only plain left-clicks — let the browser own modified / middle clicks.
+  if (event.button !== 0) return
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+
+  const target = event.target as Element | null
+  const anchor = target?.closest?.('a') as HTMLAnchorElement | null
+  if (!anchor || !anchor.getAttribute('href')) return
+  if (!active.shouldIntercept(anchor, event)) return
+
+  event.preventDefault()
+  void navigate(anchor.href)
+}
+
+function defaultShouldIntercept(anchor: HTMLAnchorElement): boolean {
+  if (anchor.dataset.bfRouter === 'false') return false
+  if (anchor.hasAttribute('download')) return false
+
+  const linkTarget = anchor.getAttribute('target')
+  if (linkTarget && linkTarget !== '_self') return false
+
+  const rel = anchor.getAttribute('rel') ?? ''
+  if (rel.split(/\s+/).includes('external')) return false
+
+  let url: URL
+  try {
+    url = new URL(anchor.href, window.location.href)
+  } catch {
+    return false
+  }
+  if (url.origin !== window.location.origin) return false
+
+  // Same page, hash-only change → let the browser scroll to the anchor.
+  if (
+    url.pathname === window.location.pathname &&
+    url.search === window.location.search &&
+    url.hash
+  ) {
+    return false
+  }
+
+  return true
+}
+
+function onPopState(): void {
+  if (!active) return
+  // A query-only back/forward on the same route doesn't need a swap: push the
+  // new query into the env signal (if a consumer registered the seam) and let
+  // islands react fine-grained. A pathname change does need a swap, but the
+  // browser already moved history, so don't write it again (`history: false`).
+  if (
+    window.location.pathname === active.currentPath &&
+    pushSearchSeam(window.location.search)
+  ) {
+    return
+  }
+  void navigate(window.location.href, { history: false })
+}
+
+// --- Core navigation ------------------------------------------------------
+
+export async function navigate(url: string, options: NavigateOptions = {}): Promise<void> {
+  // SSR / non-DOM: a no-op. The bare `navigate` export is documented SSR-safe,
+  // but on the server `active` is null and the fall-through to `hardNavigate`
+  // would touch `window` and throw — guard before that.
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  const mode = options.history ?? 'push'
+  const state = active
+  if (!state) {
+    hardNavigate(url)
+    return
+  }
+
+  const target = new URL(url, window.location.href)
+  // Different origin → hand back to the browser.
+  if (target.origin !== window.location.origin) {
+    hardNavigate(url)
+    return
+  }
+
+  // Same-route, query-only change → if a `searchParams()` consumer registered
+  // the seam, update the signal + URL but DON'T swap (islands react fine-
+  // grained). Otherwise fall through to a normal swap (legacy behaviour).
+  if (
+    target.pathname === window.location.pathname &&
+    target.search !== window.location.search &&
+    pushSearchSeam(target.search)
+  ) {
+    state.inflight?.abort()
+    if (mode === 'push') commitHistory('push', target.href)
+    else if (mode === 'replace') commitHistory('replace', target.href)
+    return
+  }
+
+  // Supersede any in-flight navigation. `inflight` doubles as a "still current"
+  // flag: a newer navigation aborts it, and the abort checks after each `await`
+  // let the latest navigation win. The fetch itself isn't cancelled — it still
+  // populates the shared cache.
+  state.inflight?.abort()
+  const controller = new AbortController()
+  state.inflight = controller
+
+  try {
+    const snap = await loadPage(state, target.href)
+    if (controller.signal.aborted) return
+    if (!snap) {
+      hardNavigate(target.href)
+      return
+    }
+    const finalUrl = snap.finalUrl
+
+    // Parse the incoming page once. Module srcs are collected from the whole
+    // document and resolved against the response's final URL (after redirects),
+    // not the current location.
+    const incomingDoc = parseDocument(snap.html)
+    const title = incomingDoc.querySelector('title')?.textContent ?? null
+    const moduleSrcs = [...collectModuleScripts(incomingDoc, finalUrl)]
+
+    // Decide the swap point(s). When the compiler-derived region ids line up
+    // across both documents, swap only the deepest regions whose owned content
+    // differs (nested/sibling, spec v2); otherwise fall back to the single
+    // broadest region (v0).
+    const plan = planRegionSwaps(document, incomingDoc, state.regionSelector, state.regionBaselines)
+    let targets: RegionSwap[]
+    if (plan.mode === 'regions') {
+      targets = plan.targets
+    } else {
+      // Ids diverge or collide. Swap the broadest region only if it is a true
+      // root containing every other region (one swap rebuilds them all — the v0
+      // single-region behaviour). If the regions are siblings, a single swap
+      // would half-update the page, so hard-navigate instead (never worse than
+      // an MPA).
+      const current = document.querySelector(state.regionSelector)
+      const incoming = incomingDoc.querySelector(state.regionSelector)
+      if (!current || !incoming || !isRootRegion(current, state.regionSelector)) {
+        hardNavigate(finalUrl)
+        return
+      }
+      targets = [{ current, incoming }]
+    }
+
+    // Swap every target synchronously, before any `await`. A morph-preserved
+    // node therefore travels current → fragment → current without ever being
+    // detached across the dispose `await`: a navigation that supersedes this
+    // one still finds it under its region (last-wins safe), and an abort/throw
+    // during dispose can't leave it orphaned. Each `outgoing` is a shallow clone
+    // of its region element (tag, attributes, id, classes — e.g.
+    // `main[bf-region]`) so a custom `dispose` sees the same shell it ran
+    // against on first mount, not a bare `<div>`. With no permanent nodes and a
+    // single region this is exactly the v0 `replaceChildren` swap.
+    const swapped: { region: Element; outgoing: Element }[] = []
+    for (const { current, incoming } of targets) {
+      const nodes = importRegionChildren(incoming)
+      const fragment = state.morph ? buildMorphedContent(current, nodes) : toFragment(nodes)
+      const outgoing = current.cloneNode(false) as Element
+      // An explicit drain (rather than `append(...current.childNodes)`) is
+      // unambiguous about not skipping nodes while the live `childNodes` shrinks.
+      while (current.firstChild) outgoing.append(current.firstChild)
+      current.replaceChildren(fragment)
+      swapped.push({ region: current, outgoing })
+    }
+    if (title !== null) document.title = title
+
+    // Refresh the per-region baselines to the server render now displayed: from
+    // the incoming keys (matched regions), else recaptured from the live DOM
+    // (the broadest fallback just inserted fresh server content). Done right
+    // after the synchronous swaps so a superseded navigation that bails below
+    // still leaves baselines consistent with the committed DOM.
+    if (plan.mode === 'regions') {
+      for (const [id, key] of plan.incomingKeys) state.regionBaselines.set(id, key)
+    } else {
+      state.regionBaselines = captureRegionBaselines(document, state.regionSelector)
+    }
+
+    // Dispose the outgoing islands, sequentially in document order. `dispose` is
+    // user-overridable and may do global teardown or assume single-call
+    // ordering, so we never run several in parallel (the region count is small).
+    // Each `outgoing` is already detached and the swaps are committed, so a
+    // superseded navigation just skips the remaining work below — it never has
+    // to undo a DOM mutation. With `morph`, any matched `[data-bf-permanent]`
+    // node was moved into the new tree above, so it isn't here; with
+    // `morph: false` the permanent nodes stay in `outgoing` and are disposed.
+    for (const { outgoing } of swapped) await state.dispose(outgoing)
+    if (controller.signal.aborted) return
+
+    // Register any island modules this response introduced before hydrating.
+    await loadNewModules(state, moduleSrcs)
+    if (controller.signal.aborted) return
+
+    if (mode === 'push') commitHistory('push', finalUrl)
+    else if (mode === 'replace') commitHistory('replace', finalUrl)
+
+    const committed = new URL(finalUrl, window.location.href)
+    state.currentPath = committed.pathname
+    pushSearchSeam(committed.search)
+
+    if (state.scrollToTop) window.scrollTo(0, 0)
+
+    // Re-hydrate the freshly inserted islands (subtree-scoped, per region),
+    // sequentially in document order — like `dispose`, `rehydrate` is
+    // user-overridable and may touch shared global state, so parallel runs are
+    // avoided (the region count is small).
+    for (const { region } of swapped) await state.rehydrate(region)
+    // `rehydrate` may await (a dynamic import); a newer navigation could have
+    // superseded us in the meantime — don't run a11y side effects on what is
+    // now stale content.
+    if (controller.signal.aborted) return
+
+    // Accessibility: move focus into the first swapped region (the broadest /
+    // topmost in document order) and announce the route. A navigation with no
+    // changed region (targets empty) still committed history + title above.
+    if (state.manageFocus && swapped.length > 0) {
+      focusRegion(swapped[0].region)
+      announceNavigation(title)
+    }
+  } finally {
+    if (state.inflight === controller) state.inflight = null
+  }
+}
+
+// --- Prefetch -------------------------------------------------------------
+
+function prefetch(url: string): void {
+  const state = active
+  if (!state) return
+  let target: URL
+  try {
+    target = new URL(url, window.location.href)
+  } catch {
+    return
+  }
+  if (target.origin !== window.location.origin) return
+  if (target.href === window.location.href) return // current page
+
+  void loadPage(state, target.href).then((snap) => {
+    if (snap) preloadModules(state, snap)
+  })
+}
+
+function preloadModules(state: RouterState, snap: PageSnapshot): void {
+  // Parse once and read only the module srcs (no region-node import), resolved
+  // against the fetched page's final URL.
+  const srcs = collectRegionModuleSrcs(snap.html, state.regionSelector, snap.finalUrl) ?? []
+  for (const src of srcs) {
+    if (state.loadedModules.has(src) || state.preloaded.has(src)) continue
+    state.preloaded.add(src)
+    const link = document.createElement('link')
+    link.rel = 'modulepreload'
+    link.href = src
+    document.head.appendChild(link)
+  }
+}
+
+// The dwell timer lives on `RouterState` (per instance), not at module scope —
+// so two routers don't share one timer and tests are isolated without manual
+// global resets.
+function clearHoverTimer(state: RouterState): void {
+  if (state.hoverTimer !== null) {
+    clearTimeout(state.hoverTimer)
+    state.hoverTimer = null
+  }
+  state.hoverAnchor = null
+}
+
+function prefetchableAnchor(event: Event): HTMLAnchorElement | null {
+  const state = active
+  if (!state) return null
+  const anchor = (event.target as Element | null)?.closest?.('a') as HTMLAnchorElement | null
+  if (!anchor || !anchor.getAttribute('href')) return null
+  if (!state.shouldIntercept(anchor, event)) return null
+  return anchor
+}
+
+function onPointerOver(event: MouseEvent): void {
+  const state = active
+  if (!state) return
+  const anchor = prefetchableAnchor(event)
+  if (!anchor) return
+  // `mouseover` bubbles, so moving between descendants of the same link fires it
+  // repeatedly — don't restart the dwell each time we're already on this anchor.
+  if (anchor === state.hoverAnchor) return
+  clearHoverTimer(state)
+  state.hoverAnchor = anchor
+  const href = anchor.href
+  state.hoverTimer = setTimeout(() => {
+    state.hoverTimer = null
+    state.hoverAnchor = null
+    prefetch(href)
+  }, state.prefetchDelay)
+}
+
+function onPointerOut(event: MouseEvent): void {
+  const state = active
+  if (!state || !state.hoverAnchor) return
+  // `mouseout` also bubbles: moving between descendants inside the same `<a>`
+  // fires it even though the pointer is still over the link. Only cancel when
+  // the pointer actually left the dwelled anchor (it moved to a node outside it).
+  const to = event.relatedTarget as Node | null
+  if (to && state.hoverAnchor.contains(to)) return
+  clearHoverTimer(state)
+}
+
+function onFocusIn(event: FocusEvent): void {
+  const anchor = prefetchableAnchor(event)
+  if (anchor) prefetch(anchor.href) // keyboard focus is intentional — no dwell
+}
+
+function onPointerDown(event: MouseEvent): void {
+  if (event.button !== 0) return
+  const anchor = prefetchableAnchor(event)
+  if (anchor) prefetch(anchor.href)
+}

package/src/seams.ts

@@ -0,0 +1,130 @@
+/**
+ * Window bridges to the optional `@barefootjs/client` runtime.
+ *
+ * The router core never statically imports `@barefootjs/client` — that keeps it
+ * an *optional* peer, so a static-shell site ships the router with zero client
+ * runtime. Every coupling lives here, and every coupling is correct by default:
+ * `dispose`/`rehydrate` degrade through the SAME fallback chain ending at
+ * `@barefootjs/client/runtime`, and neither silently no-ops on a page that has
+ * islands (spec/router.md "Seams & correctness" — the #1910 `setupStreaming()`
+ * footgun, where islands leaked unless the dev opted in, is what this avoids).
+ */
+
+import {
+  BF_HOST,
+  BF_SCOPE,
+  BF_SEAM_DISPOSE_WITHIN,
+  BF_SEAM_HYDRATE,
+  BF_SEAM_HYDRATE_WITHIN,
+  BF_SEAM_PUSH_SEARCH,
+} from '@barefootjs/shared'
+
+// Seam-name keys come from `@barefootjs/shared` so this reader and the client
+// installer can never disagree on a property name (a typo would otherwise just
+// fall through to the dynamic-import path and silently change behaviour).
+interface ClientSeams {
+  /** Subtree-scoped re-hydration (O(region)); installed by the client runtime. */
+  [BF_SEAM_HYDRATE_WITHIN]?: (root: Element) => void
+  /** Subtree-scoped disposal; installed by the client runtime. */
+  [BF_SEAM_DISPOSE_WITHIN]?: (root: Element) => void
+  /** Whole-document re-hydration fallback. */
+  [BF_SEAM_HYDRATE]?: () => void
+  /**
+   * Push a new query string into the `searchParams()` env signal
+   * (`@barefootjs/client`, v0.5). The router owns popstate/query-only nav and
+   * pushes through this seam; the client installs it lazily on first
+   * `searchParams()` read, so the client package stays `sideEffects: false`.
+   */
+  [BF_SEAM_PUSH_SEARCH]?: (search: string) => void
+}
+
+/**
+ * Push the committed query string into the env signal, if a `searchParams()`
+ * consumer has registered the seam. Returns whether the seam exists — the
+ * caller uses that boolean to decide query-only-vs-structural navigation.
+ */
+export function pushSearchSeam(search: string): boolean {
+  const w = window as unknown as ClientSeams
+  const push = w[BF_SEAM_PUSH_SEARCH]
+  if (typeof push !== 'function') return false
+  push(search)
+  return true
+}
+
+export async function defaultRehydrate(region: Element): Promise<void> {
+  const w = window as unknown as ClientSeams
+  // Prefer the subtree-scoped walk — O(region), not O(document).
+  const hydrateWithin = w[BF_SEAM_HYDRATE_WITHIN]
+  if (typeof hydrateWithin === 'function') {
+    hydrateWithin(region)
+    return
+  }
+  const hydrateAll = w[BF_SEAM_HYDRATE]
+  if (typeof hydrateAll === 'function') {
+    hydrateAll()
+    return
+  }
+  // Fall back to the runtime's named exports. The specifier is a *variable* so
+  // bundlers can't statically resolve (and thus bundle) the optional peer; the
+  // browser resolves the bare specifier through the page's import map.
+  try {
+    const spec = '@barefootjs/client/runtime'
+    const mod = (await import(spec)) as {
+      rehydrateScope?: (root: Element) => void
+      rehydrateAll?: () => void
+    }
+    if (mod.rehydrateScope) mod.rehydrateScope(region)
+    else mod.rehydrateAll?.()
+  } catch {
+    // A region with hydration markers but no reachable runtime is a real
+    // failure — the swapped content won't be interactive. Surface it rather
+    // than silently no-op (spec/router.md "Neither may silently no-op"). A
+    // static shell (no markers) genuinely has nothing to do, so stays quiet.
+    warnIfIslandsUnreachable(region, 're-hydrate')
+  }
+}
+
+export async function defaultDispose(region: Element): Promise<void> {
+  const w = window as unknown as ClientSeams
+  const disposeWithin = w[BF_SEAM_DISPOSE_WITHIN]
+  if (typeof disposeWithin === 'function') {
+    disposeWithin(region)
+    return
+  }
+  try {
+    const spec = '@barefootjs/client/runtime'
+    const mod = (await import(spec)) as { disposeScope?: (root: Element) => void }
+    mod.disposeScope?.(region)
+  } catch {
+    // Same as re-hydrate: a no-op dispose on a region that has islands leaks
+    // their handlers/effects across the navigation — surface it.
+    warnIfIslandsUnreachable(region, 'dispose')
+  }
+}
+
+/**
+ * Does the region contain BarefootJS hydration markers (`bf-s` scope roots or
+ * `bf-h` child-scope hosts)? If so, the client runtime *should* be on the page,
+ * and failing to reach it is an error worth surfacing — not the silent
+ * "static shell" path.
+ */
+export function regionHasIslands(region: Element): boolean {
+  return (
+    region.hasAttribute(BF_SCOPE) ||
+    region.hasAttribute(BF_HOST) ||
+    region.querySelector(`[${BF_SCOPE}],[${BF_HOST}]`) !== null
+  )
+}
+
+function warnIfIslandsUnreachable(region: Element, op: 'dispose' | 're-hydrate'): void {
+  if (!regionHasIslands(region)) return
+  console.error(
+    `[barefootjs/router] could not load @barefootjs/client/runtime to ${op} a region that contains islands. ` +
+      `The swapped content may leak handlers or not be interactive — ensure the runtime is served and mapped in the page's import map.`,
+  )
+}
+
+/** Full browser navigation — the "never worse than an MPA" floor. */
+export function hardNavigate(url: string): void {
+  window.location.assign(url)
+}