@ultimat3/render 22.15.0 → 24.0.0

package/src/jsx.ts

@@ -28,16 +28,37 @@ export function isJsxNode(value: unknown): value is JsxNode {
  * component reading `props.children` behaves the same whether its children came from the classic
  * factory's rest arguments or from an explicit `children` prop.
  */
+export function h(type: string, props: JsxProps | null, ...children: readonly unknown[]): JsxNode;
+/**
+ * A component, with the props IT declares. `JsxComponent` takes any record, so a component typed
+ * for its own props — an `island()`, a page's `Shell` — is not one under `strictFunctionTypes`,
+ * and a hand-written `h(Toggle, { label })` was refused where the `.tsx` loader's own call is not.
+ * The props are checked against the component here; `children` rides as the rest arguments.
+ */
+export function h<Props extends object>(
+  type: (props: Props) => unknown,
+  props: Omit<Props, 'children'> | null,
+  ...children: readonly unknown[]
+): JsxNode;
 export function h(
   type: string | JsxComponent,
   props: JsxProps | null,
   ...children: readonly unknown[]
+): JsxNode;
+export function h(
+  // `never` is the one parameter type every component's props satisfy.
+  type: string | ((props: never) => unknown),
+  props: object | null,
+  ...children: readonly unknown[]
 ): JsxNode {
-  const base = props ?? {};
-  if (children.length === 0) return { [JSX_NODE]: true, type, props: base };
+  // The overloads above are where a call is checked; a node carries the pair erased, which is all
+  // `render-html.ts` ever reads — it hands `props` back to the `type` it arrived with.
+  const erased = type as string | JsxComponent;
+  const base = (props ?? {}) as JsxProps;
+  if (children.length === 0) return { [JSX_NODE]: true, type: erased, props: base };
   return {
     [JSX_NODE]: true,
-    type,
+    type: erased,
     props: { ...base, children: children.length === 1 ? children[0] : children },
   };
 }

package/src/modes.ts

@@ -6,7 +6,7 @@
  */
 
 import type { HydrateStrategy, RenderMode } from '@ultimat3/core';
-import { HYDRATE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
+import { HYDRATE_STRATEGIES, RENDER_MODES, renderCauseValue } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
 import type { RouteConfig } from './route';
@@ -84,14 +84,14 @@ export function assertModeShape(config: RouteShape): void {
     : undefined;
   if (spec === undefined) {
     throw new RouteModeInvalidError(
-      `render: ${JSON.stringify(config.render)} is not a render mode`,
+      `render: ${renderCauseValue(config.render)} is not a render mode`,
       `use one of ${RENDER_MODES.join(' | ')}`,
     );
   }
 
   if (!HYDRATE_STRATEGIES.includes(config.hydrate)) {
     throw new RouteModeInvalidError(
-      `hydrate: ${JSON.stringify(config.hydrate)} is not a hydration strategy`,
+      `hydrate: ${renderCauseValue(config.hydrate)} is not a hydration strategy`,
       `use one of ${HYDRATE_STRATEGIES.join(' | ')}`,
     );
   }
@@ -200,6 +200,17 @@ export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext):
     );
   }
 
