@gemboss/ui 0.8.1 → 0.10.0

package/src/index.ts

@@ -5,6 +5,8 @@ export {
 // Page width (0.8.1): its own plain module, so nothing the admin imports from shell.tsx carries it (first-load budget).
 export { PageContainer, pageWidthClass } from "./page";
 export type { PageWidth } from "./page";
+// The loading boundary every route group under @gemboss/ui/next needs (0.10.0). Plain module, like ./page.
+export { RouteCover, RouteHolding } from "./route-holding";
 export { GemMark } from "./GemMark";
 export { AuthError, AuthField, AuthFoot, AuthForm, AuthHelp, AuthLayout, PasswordField, AuthSubmit } from "./auth";
 export { BrandLockup } from "./brand";

package/src/kit-plain.css

@@ -40,10 +40,19 @@
 .ui-menu__sep { height: 1px; margin: var(--ui-space-1) 0; border: 0; background: var(--ui-border); }
 /* Checkbox: the LABEL is the target; disabled turns both the label and the box to not-allowed. Focus ring in the
    kit's own token (no --p-* here: this file is appended after the export's Polaris resolver runs). */
-.ui-check { display: inline-flex; align-items: center; gap: var(--ui-space-2); min-height: 44px; cursor: pointer; font-size: var(--ui-fs-body); color: var(--ui-text); }
+.ui-check { display: inline-flex; align-items: center; gap: var(--ui-space-2); min-height: 44px; max-width: 100%; overflow-wrap: break-word; cursor: pointer; font-size: var(--ui-fs-body); color: var(--ui-text); }
 .ui-check > input { flex: none; width: 18px; height: 18px; margin: 0; accent-color: var(--ui-accent); cursor: inherit; }
 .ui-check > input:focus-visible { outline: 2px solid var(--ui-focus); outline-offset: 2px; }
 .ui-check:has(> input:disabled) { opacity: .5; cursor: not-allowed; }
+/* 0.9.0: a long run with no spaces (a URL, "clinical/premium/…/utility") breaks inside the label instead of widening
+   the page: gemwatcher Operations overflowed 69px at 320 on one switch description (#375). Three parts: the label is
+   capped at its parent (max-width above), its TEXT child may shrink (min-width 0, the last child only so a badge in
+   front keeps its width), and break-word breaks the run once it cannot fit a line.
+   break-word, NOT anywhere: anywhere also drops the label's min-content, and a flex row then squeezes a short label
+   ("Lock" beside a long band name in GemFactory) into "Lo/ck". Two cases stay the surface's job: the text must be an
+   element (`input + span`; bare text is an anonymous flex item min-width cannot reach), and in a flex ROW the label
+   keeps its min-content, so that row must wrap. */
+.ui-check > :last-child:not(input) { min-width: 0; }
 .ui-label { display: block; margin: 0 0 var(--ui-space-1); font-size: var(--ui-fs-caption); font-weight: 600; color: var(--ui-text-muted); }
 .ui-kv { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: var(--ui-space-2) var(--ui-space-4); margin: 0; font-size: var(--ui-fs-body); }
 .ui-kv > dt { color: var(--ui-text-muted); }
@@ -310,12 +319,13 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
 }
 
 /* Radio: the checkbox's row with `type="radio"` — `<fieldset class="ui-choices"><legend class="ui-label">Plan</legend>
-   <label class="ui-check"><input type="radio" name="plan" checked> Basic</label>…</fieldset>`. */
-.ui-choices { display: grid; gap: 0; margin: 0; padding: 0; border: 0; min-width: 0; }
+   <label class="ui-check"><input type="radio" name="plan" checked><span>Basic</span></label>…</fieldset>`.
+   One minmax(0, 1fr) column: an auto column grows to the longest unbroken word in any label (0.9.0). */
+.ui-choices { display: grid; grid-template-columns: minmax(0, 1fr); gap: 0; margin: 0; padding: 0; border: 0; min-width: 0; }
 .ui-choices > legend { padding: 0; }
 
 /* Switch: a checkbox that reads as on / off, for a setting that applies at once (no Save button).
-   `<label class="ui-check ui-switch"><input type="checkbox" role="switch" checked> Send Monday digest</label>`.
+   `<label class="ui-check ui-switch"><input type="checkbox" role="switch" checked><span>Send Monday digest</span></label>`.
    Track 32×20, thumb 16; the row stays the checkbox's 44px target. */
 .ui-switch > input[type="checkbox"] {
   appearance: none; -webkit-appearance: none; position: relative; width: 32px; height: 20px; margin: 0;

package/src/kit-plain.js

@@ -16,6 +16,7 @@
      initShell();                       // a hand-written AppShell: ☰ drawer, backdrop, Escape, followed link
      initPasswordFields();              // .gb-auth-pw-toggle reveal; resetPasswordFields() on sign-out
      initSearch();                      // TopbarSearch: ⌘K / Ctrl+K and "/" focus the box, Escape leaves it
+     // initNav() runs by itself (0.10.0): a followed rail link shows a spinner, a rested-on link is prefetched
 */
 (function (g) {
   "use strict";
@@ -317,7 +318,123 @@
     });
   }
 
+  /* Navigation pending (0.10.0), the same behaviour as `@gemboss/ui/next` NavLink for a page with no router: a followed
+     rail link answers on the first frame (its icon becomes a spinner: `aria-busy="true"`, drawn by app-shell.css), and a
+     link the pointer or keyboard focus RESTS on for 120 ms, or a finger touches, is prefetched once (speculation rules in Chromium, else
+     `<link rel="prefetch">`; see navPrefetch), so the click that follows does not wait for the server. Runs by itself
+     when the script loads (delegated on the document, so links
+     rendered later are covered); `initNav()` is idempotent.
+     Which links: `.gnav-item` / `.gnav-subitem` anchors, and any `a[data-gb-pending]` ("inline" | "corner": a page link
+     that gets the small spinner). Same origin, a plain left click (no modifier key), no `target` other than _self, no
+     `download`, and not a jump to `#hash` on this same page. Opt out: `data-gb-nav="off"` on the link or any ancestor
+     (`<html>` for the whole page); `data-gb-prefetch="off"` keeps the spinner and skips the prefetch (a GET with an
+     effect, e.g. a sign-out link). A link marked `data-gb-nav="next"` belongs to NavLink and is left alone, and in a
+     Next app, or once a rail click was taken over by a client router, nothing is prefetched here (the router owns that).
+     The mark comes off on `pageshow` (back/forward cache: the page you return to must not still be "loading"), when the
+     navigation is cancelled (Escape / the browser's stop: the Navigation API's `navigateerror`), on the next followed
+     link, and after 15 s at the latest (a 204, a download served as a page link). */
+  var NAV_DWELL = 120, NAV_NET = 15000;
+  var SPEC_RULES = typeof HTMLScriptElement !== "undefined" && !!HTMLScriptElement.supports && HTMLScriptElement.supports("speculationrules");
+  var navOn = false, navTimer = 0, navNet = 0, navArmed = null, prefetched = {}, clientRouted = false;
+  function navLink(t) {
+    var a = t && t.closest ? t.closest("a[href]") : null;
+    if (!a || !(a.matches(".gnav-item, .gnav-subitem") || a.hasAttribute("data-gb-pending"))) return null;
+    if (a.getAttribute("data-gb-nav") === "next" || a.closest('[data-gb-nav="off"]')) return null;
+    if ((a.target && a.target !== "_self") || a.hasAttribute("download")) return null;
+    var u;
+    try { u = new URL(a.href, location.href); } catch (_) { return null; }
+    if (u.origin !== location.origin || !/^https?:$/.test(u.protocol)) return null;
+    // A #hash on this same page scrolls; nothing loads. `href="#"` too: its URL's .hash is "" (review #3777).
+    if (u.pathname === location.pathname && u.search === location.search && (u.hash || (a.getAttribute("href") || "").indexOf("#") > -1)) return null;
+    return a;
+  }
+  function navClear() {
+    clearTimeout(navNet);
+    document.querySelectorAll('[data-gb-busy]').forEach(function (a) {
+      a.removeAttribute("data-gb-busy");
+      a.removeAttribute("aria-busy");
+      var m = a.querySelector(":scope > .gb-pending-mark");
+      if (m) m.remove();
+    });
+  }
+  function navMark(a) {
+    navClear();
+    a.setAttribute("data-gb-busy", "");
+    a.setAttribute("aria-busy", "true");
+    if (a.hasAttribute("data-gb-pending")) {
+      var m = document.createElement("span");
+      m.className = "gb-pending-mark";
+      m.setAttribute("role", "status");
+      m.innerHTML = '<span class="ui-sr-only">' + esc(a.getAttribute("data-gb-pending-label") || "Loading") + "</span>";
+      a.appendChild(m);
+    }
+    navNet = setTimeout(navClear, NAV_NET);
+  }
+  function navPrefetch(a) {
+    // A page whose router owns its links fetches them itself: Next (detected), or any app seen taking a rail click over
+    // (preventDefault: react-router, a SPA). A document prefetch there is a server request the click never uses.
+    if (clientRouted || g.next || g.__next_f || g.__NEXT_DATA__ || a.closest('[data-gb-prefetch="off"]')) return;
+    var c = navigator.connection;
+    if (c && c.saveData) return;
+    var u = new URL(a.href, location.href);
+    u.hash = "";
+    var href = u.href;
+    if (prefetched[href] || (u.pathname === location.pathname && u.search === location.search)) return;
+    prefetched[href] = true;
+    // Speculation rules where the browser has them (Chromium): its prefetch is what the click then USES. A plain
+    // `<link rel="prefetch">` of a page is reused only when that page is cacheable (max-age > 0); a server-rendered page
+    // sends max-age=0 / no-cache, so the click fetched it a second time, and one still in flight made the click SLOWER
+    // (measured 05/10/2026 through a 280 ms proxy: 1121 ms to the new page against 737 ms with no prefetch at all).
+    // Speculation rules were reused under every Cache-Control tried. Other browsers get the link, which helps there
+    // only for cacheable pages.
+    var el;
+    if (SPEC_RULES) {
+      el = document.createElement("script");
+      el.type = "speculationrules";
+      el.textContent = JSON.stringify({ prefetch: [{ source: "list", urls: [href] }] });
+    } else {
+      el = document.createElement("link");
+      el.rel = "prefetch";
+      el.href = href;
+    }
+    el.setAttribute("data-gb-prefetched", "");
+    document.head.appendChild(el);
+  }
+  function initNav() {
+    // A bundled app also evaluates this file on the server (a client module is rendered there too): no document.
+    if (navOn || typeof document === "undefined") return;
+    navOn = true;
+    // On the WINDOW, bubble phase: the last stop of a click, after every element and document listener the page adds
+    // (this script loads early, so a document listener here would run before the page's own delegated handlers). A
+    // handler that took the click over (a client router, a popup) has called preventDefault by now.
+    addEventListener("click", function (e) {
+      if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      var a = navLink(e.target);
+      if (!a) return;
+      if (e.defaultPrevented) { clientRouted = true; return; }
+      navMark(a);
+    });
+    // Pointer and keyboard focus both have to REST: a sweep down the rail, or Tab run down it, fetches nothing.
+    var arm = function (a) {
+      if (a === navArmed) return; // moving between the icon and the label of the same link is not a new rest
+      clearTimeout(navTimer);
+      navArmed = a;
+      if (a) navTimer = setTimeout(function () { if (navArmed === a) navPrefetch(a); }, NAV_DWELL);
+    };
+    // The focus a press gives a link is not keyboard intent: that click is already navigating.
+    var pressed = null;
+    document.addEventListener("mousedown", function (e) { pressed = navLink(e.target); if (pressed && pressed === navArmed) clearTimeout(navTimer); });
+    document.addEventListener("mouseover", function (e) { arm(navLink(e.target)); });
+    document.addEventListener("focusin", function (e) { var a = navLink(e.target); if (a && a === pressed) return; arm(a); });
+    // A touch is already deliberate (its click follows in ~100 ms).
+    document.addEventListener("touchstart", function (e) { var a = navLink(e.target); if (a) navPrefetch(a); }, { passive: true });
+    addEventListener("pageshow", navClear);
+    addEventListener("keydown", function (e) { if (e.key === "Escape") navClear(); });
+    if (g.navigation && g.navigation.addEventListener) g.navigation.addEventListener("navigateerror", navClear);
+  }
+  initNav();
+
   g.gembossUI = { openModal: openModal, toast: toast, confirm: confirm, initMenus: initMenus, closeMenus: closeMenus,
     initSearch: initSearch, initShell: initShell, initPasswordFields: initPasswordFields, resetPasswordFields: resetPasswordFields,
-    openModals: function () { return MODALS.length; } };
+    initNav: initNav, openModals: function () { return MODALS.length; } };
 })(globalThis);

