@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/server/tree-match.ts

@@ -0,0 +1,262 @@
+/**
+ * Shared URL-matching tree walker for segment trees.
+ *
+ * Both the main route matcher (`route-matcher.ts`) and slot resolver
+ * (`slot-resolver.ts`) need to walk a SegmentNode tree, matching URL
+ * parts against children with the same priority semantics:
+ *
+ *   static > dynamic > catch-all > optional-catch-all
+ *
+ * Before this module, each had its own walker with subtle divergences
+ * (different group handling, missing backtracking, incomplete
+ * optional-catch-all support). This shared walker is the single
+ * source of truth for URL-to-segment matching.
+ *
+ * See design/07-routing.md §"Request Lifecycle" and TIM-940.
+ */
+
+import type { SegmentNode } from '../routing/types.ts';
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+/** Result of matching URL parts against a segment tree. */
+export interface TreeMatchResult<TFile> {
+  /** Matched segment chain from root to leaf, inclusive. */
+  chain: SegmentNode<TFile>[];
+  /** Collected params, keyed by param name. Catch-all params are string[]. */
+  params: Record<string, string | string[]>;
+}
+
+export interface TreeMatchOptions {
+  /**
+   * When true (default), only match if the leaf node has a page or route
+   * handler. Set to false for metadata route matching, where we just need
+   * to find the owning segment regardless of whether it has a page.
+   */
+  requireTerminal?: boolean;
+}
+
+/**
+ * Match URL path parts against a segment tree.
+ *
+ * Walks the tree depth-first with backtracking, applying priority
+ * ordering globally across group boundaries. Returns the matched
+ * segment chain and collected params, or null if no route matches.
+ *
+ * By default, a match requires a terminal node (one with `page` or
+ * `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+ * any segment (used by metadata route matching).
+ *
+ * @param root  The root segment node to start matching from.
+ * @param parts URL path parts (e.g. ['blog', 'hello-world']).
+ *              Empty array matches the root itself (if terminal).
+ */
+export function matchUrlParts<TFile>(
+  root: SegmentNode<TFile>,
+  parts: string[],
+  options?: TreeMatchOptions
+): TreeMatchResult<TFile> | null {
+  const chain: SegmentNode<TFile>[] = [];
+  const params: Record<string, string | string[]> = {};
+  const requireTerminal = options?.requireTerminal ?? true;
+
+  if (matchNode(root, parts, 0, chain, params, requireTerminal)) {
+    return { chain, params };
+  }
+  return null;
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────
+
+/**
+ * A child node flattened through group segments, along with the
+ * chain of group nodes that must appear in the segment chain
+ * before the child to preserve the tree path.
+ */
+interface EffectiveChild<TFile> {
+  child: SegmentNode<TFile>;
+  groupChain: SegmentNode<TFile>[];
+}
+
+/**
+ * Flatten children through group segments.
+ *
+ * Groups are transparent for URL matching — their non-group descendants
+ * are returned with the chain of group nodes leading to them. This lets
+ * the caller apply priority ordering (static > dynamic > catch-all >
+ * optional-catch-all) across all groups uniformly instead of per-group.
+ */
+function collectEffectiveChildren<TFile>(
+  node: SegmentNode<TFile>,
+  groupChain: SegmentNode<TFile>[] = []
+): EffectiveChild<TFile>[] {
+  const result: EffectiveChild<TFile>[] = [];
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      const nested = collectEffectiveChildren(child, [...groupChain, child]);
+      result.push(...nested);
+    } else {
+      result.push({ child, groupChain });
+    }
+  }
+  return result;
+}
+
+/** A node is terminal if it can serve a response (has a page or route handler). */
+function isTerminal<TFile>(node: SegmentNode<TFile>): boolean {
+  return !!(node.page || node.route);
+}
+
+/** Combined affix length for specificity ordering. */
+function affixLength<TFile>(node: SegmentNode<TFile>): number {
+  return (node.paramPrefix?.length ?? 0) + (node.paramSuffix?.length ?? 0);
+}
+
+/**
+ * Recursive depth-first matcher with backtracking.
+ *
+ * Mutates `chain` and `params` in place for performance; backtracks
+ * (restores previous state) when a candidate doesn't lead to a match.
+ */
+function matchNode<TFile>(
+  node: SegmentNode<TFile>,
+  parts: string[],
+  index: number,
+  chain: SegmentNode<TFile>[],
+  params: Record<string, string | string[]>,
+  requireTerminal: boolean
+): boolean {
+  chain.push(node);
+
+  // All parts consumed — check if this node is terminal (or any node if !requireTerminal)
+  if (index >= parts.length) {
+    if (!requireTerminal || isTerminal(node)) return true;
+
+    // Groups don't consume URL segments, so a group child's page can
+    // match at the same URL depth. Recurse into groups transparently.
+    for (const child of node.children) {
+      if (child.segmentType === 'group') {
+        if (matchNode(child, parts, index, chain, params, requireTerminal)) {
+          return true;
+        }
+      }
+    }
+
+    // Optional catch-all with zero segments (direct and through groups).
+    // The param is NOT set — matching Next.js semantics for [[...slug]]
+    // with no path segments.
+    const effective = collectEffectiveChildren(node);
+    for (const { child, groupChain } of effective) {
+      if (child.segmentType === 'optional-catch-all' && (!requireTerminal || isTerminal(child))) {
+        chain.push(...groupChain, child);
+        return true;
+      }
+    }
+
+    chain.pop();
+    return false;
+  }
+
+  const part = parts[index];
+
+  // Flatten children through groups so priority ordering applies globally.
+  const effective = collectEffectiveChildren(node);
+
+  // 1. Static segments (exact name match)
+  for (const { child, groupChain } of effective) {
+    if (child.segmentType === 'static' && child.segmentName === part) {
+      chain.push(...groupChain);
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      chain.length -= groupChain.length;
+    }
+  }
+
+  // 2. Affixed dynamic segments (e.g. img-[id].png) — more specific than bare dynamic.
+  //    Sorted by specificity: longer combined prefix+suffix wins.
+  const affixed = effective.filter(
+    ({ child }) =>
+      child.segmentType === 'dynamic' && child.paramName && (child.paramPrefix || child.paramSuffix)
+  );
+  affixed.sort((a, b) => affixLength(b.child) - affixLength(a.child));
+  for (const { child, groupChain } of affixed) {
+    const prefix = child.paramPrefix ?? '';
+    const suffix = child.paramSuffix ?? '';
+    if (
+      part.length > prefix.length + suffix.length &&
+      (!prefix || part.startsWith(prefix)) &&
+      (!suffix || part.endsWith(suffix))
+    ) {
+      const value = part.slice(prefix.length, part.length - (suffix.length || 0));
+      chain.push(...groupChain);
+      const prev = params[child.paramName!];
+      params[child.paramName!] = value;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName!] = prev;
+      } else {
+        delete params[child.paramName!];
+      }
+    }
+  }
+
+  // 3. Bare dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'dynamic' &&
+      child.paramName &&
+      !child.paramPrefix &&
+      !child.paramSuffix
+    ) {
+      chain.push(...groupChain);
+      const prev = params[child.paramName];
+      params[child.paramName] = part;
+      if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) {
+        return true;
+      }
+      // Backtrack
+      chain.length -= groupChain.length;
+      if (prev !== undefined) {
+        params[child.paramName] = prev;
+      } else {
+        delete params[child.paramName];
+      }
+    }
+  }
+
+  // 4. Catch-all segments ([...param]) — must be terminal unless the
+  // caller passed requireTerminal:false (metadata route matching needs to
+  // find the owning segment even when it has no page).
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  // 5. Optional catch-all segments ([[...param]]) — same terminal rule
+  for (const { child, groupChain } of effective) {
+    if (
+      child.segmentType === 'optional-catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
+      chain.push(...groupChain, child);
+      params[child.paramName] = parts.slice(index);
+      return true;
+    }
+  }
+
+  chain.pop();
+  return false;
+}