+  // `js` is the one budget anything measures. `lcp`, `css`, `cls` and `tbt` were each accepted,
+  // stored and compared by nothing that had a measurement — a false green — so a key the type no
+  // longer declares, arriving by a cast or from plain JS, is refused rather than carried.
+  for (const key of Object.keys(config.budget)) {
+    if (key === 'js') continue;
+    throw new RouteModeInvalidError(
+      `${ctx.file} declares budget.${key}, which nothing in the framework measures — only budget.js is weighed (x verify's budgets step). In ${ctx.file}, delete ${key}: the whole budget is the js key`,
+      "budget: { js: '10kb' }",
+    );
+  }
+
   // `budget` is always on the descriptor; `budget.js` is the field that stays optional,
   // and its absence is the failure — site/ is 0kb until a route says otherwise, in bytes.
   if (ctx.surface === 'site' && config.hydrate !== 'never' && config.budget.js === undefined) {

package/src/module-loader.ts

@@ -76,6 +76,11 @@ export interface Stylesheet {
   readonly file: string;
   /** The surface that owns it, or `null` for a package stylesheet shared by both graphs. */
   readonly surface: Surface | null;
+  /**
+   * A PACKAGE's sheet whose surface came from `claimStylesheets`, not from where the file sits.
+   * It is carried by that one surface and still ordered with the library — see `stylesheetOrder`.
+   */
+  readonly claimed: boolean;
   /** A plain (non-module) stylesheet: the tokens and the reset, which the cascade needs first. */
   readonly global: boolean;
   /**
@@ -118,8 +123,46 @@ export function registeredStylesheets(): readonly Stylesheet[] {
  */
 let stylesheetRoot: string | undefined;
 
+/**
+ * Directories a package claimed for ONE surface, longest first. A package's sheet has no surface
+ * of its own and rides both graphs — right for a design system, and the reason an app's static
+ * `site/` documents carried the admin's stylesheet for screens only `app/` serves (axiom 6).
+ */
+const claims: { readonly dir: string; readonly surface: Surface }[] = [];
+
+const claimedSurface = (path: string): Surface | undefined =>
+  claims.find((claim) => path.startsWith(`${claim.dir}/`))?.surface;
+
 const surfaceOfSheet = (path: string): Surface | null =>
-  surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+  claimedSurface(path) ?? surfaceUnder(stylesheetRoot ?? process.cwd(), path);
+
+/** Every registered sheet, classified again; the revision moves only when an answer does. */
+const reclassify = (): void => {
+  for (const [path, sheet] of stylesheets) {
+    const surface = surfaceOfSheet(path);
+    const claimed = claimedSurface(path) !== undefined;
+    if (surface === sheet.surface && claimed === sheet.claimed) continue;
+    stylesheets.set(path, { ...sheet, surface, claimed });
+    revision += 1;
+  }
+};
+
+/**
+ * A package says its own stylesheets belong to one surface: every sheet below `dir` is carried by
+ * documents of `surface` and by no other. Called by the package that OWNS the directory, with its
+ * own `import.meta.dir` — a sheet loads when its module is linked, which is before the claiming
+ * module's body runs, so a claim re-classifies what is already registered.
+ *
+ * A claim is a fact about a package's source, made once per process: `clearStylesheets()` leaves
+ * it standing, because the module that made it is cached and will not make it again.
+ */
+export function claimStylesheets(dir: string, surface: Surface): void {
+  const claimed = resolve(dir);
+  if (claims.some((claim) => claim.dir === claimed && claim.surface === surface)) return;
+  claims.push({ dir: claimed, surface });
+  claims.sort((a, b) => b.dir.length - a.dir.length);
+  reclassify();
+}
 
 /**
  * Names the app root the registry classifies against; `loadApp` calls it before importing a module.
@@ -132,12 +175,7 @@ const surfaceOfSheet = (path: string): Surface | null =>
 export function setStylesheetRoot(root: string | undefined): void {
   // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
   stylesheetRoot = root === undefined ? undefined : resolve(root);
-  for (const [path, sheet] of stylesheets) {
-    const surface = surfaceOfSheet(path);
-    if (surface === sheet.surface) continue;
-    stylesheets.set(path, { ...sheet, surface });
-    revision += 1;
-  }
+  reclassify();
 }
 
 /** Test seam: the registry is process-global because the module cache it mirrors is too. */
@@ -180,7 +218,8 @@ export function stylesFor(surface: Surface | null): string {
 }
 
 const OWNER_RANK = (sheet: Stylesheet): number =>
-  sheet.surface === null ? 0 : sheet.surface === 'shared' ? 1 : 2;
+  // A claimed sheet is a package's whichever surface carries it: library first.
+  sheet.surface === null || sheet.claimed ? 0 : sheet.surface === 'shared' ? 1 : 2;
 
 /** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
 const orderPath = (sheet: Stylesheet): string => {
@@ -233,6 +272,7 @@ export function loadStylesheet(
     stylesheets.set(path, {
       file: path,
       surface: surfaceOfSheet(path),
+      claimed: claimedSurface(path) !== undefined,
       global: isGlobalStylesheet(path),
       island,
       css: compiled.css,

package/src/mounted-routes.ts

@@ -0,0 +1,74 @@
+/**
+ * The routes a package MOUNTS — screens no surface file declares, like the admin's — held beside
+ * the file routes so `registry.ts` can describe both in the one route list. Storage and the
+ * collision rule only: nothing here renders, matches or serves.
+ */
+
+import { RouteDuplicateError } from './errors';
+import type { RouteConfig } from './route';
+import type { Surface } from './surfaces';
+
+/** Who put a mounted route in the table, and what it requires. */
+export interface RouteMount {
+  /** The call that declared it: `defineAdmin`. */
+  readonly by: string;
+  /** Every permission the route's own screen decides on, coarse gate first. */
+  readonly permissions: readonly string[];
+}
+
+/** The mount a set of routes belongs to. `key` is what a re-declaration replaces. */
+export interface RouteMountInput {
+  readonly key: string;
+  readonly by: string;
+  /** What `RouteDescriptor.file` reads for these routes: the package, since no app file is. */
+  readonly file: string;
+  readonly surface: Exclude<Surface, 'shared'>;
+}
+
+export interface MountedRouteInput {
+  readonly path: string;
+  readonly config: RouteConfig;
+  readonly permissions: readonly string[];
+}
+
+export interface MountedRoute extends MountedRouteInput {
+  readonly mount: RouteMountInput;
+}
+
+const mounted = new Map<string, readonly MountedRoute[]>();
+
+/** Every mounted route, in mount-declaration order. */
+export function mountedRoutes(): readonly MountedRoute[] {
+  return [...mounted.values()].flat();
+}
+
+/** The mounted route claiming `path`, if one does. */
+export function mountedAt(path: string): MountedRoute | undefined {
+  return mountedRoutes().find((route) => route.path === path);
+}
+
+/** Replaces the set under `mount.key`: a re-declaration is the same mount, saved again. */
+export function setMountedRoutes(
+  mount: RouteMountInput,
+  declared: readonly MountedRouteInput[],
+): void {
+  mounted.set(
+    mount.key,
+    declared.map((route) => ({ ...route, mount })),
+  );
+}
+
+export function clearMountedRoutes(): void {
+  mounted.clear();
+}
+
+/** One URL, one claimant — a file and a mount on the same path is two servers for it. */
+export const mountCollision = (
+  path: string,
+  file: string,
+  mount: RouteMountInput,
+): RouteDuplicateError =>
+  new RouteDuplicateError(
+    `${path} is claimed by both ${file} and ${mount.by}() — a route ${mount.file} mounts`,
+    `delete ${file}: ${mount.by}() already serves ${path}, and the route table is keyed by URL`,
+  );

package/src/navigation-dom.ts

@@ -39,6 +39,28 @@ export function anchorOf(target: EventTarget | null): HTMLAnchorElement | HTMLAr
 export const fieldText = (value: unknown): string =>
   value instanceof File ? value.name : String(value);
 
+/** Every lone CR, lone LF and CRLF in `text`, as CRLF. */
+const crlf = (text: string): string => text.replace(/\r\n|\r|\n/g, '\r\n');
+
+/**
+ * The fields as a GET query or a urlencoded body carries them — names and values with their line
+ * breaks normalised to CRLF, as the browser's own submit does (HTML's "convert to a list of
+ * name-value pairs"). A `<textarea>`'s value holds bare LFs; sent as they were, the router's
+ * submit and a native one delivered two different bodies for one form. A multipart body needs
+ * none of this: `fetch` encodes a `FormData` with the same normalisation.
+ */
+export const formPairs = (fields: FormData): readonly (readonly [string, string])[] =>
+  [...fields].map(([name, value]: [string, unknown]) => [crlf(name), crlf(fieldText(value))]);
+
+/**
+ * A form's action, resolved against the document — or the raw text when it does not resolve, which
+ * `formVerdict` leaves to the browser (`'unparsable'`) rather than throwing from a submit handler.
+ */
+export function formAction(raw: string, fallback: string, base: string): string {
+  const action = raw || fallback;
+  return URL.canParse(action, base) ? new URL(action, base).href : action;
+}
+
 /** The submitted fields, the submitter's own name/value included, as the browser would send. */
 export function formFields(form: HTMLFormElement, submitter: HTMLElement | null): FormData {
   try {
@@ -59,7 +81,7 @@ const hush = (): void => undefined;
 export async function transition(
   win: Window,
   apply: () => void,
-  track?: (running: RunningTransition | undefined) => void,
+  track?: (running: RunningTransition, finished: boolean) => void,
 ): Promise<void> {
   const doc = win.document as Document & {
     startViewTransition?: (update: () => void) => RunningTransition;
@@ -70,12 +92,12 @@ export async function transition(
     return;
   }
   const running = doc.startViewTransition(apply);
-  track?.(running);
+  track?.(running, false);
   running.ready.catch(hush);
-  running.finished.then(
-    () => track?.(undefined),
-    () => track?.(undefined),
-  );
+  // The transition itself, never "whichever is running": an older one finishing after a newer one
+  // started must not clear the newer one (the caller compares by identity).
+  const done = (): void => track?.(running, true);
+  running.finished.then(done, done);
   await running.updateCallbackDone;
 }
 

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();
+    },
+  };
+}