@ultimat3/render 22.5.1 → 22.6.1

package/CLAUDE.md

@@ -25,7 +25,7 @@ axiom 6). Never `cli` (upward).
 |---|---|
 | `offline`, `meta` | required by `RouteDefinition`. Never make them optional. |
 | `hydrate` | optional, **derived from `island()`** — `'interaction'` when the module declared one, `'never'` when not. Declaring it still wins and is the only way to reach `idle` / `visible`. Never give an island its own strategy: `RouteDescriptor.hydrate` is read by `sw.js`, the web manifest and `x routes`. |
-| `defineRoute` shape | exactly the contract's 10 keys (`cache`, `ssr` only, is the tenth). New route *metadata* goes inside `meta`. |
+| `defineRoute` shape | exactly the contract's 11 keys (`cache`, `ssr` only, is the tenth; `post`, an action's export name bound to `POST` at the page URL, the eleventh — never on `static`, `X_ROUTE_POST_INVALID`; the CLI mounts it and refuses an unregistered name at boot). New route *metadata* goes inside `meta`. |
 | `load` | optional, and the ONE server-side data seam. Resolved once per render by `routeDataFor()` and handed to **both** `meta` and the page component. Absent `load`, the context IS the data (`{ params, url }`). |
 | `load` is required when the context cannot supply the data | `LoadRequirement<TData>` in `defineRoute`'s parameter. `RouteContext` is a type ALIAS on purpose — only an alias carries the implicit index signature that makes it a `RouteData`. |
 | A loader's own error | rethrown only when `isUltimateError` says so (core's brand), never a `code` property and never `instanceof UltimateError` — a tier-0 error is branded, not a subclass. Everything else is `X_ROUTE_LOAD_FAILED`. |

package/README.md

@@ -117,6 +117,15 @@ through `cacheControl()`, and its `vary` joins the defaults. `As of 2026-09-24`
 `RouteCache`; `@ultimat3/http` is a dependency of this package for that type and for
 `cacheControl` in the server half.
 
+## `post` — the page's URL also answers `POST`
+
+`defineRoute({ render: 'ssr', …, post: 'unsubscribeOnboarding' })` binds `POST <this page's path>`
+to the named action: its policy, idempotency and redirect, with the URL's query merged over the
+posted fields (query wins). An RFC 8058 one-click `POST /correos/baja?t=…` with
+`List-Unsubscribe=One-Click` reaches the action as `{ t, 'List-Unsubscribe': 'One-Click' }`, while
+`GET` stays the confirm page. `@ultimat3/cli` mounts it in both boots; a name no action is
+registered under is `X_ROUTE_POST_INVALID` at boot, as is `post` on a `static` page.
+
 ## Mode invariants, checked at registration
 
 | Mode | Invariant | Error if violated |

package/package.json

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

package/src/errors.ts

@@ -26,6 +26,7 @@ export const RENDER_ERROR_CODES = [
   // about render's own output. `x verify` is only the surface that reports it.
   'X_STYLES_GLOBAL_MISSING',
   'X_ASSET_MISSING',
+  'X_ROUTE_POST_INVALID',
 ] as const;
 
 export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
@@ -49,6 +50,7 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   X_STYLES_GLOBAL_MISSING:
     'a surface renders documents whose CSS defines no :root custom properties',
   X_ASSET_MISSING: 'a page names a site asset the app does not have',
+  X_ROUTE_POST_INVALID: "a page route's post binding cannot be mounted",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -183,6 +185,21 @@ export class PrerenderFailedError extends UltimateError {
 }
 
 /** `load` is optional, so this catches a value that is present and not callable. */
