@ultimat3/render 22.15.0 → 24.0.0

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,19 +5,32 @@
  * 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';
 import { assertModeInvariants, defaultIslandBudget } from './modes';
+import type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
+import {
+  clearMountedRoutes,
+  mountCollision,
+  mountedAt,
+  mountedRoutes,
+  setMountedRoutes,
+} from './mounted-routes';
 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';
 
@@ -82,16 +95,14 @@ 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.
+   */
+  readonly mount?: RouteMount;
 }
 
-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;
-}
+export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
 
 /**
  * `apps/web/site/blog/[slug]/page.tsx` → `{ surface: 'site', path: '/blog/:slug' }`.
@@ -194,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;
@@ -241,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>,
@@ -277,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(
@@ -284,6 +290,8 @@ export function registerRoute<TData = RouteData>(
       `rename or delete one of them — the route table is keyed by URL`,
     );
   }
+  const claimed = mountedAt(path);
+  if (claimed !== undefined) throw mountCollision(path, input.file, claimed.mount);
 
   const entry: RouteEntry<TData> = {
     file: input.file,
@@ -329,8 +337,28 @@ function withIslandBudget<TData>(config: RouteConfig<TData>, surface: Surface):
   return Object.freeze(derived);
 }
 
+/**
+ * Declare the routes a package MOUNTS — screens no surface file exists for, like the admin's — so
+ * the one route list carries them. Described, never rendered here: the mounting host serves them,
+ * and `routeEntries()` stays the pages a file declares. Re-declaring a `key` replaces its set,
+ * because `x dev` re-evaluates the module that declared it on every save.
+ */
+export function registerMountedRoutes(
+  mount: RouteMountInput,
+  declared: readonly MountedRouteInput[],
+): void {
+  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;
+}
+
 export function clearRoutes(): void {
   routes.clear();
+  clearMountedRoutes();
   described = undefined;
 }
 
@@ -361,26 +389,50 @@ export function describeRoutes(): readonly RouteDescriptor[] {
 }
 
 function buildDescriptors(): RouteDescriptor[] {
-  return routeEntries().map((entry) => ({
-    path: entry.path,
-    file: entry.file,
-    surface: entry.surface,
-    mode: entry.config.render,
-    offline: entry.config.offline,
-    hydrate: entry.config.hydrate,
-    revalidateTags: tagKeys(entry.config.revalidate?.tags),
-    revalidateTtl: entry.config.revalidate?.ttl ?? null,
-    prerenderable: entry.config.prerender !== undefined,
-    dynamic: entry.pattern.keys.length > 0,
-    hasPolicy: entry.config.policy !== undefined,
-    personal: isPersonal(entry.config),
-    islands: entry.islands,
-    islandSources: entry.config.islands.map((spec) => spec.src),
-    budgetJs: entry.config.budget.js ?? null,
-    budgetLcp: entry.config.budget.lcp ?? null,
-  }));
+  const files = routeEntries().map((entry) =>
+    descriptorOf(entry.path, entry.file, entry.surface, entry.config, entry.pattern.keys.length),
+  );
+  const mounts = mountedRoutes().map(
+    (route): RouteDescriptor => ({
+      ...descriptorOf(
+        route.path,
+        route.mount.file,
+        route.mount.surface,
+        route.config,
+        compilePattern(route.path).keys.length,
+      ),
+      mount: { by: route.mount.by, permissions: [...route.permissions] },
+    }),
+  );
+  return mounts.length === 0
+    ? files
+    : [...files, ...mounts].sort((a, b) => byCodeUnit(a.path, b.path));
 }
 
+const descriptorOf = (
+  path: string,
+  file: string,
+  surface: Surface,
+  config: RouteConfig,
+  params: number,
+): RouteDescriptor => ({
+  path,
+  file,
+  surface,
+  mode: config.render,
+  offline: config.offline,
+  hydrate: config.hydrate,
+  revalidateTags: tagKeys(config.revalidate?.tags),
+  revalidateTtl: config.revalidate?.ttl ?? null,
+  prerenderable: config.prerender !== undefined,
+  dynamic: params > 0,
+  hasPolicy: config.policy !== undefined,
+  personal: isPersonal(config),
+  islands: config.islands.map((spec) => spec.moduleId),
+  islandSources: config.islands.map((spec) => spec.src),
+  budgetJs: config.budget.js ?? null,
+});
+
 /** See `RouteDescriptor.personal`. */
 function isPersonal(config: RouteConfig): boolean {
   if (config.policy !== undefined || config.render === 'stream') return true;

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));
 }
 
 /**