@ultimat3/render 23.0.0 → 24.0.0

package/src/navigation-rules.ts

@@ -70,7 +70,8 @@ export type NativeReason =
   | 'hash'
   | 'method'
   | 'encoding'
-  | 'file';
+  | 'file'
+  | 'unparsable';
 
 export type LinkVerdict =
   | { readonly kind: 'soft'; readonly url: string }
@@ -97,9 +98,12 @@ const native = (reason: NativeReason): { readonly kind: 'native'; reason: Native
   reason,
 });
 
-/** Same document, fragment only: the browser scrolls, no fetch. */
-const hashOnly = (to: URL, from: URL): boolean =>
-  to.hash !== '' && to.pathname === from.pathname && to.search === from.search;
+/**
+ * Same document, fragment only: the browser scrolls, no fetch. Asked of the HREF, not `to.hash`:
+ * an empty fragment (`<a href="#">`) parses to `hash === ''`, and was soft-navigated and re-fetched.
+ */
+const hashOnly = (href: string, to: URL, from: URL): boolean =>
+  href.includes('#') && to.pathname === from.pathname && to.search === from.search;
 
 /**
  * The link rules, in the order a reader checks them. The SURFACE is not decided here: the URL
@@ -113,12 +117,15 @@ export function linkVerdict(facts: LinkFacts): LinkVerdict {
   if (facts.download) return native('download');
   if (facts.rel.split(/\s+/).includes('external')) return native('external');
   if (facts.reload) return native('opt-out');
+  // `a.href` is the raw attribute when it does not parse (`href="http://"`): the browser decides
+  // what such a link does, where `new URL` threw a bare `TypeError` out of the click handler.
+  if (!URL.canParse(facts.href)) return native('unparsable');
   const to = new URL(facts.href);
   const from = new URL(facts.current);
   if (to.origin !== from.origin || (to.protocol !== 'http:' && to.protocol !== 'https:')) {
     return native('cross-origin');
   }
-  if (hashOnly(to, from)) return native('hash');
+  if (hashOnly(facts.href, to, from)) return native('hash');
   return { kind: 'soft', url: to.href };
 }
 
@@ -153,7 +160,7 @@ export type FormVerdict =
 
 /** What a `submit` tells the router — the submitter's `formmethod`/`formaction` already applied. */
 export interface FormFacts {
-  /** Resolved action URL. */
+  /** Resolved action URL — or the raw attribute when it does not resolve (`'unparsable'`). */
   readonly action: string;
   readonly current: string;
   /** Lower case: `get`, `post` or `dialog`. */
@@ -175,6 +182,7 @@ export function formVerdict(facts: FormFacts): FormVerdict {
   if (facts.method !== 'get' && facts.method !== 'post') return native('method');
   // `text/plain` is the browser's own encoding, with no `fetch` body that reproduces it byte for byte.
   if (facts.method === 'post' && facts.enctype === 'text/plain') return native('encoding');
+  if (!URL.canParse(facts.action)) return native('unparsable');
   const to = new URL(facts.action);
   if (to.origin !== new URL(facts.current).origin) return native('cross-origin');
   if (facts.method === 'get') {
@@ -246,6 +254,14 @@ export function responseVerdict(facts: ResponseFacts): ResponseVerdict {
   }
   if (facts.status === 204) {
     if (facts.location === null) return { kind: 'stay' };
+    // The caller ASSIGNS this to `window.location`, so only http(s) is a place to go: a scheme
+    // that runs in the page would be script in the app's origin. `@ultimat3/http`'s `locationFor`
+    // refuses it at the source; this is the same rule for an answer something else wrote. The
+    // requested url is loaded as a document instead — a POST is never re-sent, so it fails.
+    if (!/^https?:\/\/./i.test(facts.location) || !URL.canParse(facts.location)) {
+      const reason = 'a location that is not http(s)';
+      return get ? load(facts.requested, reason) : { kind: 'failed', reason };
+    }
     if (origin(facts.location) !== origin(facts.requested))
       return load(facts.location, 'another origin');
     // The server asked for THIS url as a document: the route did not run, the browser runs it.

package/src/navigation-scroll.ts

@@ -0,0 +1,51 @@
+/**
+ * The client router's scroll keeping: the browser's own restoration is off, so the router restores
+ * a saved offset when a document LOADS onto one of its entries (reload, or Back after a full load),
+ * then saves the offset into the entry on screen as the visitor scrolls.
+ */
+
+import { entryOf, saveEntryScroll } from './navigation-history';
+
+export interface ScrollKeeper {
+  /** The offset, into the entry of the document on screen now. */
+  save(): void;
+  /** Drops a save still pending — it belongs to the entry just left. */
+  cancel(): void;
+  stop(): void;
+}
+
+/** How long a scroll must rest before it is saved: a browser caps `replaceState` calls. */
+const SCROLL_SETTLE_MS = 150;
+
+export function scrollKeeper(win: Window, rendered: () => string): ScrollKeeper {
+  win.history.scrollRestoration = 'manual';
+  // BEFORE the first save. With restoration manual, a reload or a Back that is a full load lands
+  // at the top, and the save below then overwrote the entry's offset with that 0 — the place the
+  // visitor left was lost twice. Only this document's own entry: one an app pushed has no offset.
+  const held = entryOf(win.history.state);
+  if (held !== undefined && held.doc === rendered()) {
+    win.scrollTo({
+      left: held.scroll[0],
+      top: held.scroll[1],
+      behavior: 'instant' as ScrollBehavior,
+    });
+  }
+  const save = (): void => saveEntryScroll(win, rendered());
+  save();
+  // Saved as the visitor scrolls, once the scroll settles — so FORWARD restores too.
+  let settle: number | undefined;
+  const cancel = (): void => win.clearTimeout(settle);
+  const onScroll = (): void => {
+    cancel();
+    settle = win.setTimeout(save, SCROLL_SETTLE_MS);
+  };
+  win.addEventListener('scroll', onScroll, { passive: true });
+  return {
+    save,
+    cancel,
+    stop() {
+      cancel();
+      win.removeEventListener('scroll', onScroll);
+    },
+  };
+}

package/src/navigation-swap.ts

@@ -56,8 +56,15 @@ export function missingStylesheets(doc: Document, next: Document): readonly stri
     .filter((href) => !loaded.has(href));
 }
 
-/** Resolves once every sheet loaded OR failed — a missing sheet must not hang the navigation. */
-export function loadStylesheets(doc: Document, hrefs: readonly string[]): Promise<void> {
+/**
+ * Resolves once every sheet loaded OR failed — a missing sheet must not hang the navigation. Each
+ * sheet joins `owned` as it is appended, so a swap that never happens still leaves it retirable.
+ */
+export function loadStylesheets(
+  doc: Document,
+  hrefs: readonly string[],
+  owned: WeakSet<Element>,
+): Promise<void> {
   return Promise.all(
     hrefs.map(
       (href) =>
@@ -68,6 +75,7 @@ export function loadStylesheets(doc: Document, hrefs: readonly string[]): Promis
           link.onload = () => done();
           link.onerror = () => done();
           doc.head.append(link);
+          owned.add(link);
         }),
     ),
   ).then(() => undefined);

package/src/navigation-tabs.ts

@@ -0,0 +1,58 @@
+/**
+ * The client router's tie to the origin's other tabs: one `BroadcastChannel`, so a write or a new
+ * principal in one tab empties every tab's prefetch cache. Closed while the page sits in the
+ * back/forward cache (an open channel keeps a page out of it); reopened, cache emptied, on return.
+ */
+
+import { onClientWrite, onRescope } from '@ultimat3/core/page';
+
+/** One channel per origin: a principal change or a write in one tab empties every tab's cache. */
+export const NAVIGATION_CHANNEL = 'ultimate:navigation';
+
+export interface TabSync {
+  /** This tab and every other: a write or a new principal makes every held page suspect. */
+  forget(): void;
+  stop(): void;
+}
+
+/** `clear` empties this tab's cache; called for this tab's own events and every other tab's. */
+export function tabSync(win: Window, clear: () => void): TabSync {
+  const open = (): BroadcastChannel | undefined => {
+    if (!('BroadcastChannel' in win)) return undefined;
+    const opened = new BroadcastChannel(NAVIGATION_CHANNEL);
+    opened.onmessage = clear;
+    return opened;
+  };
+  let channel = open();
+  const forget = (): void => {
+    clear();
+    channel?.postMessage('clear');
+  };
+  // `pagehide`, not `unload`: it fires for a page entering the back/forward cache too, and a page
+  // holding an open channel is refused by it — Back then reloads the page from the network.
+  const onHide = (): void => {
+    channel?.close();
+    channel = undefined;
+  };
+  // Restored from that cache: every message sent while it was frozen was missed, so nothing held
+  // can be trusted. A `pageshow` of a fresh load finds the channel open and leaves it.
+  const onShow = (event: PageTransitionEvent): void => {
+    if (!event.persisted || channel !== undefined) return;
+    channel = open();
+    clear();
+  };
+  win.addEventListener('pagehide', onHide);
+  win.addEventListener('pageshow', onShow);
+  const offWrite = onClientWrite(forget);
+  const offRescope = onRescope(forget);
+  return {
+    forget,
+    stop() {
+      win.removeEventListener('pagehide', onHide);
+      win.removeEventListener('pageshow', onShow);
+      offWrite();
+      offRescope();
+      onHide();
+    },
+  };
+}

package/src/navigation.ts

@@ -14,19 +14,15 @@
  * on documents whose surface opted in (`navigation: { client: [...] }` in `app.config.ts`).
  */
 
-import {
-  CLIENT_BUILD_META,
-  CLIENT_SCOPE_META,
-  onClientWrite,
-  onRescope,
-} from '@ultimat3/core/page';
+import { CLIENT_BUILD_META, CLIENT_SCOPE_META } from '@ultimat3/core/page';
 import { navigationCache } from './navigation-cache';
 import {
   anchorOf,
   announcer,
-  fieldText,
   focusMain,
+  formAction,
   formFields,
+  formPairs,
   handOver,
   linkFacts,
   type RunningTransition,
@@ -37,7 +33,6 @@ import {
   type EntryState,
   entryOf,
   STATE_KEY,
-  saveEntryScroll,
   scrollAfter,
   withoutFragment,
 } from './navigation-history';
@@ -60,6 +55,7 @@ import {
   responseVerdict,
   reusable,
 } from './navigation-rules';
+import { scrollKeeper } from './navigation-scroll';
 import {
   documentHead,
   loadStylesheets,
@@ -68,6 +64,7 @@ import {
   runScripts,
   swapDocument,
 } from './navigation-swap';
+import { tabSync } from './navigation-tabs';
 
 export interface NavigateOptions {
   readonly method?: 'GET' | 'POST';
@@ -84,9 +81,6 @@ export interface NavigationRouter {
   stop(): void;
 }
 
-/** One channel per origin: a principal change or a write in one tab empties every tab's cache. */
-const CHANNEL = 'ultimate:navigation';
-
 interface RouterWindow extends Window {
   __xNavigation?: NavigationRouter;
 }
@@ -122,28 +116,9 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   const live = announcer(doc);
   const owned = documentHead(doc);
   notePersisted(doc);
-  win.history.scrollRestoration = 'manual';
-
-  const channel = 'BroadcastChannel' in win ? new BroadcastChannel(CHANNEL) : undefined;
-  if (channel !== undefined) channel.onmessage = () => cache.clear();
-  /** This tab and every other: a write or a new principal makes every held page suspect. */
-  const forget = (): void => {
-    cache.clear();
-    channel?.postMessage('clear');
-  };
-  const offWrite = onClientWrite(forget);
-  const offRescope = onRescope(forget);
-
-  const saveScroll = (): void => saveEntryScroll(win, rendered);
-
-  saveScroll();
-  // Saved as the visitor scrolls, once the scroll settles — so FORWARD restores too, and a
-  // browser's cap on `replaceState` calls is never approached.
-  let settle: number | undefined;
-  const onScroll = (): void => {
-    win.clearTimeout(settle);
-    settle = win.setTimeout(saveScroll, 150);
-  };
+  const tabs = tabSync(win, () => cache.clear());
+  const forget = tabs.forget;
+  const scroll = scrollKeeper(win, () => rendered);
 
   const request = (url: string, purpose: 'soft' | 'prefetch', init?: RequestInit) =>
     fetchDocument(win, doc, url, purpose, init);
@@ -172,12 +147,11 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     signal: AbortSignal,
   ) => {
     if (method === 'POST') {
+      // Before AND once it settles, landed or not: a guess sent while the write was in flight
+      // may have rendered the old state, and a write that failed here may still have committed.
       forget();
-      return request(url, 'soft', {
-        method,
-        ...(options.body === undefined ? {} : { body: options.body }),
-        signal,
-      });
+      const body = options.body === undefined ? {} : { body: options.body };
+      return request(url, 'soft', { method, ...body, signal }).finally(forget);
     }
     const held = cache.peek(url);
     cache.delete(url);
@@ -212,7 +186,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     inflight = mine;
     win.clearTimeout(intent);
     navigatingTo = withoutFragment(url);
-    if (options.history !== 'none') saveScroll();
+    if (options.history !== 'none') scroll.save();
     const progress = win.setTimeout(
       () => doc.documentElement.setAttribute(NAVIGATING_ATTRIBUTE, ''),
       NAVIGATION_PROGRESS_DELAY_MS,
@@ -274,11 +248,15 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       if (next === null) return;
       const landed = `${withoutFragment(url)}${new URL(url).hash}`;
       try {
-        await loadStylesheets(doc, missingStylesheets(doc, next));
+        // Owned from the moment they are appended: a navigation aborted after this point left its
+        // sheets in the head for good, styling every page after it — the next swap retires an
+        // owned sheet its page does not link.
+        await loadStylesheets(doc, missingStylesheets(doc, next), owned);
         if (mine.signal.aborted) return;
         let swapped: ReturnType<typeof swapDocument> | undefined;
-        const track = (running: RunningTransition | undefined): void => {
-          animating = running;
+        const track = (running: RunningTransition, finished: boolean): void => {
+          if (!finished) animating = running;
+          else if (animating === running) animating = undefined;
         };
         await transition(
           win,
@@ -375,7 +353,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     const say = (attr: string, fallback: string): string =>
       submitter?.getAttribute(`form${attr}`) ?? form.getAttribute(attr) ?? fallback;
     const facts: FormFacts = {
-      action: new URL(say('action', win.location.href) || win.location.href, doc.baseURI).href,
+      action: formAction(say('action', ''), win.location.href, doc.baseURI),
       current: win.location.href,
       method: say('method', 'get').toLowerCase(),
       enctype: say('enctype', 'application/x-www-form-urlencoded').toLowerCase(),
@@ -388,9 +366,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       hasFile: [...fields.values()].some(
         (value: unknown) => value instanceof File && value.name !== '',
       ),
-      fields: [...fields].map(
-        ([name, value]: [string, unknown]) => [name, fieldText(value)] as const,
-      ),
+      fields: formPairs(fields),
     };
     const verdict = formVerdict(facts);
     if (verdict.kind === 'native') return;
@@ -438,8 +414,7 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
    * screen it is fetched; when it is, only the scroll moves — the app keeps its own history.
    */
   const onPop = (event: PopStateEvent): void => {
-    // A save still pending belongs to the entry just left.
-    win.clearTimeout(settle);
+    scroll.cancel();
     const url = win.location.href;
     const entry = entryOf(event.state);
     const wanted = entry?.doc ?? withoutFragment(url);
@@ -464,7 +439,6 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
   // had its chance to `preventDefault`, which the rules then honour.
   win.addEventListener('click', onClick);
   win.addEventListener('submit', onSubmit);
-  win.addEventListener('scroll', onScroll, { passive: true });
   doc.addEventListener('pointerover', onIntent, { passive: true });
   doc.addEventListener('pointerout', onLeave, { passive: true });
   doc.addEventListener('focusin', onIntent);
@@ -480,7 +454,6 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
     stop() {
       win.removeEventListener('click', onClick);
       win.removeEventListener('submit', onSubmit);
-      win.removeEventListener('scroll', onScroll);
       doc.removeEventListener('pointerover', onIntent);
       doc.removeEventListener('pointerout', onLeave);
       doc.removeEventListener('focusin', onIntent);
@@ -489,9 +462,8 @@ export function startNavigation(win: RouterWindow = window): NavigationRouter |
       doc.removeEventListener('pointerdown', onPress, { capture: true });
       doc.removeEventListener('pointerup', onRelease, { capture: true });
       doc.removeEventListener('pointercancel', onRelease, { capture: true });
-      offWrite();
-      offRescope();
-      channel?.close();
+      scroll.stop();
+      tabs.stop();
       delete win.__xNavigation;
     },
   };

package/src/registry.ts

@@ -5,12 +5,15 @@
  * from. Nothing downstream may keep its own list of routes.
  */
 
+import type { CacheTag } from '@ultimat3/cache';
+import { serializeTag, surrogateKeys } from '@ultimat3/cache';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-import { finiteCount } from '@ultimat3/core';
+import { finiteCount, isUltimateError, renderFixLiteral } from '@ultimat3/core';
 import { byCodeUnit } from './code-unit-order';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
+  RouteModeInvalidError,
   RouteUnnormalizedError,
   SurfaceBoundaryError,
 } from './errors';
@@ -26,6 +29,8 @@ import {
 import type { RouteConfig, RouteData } from './route';
 import { isRouteConfig, tagKeys } from './route';
 import type { RouteComponent } from './route-component';
+import type { CompiledPattern } from './route-pattern';
+import { compilePattern } from './route-pattern';
 import type { Surface } from './surfaces';
 import { locateSurface } from './surfaces';
 
@@ -90,7 +95,6 @@ export interface RouteDescriptor {
    */
   readonly islandSources: readonly string[];
   readonly budgetJs: string | null;
-  readonly budgetLcp: number | null;
   /**
    * Present on a route NO surface file declares: who mounted it and every permission that gates
    * it. Absent on a file route — so a reader never has to ask whether `file` is a path.
@@ -100,14 +104,6 @@ export interface RouteDescriptor {
 
 export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
 
-export interface CompiledPattern {
-  readonly source: string;
-  readonly regex: RegExp;
-  readonly keys: readonly string[];
-  /** Higher wins when two patterns match the same pathname. */
-  readonly specificity: number;
-}
-
 /**
  * `apps/web/site/blog/[slug]/page.tsx` → `{ surface: 'site', path: '/blog/:slug' }`.
  *
@@ -209,34 +205,6 @@ function toUrlSegment(segment: string): string {
   return segment;
 }
 
-export function compilePattern(path: string): CompiledPattern {
-  const keys: string[] = [];
-  let specificity = 0;
-  const segments = path.split('/').filter((s) => s.length > 0);
-
-  const parts = segments.map((segment) => {
-    if (segment.startsWith('*')) {
-      keys.push(segment.slice(1));
-      specificity += 1;
-      return '(.*)';
-    }
-    if (segment.startsWith(':')) {
-      keys.push(segment.slice(1));
-      specificity += 10;
-      return '([^/]+)';
-    }
-    specificity += 100;
-    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  });
-
-  return {
-    source: path,
-    regex: new RegExp(`^/${parts.join('/')}/?$`),
-    keys,
-    specificity,
-  };
-}
-
 const routes = new Map<string, RouteEntry>();
 /** The table `describeRoutes()` last built, dropped whenever a route registers or the registry clears. */
 let described: readonly RouteDescriptor[] | undefined;
@@ -256,6 +224,27 @@ export interface RegisterRouteInput<TData = RouteData> {
   readonly component?: RouteComponent;
 }
 
+/**
+ * A `revalidate.tags` entry goes out as a purge key on every response of the route
+ * (`render-isr.ts`), so one a CDN would split is refused HERE, naming the file. Asked of
+ * `@ultimat3/cache`'s own screen rather than restated: found at serve time it is a 500 on a
+ * public page, found at purge time it is a document nothing can clear.
+ */
+function assertPurgeableTags(file: string, tags: readonly CacheTag[] | undefined): void {
+  for (const owned of tags ?? []) {
+    try {
+      surrogateKeys([owned], file);
+    } catch (error) {
+      if (!isUltimateError(error) || error.code !== 'X_CACHE_PURGE_FAILED') throw error;
+      const wire = renderFixLiteral(serializeTag(owned), '<the tag>');
+      throw new RouteModeInvalidError(
+        `${file} declares revalidate tag ${wire}, which cannot be a CDN purge key — a key is split on whitespace and commas and capped at 1024 bytes, so every response of the route would carry one no purge can name`,
+        `edit revalidate.tags in ${file}: replace ${wire} with a tag whose entity and id carry no whitespace or comma`,
+      );
+    }
+  }
+}
+
 /** Register a route and enforce every invariant that needs the surrounding module. */
 export function registerRoute<TData = RouteData>(
   input: RegisterRouteInput<TData>,
@@ -292,6 +281,8 @@ export function registerRoute<TData = RouteData>(
     suspenseBoundaries,
   });
 
+  assertPurgeableTags(input.file, config.revalidate?.tags);
+
   const existing = routes.get(path);
   if (existing !== undefined && existing.file !== input.file) {
     throw new RouteDuplicateError(
@@ -359,6 +350,7 @@ export function registerMountedRoutes(
   for (const route of declared) {
     const file = routes.get(route.path)?.file;
     if (file !== undefined) throw mountCollision(route.path, file, mount);
+    assertPurgeableTags(mount.file, route.config.revalidate?.tags);
   }
   setMountedRoutes(mount, declared);
   described = undefined;
@@ -439,7 +431,6 @@ const descriptorOf = (
   islands: config.islands.map((spec) => spec.moduleId),
   islandSources: config.islands.map((spec) => spec.src),
   budgetJs: config.budget.js ?? null,
-  budgetLcp: config.budget.lcp ?? null,
 });
 
 /** See `RouteDescriptor.personal`. */

package/src/render-html.ts

@@ -11,7 +11,7 @@ import {
   IslandPropsInvalidError,
   PrerenderFailedError,
 } from './errors';
-import { escapeText, renderAttributes, VOID_ELEMENTS } from './html';
+import { escapeHtml, renderAttributes, VOID_ELEMENTS } from './html';
 import { emitIslandAttributes, emitIslandProps } from './hydrate';
 import type { IslandNode } from './island';
 import { isIslandNode } from './island';
@@ -62,8 +62,8 @@ export interface RenderHtmlOptions {
 async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): Promise<string> {
   assertDepth(depth);
   if (value === null || value === undefined || value === false || value === true) return '';
-  if (typeof value === 'string') return escapeText(value);
-  if (typeof value === 'number' || typeof value === 'bigint') return escapeText(String(value));
+  if (typeof value === 'string') return escapeHtml(value);
+  if (typeof value === 'number' || typeof value === 'bigint') return escapeHtml(String(value));
   if (value instanceof Promise) return unwrap(await value, depth, walk);
   // Before the array branch, never after: an island node IS an array — the only object shape the
   // configured `JSX.Element` admits — so the generic branch would render its empty contents and
@@ -75,7 +75,7 @@ async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): P
   }
   if (isJsxNode(value)) return renderNode(value.type, value.props, depth, walk);
   if (typeof value === 'function') return unwrap((value as () => unknown)(), depth + 1, walk);
-  return escapeText(String(value));
+  return escapeHtml(String(value));
 }
 
 /**