package/src/nav-dwell.ts

@@ -0,0 +1,6 @@
+/** How long a pointer (or keyboard focus) must rest on a link before it is prefetched. Long enough that a sweep across
+ *  the rail never stops this long on a link it is only passing; far shorter than the time from stopping to pressing the
+ *  button. The admin's rail uses the same number (apps/admin/src/components/AppShell.tsx), and kit-plain.js (a classic
+ *  script, cannot import) writes it as `NAV_DWELL = 120`: nav-pending.test.tsx holds the two equal.
+ *  A plain module, not the "use client" one, so a server component that imports it gets a number. */
+export const NAV_DWELL_MS = 120;

package/src/next/index.ts

@@ -0,0 +1,4 @@
+// @gemboss/ui/next (0.10.0): navigation feedback for Next.js App Router surfaces. Its own entry so the main entry never
+// imports `next` (an optional peer): see ./nav.tsx.
+export { NavLink, PendingIcon, PendingLink, type NavLinkProps } from "./nav";
+export { NAV_DWELL_MS } from "../nav-dwell";

package/src/next/nav.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * Navigation feedback for a Next.js (App Router) surface: a click answers on the first frame, and the page a visitor
+ * is about to open is fetched while their pointer rests on it. The standard since 0.10.0 (Chris, 05/10/2026): "bấm vào
+ * menu cái icon chuyển thành icon loading, sub menu cũng có … rồi hover load trước".
+ *
+ * Source: content-radar's rail (gemlabs #828, #836), measured 04/10/2026 on a server ~280 ms away: a rail click left the
+ * screen unchanged for 321-503 ms; with this, 6-8 ms. Two things, each one a measured fix:
+ *
+ * 1. Prefetch on INTENT, not on sight. A rail has ~15 links all on screen at once, and Next's default prefetches every
+ *    visible link, i.e. ~15 server requests per page view for pages nobody opens (the admin measured 25 full renders
+ *    in 19 s with nobody touching the mouse, 23/08/2026). Here a link is prefetched when the pointer RESTS on it for
+ *    NAV_DWELL_MS (keyboard focus too), or on touchstart; a pointer sweeping down the rail, or Tab run down it, fires nothing.
+ * 2. `useLinkStatus` (Next 15.3+): while the destination loads, the link carries a status child. Inside a rail item the
+ *    shell CSS (app-shell.css) turns that into a spinner in place of the icon; PendingLink draws a small one by itself.
+ *
+ * Its own entry (`@gemboss/ui/next`) so the main entry never imports `next`: gemwatcher (Vite) and the plain-HTML
+ * surfaces load the package without it, and the admin's first load does not grow by a module it does not use.
+ */
+import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
+import Link, { useLinkStatus } from "next/link";
+
+import { NAV_DWELL_MS } from "../nav-dwell";
+
+type LinkProps = React.ComponentProps<typeof Link>;
+
+export type NavLinkProps = LinkProps & {
+  /** What to prefetch once the visitor shows intent. `null` (default): Next's own choice, which for a dynamic route is
+   *  only its loading boundary (cheap, and it is what lets the click paint at once). `true`: the whole page. `false`:
+   *  never. Before any intent it is always `false`. */
+  prefetch?: LinkProps["prefetch"];
+  /** The text a screen reader hears while the page loads. */
+  pendingLabel?: string;
+};
+
+type Mark = (label: string, href: LinkProps["href"]) => React.ReactNode;
+
+/** next/link + prefetch on intent. `mark` renders inside the link (useLinkStatus is only readable there). */
+function IntentLink({ prefetch = null, pendingLabel = "Loading", onMouseEnter, onMouseLeave, onFocus, onBlur, onTouchStart,
+  onMouseDown, children, mark, ...props }: NavLinkProps & { mark: Mark }) {
+  const [warm, setWarm] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const pressed = useRef(false);
+  useEffect(() => () => clearTimeout(timer.current), []);
+  const rest = () => { clearTimeout(timer.current); timer.current = setTimeout(() => setWarm(true), NAV_DWELL_MS); };
+  const stop = () => clearTimeout(timer.current);
+  return (
+    <Link {...props}
+      // kit-plain.js (loaded by most Next surfaces too, for confirm/toast) leaves a link marked this way to its owner.
+      data-gb-nav="next"
+      prefetch={warm ? prefetch : false}
+      onMouseEnter={(e) => { rest(); onMouseEnter?.(e); }}
+      onMouseLeave={(e) => { stop(); onMouseLeave?.(e); }}
+      // A press ends the dwell: a timer firing AFTER the click would change `prefetch` mid-navigation, and Next would
+      // remount this link's instance and lose track of it (the spinner then never clears on the next click).
+      onMouseDown={(e) => { stop(); pressed.current = true; onMouseDown?.(e); }}
+      // Focus rests like a pointer does: tabbing down the rail passes each link in well under 120 ms and fetches none. The
+      // focus a press gives the link is not keyboard intent, and arming on it would bring back the timer the press ended.
+      onFocus={(e) => { if (!pressed.current) rest(); onFocus?.(e); }}
+      onBlur={(e) => { stop(); pressed.current = false; onBlur?.(e); }}
+      // A touch is already deliberate (the tap's click follows in ~100 ms): no dwell to infer.
+      onTouchStart={(e) => { stop(); setWarm(true); onTouchStart?.(e); }}>
+      {children}
+      {mark(pendingLabel, props.href)}
+    </Link>
+  );
+}
+
+/**
+ * `html[data-gb-navigating]` while any of these links is pending: what shows RouteCover (the holding frame over the
+ * content area) on the click's first frames. A layout effect, so the attribute lands before that frame is painted;
+ * counted, because a second click can start before the first navigation ends.
+ */
+let navigating = 0;
+const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/** The cover is for a NEW screen: a link to the page already shown (a tab that only changes `?tab=`) keeps its own small
+ *  spinner and does not cover content that is not changing. */
+function leavesThisPage(href: LinkProps["href"]): boolean {
+  const raw = typeof href === "string" ? href : (href.pathname ?? "");
+  try { return new URL(raw || ".", window.location.href).pathname !== window.location.pathname; } catch { return true; }
+}
+function useNavigatingFlag(pending: boolean, href: LinkProps["href"]) {
+  useBeforePaint(() => {
+    if (!pending || !leavesThisPage(href)) return;
+    navigating += 1;
+    document.documentElement.setAttribute("data-gb-navigating", "");
+    return () => {
+      navigating = Math.max(0, navigating - 1);
+      if (!navigating) document.documentElement.removeAttribute("data-gb-navigating");
+    };
+  }, [pending]);
+}
+
+/** The status a rail item carries while its page loads. The CSS reads it with `:has(> .gnav-pending)`. */
+function RailStatus({ label, href }: { label: string; href: LinkProps["href"] }) {
+  const { pending } = useLinkStatus();
+  useNavigatingFlag(pending, href);
+  return pending ? <span className="gnav-pending" role="status">{label}</span> : null;
+}
+
+/** The kit's small spinner with its status text: what PendingLink and PendingIcon show while the page loads. */
+function Spinner({ label }: { label: string }) {
+  return <span className="gb-pending-mark" role="status"><span className="ui-sr-only">{label}</span></span>;
+}
+
+function PageStatus({ label, href }: { label: string; href: LinkProps["href"] }) {
+  const { pending } = useLinkStatus();
+  useNavigatingFlag(pending, href);
+  return pending ? <Spinner label={label} /> : null;
+}
+
+const railMark: Mark = (label, href) => <RailStatus label={label} href={href} />;
+const pageMark: Mark = (label, href) => <PageStatus label={label} href={href} />;
+
+/**
+ * The link for the rail and for any menu: `<RailItem as={NavLink} href="/x" icon={…} label="X" />`, or
+ * `<RailSubItem as={NavLink} href="/x/y">Y</RailSubItem>`. Prefetches on intent; while the page loads, the rail item's
+ * icon becomes a spinner (a sub item gets a 12px one in its indent, before the label). Outside the rail it adds only the status text: use
+ * PendingLink there, or PendingIcon for a link with its own icon.
+ */
+export function NavLink(props: NavLinkProps) {
+  return <IntentLink {...props} mark={railMark} />;
+}
+
+/**
+ * A link in the PAGE (a list row, a card, a tab): prefetch on intent, and a small spinner while its page loads.
+ * `mark="inline"` (default) puts it 12px after the text; `"corner"` puts it in the top right corner, out of the
+ * flow, for a link that wraps a whole card. Marked with `data-gb-pending`, not a class, so a surface that colours
+ * bare links with `a:not([class])` keeps its colour.
+ */
+export function PendingLink({ mark = "inline", ...props }: NavLinkProps & { mark?: "inline" | "corner" }) {
+  return <IntentLink {...props} data-gb-pending={mark === "corner" ? "corner" : "inline"} mark={pageMark} />;
+}
+
+/** An icon that becomes the 20px spinner while ITS link's page loads. Must sit inside a next/link or a NavLink outside
+ *  the rail (a tab with an icon). Not inside PendingLink, which draws its own spinner (two spinners, "Loading" read
+ *  twice), and not in a rail item: `RailItem as={NavLink}` swaps its icon already. */
+export function PendingIcon({ label = "Loading", children }: { label?: string; children?: React.ReactNode }) {
+  const { pending } = useLinkStatus();
+  return pending ? <Spinner label={label} /> : <>{children}</>;
+}

