@tokenoftrust/storefront-runner 3.4.0 → 3.5.0

package/apps/storefront/src/lib/assets/registeredRenditions.ts

@@ -0,0 +1,86 @@
+/**
+ * Responsive renditions on Worker-rendered pages (preview on both providers, and every page the
+ * Worker renders rather than serves from a static bundle). The Worker never encodes: renditions are
+ * produced and registered on the node side (the candidate prebuild and every publish,
+ * `scripts/publish/lib/hosted-original-publication.mjs`), and a rendered page points at the ones the
+ * R2 asset registry (`registry/assets.json` in `STATIC_BUNDLES`) holds, with the same `<picture>` the
+ * static bundle carries (`@tot/public-runtime/responsive-renditions`). A source without a complete
+ * registered set keeps its original tag.
+ *
+ * The parsed registry is kept per isolate under the document's ETag; each render pays one `head`
+ * while it is unchanged, and none when the page names no pinned raster.
+ */
+import {
+  ASSET_REGISTRY_KEY,
+  MAX_ASSET_REGISTRY_BYTES,
+  parseAssetRegistry,
+  registeredRenditionSet,
+  type AssetRegistry,
+} from "@tot/public-runtime/asset-registry";
+import {
+  pinnedRasterRef,
+  renditionRecipes,
+  responsiveImgSrcs,
+  rewritePinnedRenditions,
+} from "@tot/public-runtime/responsive-renditions";
+import { R2_ASSET_REGISTRY_STORE } from "@/lib/assets/assetRegistryR2";
+
+export interface RenditionRegistryBucket {
+  head(key: string): Promise<{ etag: string; size: number } | null>;
+  get(key: string): Promise<{ etag: string; size: number; arrayBuffer(): Promise<ArrayBuffer> } | null>;
+}
+
+let cached: { etag: string; registry: AssetRegistry } | null = null;
+
+/** The R2 asset registry, or null when it is absent, oversized or unreadable. */
+export async function readRenditionRegistry(bucket: RenditionRegistryBucket): Promise<AssetRegistry | null> {
+  const head = await bucket.head(ASSET_REGISTRY_KEY);
+  if (!head || head.size > MAX_ASSET_REGISTRY_BYTES) return null;
+  if (cached?.etag === head.etag) return cached.registry;
+  const object = await bucket.get(ASSET_REGISTRY_KEY);
+  if (!object || object.size > MAX_ASSET_REGISTRY_BYTES) return null;
+  const registry = parseAssetRegistry(new Uint8Array(await object.arrayBuffer()), R2_ASSET_REGISTRY_STORE);
+  if (registry) cached = { etag: object.etag, registry };
+  return registry;
+}
+
+/** `html` with every pinned raster `<img>` pointed at `tenantId`'s registered renditions. */
+export function applyRegisteredRenditions(html: string, tenantId: string, registry: AssetRegistry): string {
+  return rewritePinnedRenditions(html, (entry) =>
+    registeredRenditionSet(registry, tenantId, entry, (width) => renditionRecipes(entry, width)));
+}
+
+/**
+ * A rendered HTML document with registered renditions applied; any other response unchanged. A
+ * static-bundle response is served verbatim (its renditions were decided when it was built), and a
+ * registry that cannot be read leaves the page as rendered.
+ */
+export async function withRegisteredRenditions(response: Response, input: {
+  tenantId: string | undefined;
+  readBucket: () => Promise<RenditionRegistryBucket | null | undefined>;
+}): Promise<Response> {
+  if (!input.tenantId || response.status !== 200 || !response.body ||
+    !(response.headers.get("content-type") ?? "").includes("text/html") ||
+    response.headers.has("x-tot-static-bundle")) return response;
+  const html = await response.text();
+  const rebuilt = (body: string) => {
+    const headers = new Headers(response.headers);
+    headers.delete("content-length");
+    headers.delete("etag");
+    return new Response(body, { status: response.status, statusText: response.statusText, headers });
+  };
+  if (!responsiveImgSrcs(html).some((src) => pinnedRasterRef(src))) return rebuilt(html);
+  let registry: AssetRegistry | null = null;
+  try {
+    const bucket = await input.readBucket();
+    registry = bucket ? await readRenditionRegistry(bucket) : null;
+  } catch {
+    registry = null;
+  }
+  return rebuilt(registry ? applyRegisteredRenditions(html, input.tenantId, registry) : html);
+}
+
+/** Test seam: forget the isolate's cached registry. */
+export function resetRenditionRegistryCache(): void {
+  cached = null;
+}