package/src/server/types.ts

@@ -1,6 +1,7 @@
 // Server-side type definitions
 
-import type { EarlyHint } from './early-hints.js';
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { EarlyHint } from './early-hints.ts';
 
 /**
  * A value that is safe to pass through `JSON.stringify` without data loss.
@@ -22,23 +23,55 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
+  segmentParams: CoercedParams;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
+  /**
+   * Per-request CSP nonce, generated on first read. Put it in the
+   * `Content-Security-Policy` header you set via `ctx.headers`, and the
+   * framework stamps the same value on every inline `<script>` in the
+   * response (React's bootstrap and Suspense runtime, the RSC payload
+   * scripts, and its own). Reading it is the opt-in: a request whose
+   * middleware never reads `ctx.nonce` renders without nonce attributes.
+   * See design/13-security.md §"Content Security Policy".
+   */
+  readonly nonce: string;
 }
 
+/**
+ * Context passed to `route.ts` HTTP method handlers (GET/POST/etc.).
+ *
+ * `req` is the original incoming Request; `headers` is the response-headers
+ * container the framework will apply to the final Response.
+ *
+ * Segment params and query parameters are NOT on this context — they are read
+ * the same way pages read them:
+ *
+ * ```ts
+ * // app/schema.ts — every dynamic segment's codec, keyed by bracket name
+ * export default defineSchema({ segmentParams: { '[id]': z.coerce.number() } });
+ *
+ * // app/api/users/[id]/route.ts
+ * import { getSegmentParams } from '@timber-js/app/server';
+ * import { SEGMENT_PATH } from './$segment';
+ * export async function GET() {
+ *   const { id } = getSegmentParams(SEGMENT_PATH); // typed number — 404 on bad input
+ * }
+ * ```
+ *
+ * For query parameters, import a `defineSearchParams` definition and call
+ * `.get()` on it.
+ *
+ * See design/07-routing.md §"RouteContext", design/23-search-params.md,
+ * design/41-global-params.md.
+ */
 export interface RouteContext {
   req: Request;
-  params: Record<string, string | string[]>;
-  searchParams: URLSearchParams;
   headers: Headers;
 }
 
