@ultimat3/render 26.1.1 → 27.1.0

package/CLAUDE.md

@@ -4,7 +4,7 @@ Owns: the `route` primitive, the four render modes, the route table, the surface
 islands + budgets, hydration directives, `<head>` merge, **the server JSX runtime and the two Bun
 loaders that make an app's `.tsx` and `.scss` runnable**.
 
-**Two entry points, disjoint.** `"."` (`index.ts`) is the CLIENT half and bundles for the browser;
+**Three entry points**; `"."` and `"./server"` disjoint. `"."` (`index.ts`) is the CLIENT half and bundles for the browser;
 `"./server"` (`server.ts`) is the build-time half — `css-modules`, `module-loader`, `render-html`,
 `render-isr`, `render-ssr`, `render-static`, `render-stream` — and does not (`css-modules.ts` needs
 `node:url`, which a browser build cannot link; no `sideEffects` value repairs that). Never re-export
@@ -91,7 +91,7 @@ axiom 6). Never `cli` (upward).
 | An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts`. |
 | ISR registration | reconciled against `store.paths()` after every generation (`forgetEvictedPaths`). |
 | Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15 s), `holeTimeoutMs: null` to opt out, otherwise a whole number ≥ 1. A hole reveals exactly once — promise, rejection or deadline. |
-| Errors | `errors.ts` subclasses only. Never a bare `Error`, never a bare `TODO`. |
+| Errors | `errors.ts` subclasses only, but for `navigation-errors.ts` (re-exported; keeps `./client` off the table). Never a bare `Error`, never a bare `TODO`. |
 | Policy | render checks *presence* only. Evaluation belongs to `@ultimat3/policy`. |
 | A gated route is never a cached one | `modes.ts` refuses `policy` on both `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `ssr` is the one gated mode. |
 | Responses | return `RenderResult`. `@ultimat3/http` builds the `Response`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "26.1.1",
+  "version": "27.1.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "26.1.1",
-    "@ultimat3/core": "26.1.1",
-    "@ultimat3/http": "26.1.1",
-    "@ultimat3/i18n": "26.1.1",
-    "@ultimat3/seo": "26.1.1",
+    "@ultimat3/cache": "27.1.0",
+    "@ultimat3/core": "27.1.0",
+    "@ultimat3/http": "27.1.0",
+    "@ultimat3/i18n": "27.1.0",
+    "@ultimat3/seo": "27.1.0",
     "sass": "1.105.1"
   }
 }

package/src/mounted-routes.ts

@@ -14,6 +14,12 @@ export interface RouteMount {
   readonly by: string;
   /** Every permission the route's own screen decides on, coarse gate first. */
   readonly permissions: readonly string[];
+  /**
+   * `true` when an app FILE serves the path in the mount's place — a config the mounter issued
+   * for it (`RouteMountInput.claimable`). The descriptor's `file` is then that file. Absent
+   * otherwise, never `false`.
+   */
+  readonly claimed?: true;
 }
 
 /** The mount a set of routes belongs to. `key` is what a re-declaration replaces. */
