@ultimat3/render 22.3.0 → 22.3.1

package/CLAUDE.md

@@ -94,7 +94,7 @@ axiom 6). Never `cli` (upward).
 | Escaping | `html.ts` only — including `render-stream.ts`'s `holeMarker` and `revealChunk` (`JSON.stringify`), and `head.ts`'s `themeScript`. `escapeAttribute` is `@ultimat3/seo`'s, re-exported by `html.ts`. |
 | Script and style CONTENT | never raw: `escapeText`, `escapeRawTextContent` (`</` → `<\/`, `<!--` → `<\!--`), or `escapeJsonContent` for a `type` ending in `json`. Never HTML-escape a script body. |
 | Which export is the page | `route-component.ts`: `Page` → a single `…Page` → a single capitalised function. |
-| Stylesheets | compiled by `css-modules.ts`, grouped per surface, served by the CLI as one content-hashed file per surface (`@ultimat3/cli`'s `style-bundle.ts`) from `stylesFor`. `sass` is this package's only third-party dependency. |
+| Stylesheets | compiled by `css-modules.ts`, grouped per surface, served by the CLI as one content-hashed file per surface (`@ultimat3/cli`'s `style-bundle.ts`) from `stylesFor`. `sass` is this package's only third-party dependency. Each compile goes through `sass-cache.ts`: `.x/cache/sass/` under cwd, a hit only while every file the compile read hashes the same; `setSassCacheDir(null)` turns it off. |
 | CSS order | `stylesFor` sorts **globals before modules** (`isGlobalStylesheet`). `shared/` is carried by both graphs. |
 | The global layer | the app's `shared/global.scss` `@use`s `@ultimat3/ui/global.scss`, side-effect-imported by `shared/global.ts` (this package may not import `ui`). `x verify` fails with `X_STYLES_GLOBAL_MISSING` when a surface's document defines none. |
 | Colours | tokens and `data-theme` only. No hex in `head.ts` or any emitted script. |

package/package.json

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

package/src/css-modules.ts

@@ -11,6 +11,7 @@ import { renderThrowable } from '@ultimat3/core';
 import type * as Sass from 'sass';
 import { PrerenderFailedError } from './errors';
 import { contentHash } from './render-static';
+import { cachedSassCompile } from './sass-cache';
 
 export interface CompiledStylesheet {
   readonly css: string;
@@ -145,13 +146,18 @@ export function scopeClasses(
     classes[name] = local;
     return `.${local}`;
   });
-  const restored = scoped.replace(
-    MASKED,
-    // The mask is dense and index-addressed, so a miss is impossible; `??` only keeps
-    // `noUncheckedIndexedAccess` honest.
-    (_match, index: string) => literals[Number(index)] ?? '',
-  );
-  return { css: restored, classes };
+  // Recursive: a `:global()` payload is masked AFTER the strings inside it were, so its literal
+  // holds their placeholders — one pass restored `html[data-theme='light']` as
+  // `html[data-theme=\0 0 \0]`, a selector that matched nothing. A literal only ever holds
+  // placeholders with LOWER indexes than its own, so the recursion ends.
+  const restore = (text: string): string =>
+    text.replace(
+      MASKED,
+      // The mask is dense and index-addressed, so a miss is impossible; `??` only keeps
+      // `noUncheckedIndexedAccess` honest.
+      (_match, index: string) => restore(literals[Number(index)] ?? ''),
+    );
+  return { css: restore(scoped), classes };
 }
 
 /** The fix line for a stylesheet that names tokens `@ultimat3/ui/tokens` does not export. */
@@ -198,20 +204,45 @@ const sassCompiler = (): typeof Sass => {
   return loadedSass;
 };
 
+/** Changes whenever the `compileString` options below do, so a cached entry never outlives them. */
+const COMPILE_OPTIONS = 'v1 compressed charset:false loadPaths:dirname importer:package';
+
+let loadedVersion: string | undefined;
+
+/** `sass`'s own version, without evaluating `sass` — the cache key needs it before any compile. */
+const sassVersion = (): string => {
+  loadedVersion ??= String(
+    (require('sass/package.json') as { readonly version?: unknown }).version ?? 'unknown',
+  );
+  return loadedVersion;
+};
+
 export function compileStylesheet(file: string, source: string): CompiledStylesheet {
   let css: string;
   try {
+    // Everything that is not a loaded file goes in the key: the compiler, the options below (named
+    // by `COMPILE_OPTIONS`), the path the relative `@use`s resolve from, and the source itself. The
+    // version is read from Sass's package.json, so a run whose every sheet hits never loads Sass.
+    const key = `${sassVersion()}\0${COMPILE_OPTIONS}\0${file}\0${source}`;
     css = stripCharset(
-      sassCompiler().compileString(source, {
-        url: pathToFileURL(file),
-        loadPaths: [dirname(file)],
-        importers: [packageImporter(dirname(file))],
-        style: 'compressed',
-        // No `@charset`, no BOM — see `stripCharset`. Dart Sass writes one for any compressed
-        // output holding a non-ASCII character, and re-emits an escaped `\\00b7` as the literal
-        // character, so escaping in the app cannot avoid it.
-        charset: false,
-      }).css,
+      cachedSassCompile(key, () => {
+        const result = sassCompiler().compileString(source, {
+          url: pathToFileURL(file),
+          loadPaths: [dirname(file)],
+          importers: [packageImporter(dirname(file))],
+          style: 'compressed',
+          // No `@charset`, no BOM — see `stripCharset`. Dart Sass writes one for any compressed
+          // output holding a non-ASCII character, and re-emits an escaped `\\00b7` as the literal
+          // character, so escaping in the app cannot avoid it.
+          charset: false,
+        });
+        return {
+          css: result.css,
+          loaded: result.loadedUrls.map((loaded) =>
+            loaded.protocol === 'file:' ? fileURLToPath(loaded) : undefined,
+          ),
+        };
+      }),
     );
   } catch (error) {
     // `renderThrowable`, never `.message`/`String()`: an importer, a plugin or a future Sass

package/src/sass-cache.ts

@@ -0,0 +1,139 @@
+// A content-addressed disk cache for one Sass compilation: keyed by the compiler, the file and its
+// source, and valid only while every file that compilation READ still hashes the same. Sass has no
+// cache across compilations, so every `.module.scss` re-parses `@ultimat3/ui/tokens` — measured on
+// notificado.co (140 modules), 3.7 s wall and 12 s CPU of `x manifest --check`'s 6.5 s wall.
+
+// why: `compileStylesheet` is synchronous — Bun's loader `onLoad` path calls it inline — and Bun
+// ships no synchronous file read, write or rename; `node:fs` is the only sync file API.
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+
+/** Relative to the process's cwd — the app root for every `x` command. `.x/` is gitignored. */
+export const SASS_CACHE_DIR = join('.x', 'cache', 'sass');
+
+/** Bumped when the entry shape changes, so an old entry is a miss and never a misread. */
+const ENTRY_VERSION = 1;
+
+/** `undefined`: the default dir under cwd. `null`: off. A string: that directory. */
+let configured: string | null | undefined;
+
+/** Test/host seam. `null` turns the cache off; `undefined` restores the default. */
+export function setSassCacheDir(dir: string | null | undefined): void {
+  configured = dir;
+}
+
+const cacheDir = (): string | null =>
+  configured === undefined ? join(process.cwd(), SASS_CACHE_DIR) : configured;
+
+const sha256 = (input: string | Uint8Array): string =>
+  new Bun.CryptoHasher('sha256').update(input).digest('hex');
+
+/**
+ * What one compilation produced, and every file it read to produce it — as PATHS, `undefined` for
+ * a load that was not a file. The caller converts Sass's URLs: `node:url` stays in `css-modules.ts`,
+ * the one file the browser-barrel test names as the build-time half.
+ */
+export interface SassOutput {
+  readonly css: string;
+  readonly loaded: readonly (string | undefined)[];
+}
+
+interface Entry {
+  readonly v: number;
+  readonly css: string;
+  /** `[absolute path, sha256 of its bytes]` for every file the compilation read. */
+  readonly loaded: readonly (readonly [string, string])[];
+}
+
+/**
+ * Every module `@use`s the same token files, so one run hashes each of them once rather than once
+ * per module. Keyed by size and mtime as well as path: under `x dev` a token file is edited while
+ * the process lives, and a path-only memo would validate every entry against the old bytes.
+ */
+const digests = new Map<string, string>();
+
+const digestOf = (path: string): string | undefined => {
+  try {
+    const stat = statSync(path);
+    const memo = `${path}\0${String(stat.size)}\0${String(stat.mtimeMs)}`;
+    const known = digests.get(memo);
+    if (known !== undefined) return known;
+    const digest = sha256(readFileSync(path));
+    digests.set(memo, digest);
+    return digest;
+  } catch {
+    return undefined;
+  }
+};
+
+const isEntry = (value: unknown): value is Entry => {
+  if (typeof value !== 'object' || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    entry['v'] === ENTRY_VERSION &&
+    typeof entry['css'] === 'string' &&
+    Array.isArray(entry['loaded']) &&
+    entry['loaded'].every(
+      (pair: unknown) =>
+        Array.isArray(pair) &&
+        pair.length === 2 &&
+        typeof pair[0] === 'string' &&
+        typeof pair[1] === 'string',
+    )
+  );
+};
+
+/** A hit only when every file the stored compilation read is byte-identical today. */
+const readHit = (file: string): string | undefined => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+  if (!isEntry(parsed)) return undefined;
+  return parsed.loaded.every(([path, digest]) => digestOf(path) === digest)
+    ? parsed.css
+    : undefined;
+};
+
+/**
+ * Best effort: a read-only filesystem (a production container) or a race with another worker
+ * costs the next run a compile, never this one its result. Written beside and renamed, so a
+ * concurrent reader sees a whole entry or none.
+ */
+const store = (dir: string, file: string, output: SassOutput): void => {
+  // A compilation that read something other than a file cannot be validated by re-reading it.
+  const loaded: (readonly [string, string | undefined])[] = [];
+  for (const path of output.loaded) {
+    if (path === undefined) return;
+    loaded.push([path, digestOf(path)]);
+  }
+  if (loaded.some(([, digest]) => digest === undefined)) return;
+  const entry = { v: ENTRY_VERSION, css: output.css, loaded };
+  try {
+    mkdirSync(dir, { recursive: true });
+    const temporary = `${file}.${process.pid}.${Bun.nanoseconds()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(entry));
+    renameSync(temporary, file);
+  } catch {
+    // Nothing to report: the css this call returns is already correct.
+  }
+};
+
+/**
+ * The css `compile` would return for `key`, read from disk when a previous compilation of the
+ * same key read the same bytes. `key` must name everything that is not a loaded file: the
+ * compiler version, the options, the file's path and its source.
+ */
+export function cachedSassCompile(key: string, compile: () => SassOutput): string {
+  const dir = cacheDir();
+  if (dir === null) return compile().css;
+  const file = join(dir, `${sha256(key)}.json`);
+  const hit = readHit(file);
+  if (hit !== undefined) return hit;
+  const output = compile();
+  store(dir, file, output);
+  return output.css;
+}