@ultimat3/core 22.14.0 → 22.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.14.0",
+  "version": "22.15.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.14.0"
+    "@ultimat3/schema": "22.15.0"
   }
 }

package/src/config-navigation.ts

@@ -6,6 +6,7 @@
 // were: shape, merge and screen are one subject.
 
 import { describeValue } from './error-render';
+import { ConfigInvalidError } from './errors';
 
 /**
  * The surfaces that render documents a browser navigates between. `api` answers JSON and `shared`
@@ -23,28 +24,146 @@ export type NavigationSurface = (typeof NAVIGATION_SURFACES)[number];
  */
 export interface NavigationConfig {
   readonly client: readonly NavigationSurface[];
+  readonly speculation: SpeculationConfig;
 }
 
+/**
+ * How eagerly a browser may fetch a link's document before the click, on a page that carries no
+ * client router. `'moderate'`: on pointer rest or pointer down. `'conservative'`: on pointer down
+ * only. `'eager'` and `'immediate'` are not offered — they fetch links nobody pointed at.
+ */
+export const SPECULATION_EAGERNESS = ['moderate', 'conservative'] as const;
+export type SpeculationEagerness = (typeof SPECULATION_EAGERNESS)[number];
+
+/**
+ * Speculation Rules (`<script type="speculationrules">`) for the documents a browser navigates
+ * between WITHOUT the client router — the 0kb answer to a slow full-page load. PREFETCH only, never
+ * prerender: a prefetch runs no script of the next page, so no analytics hit and no island boots
+ * for a page nobody opened. ON BY DEFAULT at `'moderate'`; `prefetch: false` emits nothing.
+ *
+ * Only pages the route table knows to be a pure read are candidates (`@ultimat3/cli`'s
+ * `page-speculation.ts`); `exclude` removes more, as URL patterns (`/blog/*`, `/legal/:doc`).
+ */
+export interface SpeculationConfig {
+  readonly prefetch: SpeculationEagerness | false;
+  readonly exclude: readonly string[];
+}
+
+export const DEFAULT_SPECULATION: SpeculationConfig = Object.freeze({
+  prefetch: 'moderate',
+  exclude: Object.freeze([]) as readonly string[],
+});
+
 export interface NavigationSection {
   readonly navigation: NavigationConfig;
 }
 
 export interface NavigationSectionInput {
-  readonly navigation?: { readonly client?: readonly NavigationSurface[] | undefined } | undefined;
+  readonly navigation?:
+    | {
+        readonly client?: readonly NavigationSurface[] | undefined;
+        readonly speculation?:
+          | {
+              readonly prefetch?: SpeculationEagerness | false | undefined;
+              readonly exclude?: readonly string[] | undefined;
+            }
+          | undefined;
+      }
+    | undefined;
 }
 
