@ultimat3/render 22.6.2 → 22.7.0

package/package.json

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

package/src/css-modules.ts

@@ -9,7 +9,8 @@ import { basename, dirname, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { renderThrowable } from '@ultimat3/core';
 import type * as Sass from 'sass';
-import { PrerenderFailedError } from './errors';
+import { type AssetPath, asset } from './asset';
+import { AssetMissingError, PrerenderFailedError } from './errors';
 import { contentHash } from './render-static';
 import { cachedSassCompile } from './sass-cache';
 
@@ -17,6 +18,12 @@ export interface CompiledStylesheet {
   readonly css: string;
   /** `hero` → `hero_1f2e3d4c`. Empty for a plain (non-module) stylesheet. */
   readonly classes: Readonly<Record<string, string>>;
+  /**
+   * Every OTHER file the compilation read — the partials it `@use`s, `@forward`s or `@import`s,
+   * transitively, as absolute paths. What `x dev` watches to recompile a sheet whose own bytes
+   * did not change.
+   */
+  readonly dependencies: readonly string[];
 }
 
 /** A file is a CSS module when its name says so — one spelling, per the `.module.scss` convention. */
@@ -217,17 +224,59 @@ const sassVersion = (): string => {
   return loadedVersion;
 };
 
+/**
+ * `asset('assets/fonts/inter.woff2')` in Sass — the same path, the same table and the same refusals
+ * as the TypeScript `asset()`, so `src: url(asset('assets/fonts/inter.woff2'))` compiles to the
+ * content-hashed URL `/assets/*` serves. Records each call for the disk cache (`SassOutput.assets`)
+ * and keeps the typed failure: Sass wraps a thrown function error in its own exception, and an
+ * `X_ASSET_MISSING` must reach the author as itself, not as a Sass stack.
+ */
+function sassAssetFunction(
+  sass: typeof Sass,
+  calls: [string, string][],
+  failed: { error?: AssetMissingError },
+): Record<string, Sass.CustomFunction<'sync'>> {
+  return {
+    'asset($path)': (args: readonly Sass.Value[]): Sass.Value => {
+      const path = args[0]?.assertString('path').text ?? '';
+      try {
+        const url = asset(path as AssetPath);
+        calls.push([path, url]);
+        return new sass.SassString(url, { quotes: true });
+      } catch (error) {
+        if (error instanceof AssetMissingError) failed.error = error;
+        throw error;
+      }
+    },
+  };
+}
+
+/** A cache entry's assets are current when each path still resolves to the URL it baked in. */
+const assetsCurrent = (assets: readonly (readonly [string, string])[]): boolean => {
+  try {
+    return assets.every(([path, url]) => asset(path as AssetPath) === url);
+  } catch {
+    return false;
+  }
+};
+
 export function compileStylesheet(file: string, source: string): CompiledStylesheet {
   let css: string;
+  let dependencies: readonly string[];
+  const failed: { error?: AssetMissingError } = {};
   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(
-      cachedSassCompile(key, () => {
-        const result = sassCompiler().compileString(source, {
+    const output = cachedSassCompile(
+      key,
+      () => {
+        const sass = sassCompiler();
+        const assets: [string, string][] = [];
+        const result = sass.compileString(source, {
           url: pathToFileURL(file),
+          functions: sassAssetFunction(sass, assets, failed),
           loadPaths: [dirname(file)],
           importers: [packageImporter(dirname(file))],
           style: 'compressed',
@@ -241,10 +290,17 @@ export function compileStylesheet(file: string, source: string): CompiledStylesh
           loaded: result.loadedUrls.map((loaded) =>
             loaded.protocol === 'file:' ? fileURLToPath(loaded) : undefined,
           ),
+          assets,
         };
-      }),
+      },
+      assetsCurrent,
+    );
+    css = stripCharset(output.css);
+    dependencies = output.loaded.filter(
+      (loaded): loaded is string => loaded !== undefined && loaded !== file,
     );
   } catch (error) {
+    if (failed.error !== undefined) throw failed.error;
     // `renderThrowable`, never `.message`/`String()`: an importer, a plugin or a future Sass
     // release can throw a value whose own read raises, and this frame is what turns a failed
     // compile into `X_PRERENDER_FAILED` naming the file — a laundered read leaves it a bare one.
@@ -254,9 +310,9 @@ export function compileStylesheet(file: string, source: string): CompiledStylesh
       `edit ${file}: ${TOKEN_FIX}`,
     );
   }
-  if (!isCssModule(file)) return { css, classes: {} };
+  if (!isCssModule(file)) return { css, classes: {}, dependencies };
   // Content-addressed, not path-addressed: a checkout at a different absolute path must produce
   // byte-identical CSS, which a hash over the absolute filename would not.
   const scoped = scopeClasses(css, contentHash(`${file.split('/').pop() ?? file} ${source}`));
-  return { css: scoped.css, classes: scoped.classes };
+  return { css: scoped.css, classes: scoped.classes, dependencies };
 }

package/src/head-seo.ts

@@ -31,14 +31,30 @@ 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);
+  // A link with no hreflang and no canonical rel is one of the route's own `links`, and two of
+  // them share a rel by design — two font preloads, a preconnect per origin. Keyed by rel alone,
+  // the second replaced the first. Its href is part of what it is.
+  const rel = tag.attrs['rel'];
+  const href = tag.attrs['href'];
+  const linkHref =
+    tag.tag === 'link' &&
+    rel !== 'canonical' &&
+    tag.attrs['hreflang'] === undefined &&
+    href !== undefined
+      ? [href]
+      : [];
   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(
-    ':',
-  );
+  return [
+    tag.tag,
+    ...identity,
+    ...linkHref,
+    ...repeated,
+    ...(tag.tag === 'script' ? [String(index)] : []),
+  ].join(':');
 }
 
 export function toHeadTag(tag: SeoHeadTag, index: number): HeadTag {

package/src/module-loader.ts

@@ -85,6 +85,8 @@ export interface Stylesheet {
    */
   readonly island: boolean;
   readonly css: string;
+  /** The partials this sheet's compilation read (`CompiledStylesheet.dependencies`). */
+  readonly dependencies: readonly string[];
 }
 
 const stylesheets = new Map<string, Stylesheet>();
@@ -234,6 +236,7 @@ export function loadStylesheet(
       global: isGlobalStylesheet(path),
       island,
       css: compiled.css,
+      dependencies: compiled.dependencies,
     });
   }
   return `export default ${JSON.stringify(compiled.classes)};`;

