npm - @barefootjs/router - Versions diffs - 0.28.0 → 0.29.0 - Mend

@barefootjs/router 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -57,12 +57,75 @@ setup step.
   existing state (scroll-restoration libs, framework state).
 - **A11y**: focus moves into the swapped region (its first heading) and the new
   title is announced via a polite live region.
+- **Head metadata**: title, description, `og:`/`twitter:`, canonical and friends
+  are reconciled against the incoming page; head *resources* are not (see below).
 - **Persistence** (`data-bf-permanent`): an element marked
   `<div data-bf-permanent="player">` keeps its *live* node across a swap — its
   state, media playback, scroll, and hydrated scope survive — matched between
   documents by the attribute value (or `id`). A no-op when no element is marked;
   pass `morph: false` for a plain swap.
+## `<head>`: metadata is reconciled, resources are not
+A region is a **body** subtree, so `<head>` is not swapped wholesale. It splits
+in two, and the split is the whole contract.
+### Page metadata — reconciled on every swap, always
+Page metadata is page-scoped by definition, so the router brings a closed
+allowlist of it in line with the incoming document. This always runs and there
+is no flag to disable it: a stale `<meta name="description">` is wrongness you
+*cannot see* in development (unlike the tab title), and this package doesn't
+leave that class opt-in.
+| head node | key |
+| --- | --- |
+| `<title>` | — |
+| `<meta name="description \| keywords \| robots \| author \| theme-color">` | `name` |
+| `<meta property="og:*">` / `<meta name="twitter:*">` | `name` or `property` |
+| `<link rel="canonical \| alternate \| prev \| next">` | `rel` + `hreflang`/`type`/`media` |
+A key in both documents is replaced (skipped when the nodes are already equal,
+so metadata shared across routes causes no DOM churn); a key only in the
+incoming page is added; a key only in the live page is **removed**, so it can't
+leak forward into every later route.
+Anything whose key isn't in that table is never read, replaced, or removed —
+runtime-injected analytics tags, CSP `<meta http-equiv>`, `<link rel=preconnect>`
+and friends are safe by construction. (This is the deliberate difference from
+Turbo, which removes every untracked head element.) Opt a node out with
+`data-bf-head="false"` when the page itself owns it.
+### Head resources — untouched
+`<link rel="stylesheet">`, `<script>`, and `<style>` in `<head>` are left alone
+in both directions. Not an oversight: a resource's lifetime isn't derivable from
+the incoming document. The shell, a `[data-bf-permanent]` node, a portal, or an
+island that outlives the region may still depend on a sheet the next page's head
+doesn't list, so "absent downstream" is no evidence of "no longer needed".
+That makes a **route-scoped stylesheet in `<head>`** the one real trap:
+navigating *into* the route renders it unstyled (a reload "fixes" it, which
+points the investigation at caching or the build instead of at navigation), and
+navigating *out* leaves the sheet linked, so its rules then apply to every route
+after it.
+Put it **inside** the region, where it enters and leaves with the swap:
+```tsx
+<Region>
+  {isEditor ? <link rel="stylesheet" href="/editor.css" /> : null}
+  {children}
+</Region>
+```
+`rel="stylesheet"` is body-ok per HTML, so this is valid — and it is the right
+placement under a region-swap contract, not a workaround. It gets both orderings
+right *by construction* (the sheet is inserted with the content it styles and
+removed with it), with no load awaited in the navigation path. Sheets that are
+genuinely global stay in `<head>`, where never touching them is exactly what you
+want.
 ## Scope
 A **single authored region** (the broadest `[bf-region]` match), correct by

