@ultimat3/render 22.2.2 → 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/README.md

@@ -453,6 +453,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `AssetMissingError` | `X_ASSET_MISSING` | `src/errors.ts` |
 | `BudgetExceededError` | `X_BUDGET_EXCEEDED` | `src/errors.ts` |
 | `IslandInvalidError` | `X_ISLAND_INVALID` | `src/errors.ts` |
 | `IslandNotHydratedError` | `X_ISLAND_NOT_HYDRATED` | `src/errors.ts` |
@@ -477,6 +478,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `defineRoute` | the `route` primitive |
 | `withStatus`, `routeStatusOf` | the status a loader answers, carried on its data; 200 when nothing asked |
 | `island`, `createIslandCollector` | one interactive component on a static page |
+| `asset`, `setAssetResolver`, `assetPathProblem`, `AssetPath` | `asset('assets/x.avif')` → the content-hashed URL of a public site file; the table is the CLI's ([Static Assets](../../wiki/Static-Assets.md)) |
 | `MODE_SPECS`, `assertModeShape`, `assertModeInvariants` | the mode invariant table |
 | `registerRoute`, `describeRoutes`, `routeFor`, `routePathFromFile` | the route table |
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "22.2.2",
+  "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.2.2",
-    "@ultimat3/core": "22.2.2",
-    "@ultimat3/http": "22.2.2",
-    "@ultimat3/i18n": "22.2.2",
-    "@ultimat3/seo": "22.2.2",
+    "@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/asset.ts

@@ -0,0 +1,109 @@
+/**
+ * `asset('assets/hero.avif')` — the one way a page names a public file of its own: the path under
+ * `apps/web/site/assets/` in, its content-hashed URL out. Typed so a path outside that tree or with
+ * an extension nothing serves is a compile error, and resolved while the page RENDERS so a file
+ * that is not there fails `x build --target static` with `X_ASSET_MISSING`, exactly as a bad
+ * `island({ src })` does. The table is the CLI's (`site-assets.ts`); this file holds only the seam.
+ */
+
+import { AssetMissingError } from './errors';
+
+/**
+ * What the asset surface serves, by extension. A list and not a pattern: each one has a content
+ * type the server answers with, and an extension outside it would be a file the export copies and
+ * the container serves as `application/octet-stream`.
+ */
+export const ASSET_EXTENSIONS = [
+  'avif',
+  'webp',
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'svg',
+  'ico',
+  'woff2',
+  'mp4',
+  'webm',
+  'vtt',
+] as const;
+
+export type AssetExtension = (typeof ASSET_EXTENSIONS)[number];
+
+/** Relative to the site surface, always under `assets/`: `assets/brand/logo.svg`. */
+export type AssetPath = `assets/${string}.${AssetExtension}`;
+
+/** Maps a declared path to the URL a browser fetches. Throws `X_ASSET_MISSING` on a miss. */
+export type AssetResolver = (path: AssetPath) => string;
+
+/** The directory every asset path starts with, and the URL prefix every hashed URL starts with. */
+export const ASSET_DIR = 'assets';
+
+const EXTENSIONS: ReadonlySet<string> = new Set(ASSET_EXTENSIONS);
+
+/**
+ * Why `path` can never name a servable asset, or `undefined` when it can. Shared with the CLI's
+ * table and route, so the page, the build and the server refuse one set of paths — a `..` segment
+ * the type admits (`assets/../app.config.ts` is a `string`, and so an `AssetPath` suffix) is
+ * refused here, before any disk is asked.
+ */
+export function assetPathProblem(path: string): string | undefined {
+  if (path.includes('\\')) return `"${path}" contains a backslash`;
+  const segments = path.split('/');
+  if (segments[0] !== ASSET_DIR || segments.length < 2) {
+    return `"${path}" is not under ${ASSET_DIR}/`;
+  }
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return `"${path}" has an empty, "." or ".." segment`;
+  }
+  const name = segments[segments.length - 1] ?? '';
+  const dot = name.lastIndexOf('.');
+  const extension = dot <= 0 ? '' : name.slice(dot + 1).toLowerCase();
+  if (!EXTENSIONS.has(extension)) {
+    return `"${path}" has an extension the asset surface does not serve (one of ${ASSET_EXTENSIONS.join(', ')})`;
+  }
+  return undefined;
+}
+
+/**
+ * Registered globally, like the island brand, so two copies of this module — the app's and the
+ * CLI's, resolved through different `node_modules` — read the table one boot installed.
+ */
+const RESOLVER_SLOT: unique symbol = Symbol.for('ultimate.render.assetResolver') as never;
+
+interface ResolverHolder {
+  [RESOLVER_SLOT]?: AssetResolver | undefined;
+}
+
+const holder = globalThis as unknown as ResolverHolder;
+
+/**
+ * Installed by the process that renders: `loadApp` does it for `x dev`, the container and the
+ * static build alike. `undefined` uninstalls — a test that installed one hands the slot back.
+ */
+export function setAssetResolver(resolver: AssetResolver | undefined): void {
+  holder[RESOLVER_SLOT] = resolver;
+}
+
+/**
+ * The hashed URL of one site asset, e.g. `/assets/hero.3f2a1b9c.avif`, served
+ * `public, max-age=31536000, immutable`. Call it in a page or a server component and hand the URL
+ * to an island as a prop: a browser has no asset table, and an island calling this throws.
+ */
+export function asset(path: AssetPath): string {
+  const problem = assetPathProblem(path);
+  if (problem !== undefined) {
+    throw new AssetMissingError(
+      `asset(${JSON.stringify(path)}): ${problem}`,
+      `name a file under apps/web/site/${ASSET_DIR}/ with one of: ${ASSET_EXTENSIONS.join(', ')}`,
+    );
+  }
+  const resolver = holder[RESOLVER_SLOT];
+  if (resolver === undefined) {
+    throw new AssetMissingError(
+      `asset(${JSON.stringify(path)}) ran with no site asset table installed — in a browser (an island), or in a test that never loaded the app`,
+      'call asset() in the page and pass the URL to the island as a prop; a unit test installs a table with setAssetResolver((path) => "/" + path)',
+    );
+  }
+  return resolver(path);
+}

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/errors.ts

