@ultimat3/render 11.3.0 → 12.0.0

package/CLAUDE.md

@@ -40,6 +40,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | Type claims | `type-pins.tsx`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one. `.tsx` since 1.2.0: the island-as-JSX claim is only decidable by writing the JSX an author writes, checked against the same `solid-js` `JSX.Element` a page is. |
 | Descriptor `meta` / `load` | always `(x) => Promise<…>`. Authors may declare either sync; consumers never branch. |
 | Descriptor `budget` | always an object, `{}` when undeclared. Its *fields* stay optional — `budget.js === undefined` is the site/ hydration failure. |
+| `RouteBudget` keys | **`js` and `lcp`, and every key is PROJECTED** (`As of 2026-08-24`). `css`, `cls` and `tbt` were declared on the contract, flattened away by `registerRoute` — the descriptor carries `budgetJs` + `budgetLcp` and nothing else — and read by NOTHING: `x verify`'s `budgets` step, `x.manifest.json`, `x routes` and the dev dashboard all read those two. So `budget: { cls: 0.1 }` was accepted, normalised, stored and ignored while the gate that exists to enforce budgets reported green — the shape `jobs.driver` and `realtime.tier` had one declaration surface over. **Deleted, not wired**, for `PwaConfig.installPrompt`'s reason: the measuring half does not exist either. `type-pins.tsx` derives the allowed set from `RouteDescriptor`'s own `budget*` keys, so a key added here without a projection is a build error; `scripts/declaration-readers.ts` is the rule that finds the class across every declaration. **Breaking**: three keys are gone from `RouteBudget`. |
 | No `describe()` on a route | `describeRoutes()` is the one route list. A per-route projection would be a second one. |
 | Mode invariants | `modes.ts` only. Never inline a mode check in a render-\* file. **Four modes, and every one renders the route's component** — `spa` did not, and `renderSpa` never read `entry.component`, so a `spa` route served `<div id="x-root"></div>` in every app that ever declared one. A gated page is `ssr`; a body that belongs in the browser is an `island({ src })`. A fifth mode has to name the function that renders it. |
 | Island declaration | `island({ src })` — a **specifier**, never an import. That is the whole boundary: a string has no scope to close over and no edge for a bundler or `checkSurfaceBoundary` to follow, so a `static` page's graph cannot grow the island's dependencies. Never add an overload that takes a component. |

package/package.json

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

package/src/route.ts

@@ -42,14 +42,28 @@ export interface RevalidateConfig {
   readonly ttl?: string | number;
 }
 
+/**
+ * What a route promises to stay under. **Two keys, and every one of them is PROJECTED** — a key
+ * here that `RouteDescriptor` does not carry is a number an author writes and nothing can ever
+ * compare against, which `type-pins.tsx` now makes a build error.
+ *
+ * `css`, `cls` and `tbt` were three such keys and are gone in 12.0.0. `registerRoute` flattens a
+ * budget to `budgetJs` + `budgetLcp`, and every reader downstream — `x verify`'s `budgets` step,
+ * `x.manifest.json`, `x routes`, the dev dashboard — reads only those two, so `budget: { cls: 0.1 }`
+ * was accepted, normalised, stored and ignored while the gate that exists to enforce budgets
+ * reported green. Deleted rather than wired for `PwaConfig.installPrompt`'s reason: the measuring
+ * half does not exist either, and a knob that fails silently in the permissive direction is the
+ * framework's most repeated defect.
+ */
 export interface RouteBudget {
   /** `'40kb'` — measured from the real bundle graph, not the source size. */
   readonly js?: string;
-  readonly css?: string;
-  /** Milliseconds, median of N headless runs. */
+  /**
+   * Milliseconds. PUBLISHED, not enforced: it reaches `x.manifest.json` and `x routes`, and no
+   * step of the gate compares it — nothing in the framework produces an `lcp` measurement, which
+   * `packages/cli/src/templates/route.ts` states at the one place an author would write one.
+   */
   readonly lcp?: number;
-  readonly cls?: number;
-  readonly tbt?: number;
 }
 
 /**

package/src/type-pins.tsx

@@ -11,7 +11,14 @@
 import type { IslandComponent } from './island';
 import { island } from './island';
 import type { JsonValue } from './island-props';
-import type { LoadRequirement, RouteContext, RouteData, RouteDefinition } from './route';
+import type { RouteDescriptor } from './registry';
+import type {
+  LoadRequirement,
+  RouteBudget,
+  RouteContext,
+  RouteData,
+  RouteDefinition,
+} from './route';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -99,3 +106,22 @@ export function _IslandIsAJsxComponent(): unknown {
     </ContactSales>
   );
 }
+
+/**
+ * Every key a route may declare a BUDGET for is a key the descriptor projects.
+ *
+ * Both sides are derived, so neither can move alone: `budgetJs`/`budgetLcp` on `RouteDescriptor`
+ * give `'js' | 'lcp'`, and anything `RouteBudget` declares beyond that fails this line by name.
+ * `budget.css`, `budget.cls` and `budget.tbt` were declared on the contract for four majors, were
+ * flattened away by `registerRoute`, and reached no reader anywhere — so an author writing
+ * `budget: { cls: 0.1 }` was ignored in silence while `x verify`'s `budgets` step, the one thing
+ * that exists to enforce a budget, reported green. `scripts/declaration-readers.ts` is the rule
+ * that finds the class; this is the build error that keeps THIS declaration honest.
+ */
+type BudgetKeyOf<K> = K extends `budget${infer Rest}` ? Uncapitalize<Rest> : never;
+
+type UnprojectedBudgetKey = Exclude<keyof RouteBudget, BudgetKeyOf<keyof RouteDescriptor>>;
+
+export type _EveryBudgetKeyIsProjected = Assert<
+  [UnprojectedBudgetKey] extends [never] ? true : false
+>;