package/src/sass-cache.ts

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 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;
+const ENTRY_VERSION = 2;
 
 /** `undefined`: the default dir under cwd. `null`: off. A string: that directory. */
 let configured: string | null | undefined;
@@ -37,6 +37,12 @@ const sha256 = (input: string | Uint8Array): string =>
 export interface SassOutput {
   readonly css: string;
   readonly loaded: readonly (string | undefined)[];
+  /**
+   * Every `asset('assets/…')` the compilation called, `[path, url]`. The URL is content-hashed, so
+   * an entry is only valid while each path still resolves to the URL baked into its css — an
+   * edited font under an unchanged sheet would otherwise be served at its old hash.
+   */
+  readonly assets?: readonly (readonly [string, string])[];
 }
 
 interface Entry {
@@ -44,6 +50,7 @@ interface Entry {
   readonly css: string;
   /** `[absolute path, sha256 of its bytes]` for every file the compilation read. */
   readonly loaded: readonly (readonly [string, string])[];
+  readonly assets: readonly (readonly [string, string])[];
 }
 
 /**
@@ -80,12 +87,23 @@ const isEntry = (value: unknown): value is Entry => {
         pair.length === 2 &&
         typeof pair[0] === 'string' &&
         typeof pair[1] === 'string',
+    ) &&
+    Array.isArray(entry['assets']) &&
+    entry['assets'].every(
+      (pair: unknown) =>
+        Array.isArray(pair) &&
+        pair.length === 2 &&
+        typeof pair[0] === 'string' &&
+        typeof pair[1] === 'string',
     )
   );
 };
 
+/** Answers whether every `[path, url]` an entry baked in still resolves to that url. */
+export type AssetCheck = (assets: readonly (readonly [string, string])[]) => boolean;
+
 /** A hit only when every file the stored compilation read is byte-identical today. */
-const readHit = (file: string): string | undefined => {
+const readHit = (file: string, assetsValid: AssetCheck): SassOutput | undefined => {
   let parsed: unknown;
   try {
     parsed = JSON.parse(readFileSync(file, 'utf8'));
@@ -93,9 +111,9 @@ const readHit = (file: string): string | undefined => {
     return undefined;
   }
   if (!isEntry(parsed)) return undefined;
-  return parsed.loaded.every(([path, digest]) => digestOf(path) === digest)
-    ? parsed.css
-    : undefined;
+  if (!parsed.loaded.every(([path, digest]) => digestOf(path) === digest)) return undefined;
+  if (parsed.assets.length > 0 && !assetsValid(parsed.assets)) return undefined;
+  return { css: parsed.css, loaded: parsed.loaded.map(([path]) => path), assets: parsed.assets };
 };
 
 /**
@@ -111,7 +129,7 @@ const store = (dir: string, file: string, output: SassOutput): void => {
     loaded.push([path, digestOf(path)]);
   }
   if (loaded.some(([, digest]) => digest === undefined)) return;
-  const entry = { v: ENTRY_VERSION, css: output.css, loaded };
+  const entry = { v: ENTRY_VERSION, css: output.css, loaded, assets: output.assets ?? [] };
   try {
     mkdirSync(dir, { recursive: true });
     const temporary = `${file}.${process.pid}.${Bun.nanoseconds()}.tmp`;
@@ -123,17 +141,23 @@ const store = (dir: string, file: string, output: SassOutput): void => {
 };
 
 /**
- * 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.
+ * What `compile` would return for `key` — the css and every file it 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. The loaded
+ * list is returned on a hit too: `x dev` reloads a sheet when a partial it `@use`s changes, and a
+ * hit that forgot its partials would make that the one sheet that never reloads.
  */
-export function cachedSassCompile(key: string, compile: () => SassOutput): string {
+export function cachedSassCompile(
+  key: string,
+  compile: () => SassOutput,
+  assetsValid: AssetCheck = () => false,
+): SassOutput {
   const dir = cacheDir();
-  if (dir === null) return compile().css;
+  if (dir === null) return compile();
   const file = join(dir, `${sha256(key)}.json`);
-  const hit = readHit(file);
+  const hit = readHit(file, assetsValid);
   if (hit !== undefined) return hit;
   const output = compile();
   store(dir, file, output);
-  return output.css;
+  return output;
 }