@@ -25,6 +25,7 @@ export const RENDER_ERROR_CODES = [
   // stylesheet registry and `stylesFor`, so "the CSS a document on this surface carries" is a fact
   // about render's own output. `x verify` is only the surface that reports it.
   'X_STYLES_GLOBAL_MISSING',
+  'X_ASSET_MISSING',
 ] as const;
 
 export type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
@@ -47,6 +48,7 @@ export const RENDER_ERROR_TITLES: Readonly<Record<RenderErrorCode, string>> = {
   X_ISLAND_NOT_HYDRATED: 'a page renders an island that nothing would ever boot',
   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',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -273,3 +275,19 @@ export class RouteStatusInvalidError extends UltimateError {
     });
   }
 }
+
+/**
+ * `asset('assets/…')` named a file the app's site asset table does not hold. Raised while the
+ * page RENDERS, so the static build fails on it the way it fails on a bad island — a hashed URL
+ * that 404s in every browser is the one outcome a build-checked helper exists to prevent.
+ */
+export class AssetMissingError extends UltimateError {
+  static readonly code = 'X_ASSET_MISSING' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: AssetMissingError.code,
+      cause,
+      fix,
+    });
+  }
+}

package/src/head-seo.ts

@@ -15,6 +15,13 @@ const IDENTITY: Readonly<Record<SeoHeadTag['tag'], readonly string[]>> = {
   script: ['type'],
 };
 
