@decocms/start 6.2.1 → 6.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "6.2.1",
+  "version": "6.3.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/templates/server-entry.ts

@@ -89,6 +89,14 @@ const decoWorker = createDecoWorkerEntry(serverEntry, {
     handleRender,
     corsHeaders,
   },
+  // Region splits the cache so a RJ-cached response isn't served to SP visitors
+  // when pages use the website/matchers/location.ts matcher. Without this, the
+  // first geo-resolved response leaks across regions.
+  buildSegment: (request) => {
+    const cf = (request as unknown as { cf?: { regionCode?: string } }).cf;
+    const regionCode = request.headers.get("cf-region-code") ?? cf?.regionCode ?? "";
+    return regionCode ? { regionId: regionCode } : {};
+  },
 });
 
 export default instrumentWorker(decoWorker, {
@@ -155,11 +163,16 @@ const decoWorker = createDecoWorkerEntry(serverEntry, {
   csp: CSP_DIRECTIVES,
   buildSegment: (request) => {
     const vtx = extractVtexContext(request);
+    const cf = (request as unknown as { cf?: { regionCode?: string } }).cf;
+    const geoRegion = request.headers.get("cf-region-code") ?? cf?.regionCode ?? "";
     return {
       device: MOBILE_RE.test(request.headers.get("user-agent") ?? "") ? "mobile" : "desktop",
       loggedIn: vtx.isLoggedIn,
       salesChannel: vtx.salesChannel,
-      regionId: (vtx as any).regionId ?? undefined,
+      // Prefer VTEX regionalization regionId when present; otherwise fall back
+      // to Cloudflare geo so the website/matchers/location.ts matcher gets a
+      // properly segmented cache.
+      regionId: (vtx as any).regionId ?? (geoRegion || undefined),
     };
   },
   admin: {

package/src/admin/schema.ts

@@ -301,35 +301,53 @@ registerMatcherSchemas([
     key: "website/matchers/location.ts",
     title: "Location",
     namespace: "website",
-    propsSchema: {
-      type: "object",
-      properties: {
-        includeLocations: {
-          type: "array",
-          title: "Include Locations",
-          items: {
-            type: "object",
-            properties: {
-              country: { type: "string", title: "Country" },
-              regionCode: { type: "string", title: "Region" },
-              city: { type: "string", title: "City" },
-            },
+    propsSchema: (() => {
+      const locationOrMapItem = {
+        type: "object" as const,
+        properties: {
+          city: {
+            type: "string",
+            title: "City",
+            examples: ["São Paulo"],
+            description: "Exact city name (case-insensitive) as returned by Cloudflare's cf-ipcity header.",
+          },
+          regionCode: {
+            type: "string",
+            title: "Region Code",
+            examples: ["SP", "RJ", "MG", "47"],
+            description:
+              "Matches Cloudflare's cf-region-code header. Usually the ISO 3166-2 subdivision code (SP, RJ, MG, …); for some regions Cloudflare returns numeric codes (e.g. 47). Use the same value cf-region-code returns for your audience — full region names like \"São Paulo\" are NOT matched.",
+          },
+          country: {
+            type: "string",
+            title: "Country",
+            examples: ["BR", "Brasil", "US"],
+            description: "ISO 3166-1 alpha-2 code (BR, US, AR, …) or a full country name (Brasil, United States) — the matcher resolves common aliases.",
+          },
+          coordinates: {
+            type: "string",
+            title: "Area selection",
+            examples: ["-23.5505,-46.6333,5000"],
+            description: "\"latitude,longitude,radius_in_meters\" for haversine-radius matching. Set this for the Map mode.",
           },
         },
-        excludeLocations: {
-          type: "array",
-          title: "Exclude Locations",
-          items: {
-            type: "object",
-            properties: {
-              country: { type: "string", title: "Country" },
-              regionCode: { type: "string", title: "Region" },
-              city: { type: "string", title: "City" },
-            },
+      };
+      return {
+        type: "object" as const,
+        properties: {
+          includeLocations: {
+            type: "array",
+            title: "Include Locations",
+            items: locationOrMapItem,
+          },
+          excludeLocations: {
+            type: "array",
+            title: "Exclude Locations",
+            items: locationOrMapItem,
           },
         },
-      },
-    },
+      };
+    })(),
   },
   {
     key: "website/matchers/userAgent.ts",

package/src/matchers/builtins.test.ts

@@ -0,0 +1,251 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { MatcherContext } from "../cms/resolve";
+import { evaluateMatcher } from "../cms/resolve";
+import { registerBuiltinMatchers } from "./builtins";
+
+const LOCATION_KEY = "website/matchers/location.ts";
+
+beforeEach(() => {
+  registerBuiltinMatchers();
+});
+
+function ctxFromCookies(cookies: Record<string, string>): MatcherContext {
+  return { cookies };
+}
+
+function ctxFromCf(cf: Record<string, unknown>): MatcherContext {
+  const request = new Request("https://example.com/");
+  Object.defineProperty(request, "cf", { value: cf, configurable: true });
+  return { request };
+}
+
+function ctxFromHeaders(headers: Record<string, string>): MatcherContext {
+  return {
+    request: new Request("https://example.com/", { headers }),
+  };
+}
+
+function match(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  return evaluateMatcher({ ...rule, __resolveType: LOCATION_KEY }, ctx);
+}
+
+describe("locationMatcher — typed mode (Location)", () => {
+  it("matches when regionCode equals Cloudflare's cf-region-code (SP)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("matches a raw numeric regionCode (e.g. '47') for parity with deco-cx/apps", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "47", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{ regionCode: "47" }] }, ctx)).toBe(true);
+  });
+
+  it("is case-insensitive on regionCode", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "sp" }] }, ctx)).toBe(true);
+  });
+
+  it("does NOT match a region NAME against cf-region-code (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ regionCode: "São Paulo" }] }, ctx),
+    ).toBe(false);
+  });
+
+  it("does not match when the region differs", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+
+  it("AND's multiple fields on the same entry (regionCode + country)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "BR" }] },
+        ctx,
+      ),
+    ).toBe(true);
+    expect(
+      match(
+        { includeLocations: [{ regionCode: "SP", country: "AR" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("resolves country aliases (Brasil → BR)", () => {
+    const ctx = ctxFromHeaders({ "cf-ipcountry": "BR", "cf-region-code": "SP" });
+    expect(
+      match({ includeLocations: [{ country: "Brasil" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("OR's across multiple include entries", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "RJ" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }, { regionCode: "RJ" }],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("locationMatcher — empty / shape edge cases", () => {
+  it("empty includeLocations array → match (no constraint)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({ includeLocations: [] }, ctx)).toBe(true);
+  });
+
+  it("missing includeLocations → match", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(match({}, ctx)).toBe(true);
+  });
+
+  it("entry {} inside includeLocations matches everyone (parity with original)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ includeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("entry {} inside excludeLocations does NOT exclude anyone (parity)", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP", "cf-ipcountry": "BR" });
+    expect(match({ excludeLocations: [{}] }, ctx)).toBe(true);
+  });
+
+  it("excludeLocations short-circuits over includeLocations", () => {
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        {
+          includeLocations: [{ regionCode: "SP" }],
+          excludeLocations: [{ regionCode: "SP" }],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("includeLocations with [{regionCode}] fails when geo is empty", () => {
+    expect(
+      match({ includeLocations: [{ regionCode: "SP" }] }, {}),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — Map mode (haversine)", () => {
+  it("matches when source coords are within target radius", () => {
+    // Target: São Paulo center, 5km. Source: ~500m away.
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(true);
+  });
+
+  it("does NOT match when source coords are outside the radius", () => {
+    // Target: São Paulo, 5km. Source: Rio (~360km away).
+    const ctx = ctxFromHeaders({
+      "cf-iplatitude": "-22.9068",
+      "cf-iplongitude": "-43.1729",
+    });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("Map-only rule does NOT match when source has no coordinates", () => {
+    // Deliberate divergence from deco-cx/apps: upstream lets coord-only rules
+    // vacuously pass when the visitor has no lat/lng, which matches every
+    // such visitor — a footgun in production. We require both sides to have
+    // coordinates before the haversine check passes.
+    const ctx = ctxFromHeaders({ "cf-region-code": "SP" });
+    expect(
+      match(
+        { includeLocations: [{ coordinates: "-23.5505,-46.6333,5000" }] },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+
+  it("AND's coordinates with regionCode on the same entry", () => {
+    // Source: SP coords, region=SP.
+    const ctx = ctxFromHeaders({
+      "cf-region-code": "SP",
+      "cf-iplatitude": "-23.5510",
+      "cf-iplongitude": "-46.6340",
+    });
+    // Entry asks for region=SP AND within 5km of SP center — matches.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-23.5505,-46.6333,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(true);
+    // Entry asks for region=SP AND within 5km of Rio — fails on coords.
+    expect(
+      match(
+        {
+          includeLocations: [
+            { regionCode: "SP", coordinates: "-22.9068,-43.1729,5000" },
+          ],
+        },
+        ctx,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("locationMatcher — data source fallbacks", () => {
+  it("reads from request.cf when headers are absent", () => {
+    const ctx = ctxFromCf({ country: "BR", regionCode: "SP" });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("reads from __cf_geo_* cookies as fallback", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_region_code: "SP",
+    });
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+  });
+
+  it("decodes URL-encoded cookie values (e.g. city with accent)", () => {
+    const ctx = ctxFromCookies({
+      __cf_geo_country: "BR",
+      __cf_geo_city: encodeURIComponent("São Paulo"),
+    });
+    expect(
+      match({ includeLocations: [{ city: "São Paulo" }] }, ctx),
+    ).toBe(true);
+  });
+
+  it("headers take precedence over request.cf and cookies", () => {
+    const request = new Request("https://example.com/", {
+      headers: { "cf-region-code": "SP" },
+    });
+    Object.defineProperty(request, "cf", {
+      value: { regionCode: "RJ", country: "BR" },
+      configurable: true,
+    });
+    const ctx: MatcherContext = {
+      request,
+      cookies: { __cf_geo_region_code: "MG" },
+    };
+    expect(match({ includeLocations: [{ regionCode: "SP" }] }, ctx)).toBe(true);
+    expect(match({ includeLocations: [{ regionCode: "RJ" }] }, ctx)).toBe(false);
+  });
+});

package/src/matchers/builtins.ts

@@ -186,95 +186,168 @@ function queryStringMatcher(rule: Record<string, unknown>, ctx: MatcherContext):
 }
 
 // -------------------------------------------------------------------------
-// Location matcher
+// Location matcher — parity with deco-cx/apps/website/matchers/location.ts
+//
+// Each entry in includeLocations/excludeLocations is a union of:
+//   Location: { city?, regionCode?, country? }
+//   Map:      { coordinates?: "lat,lng,radius_in_meters" }
+// Fields may coexist on the same entry; the matcher AND's every constraint
+// that is populated. An entry with zero constraints returns defaultNotMatched
+// (true for includes, false for excludes), matching upstream semantics.
 // -------------------------------------------------------------------------
 
-interface LocationRule {
+interface LocationOrMap {
   country?: string;
   regionCode?: string;
   city?: string;
+  /** "latitude,longitude,radius_in_meters" — e.g. "-23.5505,-46.6333,5000" */
+  coordinates?: string;
 }
 
-interface GeoData {
+interface GeoSource {
   country: string;
   regionCode: string;
-  regionName: string;
   city: string;
+  /** "latitude,longitude" when available */
+  coordinates?: string;
+}
+
+function decodeCookie(value: string | undefined): string {
+  if (!value) return "";
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
 }
 
 /**
  * Extract geo data from the request context.
- * Priority: request.cf (Cloudflare Workers) > geo cookies > geo headers.
+ *
+ * Read order mirrors the original deco-cx/apps matcher (header-first), with
+ * additional fallbacks for environments that don't preserve the cf-* request
+ * headers (e.g. when TanStack Start re-wraps the request and drops them):
+ *   1. cf-* request headers (cf-region-code, cf-ipcity, ...)
+ *   2. request.cf (Cloudflare Workers native)
+ *   3. __cf_geo_* cookies (injected by createDecoWorkerEntry)
  */
-function getGeoData(ctx: MatcherContext): GeoData {
-  // 1. Cloudflare Workers: request.cf has authoritative geo data
-  const req = ctx.request;
-  if (req) {
-    const cf = (req as any).cf as Record<string, unknown> | undefined;
-    if (cf?.country) {
-      return {
-        country: (cf.country as string) ?? "",
-        regionCode: (cf.regionCode as string) ?? (cf.region as string) ?? "",
-        regionName: (cf.region as string) ?? "",
-        city: (cf.city as string) ?? "",
-      };
+function getGeoData(ctx: MatcherContext): GeoSource {
+  const headers = ctx.headers ?? {};
+  const reqHeaders = ctx.request?.headers;
+  const h = (name: string): string =>
+    headers[name] ?? reqHeaders?.get(name) ?? "";
+
+  let regionCode = h("cf-region-code");
+  let country = h("cf-ipcountry") || h("x-vercel-ip-country");
+  let city = h("cf-ipcity");
+  let latitude = h("cf-iplatitude");
+  let longitude = h("cf-iplongitude");
+
+  if (!country || !regionCode || !city || !latitude || !longitude) {
+    const req = ctx.request;
+    const cf = req ? ((req as any).cf as Record<string, unknown> | undefined) : undefined;
+    if (cf) {
+      country = country || ((cf.country as string) ?? "");
+      regionCode = regionCode || ((cf.regionCode as string) ?? "");
+      city = city || ((cf.city as string) ?? "");
+      latitude = latitude || (cf.latitude != null ? String(cf.latitude) : "");
+      longitude = longitude || (cf.longitude != null ? String(cf.longitude) : "");
     }
   }
 
-  // 2. Geo cookies (set by Cloudflare middleware on Fresh/Deno sites)
-  const cookies = ctx.cookies ?? {};
-  const cookieCountry = cookies.__cf_geo_country ? decodeURIComponent(cookies.__cf_geo_country) : "";
-  if (cookieCountry) {
-    return {
-      country: cookieCountry,
-      regionCode: cookies.__cf_geo_region_code ? decodeURIComponent(cookies.__cf_geo_region_code) : "",
-      regionName: cookies.__cf_geo_region ? decodeURIComponent(cookies.__cf_geo_region) : "",
-      city: cookies.__cf_geo_city ? decodeURIComponent(cookies.__cf_geo_city) : "",
-    };
+  if (!country || !regionCode || !city || !latitude || !longitude) {
+    const cookies = ctx.cookies ?? {};
+    country = country || decodeCookie(cookies.__cf_geo_country);
+    regionCode = regionCode || decodeCookie(cookies.__cf_geo_region_code);
+    city = city || decodeCookie(cookies.__cf_geo_city);
+    latitude = latitude || decodeCookie(cookies.__cf_geo_lat);
+    longitude = longitude || decodeCookie(cookies.__cf_geo_lng);
   }
 
-  // 3. Fallback: standard geo headers (Vercel, etc.)
-  const headers = ctx.headers ?? {};
-  return {
-    country: headers["cf-ipcountry"] ?? headers["x-vercel-ip-country"] ?? "",
-    regionCode: headers["cf-region"] ?? headers["x-vercel-ip-country-region"] ?? "",
-    regionName: "",
-    city: "",
-  };
+  const coordinates = latitude && longitude ? `${latitude},${longitude}` : undefined;
+  return { country, regionCode, city, coordinates };
 }
 
-function matchesLocationRule(
-  loc: LocationRule,
-  geo: GeoData,
-): boolean {
-  if (loc.country) {
-    const code = resolveCountryCode(loc.country);
-    if (code.toUpperCase() !== geo.country.toUpperCase()) return false;
-  }
-  if (loc.regionCode) {
-    // Match against both the short code ("SP") and full name ("São Paulo")
-    // so rules authored against either format continue working.
-    const ruleVal = loc.regionCode.toLowerCase();
-    if (geo.regionCode.toLowerCase() !== ruleVal && geo.regionName.toLowerCase() !== ruleVal) return false;
+/**
+ * Haversine "within radius" check.
+ *
+ * @param source "latitude,longitude" from the request's geo.
+ * @param target "latitude,longitude,radius_in_meters" from the rule entry.
+ */
+function haversineWithinRadius(source: string, target: string): boolean {
+  const [slat, slng] = source.split(",").map(Number);
+  const parts = target.split(",").map(Number);
+  const [tlat, tlng, radiusMeters] = parts;
+  if (
+    !Number.isFinite(slat) ||
+    !Number.isFinite(slng) ||
+    !Number.isFinite(tlat) ||
+    !Number.isFinite(tlng) ||
+    !Number.isFinite(radiusMeters)
+  ) {
+    return false;
   }
-  if (loc.city && loc.city.toLowerCase() !== geo.city.toLowerCase()) return false;
-  return true;
+  const R = 6371000;
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(tlat - slat);
+  const dLng = toRad(tlng - slng);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(slat)) * Math.cos(toRad(tlat)) * Math.sin(dLng / 2) ** 2;
+  const distance = 2 * R * Math.asin(Math.sqrt(a));
+  return distance <= radiusMeters;
 }
 
-function locationMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
-  const geo = getGeoData(ctx);
-  if (!geo.country) return !((rule.includeLocations as unknown[] | undefined)?.length);
+function matchLocation(defaultNotMatched: boolean, source: GeoSource) {
+  return (target: LocationOrMap): boolean => {
+    const hasRegion = !!target.regionCode;
+    const hasCity = !!target.city;
+    const hasCountry = !!target.country;
+    const hasCoords = !!target.coordinates;
+
+    if (!hasRegion && !hasCity && !hasCountry && !hasCoords) {
+      return defaultNotMatched;
+    }
+
+    let result =
+      !hasRegion ||
+      (target.regionCode!.toLowerCase() === source.regionCode.toLowerCase());
+
+    // Map-mode entries require the visitor to have coordinates — otherwise
+    // we can't tell whether they're inside the target radius, so the
+    // conservative default is "no match". This is a deliberate divergence
+    // from deco-cx/apps, which let coord-only rules vacuously pass when the
+    // visitor had no lat/lng — that behavior matches every visitor without
+    // geo data, which is a footgun in production.
+    result = result &&
+      (!hasCoords ||
+        (!!source.coordinates &&
+          haversineWithinRadius(source.coordinates, target.coordinates!)));
+
+    result = result &&
+      (!hasCity || target.city!.toLowerCase() === source.city.toLowerCase());
+
+    result = result &&
+      (!hasCountry ||
+        resolveCountryCode(target.country!).toUpperCase() ===
+          source.country.toUpperCase());
+
+    return result;
+  };
+}
 
-  const includeLocations = rule.includeLocations as LocationRule[] | undefined;
-  const excludeLocations = rule.excludeLocations as LocationRule[] | undefined;
+function locationMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const source = getGeoData(ctx);
+  const includeLocations = rule.includeLocations as LocationOrMap[] | undefined;
+  const excludeLocations = rule.excludeLocations as LocationOrMap[] | undefined;
 
-  if (excludeLocations?.some((loc) => matchesLocationRule(loc, geo))) {
+  if (excludeLocations?.some(matchLocation(false, source))) {
     return false;
   }
-  if (includeLocations?.length) {
-    return includeLocations.some((loc) => matchesLocationRule(loc, geo));
+  if (!includeLocations || includeLocations.length === 0) {
+    return true;
   }
-  return true;
+  return includeLocations.some(matchLocation(true, source));
 }
 
 // -------------------------------------------------------------------------

package/src/middleware/observability.ts

@@ -253,6 +253,22 @@ export const MetricNames = {
    * `MIGRATION_TOOLING_PLAN.md` for the rationale.
    */
   COMMERCE_REQUEST_DURATION_MS: "commerce_request_duration_ms",
+  /**
+   * Per-loader execution duration. Emitted by `cachedLoader` for every
+   * loader call — cached or not. The `cache_status` label lets dashboards
+   * separate origin latency from in-memory hit latency without needing
+   * to join on traces.
+   *
+   * Canonical labels: `loader`, `cache_status`.
+   */
+  LOADER_DURATION_MS: "loader_duration_ms",
+  /**
+   * Counter incremented when a loader throws. Complements
+   * `loader_duration_ms` for error-rate dashboards.
+   *
+   * Canonical labels: `loader`.
+   */
+  LOADER_ERRORS_TOTAL: "loader_errors_total",
 } as const;
 
 /**
@@ -455,6 +471,35 @@ export function recordCommerceMetric(
   m.histogramRecord?.(MetricNames.COMMERCE_REQUEST_DURATION_MS, durationMs, merged);
 }
 
+/**
+ * Record a loader execution sample. Call from `cachedLoader` after the
+ * loader resolves or rejects. `cache_status` mirrors `CacheDecision` so
+ * dashboards can distinguish HIT (fresh) from STALE-HIT (SWR), STALE-ERROR
+ * (SIE fallback), MISS (origin fetch), and BYPASS (dev / no-store).
+ */
+export function recordLoaderMetric(
+  name: string,
+  durationMs: number,
+  cacheStatus: CacheDecision | "BYPASS",
+) {
+  const m = getState().meter;
+  if (!m) return;
+  m.histogramRecord?.(MetricNames.LOADER_DURATION_MS, durationMs, {
+    loader: name,
+    cache_status: cacheStatus,
+  });
+}
+
+/**
+ * Increment the loader error counter. Call when a loader throws and the
+ * error is not swallowed by a SIE fallback.
+ */
+export function recordLoaderError(name: string) {
+  const m = getState().meter;
+  if (!m) return;
+  m.counterInc(MetricNames.LOADER_ERRORS_TOTAL, 1, { loader: name });
+}
+
 function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
   return path

package/src/sdk/cachedLoader.ts

@@ -11,7 +11,12 @@
  * (e.g. "product") which derives timing from the unified profile system.
  */
 
-import { recordCacheMetric, withTracing } from "../middleware/observability";
+import {
+  recordCacheMetric,
+  recordLoaderError,
+  recordLoaderMetric,
+  withTracing,
+} from "../middleware/observability";
 import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
@@ -100,17 +105,32 @@ export function createCachedLoader<TProps, TResult>(
     if (inflight) {
       // Treat in-flight dedup as a cache hit — avoided the origin call.
       recordCacheMetric(true, name, undefined, "cachedLoader");
-      return inflight as Promise<TResult>;
+      const start = performance.now();
+      return inflight.then((r) => {
+        recordLoaderMetric(name, performance.now() - start, "HIT");
+        return r as TResult;
+      });
     }
 
     if (isDev) {
       // Dev mode: no caching, but still useful to count attempts.
       recordCacheMetric(false, name, undefined, "cachedLoader");
+      const devStart = performance.now();
       const promise = withTracing(
         "deco.cachedLoader",
-        () => loaderFn(props).finally(() => inflightRequests.delete(cacheKey)),
+        () => loaderFn(props),
         { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
-      );
+      )
+        .then((r) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          return r;
+        })
+        .catch((err) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          recordLoaderError(name);
+          throw err;
+        })
+        .finally(() => inflightRequests.delete(cacheKey));
       inflightRequests.set(cacheKey, promise);
       return promise;
     }
@@ -122,6 +142,7 @@ export function createCachedLoader<TProps, TResult>(
     if (policy === "no-cache") {
       if (entry && !isStale) {
         recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
         return entry.value;
       }
     }
@@ -129,12 +150,14 @@ export function createCachedLoader<TProps, TResult>(
     if (policy === "stale-while-revalidate") {
       if (entry && !isStale) {
         recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
         return entry.value;
       }
 
       if (entry && isStale && !entry.refreshing) {
         // Stale-while-revalidate hit: serve stale, refresh in background.
         recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-HIT");
         entry.refreshing = true;
         loaderFn(props)
           .then((result) => {
@@ -160,6 +183,7 @@ export function createCachedLoader<TProps, TResult>(
         // the decision as STALE-ERROR so dashboards can distinguish
         // this from healthy SWR.
         recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-ERROR");
         return entry.value;
       }
     }
@@ -167,11 +191,13 @@ export function createCachedLoader<TProps, TResult>(
     // Cache miss — emit metric, then run loader inside a span so individual
     // slow loaders are visible in traces.
     recordCacheMetric(false, name, "MISS", "cachedLoader");
+    const loaderStart = performance.now();
     const promise = withTracing("deco.cachedLoader", () => loaderFn(props), {
       "deco.loader": name,
       "deco.cache.policy": policy,
     })
       .then((result) => {
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
         cache.set(cacheKey, {
           value: result,
           createdAt: Date.now(),
@@ -190,9 +216,12 @@ export function createCachedLoader<TProps, TResult>(
             console.warn(
               `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
             );
+            recordLoaderMetric(name, performance.now() - loaderStart, "STALE-ERROR");
             return entry.value;
           }
         }
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
+        recordLoaderError(name);
         throw err;
       });
 

package/src/sdk/observability.ts

@@ -65,6 +65,8 @@ export {
   MetricNames,
   recordCacheMetric,
   recordCommerceMetric,
+  recordLoaderError,
+  recordLoaderMetric,
   recordRequestMetric,
   type RequestMetricLabels,
   type RequestStore,

package/src/sdk/workerEntry.ts

@@ -489,6 +489,17 @@ export function injectGeoCookies(request: Request): Request {
   }
   headers.set("cookie", combined);
 
+  // Mirror the ASCII-safe geo fields from request.cf into headers so matchers
+  // that read `request.headers.get("cf-region-code")` (parity with the
+  // upstream deco-cx/apps location matcher) still work even if the inbound
+  // request didn't carry them. Non-ASCII fields (region name, city) stay in
+  // the cookies above — putting them in headers would re-trigger the
+  // non-ASCII warning we strip on the loop above.
+  if (cf.country && !headers.has("cf-ipcountry")) headers.set("cf-ipcountry", cf.country);
+  if (cf.regionCode && !headers.has("cf-region-code")) headers.set("cf-region-code", cf.regionCode);
+  if (cf.latitude && !headers.has("cf-iplatitude")) headers.set("cf-iplatitude", cf.latitude);
+  if (cf.longitude && !headers.has("cf-iplongitude")) headers.set("cf-iplongitude", cf.longitude);
+
   return new Request(request, { headers });
 }