@ultimat3/render 25.2.0 → 26.0.0

package/CLAUDE.md

@@ -61,7 +61,7 @@ axiom 6). Never `cli` (upward).
 | A held island | `hold` on the collector (the host decides — the CLI holds realtime islands on a page-boot document); `island-hold.ts` owns the attribute, the inline `visibility:hidden`, the cap `ISLAND_HOLD_MS` and the runtime part. Emitted right after the prelude; booted at once, revealed TOGETHER on both mount arms, at the cap, or by CSS (`ISLAND_HOLD_REVEAL`, keyframes in `@ultimat3/ui`'s `global.scss`) — never hidden for good. `catchUp`'s `on` lets go after a mount it did not flush. `island-hold.test.ts`, `island-hold-replay.test.ts`. |
 | `idle`'s deadline | `IDLE_HYDRATE_TIMEOUT_MS`, interpolated INTO the runtime string and exported for `x shot`'s settle. |
 | Route truth | `registry.ts`. Never a second route list and never a second matcher — `@ultimat3/http`'s trie (`stages.ts`) serves requests. `routeFor` is an exact-path `Map` lookup. |
-| Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`. Anything else is `X_ROUTE_FILE_INVALID`. |
+| Route filename | `page.tsx` under `site/`/`app/` — `ROUTE_FILENAME`, keyed by `RouteSurface`. Anything else is `X_ROUTE_FILE_INVALID`, any file under `api/` or `shared/` included. |
 | Mounted routes | `registerMountedRoutes(mount, routes)` (`mounted-routes.ts`) — routes a PACKAGE mounts with no surface file (the admin's screens). In `describePages()` with `mount: { by, permissions }`, never in `routeEntries()`: described, not rendered here. Re-declaring a `key` replaces its set; a path a file route also claims is `X_ROUTE_DUPLICATE` in both orders. `RouteDescriptor.mount` is absent on a file route. |
 | Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED`; it fills in only the island budget. |
 | Descriptors | `describePages()` stays JSON-safe, sorted by path, deterministic. |

package/README.md

@@ -137,8 +137,7 @@ registered under is `X_ROUTE_POST_INVALID` at boot, as is `post` on a `static` p
 | gated (`policy`) | its `cache` is never `public`/`immutable` — one actor's document in a shared cache | `X_ROUTE_MODE_INVALID` |
 | `stream` | at least one `<Suspense>` boundary | `X_ROUTE_MODE_INVALID` |
 
-Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | ssr`,
-`api/` renders nothing, and a `site/` route that opts into hydration without a `budget.js`
+Plus surface rules: `site/` allows `static | isr | ssr`, `app/` allows `stream | ssr`, and a `site/` route that opts into hydration without a `budget.js`
 is a build error.
 
 ## The route table is the single source of route truth
@@ -154,11 +153,12 @@ sorted, JSON-safe descriptor list. Every downstream generator reads that one tab
 | `site/blog/[slug]/page.tsx` | `/blog/:slug` |
 | `site/docs/[...path]/page.tsx` | `/docs/*path` — `compilePattern` matches the bare `/docs` too, the path the static build writes for an empty rest |
 | `app/dashboard/page.tsx` | `/dashboard` |
-| `api/posts/route.ts` | `/api/posts` |
 
 The URL is the **directory** path under the surface; the filename names the kind of file, never a
-URL segment. One spelling per surface — `page.tsx` under `site/` and `app/`, `route.ts` under
-`api/` — and `registerRoute` refuses anything else with `X_ROUTE_FILE_INVALID`. `index.tsx` is not
+URL segment. One spelling — `page.tsx` under `site/` and `app/` — and `registerRoute` refuses anything else
+with `X_ROUTE_FILE_INVALID`, a file under `api/` included: `api/` holds the actions and queries
+`defineApi()` collects, and a wire format an action cannot speak is a plain HTTP route in the
+`routes` runtime override. `index.tsx` is not
 a page. Two spellings would make "is this file a route?" undecidable for the module scan, the
 boundary walk, `sw.js` and the author reading the folder; one spelling also co-locates
 `page.tsx` + `page.module.scss` + `page.test.ts`, and gives `[slug]/` its own stylesheet.

package/package.json

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

package/src/index.ts

@@ -206,6 +206,7 @@ export type {
   BoundaryViolation,
   ImportGraph,
   ImportRef,
+  RouteSurface,
   Surface,
   SurfaceSpec,
 } from './surfaces';

package/src/modes.ts

@@ -10,7 +10,7 @@ import { HYDRATE_STRATEGIES, RENDER_MODES, renderCauseValue } from '@ultimat3/co
 import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
 import type { RouteConfig } from './route';
-import type { Surface } from './surfaces';
+import type { RouteSurface, Surface } from './surfaces';
 import { SURFACE_SPECS, surfaceAllows } from './surfaces';
 
 /**
@@ -177,20 +177,13 @@ function hasRevalidateTrigger(config: RouteShape): boolean {
 export interface ModeCheckContext {
   readonly file: string;
   readonly path: string;
-  readonly surface: Surface;
+  readonly surface: RouteSurface;
   /** Counted from the route module's JSX by the build. `stream` needs at least one. */
   readonly suspenseBoundaries: number;
 }
 
 /** Checks that need the surrounding module and surface. Called by `registerRoute`. */
 export function assertModeInvariants(config: RouteShape, ctx: ModeCheckContext): void {
-  if (ctx.surface === 'api') {
-    throw new RouteModeInvalidError(
-      `${ctx.file} is in api/, which renders nothing, but declares render: '${config.render}'`,
-      `move ${ctx.file} into site/ or app/, or replace defineRoute with an action`,
-    );
-  }
-
   if (!surfaceAllows(ctx.surface, config.render)) {
     const allowed = SURFACE_SPECS[ctx.surface].allowedModes.join(' | ');
     throw new RouteModeInvalidError(

package/src/registry.ts

@@ -1,6 +1,6 @@
 /**
  * The route table — the single source of route truth. File path → URL conventions for
- * `site/`, `app/` and `api/`, plus `describePages()`, the serializable projection that
+ * `site/` and `app/`, plus `describePages()`, the serializable projection that
  * `x.manifest.json`, the `/_x` routes panel, the sitemap and `sw.js` are all generated
  * from. Nothing downstream may keep its own list of routes.
  */
@@ -31,40 +31,31 @@ import { isRouteConfig, routeTagKeys } 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 type { RouteSurface, Surface } from './surfaces';
 import { locateSurface } from './surfaces';
 
 /**
- * The one filename a route may carry, per surface. `shared/` is `Exclude`d rather than merely
- * absent: it is a leaf of helpers with no URL, so a route file there has nowhere to resolve to —
- * and stating that in the key type makes the other three MANDATORY. `Partial<Record<Surface, …>>`
- * said the same thing about `shared` and let any of the three go missing, which only three
- * registration tests would have caught. A dropped `api` row is not a crash: `assertRouteFilename`
- * reads `undefined` as "this file is under shared/", so every `api/` route author would have been
- * told their file is a leaf of helpers.
+ * The one filename a route may carry, per route surface. Keyed by `RouteSurface`, so both rows are
+ * MANDATORY: a dropped row would read as `undefined` in `assertRouteFilename`.
  */
-export const ROUTE_FILENAME = Object.freeze<Record<Exclude<Surface, 'shared'>, string>>({
+export const ROUTE_FILENAME = Object.freeze<Record<RouteSurface, string>>({
   site: 'page.tsx',
   app: 'page.tsx',
-  api: 'route.ts',
 });
 
 /** Stems that already meant "this directory", so the repair is a rename in place, not a new folder. */
 const DIRECTORY_STEMS = new Set(['index', 'page', 'route']);
 
-const API_PREFIX = '/api';
-
 export interface RouteEntry<TData = RouteData> {
   readonly file: string;
   readonly path: string;
-  readonly surface: Surface;
+  readonly surface: RouteSurface;
   readonly config: RouteConfig<TData>;
   readonly suspenseBoundaries: number;
   readonly islands: readonly string[];
   readonly pattern: CompiledPattern;
   /**
-   * The module's page component. Absent for `api/` routes and for a module that exports none —
-   * a `spa` shell is the mode that legitimately has no server-rendered body.
+   * The module's page component. Absent for a module that exports none.
    */
   readonly component?: RouteComponent;
 }
@@ -119,9 +110,8 @@ export type { MountedRouteInput, RouteMount, RouteMountInput } from './mounted-r
  * | `site/blog/[slug]/page.tsx` | `/blog/:slug` |
  * | `site/docs/[...path]/page.tsx` | `/docs/*path` |
  * | `app/dashboard/page.tsx` | `/dashboard` |
- * | `api/posts/route.ts` | `/api/posts` |
  */
-export function routePathFromFile(file: string): { surface: Surface; path: string } {
+export function routePathFromFile(file: string): { surface: RouteSurface; path: string } {
   const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
   // One reader of the surface segment, and it answers WHERE as well as WHICH. Slicing at
   // `indexOf('app/')` instead matched inside `myapp/`, so `apps/myapp/app/page.tsx` resolved to
@@ -130,10 +120,10 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
   if (located === null) {
     throw new SurfaceBoundaryError(
       `${file} is not inside a surface directory, so it has no URL and no bundle graph`,
-      `move ${file} under site/, app/ or api/`,
+      `move ${file} under site/ or app/, named page.tsx`,
     );
   }
-  const surface = located.surface;
+  const surface = routeSurfaceOf(normalized, located.surface);
 
   const rawSegments = located.rest.split('/').filter((s) => s.length > 0);
   assertRouteFilename(normalized, surface, rawSegments[rawSegments.length - 1]);
@@ -143,8 +133,7 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
     .filter((s) => !(s.startsWith('(') && s.endsWith(')')))
     .map(toUrlSegment);
 
-  const base = surface === 'api' ? API_PREFIX : '';
-  const path = `${base}/${urlSegments.join('/')}`.replace(/\/+$/, '') || '/';
+  const path = `/${urlSegments.join('/')}`.replace(/\/+$/, '') || '/';
   return { surface, path };
 }
 
@@ -156,20 +145,37 @@ export function routePathFromFile(file: string): { surface: Surface; path: strin
 const shellQuote = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
 
 /**
- * Enforced rather than documented (axiom 3): a convention that is not a build error is not a
- * convention. The fix is the move that makes the file a route, spelled out — the directory the
- * author already meant, plus the one filename that surface accepts.
+ * Only `site/` and `app/` hold route files. `shared/` is a leaf of helpers with no URL; `api/` is
+ * the action and query projections `defineApi()` collects — a wire format an action cannot speak
+ * is a plain HTTP route in the `routes` runtime override, never a file under `api/`.
  */
-function assertRouteFilename(file: string, surface: Surface, basename: string | undefined): void {
-  // `shared` is the one surface with no filename, and the key type now says so — which is why
-  // this is a comparison rather than an `undefined` check on the lookup.
-  const expected = surface === 'shared' ? undefined : ROUTE_FILENAME[surface];
-  if (expected === undefined) {
+function routeSurfaceOf(file: string, surface: Surface): RouteSurface {
+  if (surface === 'shared') {
     throw new RouteFileInvalidError(
       `${file} is under shared/, which is a leaf of helpers with no URL — a route cannot live there`,
-      `move ${file} under site/, app/ or api/, named page.tsx (site/, app/) or route.ts (api/)`,
+      `move ${file} under site/ or app/, named page.tsx`,
     );
   }
+  if (surface === 'api') {
+    throw new RouteFileInvalidError(
+      `${file} is under api/, which holds no route file: api/ is the actions and queries defineApi() collects`,
+      `JSON in and out: replace ${file} with an action (x g action <name>) collected by defineApi() in api/index.ts. Another wire format (a webhook, an OAuth endpoint): delete ${file} and add a plain HTTP route to the routes array exported as runtime from apps/<app>/runtime.ts`,
+    );
+  }
+  return surface;
+}
+
+/**
+ * Enforced rather than documented (axiom 3): a convention that is not a build error is not a
+ * convention. The fix is the move that makes the file a route, spelled out — the directory the
+ * author already meant, plus the one filename that surface accepts.
+ */
+function assertRouteFilename(
+  file: string,
+  surface: RouteSurface,
+  basename: string | undefined,
+): void {
+  const expected = ROUTE_FILENAME[surface];
   if (basename === expected) return;
 
   // The directory the author meant is the file's own path minus its extension: `site/pricing.tsx`

package/src/surfaces.ts

@@ -11,6 +11,12 @@ import { SurfaceBoundaryError } from './errors';
 
 export type Surface = 'site' | 'app' | 'api' | 'shared';
 
+/**
+ * The two surfaces a route file lives on. `api/` is a surface for the import boundary only: it holds
+ * the action and query projections `defineApi()` collects, and no route file.
+ */
+export type RouteSurface = Exclude<Surface, 'api' | 'shared'>;
+
 export const SURFACES = ['site', 'app', 'api', 'shared'] as const;
 
 export interface SurfaceSpec {