+/**
+ * Open Graph properties a document carries once PER VALUE. Keyed by property alone, the dedupe
+ * kept the last: an article with three tags published one, and a page in three locales named one
+ * alternate. Their content is part of their identity.
+ */
+const REPEATABLE_PROPERTIES = new Set(['og:locale:alternate', 'article:tag']);
+
 /**
  * `<meta name="description">` → `meta:description`. Scripts also carry their position: a page
  * with three JSON-LD nodes emits three tags with identical attributes, and keying them alike
@@ -24,7 +31,14 @@ export function headTagKey(tag: SeoHeadTag, index: number): string {
   const identity = IDENTITY[tag.tag]
     .map((name) => tag.attrs[name])
     .filter((value): value is string => value !== undefined);
-  return [tag.tag, ...identity, ...(tag.tag === 'script' ? [String(index)] : [])].join(':');
+  const property = tag.attrs['property'];
+  const repeated =
+    property !== undefined && REPEATABLE_PROPERTIES.has(property)
+      ? [tag.attrs['content'] ?? '']
+      : [];
+  return [tag.tag, ...identity, ...repeated, ...(tag.tag === 'script' ? [String(index)] : [])].join(
+    ':',
+  );
 }
 
 export function toHeadTag(tag: SeoHeadTag, index: number): HeadTag {

package/src/index.ts

@@ -16,6 +16,9 @@ export type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/cor
 // never had); still named here because `@ultimat3/cli`'s budget reporter reads it beside the route
 // table it prints against.
 export { formatBytes, HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from '@ultimat3/core';
+/** `asset('assets/x.avif')` → the content-hashed URL the site asset surface serves it at. */
+export type { AssetExtension, AssetPath, AssetResolver } from './asset';
+export { ASSET_DIR, ASSET_EXTENSIONS, asset, assetPathProblem, setAssetResolver } from './asset';
 /** The `<meta name="ultimate-scope">` core's `pageClient()` reads, on private documents only. */
 export {
   CLIENT_PERSIST_META,
@@ -36,6 +39,7 @@ export {
 export { parseTtlMs } from './duration';
 export type { RenderErrorCode } from './errors';
 export {
+  AssetMissingError,
   BudgetExceededError,
   IslandInvalidError,
   IslandNotHydratedError,
@@ -127,6 +131,7 @@ export type {
   PrerenderFn,
   RenderResult,
   RevalidateConfig,
+  RouteAlternate,
   RouteBudget,
   RouteCache,
   RouteConfig,

package/src/route-data.ts

@@ -6,9 +6,21 @@
  */
 
 import { isUltimateError, renderThrowable } from '@ultimat3/core';
-import { useI18n } from '@ultimat3/i18n';
+import {
+  currentLocale,
+  localizedPath,
+  routedLocales,
+  unlocalizedPath,
+  useI18n,
+} from '@ultimat3/i18n';
 import { RouteLoadFailedError } from './errors';
-import type { RouteConfig, RouteContext, RouteData, RouteMetaContext } from './route';
+import type {
+  RouteAlternate,
+  RouteConfig,
+  RouteContext,
+  RouteData,
+  RouteMetaContext,
+} from './route';
 
 /**
  * The route's data for one render.
@@ -75,5 +87,21 @@ export function metaContextFor<TData = RouteData>(
   ctx: RouteContext,
   data: TData,
 ): RouteMetaContext<TData> {
-  return { data, params: ctx.params, url: ctx.url, t: useI18n() };
+  // The UNPREFIXED path: `/en/precios` and `/precios` are one page, and every locale's spelling of
+  // it is derived from that one path rather than by rewriting whichever prefix the request wore.
+  const page = unlocalizedPath(pathnameOf(ctx.url));
+  const inLocale = (locale: string): string => localizedPath(page, locale);
+  const alternates: readonly RouteAlternate[] = routedLocales().map((locale) => ({
+    locale,
+    path: inLocale(locale),
+  }));
+  return {
+    data,
+    params: ctx.params,
+    url: ctx.url,
+    t: useI18n(),
+    locale: currentLocale(),
+    localizedPath: inLocale,
+    alternates,
+  };
 }

package/src/route.ts

@@ -129,6 +129,24 @@ export interface RouteMetaContext<TData = RouteData> {
   readonly url: string;
   /** The request's own translator. Never a hardcoded string in a `<title>`. */
   readonly t: Translator;
+  /**
+   * The locale this document renders in: a `/<locale>/` prefix's, the default on an unprefixed
+   * `site/` page, the negotiated one elsewhere. What a localized `description` is chosen by.
+   */
+  readonly locale: string;
+  /** This page's own path spelled in `locale` — unprefixed for the default, `/en/…` otherwise. */
+  readonly localizedPath: (locale: string) => string;
+  /**
+   * This page in every routed locale, the default first — what the automatic hreflang cluster is
+   * built from. One entry for a single-locale app.
+   */
+  readonly alternates: readonly RouteAlternate[];
+}
+
+/** One page in one locale. */
+export interface RouteAlternate {
+  readonly locale: string;
+  readonly path: string;
 }
 
 /** What an author writes. Sync or async, whichever the page's data needs. */

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;
+}