+/**
+ * `defineRoute({ post })` that cannot be mounted: not an export name, on a page no process
+ * answers (`static`, `spa`), or — at boot — naming no registered action.
+ */
+export class RoutePostInvalidError extends UltimateError {
+  static readonly code = 'X_ROUTE_POST_INVALID' as const;
+  constructor(cause: string) {
+    super({
+      code: RoutePostInvalidError.code,
+      cause,
+      fix: "defineRoute({ render: 'ssr', ..., post: '<actionExportName>' }) naming an action the app registers — x actions list --json prints them",
+    });
+  }
+}
+
 export class RouteLoadInvalidError extends UltimateError {
   static readonly code = 'X_ROUTE_LOAD_INVALID' as const;
   constructor(cause: string, fix: string) {

package/src/index.ts

@@ -54,6 +54,7 @@ export {
   RouteMetaMissingError,
   RouteModeInvalidError,
   RouteOfflineMissingError,
+  RoutePostInvalidError,
   RouteStatusInvalidError,
   SurfaceBoundaryError,
 } from './errors';

package/src/route.ts

@@ -15,11 +15,16 @@
 import type { CacheTag } from '@ultimat3/cache';
 import { serializeTags } from '@ultimat3/cache';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-import { OFFLINE_STRATEGIES } from '@ultimat3/core';
+import { OFFLINE_STRATEGIES, renderCauseValue } from '@ultimat3/core';
 import type { CacheHint } from '@ultimat3/http';
 import type { Translator } from '@ultimat3/i18n';
 import type { RouteMeta } from '@ultimat3/seo';
-import { RouteLoadInvalidError, RouteMetaMissingError, RouteOfflineMissingError } from './errors';
+import {
+  RouteLoadInvalidError,
+  RouteMetaMissingError,
+  RouteOfflineMissingError,
+  RoutePostInvalidError,
+} from './errors';
 import type { IslandSpec } from './island';
 import { drainDeclaredIslands } from './island';
 import { assertModeShape } from './modes';
@@ -188,7 +193,7 @@ export type LoadRequirement<TData> = RouteContext extends TData
  */
 export type RouteCache = 'no-store' | Omit<CacheHint, 'tags'>;
 
-/** The input shape of `defineRoute` — exactly the contract's ten keys, nothing else. */
+/** The input shape of `defineRoute` — exactly the contract's eleven keys, nothing else. */
 export interface RouteDefinition<TData = RouteData> {
   readonly render: RenderMode;
   readonly revalidate?: RevalidateConfig;
@@ -210,6 +215,15 @@ export interface RouteDefinition<TData = RouteData> {
   readonly meta: RouteMetaFn<TData>;
   readonly policy?: RouteGuard;
   readonly cache?: RouteCache;
+  /**
+   * Answer `POST` to THIS page's URL with the named action — its export name, as registered — with
+   * the URL's query merged over the posted fields. What an RFC 8058 one-click unsubscribe needs:
+   * the mail client POSTs `List-Unsubscribe=One-Click` to the very URL the footer links, and the
+   * action (its policy decides who may; `allow()` for an anonymous token link) does the work.
+   * The page itself stays the `GET`, and a form on it can post to its own URL with no JavaScript.
+   * Never on `static`: a file on disk has no process to answer a `POST`.
+   */
+  readonly post?: string;
 }
 
 /**
@@ -289,6 +303,8 @@ export function defineRoute<TData = RouteData>(
     );
   }
 
+  if (def.post !== undefined) assertPostBinding(def.post, def.render);
+
   const declaredMeta = def.meta;
   const declaredLoad = def.load;
   // Drained unconditionally, even when `hydrate` is stated: the list must not survive into the
@@ -321,12 +337,27 @@ export function defineRoute<TData = RouteData>(
     ...(def.prerender ? { prerender: def.prerender } : {}),
     ...(def.policy ? { policy: def.policy } : {}),
     ...(def.cache === undefined ? {} : { cache: def.cache }),
+    ...(def.post === undefined ? {} : { post: def.post }),
   };
 
   assertModeShape(config);
   return Object.freeze(config);
 }
 
+/** An export name, on a mode a process answers. The action's EXISTENCE is checked at boot. */
+function assertPostBinding(post: unknown, render: unknown): void {
+  if (typeof post !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(post)) {
+    throw new RoutePostInvalidError(
+      `post: ${renderCauseValue(post)} is not an action's export name`,
+    );
+  }
+  if (render === 'static') {
+    throw new RoutePostInvalidError(
+      `post: '${post}' sits on a render: 'static' page, a file on disk with no process to answer a POST`,
+    );
+  }
+}
+
 /** Only `index` is decided here; `follow` and the rest stay the author's. */
 function noindexOnError(meta: RouteMeta, status: number): RouteMeta {
   if (!isErrorStatus(status)) return meta;