@ultimat3/render 22.2.1 → 22.3.0

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.1",
+  "version": "22.3.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.2.1",
-    "@ultimat3/core": "22.2.1",
-    "@ultimat3/http": "22.2.1",
-    "@ultimat3/i18n": "22.2.1",
-    "@ultimat3/seo": "22.2.1",
+    "@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",
     "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/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/module-loader.ts

@@ -4,6 +4,9 @@
  * `bun test` all load a component the same way and there is no separate "bundled" behaviour.
  */
 
+// why: Bun ships no path API, and a relative app root has to be resolved against the working
+// directory before it can be compared with the absolute paths the Bun plugin hands this loader.
+import { resolve } from 'node:path';
 import { renderThrowable } from '@ultimat3/core';
 import { compileStylesheet, isGlobalStylesheet, stripCharset } from './css-modules';
 import { PrerenderFailedError } from './errors';
@@ -115,10 +118,12 @@ const surfaceOfSheet = (path: string): Surface | null =>
  * Every sheet already registered is classified again, because a sheet can load before the root is
  * named — and a classification frozen then would keep the answer the wrong root gave. The revision
  * moves only when an answer does, so naming the same root twice mints no new stylesheet URL.
- * `undefined` returns to the working directory.
+ * A relative root is resolved against the working directory. `undefined` returns to the working
+ * directory.
  */
 export function setStylesheetRoot(root: string | undefined): void {
-  stylesheetRoot = root;
+  // Resolved: `loadApp('.')` is a legal call, and `.` is a prefix of no absolute path.
+  stylesheetRoot = root === undefined ? undefined : resolve(root);
   for (const [path, sheet] of stylesheets) {
     const surface = surfaceOfSheet(path);
     if (surface === sheet.surface) continue;

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. */