package/dist/head.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+/**
+ * `<head>` metadata reconciliation across a soft navigation (#2438).
+ *
+ * A region is a **body** subtree, so a swap leaves `<head>` alone — and for
+ * *resources* (`<link rel="stylesheet">`, `<script>`, `<style>`) that is the
+ * contract, not a gap: a resource's lifetime depends on what still needs it
+ * (the shell, a `[data-bf-permanent]` node, a portal, an island that outlives
+ * the region), which the incoming document is no evidence for. Turbo reaches
+ * the same conclusion from the other side — it never removes a stylesheet
+ * unless the author writes `data-turbo-track="dynamic"`. Route-scoped sheets
+ * belong *inside* the region, where both orderings are right by construction.
+ *
+ * **Page metadata is the opposite case.** It is page-scoped by definition,
+ * costs no load, has no layout effect or ordering hazard, and is idempotent —
+ * and a stale `<meta name="description">` is *invisible* wrongness: unlike the
+ * tab title you cannot see it in development. That is the class this package
+ * refuses to leave opt-in (spec/router.md, "correct by default"), so it is
+ * reconciled on every swap, always — there is no flag to disable it.
+ *
+ * The reconciled set is a **closed allowlist**, which is the deliberate
+ * difference from Turbo's `provisionalElements` (everything untracked, so
+ * runtime-injected analytics/CSP nodes get caught in the sweep). Here anything
+ * whose key isn't listed below is never read, never replaced, and never
+ * removed.
+ */
+/**
+ * Bring the live `<head>`'s allowlisted metadata in line with `incomingDoc`.
+ *
+ * - key in both → replace in place (skipped when the nodes are already equal,
+ *   so metadata shared across routes causes no DOM churn)
+ * - key only incoming → appended
+ * - key only current → removed, so it can't leak forward into every later route
+ *   the way an unmanaged `<link rel="stylesheet">` does
+ *
+ * Duplicates under one key are collapsed to the incoming node — a page with two
+ * `<meta name="description">` is malformed, and leaving the extra behind would
+ * defeat the reconciliation.
+ *
+ * `<title>` is **not** handled here: the router writes it alongside this call
+ * because the route announcement (`announceNavigation`) needs the same string.
+ *
+ * Ordering-free — no load, no layout effect — so the caller may run it at any
+ * point around the swap.
+ */
+export declare function reconcileHead(incomingDoc: Document): void;
+//# sourceMappingURL=head.d.ts.map

package/dist/head.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"head.d.ts","sourceRoot":"","sources":["../src/head.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA4EH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAyBzD"}

package/dist/index.js CHANGED Viewed

@@ -60,6 +60,83 @@ function loadPage(state, url) {
   return snap;
 }
