@wular/pnext 0.0.1

package/src/compat/client/route-announcer.ts

@@ -0,0 +1,72 @@
+// Route announcer (next/navigation a11y): a `<next-route-announcer>` custom
+// element whose shadow root holds an `aria-live="assertive"` node. Screen
+// readers announce client-side route changes that would otherwise be silent
+// (no full document load). The DOM name is Next-specific, so it lives in compat;
+// core exposes an `onNavigationCommit` hook that this module subscribes to.
+import { onNavigationCommit } from '../../api/router/events';
+
+const ANNOUNCER_TAG = 'next-route-announcer';
+
+let announcerNode: HTMLElement | undefined;
+
+// Next skips the very first render (no initial announcement): the announcer
+// starts empty and only updates on subsequent navigations. `onNavigationCommit`
+// only fires inside softNavigate, so it never runs for the hard load — but we
+// also guard against announcing an unchanged value.
+let lastAnnouncement = '';
+
+function ensureAnnouncer(): HTMLElement | undefined {
+  if (typeof document === 'undefined') return undefined;
+  if (announcerNode?.isConnected) return announcerNode;
+
+  const existing = document.getElementsByTagName(ANNOUNCER_TAG)[0];
+  if (existing instanceof HTMLElement && existing.shadowRoot) {
+    announcerNode = existing.shadowRoot.childNodes[0] as HTMLElement;
+    return announcerNode;
+  }
+
+  const host = document.createElement(ANNOUNCER_TAG);
+  host.style.cssText = 'position:absolute';
+  const shadow = host.attachShadow({ mode: 'open' });
+  // A <div>, matching Next's app-router announcer exactly — a <p> here leaks
+  // into shadow-piercing selectors (e.g. a test's `p` lookup racing an action
+  // result) that Next's DOM never matches.
+  const live = document.createElement('div');
+  live.setAttribute('aria-live', 'assertive');
+  live.setAttribute('id', '__next-route-announcer__');
+  live.setAttribute('role', 'alert');
+  // Visually hidden but available to assistive tech (Next's own styles).
+  live.style.cssText =
+    'position:absolute;border:0;height:1px;margin:-1px;padding:0;width:1px;clip:rect(0 0 0 0);overflow:hidden;white-space:nowrap;word-wrap:normal';
+  shadow.appendChild(live);
+  document.body.appendChild(host);
+  announcerNode = live;
+  return live;
+}
+
+// Priority order matches Next: document.title, then the first <h1>, then the
+// pathname. Read after the body swap + head sync so the new title/heading are
+// already in the DOM.
+function routeAnnouncement(): string {
+  if (document.title) return document.title;
+  const h1 = document.querySelector('h1');
+  const text = h1?.textContent?.trim();
+  if (text) return text;
+  return location.pathname;
+}
+
+function announce() {
+  const node = ensureAnnouncer();
+  if (!node) return;
+  const next = routeAnnouncement();
+  if (next === lastAnnouncement) return;
+  lastAnnouncement = next;
+  node.textContent = next;
+}
+
+export function installRouteAnnouncer() {
+  if (!process.browser && typeof window === 'undefined') return;
+  // Create the empty announcer up front so it exists on first load with `''`.
+  ensureAnnouncer();
+  onNavigationCommit(announce);
+}

package/src/compat/client/segment-cache-policy.ts