package/apps/storefront/src/lib/observability/diag/serverResponseTime.ts

@@ -1,18 +1,20 @@
 /**
- * The document's server response time for the evidence panel: the `total` the Worker stamps in
- * `Server-Timing` (`lib/observability/shared/serverTiming.ts`) next to the time this self-fetch
- * waited for the response headers (TTFB as seen from the Worker). Advisory — never gates promotion.
+ * The document's server response time for the evidence panel, measured in the viewer's browser
+ * (a Worker fetching its own zone is answered by the origin, never by this Worker, so a
+ * server-side self-fetch cannot see the render). The panel script fetches the home document
+ * same-origin with the viewer's credentials and `__preview` grant, then reports the `total` the
+ * Worker stamps in `Server-Timing` (`lib/observability/shared/serverTiming.ts`) beside the time to
+ * first byte. Advisory — never gates promotion.
  *
- * The self-fetch carries the viewer's preview grant so it measures the render a reviewer gets. A
- * gate page or any non-200 answer is not that render, so it is reported as not measured rather
- * than as a number.
+ * A gate page or any non-200 answer is not the render a reviewer gets, so it is reported as not
+ * measured rather than as a number.
  */
 
 export interface ServerResponseTime {
   measured: true;
   /** `total;dur` from the document's `Server-Timing`, or null when the header is absent. */
   serverTotalMs: number | null;
-  /** Wall time until the response headers arrived. */
+  /** Time to first byte. */
   ttfbMs: number;
   /** The isolate was serving its first request (`isolate;desc="cold"`). */
   cold: boolean;
@@ -23,6 +25,8 @@ export interface ServerResponseTimeUnmeasured {
   reason: string;
 }
 
+export type ServerResponseTimeResult = ServerResponseTime | ServerResponseTimeUnmeasured;
+
 /** Pull `total;dur` and the cold marker out of a `Server-Timing` header value. */
 export function parseServerTiming(header: string | null | undefined): Pick<ServerResponseTime, "serverTotalMs" | "cold"> {
   if (!header) return { serverTotalMs: null, cold: false };
@@ -34,35 +38,54 @@ export function parseServerTiming(header: string | null | undefined): Pick<Serve
   };
 }
 