+// src/head.ts
+var META_NAMES = new Set(["description", "keywords", "robots", "author", "theme-color"]);
+var META_PREFIXES = ["og:", "twitter:"];
+var LINK_RELS = new Set(["canonical", "alternate", "prev", "next"]);
+function norm(value) {
+  return (value ?? "").trim().toLowerCase();
+}
+function optedOut(el) {
+  return el.getAttribute("data-bf-head") === "false";
+}
+function headKey(el) {
+  if (optedOut(el))
+    return null;
+  const tag = el.tagName.toLowerCase();
+  if (tag === "meta") {
+    const id = norm(el.getAttribute("name") ?? el.getAttribute("property"));
+    if (!id)
+      return null;
+    if (!META_NAMES.has(id) && !META_PREFIXES.some((p) => id.startsWith(p)))
+      return null;
+    return `meta:${id}`;
+  }
+  if (tag === "link") {
+    const rel = norm(el.getAttribute("rel"));
+    if (!LINK_RELS.has(rel))
+      return null;
+    const hreflang = norm(el.getAttribute("hreflang"));
+    const type = norm(el.getAttribute("type"));
+    const media = norm(el.getAttribute("media"));
+    return `link:${rel}|${hreflang}|${type}|${media}`;
+  }
+  return null;
+}
+function indexHead(head) {
+  const byKey = new Map;
+  for (const el of head.querySelectorAll("meta, link")) {
+    const key = headKey(el);
+    if (!key)
+      continue;
+    const bucket = byKey.get(key);
+    if (bucket)
+      bucket.push(el);
+    else
+      byKey.set(key, [el]);
+  }
+  return byKey;
+}
+function reconcileHead(incomingDoc) {
+  const head = document.head;
+  const incomingHead = incomingDoc.head;
+  if (!head || !incomingHead)
+    return;
+  const current = indexHead(head);
+  const incoming = indexHead(incomingHead);
+  if (current.size === 0 && incoming.size === 0)
+    return;
+  for (const [key, nodes] of incoming) {
+    const live = current.get(key);
+    const replacement = document.importNode(nodes[0], true);
+    if (!live) {
+      head.append(replacement);
+      continue;
+    }
+    const [first, ...duplicates] = live;
+    if (!first.isEqualNode(replacement))
+      first.replaceWith(replacement);
+    for (const dup of duplicates)
+      dup.remove();
+  }
+  for (const [key, nodes] of current) {
+    if (incoming.has(key))
+      continue;
+    for (const node of nodes)
+      node.remove();
+  }
+}
 // src/region.ts
 import { BF_HOST, BF_PROPS, BF_REGION, BF_SCOPE, BF_SCOPE_COMMENT_PREFIX, BF_SCOPE_COMMENT_END_PREFIX } from "@barefootjs/shared";
 function parseDocument(html) {
@@ -524,6 +601,7 @@ async function navigate(url, options = {}) {
     }
     if (title !== null)
       document.title = title;
+    reconcileHead(incomingDoc);
     if (plan.mode === "regions") {
       for (const [id, key] of plan.incomingKeys)
         state.regionBaselines.set(id, key);

package/dist/router.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;~~AAuBH~~,OAAO,KAAK,EACV,eAAe,EAEf,MAAM,EACN,aAAa,EAEd,MAAM,YAAY,CAAA;AAInB,wBAAgB,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAkE/D;AA4FD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,~~CA6JxF~~"}
1	+ {"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,OAAO,KAAK,EACV,eAAe,EAEf,MAAM,EACN,aAAa,EAEd,MAAM,YAAY,CAAA;AAInB,wBAAgB,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAkE/D;AA4FD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsKxF"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/router",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Backend-agnostic partial-navigation client router for BarefootJS — swaps only the page region and re-hydrates the islands inside it",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
     "directory": "packages/router"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.28.0"
+    "@barefootjs/shared": "0.29.0"
   },
   "peerDependencies": {
     "@barefootjs/client": ">=0.14.0"
@@ -51,7 +51,7 @@
     }
   },
   "devDependencies": {
-    "@barefootjs/client": "^0.28.0",
+    "@barefootjs/client": "^0.29.0",
     "@happy-dom/global-registrator": "^20.0.11",
     "typescript": "^5.0.0"
   }

package/src/head.ts ADDED Viewed

@@ -0,0 +1,145 @@
+/**
+ * `<head>` metadata reconciliation across a soft navigation (#2438).
+ *
+ * A region is a **body** subtree, so a swap leaves `<head>` alone — and for
+ * *resources* (`<link rel="stylesheet">`, `<script>`, `<style>`) that is the
+ * contract, not a gap: a resource's lifetime depends on what still needs it
+ * (the shell, a `[data-bf-permanent]` node, a portal, an island that outlives
+ * the region), which the incoming document is no evidence for. Turbo reaches
+ * the same conclusion from the other side — it never removes a stylesheet
+ * unless the author writes `data-turbo-track="dynamic"`. Route-scoped sheets
+ * belong *inside* the region, where both orderings are right by construction.
+ *
+ * **Page metadata is the opposite case.** It is page-scoped by definition,
+ * costs no load, has no layout effect or ordering hazard, and is idempotent —
+ * and a stale `<meta name="description">` is *invisible* wrongness: unlike the
+ * tab title you cannot see it in development. That is the class this package
+ * refuses to leave opt-in (spec/router.md, "correct by default"), so it is
+ * reconciled on every swap, always — there is no flag to disable it.
+ *
+ * The reconciled set is a **closed allowlist**, which is the deliberate
+ * difference from Turbo's `provisionalElements` (everything untracked, so
+ * runtime-injected analytics/CSP nodes get caught in the sweep). Here anything
+ * whose key isn't listed below is never read, never replaced, and never
+ * removed.
+ */
+/** `<meta name>` / `<meta property>` values reconciled by exact match. */
+const META_NAMES = new Set(['description', 'keywords', 'robots', 'author', 'theme-color'])
+/** …and by prefix, for the two social-card namespaces. */
+const META_PREFIXES = ['og:', 'twitter:']
+/**
+ * `<link rel>` values reconciled. Matched against the **whole** `rel`, not its
+ * tokens, so a multi-token `rel="alternate stylesheet"` — a resource, with a
+ * resource's unknowable lifetime — falls outside the allowlist by construction.
+ */
+const LINK_RELS = new Set(['canonical', 'alternate', 'prev', 'next'])
+/**
+ * Fold an attribute to its comparable form. Every attribute in a key is
+ * case-insensitive, and incidental whitespace (`hreflang=" en-US "`) must not
+ * split one logical slot into two — a split key would append a duplicate on
+ * every navigation instead of replacing the node.
+ */
+function norm(value: string | null): string {
+  return (value ?? '').trim().toLowerCase()
+}
+/** Opt-out for a node the page itself owns: `<meta name="robots" data-bf-head="false">`. */
+function optedOut(el: Element): boolean {
+  return el.getAttribute('data-bf-head') === 'false'
+}
+/**
+ * The identity a node is matched by across the two documents, or `null` when it
+ * is outside the allowlist (i.e. not ours to touch).
+ *
+ * `name` and `property` collapse into one key space on purpose: a page that
+ * writes `<meta property="og:title">` where the previous one wrote
+ * `<meta name="og:title">` still means the same slot.
+ */
+function headKey(el: Element): string | null {
+  if (optedOut(el)) return null
+  const tag = el.tagName.toLowerCase()
+  if (tag === 'meta') {
+    const id = norm(el.getAttribute('name') ?? el.getAttribute('property'))
+    if (!id) return null
+    if (!META_NAMES.has(id) && !META_PREFIXES.some((p) => id.startsWith(p))) return null
+    return `meta:${id}`
+  }
+  if (tag === 'link') {
+    const rel = norm(el.getAttribute('rel'))
+    if (!LINK_RELS.has(rel)) return null
+    // `alternate` is repeatable — a locale, a feed, a print sheet are distinct
+    // slots, so the discriminating attributes are part of the key. All three
+    // are case-insensitive (BCP 47 tags, MIME types, media queries), so they
+    // are normalized: `hreflang="en-US"` and `en-us` are one slot, not two
+    // that would accumulate a duplicate on every navigation.
+    const hreflang = norm(el.getAttribute('hreflang'))
+    const type = norm(el.getAttribute('type'))
+    const media = norm(el.getAttribute('media'))
+    return `link:${rel}|${hreflang}|${type}|${media}`
+  }
+  return null
+}
+/** Index a head's allowlisted nodes by key, keeping duplicates in document order. */
+function indexHead(head: Element): Map<string, Element[]> {
+  const byKey = new Map<string, Element[]>()
+  for (const el of head.querySelectorAll('meta, link')) {
+    const key = headKey(el)
+    if (!key) continue
+    const bucket = byKey.get(key)
+    if (bucket) bucket.push(el)
+    else byKey.set(key, [el])
+  }
+  return byKey
+}
+/**
+ * Bring the live `<head>`'s allowlisted metadata in line with `incomingDoc`.
+ *
+ * - key in both → replace in place (skipped when the nodes are already equal,
+ *   so metadata shared across routes causes no DOM churn)
+ * - key only incoming → appended
+ * - key only current → removed, so it can't leak forward into every later route
+ *   the way an unmanaged `<link rel="stylesheet">` does
+ *
+ * Duplicates under one key are collapsed to the incoming node — a page with two
+ * `<meta name="description">` is malformed, and leaving the extra behind would
+ * defeat the reconciliation.
+ *
+ * `<title>` is **not** handled here: the router writes it alongside this call
+ * because the route announcement (`announceNavigation`) needs the same string.
+ *
+ * Ordering-free — no load, no layout effect — so the caller may run it at any
+ * point around the swap.
+ */
+export function reconcileHead(incomingDoc: Document): void {
+  const head = document.head
+  const incomingHead = incomingDoc.head
+  if (!head || !incomingHead) return
+  const current = indexHead(head)
+  const incoming = indexHead(incomingHead)
+  if (current.size === 0 && incoming.size === 0) return
+  for (const [key, nodes] of incoming) {
+    const live = current.get(key)
+    const replacement = document.importNode(nodes[0], true)
+    if (!live) {
+      head.append(replacement)
+      continue
+    }
+    const [first, ...duplicates] = live
+    if (!first.isEqualNode(replacement)) first.replaceWith(replacement)
+    for (const dup of duplicates) dup.remove()
+  }
+  for (const [key, nodes] of current) {
+    if (incoming.has(key)) continue
+    for (const node of nodes) node.remove()
+  }
+}

package/src/router.ts CHANGED Viewed

@@ -10,6 +10,7 @@
 import { BF_REGION } from '@barefootjs/shared'
 import { loadPage } from './cache.ts'
+import { reconcileHead } from './head.ts'
 import {
   captureRegionBaselines,
   collectModuleScripts,
@@ -297,7 +298,16 @@ export async function navigate(url: string, options: NavigateOptions = {}): Prom
       current.replaceChildren(fragment)
       swapped.push({ region: current, outgoing })
     }
+    // Commit the page's identity: the title (also handed to the route
+    // announcement below) and the allowlisted `<head>` metadata — description,
+    // canonical, og:/twitter: (`reconcileHead`, #2438). Head *resources*
+    // (`<link rel="stylesheet">`, scripts) stay unmanaged by contract, not by
+    // oversight: their lifetime isn't derivable from the incoming document, so
+    // a route-scoped stylesheet belongs inside the region, where it enters and
+    // leaves with the swap. Both are ordering-free, so they sit with the
+    // synchronous swaps rather than in the awaited tail.
     if (title !== null) document.title = title
+    reconcileHead(incomingDoc)
     // Refresh the per-region baselines to the server render now displayed: from
     // the incoming keys (matched regions), else recaptured from the live DOM