@ultimat3/render 22.3.3 → 22.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.3.3",
+  "version": "22.3.5",
   "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.3.3",
-    "@ultimat3/core": "22.3.3",
-    "@ultimat3/http": "22.3.3",
-    "@ultimat3/i18n": "22.3.3",
-    "@ultimat3/seo": "22.3.3",
+    "@ultimat3/cache": "22.3.5",
+    "@ultimat3/core": "22.3.5",
+    "@ultimat3/http": "22.3.5",
+    "@ultimat3/i18n": "22.3.5",
+    "@ultimat3/seo": "22.3.5",
     "sass": "1.104.0"
   }
 }

package/src/module-loader.ts

@@ -78,6 +78,12 @@ export interface Stylesheet {
   readonly surface: Surface | null;
   /** A plain (non-module) stylesheet: the tokens and the reset, which the cascade needs first. */
   readonly global: boolean;
+  /**
+   * Registered only by an ISLAND build, never by the server's module graph — what `x build --target
+   * docker` records in the island store. Not an ordering key: every sheet is ordered by
+   * `stylesheetOrder`, whoever registered it.
+   */
+  readonly island: boolean;
   readonly css: string;
 }
 
@@ -139,18 +145,25 @@ export function clearStylesheets(): void {
 }
 
 /**
- * The CSS a document on `surface` must carry: the global layer first, then the modules, each group
- * in load order. A `site/` page never receives `app/` CSS — that is axiom 6 applied to bytes the
- * browser parses, not just bytes it executes.
+ * The CSS a document on `surface` must carry. A `site/` page never receives `app/` CSS — that is
+ * axiom 6 applied to bytes the browser parses, not just bytes it executes.
  *
  * `shared/` is carried by both graphs by definition — it is the one directory both surfaces import
  * from, and it is where an app's own global stylesheet lives. Filtering it out (which this did)
  * meant an app could put its tokens in the one place the convention names and have every document
  * silently drop them.
  *
- * Globals sort ahead of modules rather than riding load order: the reset styles bare elements at
- * the lowest specificity there is, so a reset that happened to register after a module rule wins
- * ties it must lose. Insertion order alone made that depend on which page a request hit first.
+ * THE ORDER IS A FUNCTION OF THE SHEETS, NEVER OF THEIR ARRIVAL (22.3.5). A sheet registers in Bun's
+ * `onLoad`, which runs as the loader fetches a module's dependencies — in parallel — and an island
+ * build's too: the arrival order differed on every boot of one image, and so did the joined bytes
+ * and the `/styles/<hash>.css` minted from them (notificado.co, 22.3.2–22.3.4: two pods, two URLs,
+ * each the other's 404). `stylesheetOrder` is the whole rule:
+ *
+ * | key | first | why |
+ * |---|---|---|
+ * | global | the global layer | the reset styles bare elements at the lowest specificity there is, so a reset after a module rule wins ties it must lose |
+ * | owner | a package's sheet, then `shared/`, then the surface's own | library before app: an app's rule wins a tie against the component it restyles |
+ * | path | app-root-relative, by code unit | a total order; the same on every machine |
  */
 export function stylesFor(surface: Surface | null): string {
   const carried = [...stylesheets.values()].filter(
@@ -158,11 +171,30 @@ export function stylesFor(surface: Surface | null): string {
   );
   // `stripCharset` on every sheet, not only the first: a `@charset` or a BOM is legal at byte 0 of
   // a FILE and nowhere else, and this join is what turns seven files into one.
-  return [...carried.filter((sheet) => sheet.global), ...carried.filter((sheet) => !sheet.global)]
+  return carried
+    .sort(stylesheetOrder)
     .map((sheet) => stripCharset(sheet.css))
     .join('');
 }
 
+const OWNER_RANK = (sheet: Stylesheet): number =>
+  sheet.surface === null ? 0 : sheet.surface === 'shared' ? 1 : 2;
+
+/** Relative to the app root, so a container at `/app` and a laptop order one app alike. */
+const orderPath = (sheet: Stylesheet): string => {
+  const root = stylesheetRoot ?? process.cwd();
+  return sheet.file.startsWith(`${root}/`) ? sheet.file.slice(root.length + 1) : sheet.file;
+};
+
+/** See `stylesFor`: global layer, then owner, then path. Exported for the tests that pin it. */
+export function stylesheetOrder(a: Stylesheet, b: Stylesheet): number {
+  if (a.global !== b.global) return a.global ? -1 : 1;
+  const owner = OWNER_RANK(a) - OWNER_RANK(b);
+  if (owner !== 0) return owner;
+  const [x, y] = [orderPath(a), orderPath(b)];
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+
 /**
  * `.tsx` source → JS calling the server factory. Exported so the transform is testable as a pure
  * function: the plugin below is the six lines of glue that hand it a file.
@@ -181,17 +213,26 @@ export function transformTsx(source: string): string {
  * compilation — so a token file `@use`d by twenty `page.module.scss` would inline its `:root` block
  * twenty times. One file, imported for its side effect, is the shape that cannot do that.
  */
-export function loadStylesheet(path: string, source: string): string {
+export function loadStylesheet(
+  path: string,
+  source: string,
+  origin: 'module' | 'island' = 'module',
+): string {
   const compiled = compileStylesheet(path, source);
   // An EMPTY compile unregisters: under `x dev` an edit that deleted every rule left the old entry
   // in place, serving rules the file no longer had until the process restarted.
   if (compiled.css.length === 0 && stylesheets.delete(path)) revision += 1;
   if (compiled.css.length > 0) {
-    if (stylesheets.get(path)?.css !== compiled.css) revision += 1;
+    const held = stylesheets.get(path);
+    // Island-only until the server graph loads it too; then it takes its place in load order.
+    const island = origin === 'island' && (held === undefined || held.island);
+    if (held?.css !== compiled.css || held.island !== island) revision += 1;
+    if (held?.island === true && !island) stylesheets.delete(path);
     stylesheets.set(path, {
       file: path,
       surface: surfaceOfSheet(path),
       global: isGlobalStylesheet(path),
+      island,
       css: compiled.css,
     });
   }