@ultimat3/core 22.7.0 → 22.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.7.0",
+  "version": "22.8.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.7.0"
+    "@ultimat3/schema": "22.8.0"
   }
 }

package/src/client-transport.ts

@@ -21,6 +21,7 @@ import type { Answer, TransportRequest } from './client-dispatch';
 import { dispatch } from './client-dispatch';
 import { transportFailed } from './client-problem';
 import { scopeChanged } from './client-scope-error';
+import { notifyClientWrite } from './client-writes';
 import type { RecordEnvelope } from './record-envelope';
 import { decodeRecordEnvelope } from './record-envelope';
 import { pageClient, recordSink } from './record-sink';
@@ -31,22 +32,31 @@ export async function clientTransport<T = unknown>(req: TransportRequest): Promi
   const read = req.method === 'GET';
   const issued = pageClient().scope.epoch;
   const flight = req.flight;
-  const answer: Answer =
-    flight === undefined
-      ? await dispatch(req, read, issued, undefined)
-      : await flight.run({
-          // A mutation never joins another mutation, idempotency key or not: the key is for the
-          // server's replay, and sharing one dispatch would hide the second intent from it.
-          key: read ? flight.keyFor(req.url, { signal: req.signal, fresh: req.fresh }) : undefined,
-          abortable: read,
-          // A stream is read once, so a second attempt re-sends a body that is already spent —
-          // and fails as the network would, until the attempts run out. One attempt, always.
-          retry: req.rawBody instanceof ReadableStream ? ONCE : req.retry,
-          run: (signal) => dispatch(req, read, issued, signal),
-          // `dispatch` makes every wire failure `X_CLIENT_TRANSPORT_FAILED`; a bare throw that
-          // reaches the flight is a caller hook's, never the network's.
-          classified: true,
-        });
+  let answer: Answer;
+  try {
+    answer =
+      flight === undefined
+        ? await dispatch(req, read, issued, undefined)
+        : await flight.run({
+            // A mutation never joins another mutation, idempotency key or not: the key is for the
+            // server's replay, and sharing one dispatch would hide the second intent from it.
+            key: read
+              ? flight.keyFor(req.url, { signal: req.signal, fresh: req.fresh })
+              : undefined,
+            abortable: read,
+            // A stream is read once, so a second attempt re-sends a body that is already spent —
+            // and fails as the network would, until the attempts run out. One attempt, always.
+            retry: req.rawBody instanceof ReadableStream ? ONCE : req.retry,
+            run: (signal) => dispatch(req, read, issued, signal),
+            // `dispatch` makes every wire failure `X_CLIENT_TRANSPORT_FAILED`; a bare throw that
+            // reaches the flight is a caller hook's, never the network's.
+            classified: true,
+          });
+  } finally {
+    // After it settles, landed or not — a write that failed on the wire may still have committed,
+    // and announcing it before it settled left a window for a prefetch to cache the old state.
+    if (!read) notifyClientWrite(req.url);
+  }
   const current = pageClient().scope.epoch;
   // A read that raced the abort still belongs to the previous principal.
   if (read && current !== issued) throw scopeChanged(req.url, issued, current);

package/src/client-writes.ts

@@ -0,0 +1,40 @@
+/**
+ * "A write just went through this tab's client": the one signal a page-side cache of server
+ * answers (the client router's prefetched documents) needs to stop trusting them. Emitted by
+ * `clientTransport` for every non-GET, landed or failed — a failed write may still have committed.
+ * On `globalThis` under one `Symbol.for` key, like the page client: every bundle's copy of core
+ * shares one listener set.
+ */
+
+const KEY = Symbol.for('ultimate.client-writes');
+
+type Listener = (url: string) => void;
+
+const listeners = (): Set<Listener> => {
+  const host = globalThis as unknown as Record<symbol, Set<Listener> | undefined>;
+  let set = host[KEY];
+  if (set === undefined) {
+    set = new Set();
+    host[KEY] = set;
+  }
+  return set;
+};
+
+/** Subscribe; returns the unsubscribe. A throwing listener never fails the write. */
+export function onClientWrite(fn: Listener): () => void {
+  const entry: Listener = (url) => fn(url);
+  listeners().add(entry);
+  return (): void => {
+    listeners().delete(entry);
+  };
+}
+
+export function notifyClientWrite(url: string): void {
+  for (const listener of [...listeners()]) {
+    try {
+      listener(url);
+    } catch {
+      // A cache that could not clear is the listener's defect; the write itself stands.
+    }
+  }
+}

package/src/config-navigation.ts

