@ultimat3/render 19.2.0 → 19.3.1

package/CLAUDE.md

@@ -69,6 +69,7 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | Route filename | `page.tsx` under `site/`/`app/`, `route.ts` under `api/` — `ROUTE_FILENAME`, one per surface. The URL is the directory path. Anything else is `X_ROUTE_FILE_INVALID`; never widen the table to accept a second spelling. |
 | Registry input | descriptors only. `registerRoute` refuses a raw declaration with `X_ROUTE_UNNORMALIZED` — `defineRoute` is the one normalizer of everything the declaration alone decides, and every reader downstream assumes it ran. The registry fills in exactly one value on top: the island budget, which needs the surface, which is a fact of the file path only the route table reads. |
 | Descriptors | `describeRoutes()` must stay JSON-safe, sorted by path, deterministic. |
+| Every string order in this package | `byCodeUnit` (`code-unit-order.ts`), never `localeCompare`. With no locale argument `localeCompare` answers from the runtime's ICU **default locale** and **collation version**: `'/A'` sorted after `'/a'` on one machine and before it on the next, and `'/zoo'` before `'/ärzte'` under `sv-SE` but after it under `en-US` — for the same route table. Three sites shipped it: `routeEntries()` (so `describeRoutes()`, and with it `x.manifest.json`, the sitemap and `sw.js`'s rule table), `checkSurfaceBoundary`'s report, and `pageComponentOf`'s fallback, whose own comment promised "the same one on every machine". Package-internal on purpose — a comparator is not public API. Same rule `@ultimat3/pwa`'s `precache.ts` and `service-worker.ts` state for the artifact they emit. |
 | Boundary | `surfaces.ts` throws; it never warns. Type-only edges are not violations. |
 | Stream cancellation | the underlying source has a `cancel()`, and `write` is guarded on it. A client that disconnects mid-stream aborts `StreamHole.resolve(signal)` and every later `write`/`close` is a no-op — `settle()` on a cancelled controller threw out of a `void`ed promise, one unhandled rejection per response, while the resolved holes kept doing their database work with nowhere to write. |
 | ISR detach | `attach()`'s returned function clears the revalidator as well as the dependents — and only if the slot is still its own, tracked in `installedRevalidator` because `@ultimat3/cache` holds ONE and offers no read back. Left installed, a detached controller and its whole store stayed reachable and kept receiving revalidations while the live one's pages never went stale. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "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": "19.2.0",
-    "@ultimat3/core": "19.2.0",
-    "@ultimat3/i18n": "19.2.0",
-    "@ultimat3/seo": "19.2.0",
+    "@ultimat3/cache": "19.3.1",
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/i18n": "19.3.1",
+    "@ultimat3/seo": "19.3.1",
     "sass": "1.102.0"
   }
 }

package/src/code-unit-order.ts

@@ -0,0 +1,18 @@
+/**
+ * The one string comparator this package orders derived output with.
+ *
+ * Package-internal on purpose: it is the ordering rule, not public API. Nothing outside
+ * `@ultimat3/render` may need it, and a comparator on the barrel is a shape apps would depend on.
+ */
+
+/**
+ * Compare by UTF-16 code unit — never `localeCompare`, which with no locale argument answers from
+ * the runtime's ICU **default locale** and **collation version**: `'/A'` sorts after `'/a'` on one
+ * machine and before it on the next, and `'/zoo'` before `'/ärzte'` under `sv-SE` but after it
+ * under `en-US`, for the same input. Everything this package orders is either diffed across
+ * deploys (`describeRoutes()` feeds `x.manifest.json`, the sitemap and `sw.js`'s rule table) or is
+ * a choice a build makes (`pageComponentOf`'s fallback), so a machine-dependent order is a no-op
+ * deploy that reads as a change — or a different page rendered per host. Same rule
+ * `@ultimat3/pwa`'s `precache.ts` and `service-worker.ts` state for the artifact they emit.
+ */
+export const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);

package/src/registry.ts

@@ -7,6 +7,7 @@
 
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
 import { finiteCount } from '@ultimat3/core';
+import { byCodeUnit } from './code-unit-order';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
@@ -322,7 +323,9 @@ export function routeCount(): number {
 }
 
 export function routeEntries(): readonly RouteEntry[] {
-  return [...routes.values()].sort((a, b) => a.path.localeCompare(b.path));
+  // Code units, never `localeCompare` — `describeRoutes()` below promises an order "identical for
+  // identical input", and `localeCompare` with no locale argument reads the runtime's ICU default.
+  return [...routes.values()].sort((a, b) => byCodeUnit(a.path, b.path));
 }
 
 export function routeFor(path: string): RouteEntry | undefined {

package/src/route-component.ts

@@ -4,6 +4,7 @@
  * ship today — so the rule is a fixed precedence, evaluated once, here.
  */
 
+import { byCodeUnit } from './code-unit-order';
 import type { JsxComponent } from './jsx';
 
 /** The page component of a route module: a function of props, sync or async. */
@@ -15,14 +16,17 @@ const isComponentExport = (name: string, value: unknown): value is RouteComponen
 /**
  * `Page` first, because that is the name `examples/dummy` uses and the one the generators should
  * converge on; then a single `…Page`; then a single capitalised function. Sorted before the last
- * fallback so a module with two components resolves to the same one on every machine.
+ * fallback so a module with two components resolves to the same one on every machine — by CODE
+ * UNIT, because `localeCompare` is what "every machine" fails on: with no locale argument it
+ * answers from the runtime's ICU default, which orders `A_Dash` before `ADash` where code units
+ * order them the other way.
  */
 export function pageComponentOf(
   module: Readonly<Record<string, unknown>>,
 ): RouteComponent | undefined {
   const components = Object.entries(module)
     .filter(([name, value]) => isComponentExport(name, value))
-    .sort(([a], [b]) => a.localeCompare(b)) as readonly (readonly [string, RouteComponent])[];
+    .sort(([a], [b]) => byCodeUnit(a, b)) as readonly (readonly [string, RouteComponent])[];
   if (components.length === 0) return undefined;
 
   const exact = components.find(([name]) => name === 'Page');

package/src/surfaces.ts

@@ -6,6 +6,7 @@
  */
 
 import type { RenderMode } from '@ultimat3/core';
+import { byCodeUnit } from './code-unit-order';
 import { SurfaceBoundaryError } from './errors';
 
 export type Surface = 'site' | 'app' | 'api' | 'shared';
@@ -147,7 +148,10 @@ export function checkSurfaceBoundary(graph: ImportGraph): readonly BoundaryViola
     walk(graph, entry, entrySurface, found);
   }
 
-  return [...found.values()].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+  // Code units, never `localeCompare`: two machines running the same check must report the same
+  // list in the same order, and `localeCompare` with no locale argument reads the runtime's ICU
+  // default locale and collation version.
+  return [...found.values()].sort((a, b) => byCodeUnit(keyOf(a), keyOf(b)));
 }
 
 function keyOf(v: BoundaryViolation): string {