@@ -0,0 +1,159 @@
+// The router's SegmentCachePolicy implementation (COMPAT client policy). Adapts the pure per-segment
+// cache in ./segment-cache.ts onto the core router seam. Kept apart from the cache itself so the cache
+// stays importable - and unit-testable - without pulling the router, and the whole DOM runtime, into
+// the module graph.
+
+import type { SegmentCacheHit, SegmentCachePolicy, SegmentCacheRecord } from '../../api/router';
+import {
+  BODY_SEGMENT_PATHS,
+  clearSegmentCache,
+  composeFetchedLayoutFrame,
+  composeCachedLayout,
+  decodeDocumentSegmentMeta,
+  decodeSegmentPayload,
+  evictPageSegments,
+  matchRoutePattern,
+  needsLayoutFrameOnly,
+  needsPageFrameOnly,
+  runtimePageFrameSatisfied,
+  recordDocumentLayoutFrame,
+  recordSegment,
+  resolvedRouteFor,
+  segmentPrefetchCovered,
+  takeComposedSegment,
+  takeSegment,
+  type SegmentPayloadMeta,
+} from './segment-cache';
+import { resetSegmentPrefetchDedupe, scheduleAppShellPrefetch } from './segment-prefetch';
+
+export function installSegmentCachePolicy(): SegmentCachePolicy {
+  return {
+    record,
+    take,
+    // Route-tree reuse seam: the router's `/_tree` cache is keyed by pathname,
+    // but a route's TREE is param-independent, so a sibling URL of an already
+    // learned route needs no tree request. These two let the router ask the
+    // segment cache which route serves a pathname (the static-sibling guard)
+    // and whether a colon-form pattern covers it.
+    routeFor: resolvedRouteFor,
+    matchesRoute: (route, pathname) => matchRoutePattern(route, pathname) !== null,
+    // w9-segment-split: when this URL's PAGE frame is cached and only its
+    // LAYOUT varied, the prefetch fetches `/_layout` alone instead of the whole
+    // route. Inert until segment-split commit is enabled (the composition half
+    // is what makes the half-fetched document paintable).
+    needsLayoutFrameOnly: (input) => needsLayoutFrameOnly(input),
+    runtimePageFrameSatisfied,
+    // w9-segment-split (G2), the live half: when this URL's LAYOUT chain is
+    // already cached (or already on screen, for a same-URL click), the
+    // navigation fetches `/_page` and splices the answer back into it. The
+    // router falls back to the whole document whenever these answer no/null.
+    needsPageFrameOnly,
+    // w9-segment-split: join a layout-only prefetch response with this URL's
+    // cached page frame. The router commits the result as the whole document,
+    // and treats a null as "this prefetch is unusable" — a layout frame alone
+    // would paint a page-less document.
+    composeLayoutFrame: composeFetchedLayoutFrame,
+    composePageFrame: composeCachedLayout,
+    recordDocumentLayout: recordDocumentLayoutFrame,
+    prefetchCovered: segmentPrefetchCovered,
+    evictPageSegments,
+    // A revalidation invalidates every window: the prefetch dedupe state (tree cache + app-shell request
+    // set) must fall with the entries, or a revalidated route stays deduped - and stale - for its whole
+    // window. evictPageSegments deliberately keeps it, since a same-URL refresh keeps layout/head dedupe.
+    clear: () => {
+      clearSegmentCache();
+      resetSegmentPrefetchDedupe();
+    },
+  };
+}
+
+function record(input: SegmentCacheRecord): void {
+  const decoded: SegmentPayloadMeta | null =
+    input.kind === 'document'
+      ? // A navigation response / the hard-loaded document: no framed payload
+        // and no vary set, so it keys on its exact URL (fix-forward 2).
+        decodeDocumentSegmentMeta(input.body)
+      : decodeSegmentPayload(input.body, input.segmentPath);
+  // No decodable payload (a header-stripping proxy, a plain document): there is
+  // no vary metadata to key on, so nothing worth caching here — the router's
+  // own whole-URL caches already hold it.
+  if (!decoded) return;
+  // App Shells (fix-forward 5): a per-URL static prerender of a params-reading
+  // route also primes the route's SHARED shell, so navigations to its other
+  // params paint instantly. No-op unless experimental.appShells is on.
+  scheduleAppShellPrefetch({
+    pathname: input.pathname,
+    route: decoded.route,
+    vary: decoded.vary,
+    static: input.static,
+    complete: input.complete,
+    runtime: input.runtime,
+  });
+  // App Shells: the per-URL prerender carried the route's shared shell. File it
+  // at the route's fallback vary path (empty vary = every param value) as a
+  // SHELL — it paints, but a navigation still fetches the per-URL remainder.
+  if (decoded.shell) {
+    recordSegment({
+      segmentPath: input.segmentPath,
+      pathname: input.pathname,
+      search: '',
+      html: decoded.shell.html,
+      staleTimeMs: input.staleTimeMs,
+      complete: false,
+      static: true,
+      runtime: false,
+      vary: [],
+      route: decoded.shell.route,
+      params: decoded.params,
+    });
+  }
+  recordSegment({
+    segmentPath: input.segmentPath,
+    pathname: input.pathname,
+    search: input.search,
+    html: input.html,
+    staleTimeMs: input.staleTimeMs,
+    complete: input.complete,
+    static: input.static,
+    runtime: input.runtime,
+    vary: decoded.vary,
+    // w9-segment-split: pass the layout/page vary sets through so the cache can
+    // file the two frames alongside the whole-document entry.
+    ...(decoded.layoutVary ? { layoutVary: decoded.layoutVary } : {}),
+    ...(decoded.pageVary ? { pageVary: decoded.pageVary } : {}),
+    // The route's static siblings, so a learned dynamic pattern never keys onto
+    // a literal sibling's URL.
+    ...(decoded.staticSiblings ? { staticSiblings: decoded.staticSiblings } : {}),
+    route: decoded.route,
+    params: decoded.params,
+  });
+}
+
+function take(input: {
+  pathname: string;
+  search: string;
+  segmentPath: string;
+}): SegmentCacheHit | null {
+  const hit = takeSegment(input);
+  if (hit) {
+    return {
+      html: hit.html,
+      networkFree: hit.networkFree,
+      prefetchSatisfied: hit.prefetchSatisfied,
+    };
+  }
+  // w9-segment-split: the whole-document entry missed because ONE of the two
+  // frames varied. Compose the cached layout + page frames instead of going to
+  // the network for both. No-op until segment-split commit is enabled.
+  if (!BODY_SEGMENT_PATHS.includes(input.segmentPath as (typeof BODY_SEGMENT_PATHS)[number])) {
+    return null;
+  }
+  const composed = takeComposedSegment({ pathname: input.pathname, search: input.search });
+  return composed
+    ? {
+        html: composed.html,
+        networkFree: composed.networkFree,
+        prefetchSatisfied: composed.prefetchSatisfied,
+      }
+    : null;
+}