@@ -0,0 +1,67 @@
+// Single responsibility: the `navigation` block of `app.config.ts` — which surfaces move between
+// their pages by client-side navigation over server-rendered documents (`@ultimat3/render`'s
+// `navigation.ts`), and the boot-time refusal of a surface that has no pages to navigate between.
+//
+// Split out of `config.ts` at its 500-line ceiling, the way `config-site.ts` and `config-pwa.ts`
+// were: shape, merge and screen are one subject.
+
+import { describeValue } from './error-render';
+
+/**
+ * The surfaces that render documents a browser navigates between. `api` answers JSON and `shared`
+ * renders nothing, so neither can opt in — and `navigation: { client: ['api'] }` is refused rather
+ * than accepted and ignored.
+ */
+export const NAVIGATION_SURFACES = ['site', 'app'] as const;
+export type NavigationSurface = (typeof NAVIGATION_SURFACES)[number];
+
+/**
+ * `client` lists the surfaces whose same-surface links and forms are followed by the client
+ * router: it fetches the next document, swaps it in, and keeps the tab's islands, sockets and
+ * scroll state alive. EMPTY BY DEFAULT — every navigation is a full document load, and a surface
+ * that does not opt in ships no router byte (axiom 6: a `site/` page stays 0kb).
+ */
+export interface NavigationConfig {
+  readonly client: readonly NavigationSurface[];
+}
+
+export interface NavigationSection {
+  readonly navigation: NavigationConfig;
+}
+
+export interface NavigationSectionInput {
+  readonly navigation?: { readonly client?: readonly NavigationSurface[] | undefined } | undefined;
+}
+
+/** A whole-value key: the last layer that listed surfaces wins, as `locales` does. */
+export function mergeNavigation(layers: readonly NavigationSectionInput[]): NavigationSection {
+  let client: readonly NavigationSurface[] = [];
+  for (const layer of layers) {
+    const said = layer.navigation?.client;
+    if (said !== undefined) client = said;
+  }
+  return { navigation: { client } };
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function navigationIssues(config: NavigationSection, issues: string[]): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const client: unknown = config.navigation.client;
+  if (!Array.isArray(client)) {
+    issues.push(`navigation.client must be a list of surfaces, not ${describeValue(client)}`);
+    return;
+  }
+  const seen = new Set<unknown>();
+  for (const surface of client as readonly unknown[]) {
+    if (!NAVIGATION_SURFACES.some((known) => known === surface)) {
+      // A string is a surface name worth echoing; anything else goes through `describeValue`.
+      const said = typeof surface === 'string' ? `"${surface}"` : describeValue(surface);
+      issues.push(
+        `navigation.client contains ${said}, not one of ${NAVIGATION_SURFACES.join(', ')}`,
+      );
+    } else if (seen.has(surface)) {
+      issues.push(`navigation.client lists "${String(surface)}" twice`);
+    }
+    seen.add(surface);
+  }
+}

package/src/config.ts

@@ -12,6 +12,8 @@ import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
 import type { DrainConfig, HealthConfig } from './config-health';
 import { readinessModeIssue } from './config-health';
 import { type Input, lastSaid, layered } from './config-merge';
+import type { NavigationConfig, NavigationSectionInput } from './config-navigation';
+import { mergeNavigation, navigationIssues } from './config-navigation';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
 import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
@@ -205,6 +207,7 @@ export interface AppConfig {
   readonly health: HealthConfig;
   readonly site: SiteConfig;
   readonly seo: SeoConfig;
+  readonly navigation: NavigationConfig;
 }
 
 /** `mcp` is the only member, and it is NESTED — `Input<AiConfig>` would make it all-or-nothing. */
@@ -223,7 +226,7 @@ export interface PwaConfigInput extends Omit<Input<PwaConfig>, 'offline'> {
   readonly offline?: Input<PwaOfflineConfig> | undefined;
 }
 