@@ -23,6 +29,13 @@ export interface RouteMountInput {
   /** What `RouteDescriptor.file` reads for these routes: the package, since no app file is. */
   readonly file: string;
   readonly surface: Exclude<Surface, 'shared'>;
+  /**
+   * May the file route declaring `config` serve `path` in the mount's place? The MOUNTER's
+   * answer, never render's: only the package that mounted a path knows which configs it issued
+   * (and with what guard inside). Asked with the config the module EXPORTED, by identity. Absent:
+   * no file may, and a file on a mounted path is `X_ROUTE_DUPLICATE`.
+   */
+  readonly claimable?: (path: string, config: RouteConfig) => boolean;
 }
 
 export interface MountedRouteInput {
@@ -62,6 +75,10 @@ export function clearMountedRoutes(): void {
   mounted.clear();
 }
 
+/** Did the mount that owns `route` issue `config` for its path? */
+export const claimedBy = (route: MountedRoute, config: RouteConfig): boolean =>
+  route.mount.claimable?.(route.path, config) === true;
+
 /** One URL, one claimant — a file and a mount on the same path is two servers for it. */
 export const mountCollision = (
   path: string,

package/src/registry.ts

@@ -20,6 +20,7 @@ import {
 import { assertModeInvariants, defaultIslandBudget } from './modes';
 import type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-routes';
 import {
+  claimedBy,
   clearMountedRoutes,
   mountCollision,
   mountedAt,
@@ -87,8 +88,9 @@ export interface RouteDescriptor {
   readonly islandSources: readonly string[];
   readonly budgetJs: string | 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.
+   * Present on a route a package mounted: who mounted it and every permission that gates it.
+   * `file` is the package — unless `mount.claimed`, when an app file serves the path in the
+   * mount's place and `file` is that file. Absent on every other file route.
    */
   readonly mount?: RouteMount;
 }
@@ -212,6 +214,11 @@ function toUrlSegment(segment: string): string {
 }
 
 const routes = new Map<string, RouteEntry>();
+/**
+ * The config each path's module EXPORTED, before `withIslandBudget` may have copied it: a mount's
+ * `claimable` answers by identity, and the entry's own config is not always that object.
+ */
+const declaredConfigs = new Map<string, RouteConfig>();
 /** The table `describePages()` last built, dropped whenever a route registers or the registry clears. */
 let described: readonly RouteDescriptor[] | undefined;
 
@@ -297,7 +304,9 @@ export function registerRoute<TData = RouteData>(
     );
   }
   const claimed = mountedAt(path);
-  if (claimed !== undefined) throw mountCollision(path, input.file, claimed.mount);
+  if (claimed !== undefined && !claimedBy(claimed, input.config as RouteConfig)) {
+    throw mountCollision(path, input.file, claimed.mount);
+  }
 
   const entry: RouteEntry<TData> = {
     file: input.file,
@@ -318,6 +327,7 @@ export function registerRoute<TData = RouteData>(
     ...(input.component === undefined ? {} : { component: input.component }),
   };
   routes.set(path, entry as RouteEntry);
+  declaredConfigs.set(path, input.config as RouteConfig);
   described = undefined;
   return entry;
 }
@@ -355,7 +365,9 @@ export function registerMountedRoutes(
 ): void {
   for (const route of declared) {
     const file = routes.get(route.path)?.file;
-    if (file !== undefined) throw mountCollision(route.path, file, mount);
+    const config = declaredConfigs.get(route.path);
+    const claimed = config !== undefined && claimedBy({ ...route, mount }, config);
+    if (file !== undefined && !claimed) throw mountCollision(route.path, file, mount);
     assertPurgeableTags(mount.file, route.config.revalidate?.tags);
   }
   setMountedRoutes(mount, declared);
@@ -364,6 +376,7 @@ export function registerMountedRoutes(
 
 export function clearRoutes(): void {
   routes.clear();
+  declaredConfigs.clear();
   clearMountedRoutes();
   described = undefined;
 }
@@ -395,21 +408,39 @@ export function describePages(): readonly RouteDescriptor[] {
 }
 
 function buildDescriptors(): RouteDescriptor[] {
-  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] },
-    }),
-  );
+  const mounted = mountedRoutes();
+  // A path an app file claimed is ONE row: the file's, still naming the mount that gates it.
+  const claimOf = (path: string): RouteMount | undefined => {
+    const route = mounted.find((candidate) => candidate.path === path);
+    return route === undefined
+      ? undefined
+      : { by: route.mount.by, permissions: [...route.permissions], claimed: true };
+  };
+  const files = routeEntries().map((entry): RouteDescriptor => {
+    const row = descriptorOf(
+      entry.path,
+      entry.file,
+      entry.surface,
+      entry.config,
+      entry.pattern.keys.length,
+    );
+    const claim = claimOf(entry.path);
+    return claim === undefined ? row : { ...row, mount: claim };
+  });
+  const mounts = mounted
+    .filter((route) => !routes.has(route.path))
+    .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));