-/** A whole-value key: the last layer that listed surfaces wins, as `locales` does. */
+/**
+ * Whole-value keys: the last layer that listed surfaces wins, as `locales` does — and so does the
+ * last one that set `speculation.prefetch` or listed `speculation.exclude`, each on its own.
+ */
 export function mergeNavigation(layers: readonly NavigationSectionInput[]): NavigationSection {
   let client: readonly NavigationSurface[] = [];
+  let prefetch: SpeculationEagerness | false = DEFAULT_SPECULATION.prefetch;
+  let exclude: readonly string[] = DEFAULT_SPECULATION.exclude;
+  // A layer that wrote something other than an object (`speculation: 'off'`, `null`, a list) has
+  // no key to merge. It is carried through AS WRITTEN so `navigationIssues` refuses it — dropped
+  // here, the app would run at the default it believed it had turned off.
+  let unmergeable: { readonly said: unknown } | undefined;
   for (const layer of layers) {
     const said = layer.navigation?.client;
     if (said !== undefined) client = said;
+    const speculation: unknown = layer.navigation?.speculation;
+    if (speculation === undefined) continue;
+    if (!isSpeculationObject(speculation)) {
+      unmergeable ??= { said: speculation };
+      continue;
+    }
+    if (speculation.prefetch !== undefined) prefetch = speculation.prefetch;
+    if (speculation.exclude !== undefined) exclude = speculation.exclude;
+  }
+  const speculation =
+    unmergeable === undefined ? { prefetch, exclude } : (unmergeable.said as SpeculationConfig);
+  return { navigation: { client, speculation } };
+}
+
+type SpeculationInput = NonNullable<
+  NonNullable<NavigationSectionInput['navigation']>['speculation']
+>;
+
+const isSpeculationObject = (value: unknown): value is SpeculationInput =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * A pattern is emitted inside a JSON string the browser parses as a URL pattern: it must be a
+ * same-origin PATH, so anything not starting with `/` (a host, a scheme, `*`) is refused.
+ */
+function speculationIssues(speculation: unknown, issues: string[]): void {
+  if (!isSpeculationObject(speculation)) {
+    issues.push(`navigation.speculation must be an object, not ${describeValue(speculation)}`);
+    return;
+  }
+  const { prefetch, exclude } = speculation as { prefetch?: unknown; exclude?: unknown };
+  if (prefetch !== false && !SPECULATION_EAGERNESS.some((known) => known === prefetch)) {
+    issues.push(
+      `navigation.speculation.prefetch must be ${SPECULATION_EAGERNESS.join(', ')} or false, not ${describeValue(prefetch)}`,
+    );
+  }
+  if (!Array.isArray(exclude)) {
+    issues.push(
+      `navigation.speculation.exclude must be a list of URL patterns, not ${describeValue(exclude)}`,
+    );
+    return;
+  }
+  for (const pattern of exclude as readonly unknown[]) {
+    if (typeof pattern !== 'string' || !pattern.startsWith('/')) {
+      issues.push(
+        `navigation.speculation.exclude contains ${describeValue(pattern)}, not a path pattern starting with "/"`,
+      );
+    }
+  }
+}
+
+/**
+ * `navigation.speculation` as some reader OUTSIDE `defineConfig` found it (`@ultimat3/cli` imports
+ * the app's config module structurally): the defaults for what it does not say, and the SAME
+ * refusal `defineConfig` gives for what it says wrongly. One validator — a second reader that
+ * coerced `'eager'` to `'moderate'` or dropped a bad pattern would serve rules the app never wrote.
+ */
+export function resolveSpeculation(said: unknown): SpeculationConfig {
+  if (said === undefined) return DEFAULT_SPECULATION;
+  const { speculation } = mergeNavigation([
+    { navigation: { speculation: said as SpeculationInput } },
+  ]).navigation;
+  const issues: string[] = [];
+  speculationIssues(speculation, issues);
+  if (issues.length > 0) {
+    throw new ConfigInvalidError({
+      cause: issues.join('; '),
+      fix: 'Correct navigation.speculation in app.config.ts: prefetch is "moderate", "conservative" or false, and exclude is a list of path patterns starting with "/"',
+      meta: { issues },
+    });
   }
-  return { navigation: { client } };
+  return speculation;
 }
 
 /** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
 export function navigationIssues(config: NavigationSection, issues: string[]): void {
+  speculationIssues(config.navigation.speculation, issues);
   // `unknown`: an untyped config file reaches this validator with whatever it wrote.
   const client: unknown = config.navigation.client;
   if (!Array.isArray(client)) {

package/src/index.ts

@@ -119,8 +119,15 @@ export type {
   NavigationSection,
   NavigationSectionInput,
   NavigationSurface,
+  SpeculationConfig,
+  SpeculationEagerness,
+} from './config-navigation';
+export {
+  DEFAULT_SPECULATION,
+  NAVIGATION_SURFACES,
+  resolveSpeculation,
+  SPECULATION_EAGERNESS,
 } from './config-navigation';
-export { NAVIGATION_SURFACES } from './config-navigation';
 export type {
   PwaColors,
   PwaConfig,