-export interface AppConfigInput extends SiteSectionsInput {
+export interface AppConfigInput extends SiteSectionsInput, NavigationSectionInput {
   readonly name: string;
   readonly locales?: readonly string[] | undefined;
   readonly defaultLocale?: string | undefined;
@@ -265,7 +268,7 @@ function isLocale(value: string): boolean {
   }
 }
 
-function defaults(name: string): Omit<AppConfig, 'name' | 'site' | 'seo'> {
+function defaults(name: string): Omit<AppConfig, 'name' | 'site' | 'seo' | 'navigation'> {
   return {
     locales: ['en'],
     defaultLocale: 'en',
@@ -373,10 +376,10 @@ function validate(config: AppConfig): void {
   }
 
   // What an install needs, asked at BOOT and not at emit — `config-pwa.ts` owns the rules and the
-  // remedy, because `pwa.enabled` turning four other requirements on is a question about that block
-  // and nothing else here.
+  // remedy: `pwa.enabled` turning four other requirements on is a question about that block alone.
   if (pwaIssues(config.pwa, issues)) pwaFix.push(PWA_FIX);
   siteIssues(config, issues);
+  navigationIssues(config, issues);
 
   // A rung the ladder cannot build is the defect this key had: `sortTiers` places a name by its
   // index in `CACHE_TIERS`, and a name missing from it sorts to `-1` — AHEAD of the request memo.
@@ -489,6 +492,7 @@ export function defineConfig(
       layers.map((layer) => layer.health),
     ),
     ...mergeSite(layers),
+    ...mergeNavigation(layers),
   };
 
   validate(config);

package/src/index.ts

@@ -90,6 +90,7 @@ export { clientTransport } from './client-transport';
 /** What a typed client puts on the wire. `retryForStatus` is what fills a failure's `retry`. */
 export type { WireAnswer } from './client-wire';
 export { FRAMEWORK_CODE, problemOf, retryForStatus, traceHeaders } from './client-wire';
+export { notifyClientWrite, onClientWrite } from './client-writes';
 export { type Clock, type FrozenClock, frozenClock, systemClock } from './clock';
 export type {
   AiConfig,
@@ -112,6 +113,13 @@ export type {
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
 export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
 export { READINESS_MODES } from './config-health';
+export type {
+  NavigationConfig,
+  NavigationSection,
+  NavigationSectionInput,
+  NavigationSurface,
+} from './config-navigation';
+export { NAVIGATION_SURFACES } from './config-navigation';
 export type {
   PwaColors,
   PwaConfig,
@@ -578,6 +586,10 @@ export { OUTBOX_DRAIN_MESSAGE, type OutboxDrainMessage } from './outbox-drain';
 export {
   APP_UPDATE_MESSAGE,
   CLIENT_BUILD_META,
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SCOPE_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,

package/src/page-meta.ts

@@ -39,3 +39,26 @@ export const CLIENT_SYNC_WORKER_META = 'ultimate-sync-worker';
  * place it learns which types `@ultimat3/realtime`'s persister may write. Absent = none.
  */
 export const CLIENT_PERSIST_META = 'ultimate-persist';
+
+/**
+ * The client router's request headers (`@ultimat3/render`'s `navigation.ts`), read by
+ * `@ultimat3/http`'s navigation gate before any app code runs. `soft` is a visit the router will
+ * swap in; `prefetch` is a guess nobody clicked yet — answered only by a route that opted in.
+ */
+export const CLIENT_NAVIGATION_HEADER = 'x-ultimate-navigation';
+
+/** `<app>:<surface>` of the document the router is running in — the only pages it may swap in. */
+export const CLIENT_NAVIGATION_SURFACE_HEADER = 'x-ultimate-surface';
+
+/**
+ * The principal of the document the router is running in, when it carries `ultimate-scope`.
+ * Absent means an unscoped document. A page rendered for someone else is refused before `load`.
+ */
+export const CLIENT_NAVIGATION_SCOPE_HEADER = 'x-ultimate-navigation-scope';
+
+/**
+ * On a `204` to a router request: "load THIS with a real navigation". The server answers it
+ * instead of a redirect (the handler already ran; the browser follows once) and instead of a page
+ * that must be a real document load (nothing ran; the browser loads it once).
+ */
+export const CLIENT_NAVIGATION_LOCATION_HEADER = 'x-ultimate-location';

package/src/page.ts

@@ -20,6 +20,7 @@ export { actionPath, queryPath, splitWords } from './client-paths';
 export type { ClientScope } from './client-scope';
 export { onRescope, rescope } from './client-scope';
 export { clientTransport } from './client-transport';
+export { notifyClientWrite, onClientWrite } from './client-writes';
 export { type Clock, systemClock } from './clock';
 export type { ConflictPolicy, Row } from './conflict-policy';
 // Registry-free: it merges two rows and throws nothing, so the page's record store settles a
@@ -38,6 +39,10 @@ export { OUTBOX_DRAIN_MESSAGE } from './outbox-drain';
 export {
   APP_UPDATE_MESSAGE,
   CLIENT_BUILD_META,
+  CLIENT_NAVIGATION_HEADER,
+  CLIENT_NAVIGATION_LOCATION_HEADER,
+  CLIENT_NAVIGATION_SCOPE_HEADER,
+  CLIENT_NAVIGATION_SURFACE_HEADER,
   CLIENT_PERSIST_META,
   CLIENT_SCOPE_HEADER,
   CLIENT_SCOPE_META,