-/**
- * The URL and headers that make a self-fetch of `path` the viewer's own render: the request's
- * `__preview` grant (query) and cookies are forwarded.
- */
-export function viewerRenderRequest(requestUrl: string, path: string, cookie: string | null): { url: URL; headers: Headers } {
-  const source = new URL(requestUrl);
-  const url = new URL(path, source.origin);
-  const grant = source.searchParams.get("__preview");
-  if (grant) url.searchParams.set("__preview", grant);
-  const headers = new Headers();
-  if (cookie) headers.set("cookie", cookie);
-  return { url, headers };
+/** Turn the home document's response into a measurement, or the reason it is not one. */
+export function classifyHomeResponse(
+  res: { status: number; headers: { get(name: string): string | null } },
+  ttfbMs: number,
+): ServerResponseTimeResult {
+  const gate = res.headers.get("x-tot-gate");
+  if (gate) return { measured: false, reason: `the fetch was answered by the access gate (${gate}), not the store render` };
+  if (res.status !== 200) return { measured: false, reason: `the home document answered ${res.status}, not a render` };
+  return { measured: true, ...parseServerTiming(res.headers.get("server-timing")), ttfbMs: Math.round(ttfbMs) };
 }
 
-/** Self-fetch and report the server response time, or why it could not be measured. */
-export async function measureServerResponseTime(
-  request: { url: URL; headers: Headers },
-  now: () => number = () => performance.now(),
-): Promise<ServerResponseTime | ServerResponseTimeUnmeasured> {
+/** The sentence the panel shows for a result. */
+export function describeServerResponseTime(result: ServerResponseTimeResult): string {
+  if (!result.measured) return `Not measured: ${result.reason}.`;
+  const server = result.serverTotalMs !== null ? `${result.serverTotalMs} ms server total (Server-Timing)` : "no Server-Timing header";
+  return `Home document: ${server} · ${result.ttfbMs} ms to first byte${result.cold ? " · cold isolate" : ""}. A hosted preview is a Worker render; a published static site is served from the CDN and is faster.`;
+}
+
+export interface BrowserDeps {
+  fetch: typeof fetch;
+  /** Resource-timing entries for a URL (`performance.getEntriesByName`). */
+  entries: (url: string) => PerformanceEntry[];
+  now: () => number;
+}
+
+/**
+ * Fetch the home document as the viewer and measure it. TTFB is the resource-timing
+ * `responseStart - requestStart` for that request, falling back to the wall time to headers.
+ */
+export async function measureHomeDocument(homeUrl: URL, deps: BrowserDeps): Promise<ServerResponseTimeResult> {
   try {
-    const started = now();
-    const res = await fetch(request.url, { headers: request.headers, redirect: "manual" });
-    const ttfbMs = now() - started;
-    await res.body?.cancel();
-    const gate = res.headers.get("x-tot-gate");
-    if (gate) return { measured: false, reason: `the fetch was answered by the access gate (${gate}), not the store render` };
-    if (res.status !== 200) return { measured: false, reason: `the home document answered ${res.status}, not a render` };
-    return { measured: true, ...parseServerTiming(res.headers.get("server-timing")), ttfbMs: Math.round(ttfbMs) };
+    const started = deps.now();
+    const res = await deps.fetch(homeUrl.href, { credentials: "include", redirect: "manual", cache: "no-store" });
+    const wallMs = deps.now() - started;
+    await res.arrayBuffer();
+    const timing = deps.entries(homeUrl.href).at(-1) as PerformanceResourceTiming | undefined;
+    const ttfbMs = timing && timing.responseStart > 0 && timing.requestStart > 0 ? timing.responseStart - timing.requestStart : wallMs;
+    return classifyHomeResponse(res, ttfbMs);
   } catch {
     return { measured: false, reason: "the home document could not be fetched" };
   }
 }
+
+/** Measure the home document and write the sentence into `target`. */
+export async function mountServerResponseTime(target: Element, pageUrl: string, deps: BrowserDeps): Promise<void> {
+  const page = new URL(pageUrl);
+  const homeUrl = new URL(target.getAttribute("data-home-path") ?? "/", page.origin);
+  const grant = page.searchParams.get("__preview");
+  if (grant) homeUrl.searchParams.set("__preview", grant);
+  target.textContent = describeServerResponseTime(await measureHomeDocument(homeUrl, deps));
+}

package/apps/storefront/src/middleware/index.ts

@@ -27,6 +27,8 @@ import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/access/sha
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/publication/shared/cdnForward";
 import { SAMPLE_CART_HANDOFF_URL, compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
+import { HTML_CACHE_POLICY_CAPTURE_PROBE } from "@tot/public-runtime";
+import type { RenditionRegistryBucket } from "@/lib/assets/registeredRenditions";
 import { DEV_DRAFT_COOKIE } from "@/lib/developer-experience/dev/devDraft";
 import { applySecurityHeaders } from "@/lib/access/shared/securityHeaders";
 import { visitorRegionFor, withVisitorRegionCookie } from "@/lib/compliance/shared/visitorRegionCookie";
@@ -80,7 +82,16 @@ export const onRequest = defineMiddleware(async (context, next) => {
   const timing = context.locals.serverTiming ?? new ServerTiming();
   context.locals.serverTiming = timing;
   const seen: { cdnForwarded: boolean; assetBasePath?: string } = { cdnForwarded: false };
-  const response = await serveRequest(context, next, seen, timing);
+  const served = await serveRequest(context, next, seen, timing);
+  // Registered responsive renditions on a rendered page, by the same addresses and markup the static
+  // bundle carries. The materialize render is left to the bundle build, which owns its renditions.
+  const { withRegisteredRenditions } = await import("@/lib/assets/registeredRenditions");
+  const response = outer && !context.request.headers.get(HTML_CACHE_POLICY_CAPTURE_PROBE)
+    ? await withRegisteredRenditions(served, {
+      tenantId: context.locals.tenant?.tenant_id,
+      readBucket: async () => (await readR2("STATIC_BUNDLES")) as unknown as RenditionRegistryBucket | undefined,
+    })
+    : served;
   const { scopePreviewPinnedImageUrls } = await import("@/lib/assets/preview-pinned-image-urls");
   const scoped = await scopePreviewPinnedImageUrls(response, context.locals.apiBasePath ?? seen.assetBasePath ?? "");
   const finished = withVisitorRegionCookie(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -20,6 +20,7 @@
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
     "./asset-registry": "./src/asset-registry.ts",
+    "./responsive-renditions": "./src/responsive-renditions.ts",
     "./svg-sanitize": "./src/svg-sanitize.ts",
     "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",

package/packages/public-runtime/src/asset-registry.ts

@@ -442,6 +442,32 @@ export function registeredRendition(
   return null;
 }
 
+/** A source's complete rendition set: each rendition's width and pool entry, and the source's dimensions. */
+export interface RenditionSet { renditions: { width: number; entry: string }[]; width: number; height: number }
+
+/**
+ * Every registered rendition of `parent` for the recipes a build makes for a source of its registered
+ * width (`recipesFor`), or null unless the registry records the source's dimensions and holds every
+ * one of them for `tenantId` ({@link registeredRendition}). A partial set is null: its source is
+ * encoded whole, or served as its original.
+ */
+export function registeredRenditionSet(
+  registry: AssetRegistry | null | undefined, tenantId: string, parent: string,
+  recipesFor: (width: number) => readonly VariantRecipe[],
+): RenditionSet | null {
+  const record = registry?.assets[parent];
+  if (!record?.width || !record.height) return null;
+  const recipes = recipesFor(record.width);
+  if (recipes.length === 0) return null;
+  const renditions: RenditionSet["renditions"] = [];
+  for (const recipe of recipes) {
+    const found = recipe.parent === parent ? registeredRendition(registry, tenantId, recipe) : null;
+    if (!found) return null;
+    renditions.push({ width: recipe.width, entry: found.entry });
+  }
+  return { renditions, width: record.width, height: record.height };
+}
+
 /**
  * The tenants a record lists other than `tenantId`, without naming them: true when the address is
  * registered and this tenant is not among its tenants. Capture uses it to refuse a reference to

package/packages/public-runtime/src/responsive-renditions.ts

@@ -0,0 +1,115 @@
+/**
+ * Responsive renditions of a tenant's raster images: the recipe every producer makes them with and
+ * the markup every renderer points at them with. One module for both, so the static bundle
+ * (`scripts/publish/lib/responsive-images.mjs`, which encodes or reuses renditions while it
+ * materializes) and the Worker's rendered pages (`apps/storefront/src/lib/assets/registeredRenditions.ts`,
+ * which only reads the asset registry) name the same renditions by the same addresses with the same
+ * `<picture>` (ADR 0038 §13).
+ *
+ * A rendition's identity is its source's pool entry plus its recipe; its bytes live at their own
+ * address, `/_a/<sha256>.webp`. An `<img>` with renditions is wrapped in
+ * `<picture style="display:contents">` with a WebP `<source srcset>`; the `<img>` itself is untouched
+ * and stays the fallback. `sizes` comes from the tag's own `sizes`, else `100vw`. A tag that already
+ * has a `srcset`, sits inside a `<picture>`, or names a URL with a query or fragment is left alone.
+ *
+ * Import-free at runtime (type imports only), so plain node runs it from the publish scripts.
+ */
+import type { RenditionSet, VariantRecipe } from "./asset-registry.js";
+
+/** Widths a rendition is produced at, ascending; each is used only below the original's own width. */
+export const RESPONSIVE_WIDTHS: readonly number[] = Object.freeze([480, 768, 1080, 1440, 1920, 2560]);
+export const RENDITION_FORMAT = "webp";
+/** Encoder quality for the WebP renditions. */
+export const WEBP_QUALITY = 78;
+/**
+ * The encoder every rendition is made with, part of each rendition's identity. It names the sharp
+ * release the lockfile pins (a test holds them equal), so an encoder upgrade is a recipe change:
+ * the next build mints new renditions beside the old ones.
+ */
+export const RENDITION_ENCODER = "sharp-0.34.5";
+
+/**
+ * The widths to emit for an original `width` px wide: every standard width below it, plus the
+ * original width itself (never upscaled).
+ */
+export function responsiveWidths(width: number): number[] {
+  if (!Number.isInteger(width) || width <= 0) return [];
+  return [...RESPONSIVE_WIDTHS.filter((w) => w < width), width];
+}
+
+/** The recipe of `parent`'s rendition at `width`; `parent` is the source's pool entry, `<sha256><ext>`. */
+export function renditionRecipe(parent: string, width: number): VariantRecipe {
+  return { kind: "variant", parent, width, format: RENDITION_FORMAT, quality: WEBP_QUALITY, encoder: RENDITION_ENCODER };
+}
+
+/** Every recipe a build makes for `parent` when the source is `width` px wide. */
+export function renditionRecipes(parent: string, width: number): VariantRecipe[] {
+  return responsiveWidths(width).map((w) => renditionRecipe(parent, w));
+}
+
+const PICTURE_OR_IMG_RE = /<picture\b[\s\S]*?<\/picture\s*>|<img\b[^>]*>/gi;
+const PINNED_RASTER_RE = /^((?:\/[A-Za-z0-9._~%-]+)*)\/_a\/([0-9a-f]{64}\.(?:jpe?g|png|webp))$/i;
+
+/** The value of the double-quoted attribute `name` on `tag`, or undefined. */
+export function imgAttr(tag: string, name: string): string | undefined {
+  return new RegExp(`\\s${name}="([^"]*)"`, "i").exec(tag)?.[1];
+}
+
+/** The `src` of an `<img>` tag renditions may be added to, or null. */
+function eligibleSrc(tag: string): string | null {
+  if (imgAttr(tag, "srcset") !== undefined) return null;
+  const src = imgAttr(tag, "src")?.trim();
+  return src && !/[?#]/.test(src) ? src : null;
+}
+
+/** The `src` of every `<img>` in `html` renditions may be added to: no srcset, outside a `<picture>`. */
+export function responsiveImgSrcs(html: string): string[] {
+  const out: string[] = [];
+  for (const [match] of html.matchAll(PICTURE_OR_IMG_RE)) {
+    if (/^<picture/i.test(match)) continue;
+    const src = eligibleSrc(match);
+    if (src) out.push(src);
+  }
+  return out;
+}
+
+/**
+ * A pinned pool raster reference: its pool entry and the path prefix it is served under (`""` at the
+ * root, or a path-routed view's base, e.g. `/<domain>` on a shared preview host).
+ */
+export function pinnedRasterRef(src: string): { prefix: string; entry: string } | null {
+  const match = PINNED_RASTER_RE.exec(src);
+  return match ? { prefix: match[1]!, entry: match[2]! } : null;
+}
+
+/**
+ * Wrap every eligible `<img>` whose `src` has a rendition set in a `<picture>` with a WebP `<source>`.
+ * `setFor` returns the set and the prefix each rendition address is served under.
+ */
+export function rewriteResponsiveImgTags(
+  html: string,
+  setFor: (src: string) => { set: RenditionSet; prefix: string } | null | undefined,
+): string {
+  return html.replace(PICTURE_OR_IMG_RE, (match) => {
+    if (/^<picture/i.test(match)) return match;
+    const src = eligibleSrc(match);
+    const found = src ? setFor(src) : undefined;
+    if (!found?.set.renditions.length) return match;
+    const srcset = found.set.renditions.map(({ width, entry }) => `${found.prefix}/_a/${entry} ${width}w`).join(", ");
+    const sizes = imgAttr(match, "sizes") ?? "100vw";
+    return `<picture style="display:contents"><source type="image/webp" srcset="${srcset}" sizes="${sizes}">${match}</picture>`;
+  });
+}
+
+/**
+ * Point every `<img>` that names a pinned pool raster at that source's registered renditions.
+ * `setForEntry` is the registry lookup for a source's pool entry; a source with no complete set keeps
+ * its original tag, so a missing rendition never puts an unserved address on the page.
+ */
+export function rewritePinnedRenditions(html: string, setForEntry: (entry: string) => RenditionSet | null): string {
+  return rewriteResponsiveImgTags(html, (src) => {
+    const ref = pinnedRasterRef(src);
+    const set = ref ? setForEntry(ref.entry) : null;
+    return ref && set ? { set, prefix: ref.prefix } : null;
+  });
+}