-export interface AccessContext {
-  params: Record<string, string | string[]>;
-  searchParams: unknown;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
+export interface AccessContext {}
 
 export interface Metadata {
   title?: string | { default?: string; template?: string; absolute?: string };
@@ -146,7 +179,7 @@ export interface Metadata {
 
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace MetadataRoute {
-  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
   export interface Sitemap extends Array<SitemapEntry> {}
   export interface SitemapEntry {
     url: string;
@@ -163,4 +196,56 @@ export namespace MetadataRoute {
     sitemap?: string | string[];
     host?: string;
   }
+  /**
+   * PWA Web App Manifest — serialized as `application/manifest+json`.
+   *
+   * Intentionally permissive: the manifest spec is large and evolving
+   * (W3C + browser-specific extensions). Users that want stricter typing
+   * can augment the return type with a library like `web-app-manifest`.
+   */
+  export type Manifest = Record<string, unknown>;
 }
+
+/**
+ * The value a dynamic metadata route handler may return.
+ *
+ * This is a structural union — the pipeline dispatches on the shape at
+ * request time (see `pipeline-phases.ts`):
+ *   - `Response` → returned as-is (e.g. `ImageResponse`, `Response.redirect()`).
+ *     Used by `icon.tsx`, `opengraph-image.tsx`,
+ *     `apple-icon.tsx`.
+ *   - `string` → written as the response body verbatim. Used by `robots.ts`
+ *     and by any handler that wants to emit a pre-serialized payload.
+ *   - `MetadataRoute.Sitemap` → serialized via the sitemap XML writer. Used
+ *     by `sitemap.ts`.
+ *   - `MetadataRoute.Manifest` → serialized via `JSON.stringify`. Used by
+ *     `manifest.ts`.
+ *
+ * See design/16-metadata.md §"Metadata Routes".
+ */
+export type MetadataResult = Response | string | MetadataRoute.Sitemap | MetadataRoute.Manifest;
+
+/**
+ * Default export signature for a dynamic metadata route file
+ * (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.tsx`,
+ * `opengraph-image.tsx`, `apple-icon.tsx`).
+ *
+ * Parameterize `TResult` to narrow the return type for a specific route:
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import type { MetadataHandler, MetadataRoute } from '@timber-js/app/server';
+ *
+ * const sitemap: MetadataHandler<MetadataRoute.Sitemap> = async () => [
+ *   { url: 'https://example.com/', changeFrequency: 'weekly', priority: 1 },
+ * ];
+ * export default sitemap;
+ * ```
+ *
+ * The handler is currently invoked with no arguments. Per-request context
+ * (`params`, `searchParams`, `Request`) is not yet wired through to metadata
+ * route handlers; when it is, this signature will grow a context parameter.
+ */
+export type MetadataHandler<TResult extends MetadataResult = MetadataResult> = () =>
+  | TResult
+  | Promise<TResult>;

package/src/server/utils/element-type.ts

@@ -0,0 +1,88 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+
+import type { ReactNode } from 'react';
+
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+
+// Marker symbols React stamps onto exotic component types. Mirrors the
+// internal `isValidElementType` check in `react.development.js` — React
+// doesn't export it, and we don't want to add `react-is` just for this one
+// validation. `isClientReference` (below) also uses REACT_CLIENT_REFERENCE_TYPE.
+const REACT_FORWARD_REF_TYPE = Symbol.for('react.forward_ref');
+const REACT_MEMO_TYPE = Symbol.for('react.memo');
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
+const REACT_PROVIDER_TYPE = Symbol.for('react.provider');
+const REACT_CONTEXT_TYPE = Symbol.for('react.context');
+const REACT_SUSPENSE_TYPE = Symbol.for('react.suspense');
+const REACT_SUSPENSE_LIST_TYPE = Symbol.for('react.suspense_list');
+const REACT_CLIENT_REFERENCE_TYPE = Symbol.for('react.client.reference');
+
+const REACT_COMPONENT_TYPE_MARKERS: ReadonlySet<symbol> = new Set([
+  REACT_FORWARD_REF_TYPE,
+  REACT_MEMO_TYPE,
+  REACT_LAZY_TYPE,
+  REACT_PROVIDER_TYPE,
+  REACT_CONTEXT_TYPE,
+  REACT_SUSPENSE_TYPE,
+  REACT_SUSPENSE_LIST_TYPE,
+  REACT_CLIENT_REFERENCE_TYPE,
+]);
+
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+/**
+ * Detect whether a component is a React client reference.
+ * Client references have $$typeof set to Symbol.for('react.client.reference')
+ * by registerClientReference() in the React Flight server runtime.
+ *
+ * Used to skip OTEL tracing wrappers that would call the component as a
+ * function. Client components must go through createElement only — they are
+ * serialized as references in the RSC Flight stream, not executed on the server.
+ */
+export function isClientReference(component: unknown): boolean {
+  return (
+    component != null &&
+    typeof component === 'function' &&
+    (component as unknown as Record<string, unknown>).$$typeof === REACT_CLIENT_REFERENCE_TYPE
+  );
+}
+
+export function isValidElementType(value: unknown): value is LoadedComponent {
+  if (typeof value === 'function') return true;
+  if (typeof value !== 'object' || value === null) return false;
+  const marker = (value as { $$typeof?: unknown }).$$typeof;
+  return typeof marker === 'symbol' && REACT_COMPONENT_TYPE_MARKERS.has(marker);
+}

package/src/server/utils/escape-html.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared HTML escaping utility.
+ *
+ * Used by both dev-only paths (error pages, 404 page) and production
+ * paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+ * it's not dev-only.
+ */
+
+/**
+ * Escape a string for safe embedding in HTML content or attributes.
+ *
+ * Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+ */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/server/version-skew.ts

@@ -0,0 +1,104 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+
+// ─── Constants ───────────────────────────────────────────────────
+
+/** Header sent by the client with every RSC/action request. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/** Response header that signals the client to do a full page reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The current build's deployment ID. Set at startup from the manifest init
+ * module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+ */
+let currentDeploymentId: string | null = null;
+
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. In dev mode this is never called (deployment ID
+ * checks are skipped).
+ */
+export function setDeploymentId(id: string): void {
+  currentDeploymentId = id;
+}
+
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export function getDeploymentId(): string | null {
+  return currentDeploymentId;
+}
+
+// ─── Skew Detection ──────────────────────────────────────────────
+
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+  /** Whether the client's deployment ID matches the server's. */
+  ok: boolean;
+  /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+  clientId: string | null;
+}
+
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export function checkVersionSkew(req: Request): SkewCheckResult {
+  // Dev mode — no deployment ID checks (HMR handles updates)
+  if (!currentDeploymentId) {
+    return { ok: true, clientId: null };
+  }
+
+  const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+
+  // No header — initial page load or non-RSC request. Always OK.
+  if (!clientId) {
+    return { ok: true, clientId: null };
+  }
+
+  // Compare deployment IDs
+  if (clientId === currentDeploymentId) {
+    return { ok: true, clientId };
+  }
+
+  return { ok: false, clientId };
+}
+
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export function applyReloadHeaders(headers: Headers): void {
+  headers.set(RELOAD_HEADER, '1');
+}

package/src/server/waituntil-bridge.ts

@@ -10,7 +10,7 @@
  * Design doc: design/11-platform.md §"waitUntil()"
  */
 
-import { waitUntilAls } from './als-registry.js';
+import { waitUntilAls } from './als-registry.ts';
 
 /**
  * Run a function with a per-request waitUntil handler installed.

package/src/server/workers-cache-bridge.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-request Workers Cache purge bridge — ALS bridge for Cloudflare adapter.
+ *
+ * The generated _worker.js wraps each request with `runWithWorkersCachePurge`,
+ * binding `ctx.cache` from the Cloudflare ExecutionContext. The
+ * `WorkersCachePurge` CDN purge handler reads from this ALS to call
+ * `ctx.cache.purge({ tags })` without needing an API token.
+ *
+ * Design doc: design/06-caching.md, design/25-production-deployments.md
+ */
+
+import { workersCachePurgeAls } from './als-registry.ts';
+import type { WorkersCachePurgeCtx } from './als-registry.ts';
+
+/**
+ * Run a function with Workers Cache purge context available.
+ *
+ * Called by the generated Cloudflare _worker.js entry to bind
+ * `ctx.cache` for the request duration.
+ */
+export function runWithWorkersCachePurge<T>(ctx: WorkersCachePurgeCtx, fn: () => T): T {
+  return workersCachePurgeAls.run(ctx, fn);
+}
+
+/**
+ * Get the current request's Workers Cache context, if available.
+ *
+ * Returns undefined outside a Cloudflare Workers request context
+ * or on platforms without Workers Cache support.
+ */
+export function getWorkersCachePurgeCtx(): WorkersCachePurgeCtx | undefined {
+  return workersCachePurgeAls.getStore();
+}