package/src/route-holding.tsx

@@ -0,0 +1,65 @@
+/**
+ * RouteHolding (0.10.0): what a route group's `loading.jsx` renders while the next page is on its way.
+ *
+ * ONE frame for every route, not a skeleton per page: a title bar and four lines in the page's content column, no card
+ * edges. The admin's holding screen (apps/admin `.gemboss-route-shell`) is drawn the same way and for the same reason:
+ * pages run in several column widths, and a fake card at the wrong width is a layout jump of its own (the admin
+ * removed per-route skeletons for that).
+ *
+ * Why a surface on `@gemboss/ui/next` MUST have one: Next prefetches a dynamic route only down to its nearest loading
+ * boundary. Without a `loading.jsx` there is nothing to prefetch, so a click waits a whole server round trip with the
+ * old page on screen. Measured on content-radar 05/10/2026 (no loading file, server ~280 ms away): hover prefetches came
+ * back with 0.3-1.2 KB and the new screen took 350-780 ms, although the rail spinner showed at 5-38 ms. The admin
+ * measured the opposite case: deleting its `app/app/loading.tsx` cost 60-270 ms per click.
+ *
+ * Its own plain module, no hooks, no "use client": a server `loading.jsx` renders it, and nothing the admin imports
+ * pulls it into the admin's first load.
+ */
+import React from "react";
+import { pageWidthClass, type PageWidth } from "./page";
+
+export function RouteHolding({ width = "default", label = "Loading", title }: {
+  /** The content column of the pages under this boundary (same tiers as PageContainer). Omit when the shell's
+   *  PageContainer already caps the column. */
+  width?: PageWidth | "none";
+  /** What a screen reader hears. */
+  label?: string;
+  /** A heading to show instead of the title bar, when the boundary knows where it leads (one route, one name). */
+  title?: React.ReactNode;
+}) {
+  const cls = width === "none" ? "gb-route-holding" : `gb-route-holding ${pageWidthClass(width)}`;
+  return (
+    <div className={cls} role={label ? "status" : undefined} aria-busy="true">
+      {label ? <span className="ui-sr-only">{label}</span> : null}
+      {title ? <div className="gb-route-holding__heading">{title}</div> : null}
+      <div className="ui-skeleton" aria-hidden="true">
+        {title ? null : <span className="ui-skeleton__line gb-route-holding__title" />}
+        <span className="ui-skeleton__line" /><span className="ui-skeleton__line" />
+        <span className="ui-skeleton__line" /><span className="ui-skeleton__line" />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * RouteCover (0.10.0): the same frame, painted the moment a NavLink / PendingLink is clicked, over the content area
+ * (below the topbar, right of the rail), until the navigation commits. Render ONE in the layout, beside the page:
+ * `<AppShell …><PageContainer>{children}</PageContainer><RouteCover /></AppShell>`.
+ *
+ * Why, when the route already has a `loading.jsx`: Next can paint that boundary only once it has it, i.e. once a
+ * prefetch or the click's own request came back, one server round trip. Measured on content-radar 05/10/2026 through a
+ * 280 ms proxy: with the boundary the new screen came at ~300-350 ms, because a 120 ms hover rarely lets the prefetch
+ * finish. This frame is already in the page, so it paints in the click's first frames; the admin found the same and
+ * covers its content area from the shell (`.gemboss-route-shell`). It shows only while `html[data-gb-navigating]`,
+ * which the `@gemboss/ui/next` links set while pending; it fades in over 80 ms with no delay (the target is a new
+ * screen within 100 ms), so a navigation served from the router cache (20-90 ms) sees only a faint partial frame. Hidden from screen readers: the clicked link already announces "Loading".
+ * Geometry is the AppShell's (topbar 56px, rail 240px; full width at <=760px, where the rail is a drawer): a surface
+ * without that shell should render RouteHolding in its own content box instead.
+ */
+export function RouteCover({ width = "default" }: { width?: PageWidth }) {
+  return (
+    <div className="gb-route-cover" aria-hidden="true">
+      <RouteHolding width={width} label="" />
+    </div>
+  );
+}

package/src/shell.tsx

@@ -97,12 +97,16 @@ export function RailGroup({ active, hasActiveChild, className, children }:
  * `.gnav-item`: icon + label (+ anything after, e.g. a count). Renders `<a>` by default; pass
  * `as={Link}` for a router link or `as="button"` for an action. `aria-current="page"` follows
  * `active` unless the caller sets it.
+ *
+ * `pending` (0.10.0): the page this item opens is on its way. It becomes `aria-busy="true"`, and the CSS
+ * (app-shell.css) swaps the icon for a spinner in the same 20px box and shows the wait cursor. A Next app
+ * does not set it by hand: `RailItem as={NavLink}` from `@gemboss/ui/next` reads the router's own status.
  */
-export function RailItem({ as: Comp = "a", icon, label, active, className, children, ...rest }:
-  Polymorphic<{ icon?: React.ReactNode; label: React.ReactNode; active?: boolean; children?: React.ReactNode }>) {
+export function RailItem({ as: Comp = "a", icon, label, active, pending, className, children, ...rest }:
+  Polymorphic<{ icon?: React.ReactNode; label: React.ReactNode; active?: boolean; pending?: boolean; children?: React.ReactNode }>) {
   return (
     <Comp className={cx("gnav-item", active && "active", className)}
-          aria-current={active ? "page" : undefined} {...rest}>
+          aria-current={active ? "page" : undefined} aria-busy={pending || undefined} {...rest}>
       <span className="gnav-ico">{icon}</span>
       <span className="gnav-label">{label}</span>
       {children}
@@ -115,14 +119,15 @@ export function RailSub({ children }: { children?: React.ReactNode }) {
   return <ul className="gnav-sub">{children}</ul>;
 }
 
-/** One `li` of `RailSub`. `soon` renders a disabled entry with a "Soon" tag instead of a link. */
-export function RailSubItem({ as: Comp = "a", active, soon, soonLabel = "Soon", className, children, ...rest }:
-  Polymorphic<{ active?: boolean; soon?: boolean; soonLabel?: string; children?: React.ReactNode }>) {
+/** One `li` of `RailSub`. `soon` renders a disabled entry with a "Soon" tag instead of a link. `pending`: as on
+ *  `RailItem`; a sub item has no icon, so the spinner (12px) sits in its indent, before the label, out of the flow. */
+export function RailSubItem({ as: Comp = "a", active, pending, soon, soonLabel = "Soon", className, children, ...rest }:
+  Polymorphic<{ active?: boolean; pending?: boolean; soon?: boolean; soonLabel?: string; children?: React.ReactNode }>) {
   if (soon) return <li><span className="gnav-subitem is-soon">{children}<em>{soonLabel}</em></span></li>;
   return (
     <li>
       <Comp className={cx("gnav-subitem", active && "active", className)}
-            aria-current={active ? "page" : undefined} {...rest}>{children}</Comp>
+            aria-current={active ? "page" : undefined} aria-busy={pending || undefined} {...rest}>{children}</Comp>
     </li>
   );
 }