@decocms/blocks 7.2.3 → 7.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.2.3",
+  "version": "7.3.1",
   "type": "module",
   "description": "Deco framework-agnostic core: CMS block resolution, section registry, matchers, portable SDK utilities",
   "repository": {
@@ -46,9 +46,11 @@
     "./sdk/cookie": "./src/sdk/cookie.ts",
     "./sdk/crypto": "./src/sdk/crypto.ts",
     "./sdk/csp": "./src/sdk/csp.ts",
+    "./sdk/detectDevice": "./src/sdk/detectDevice.ts",
     "./sdk/djb2": "./src/sdk/djb2.ts",
     "./sdk/encoding": "./src/sdk/encoding.ts",
     "./sdk/env": "./src/sdk/env.ts",
+    "./sdk/flags": "./src/sdk/flags.ts",
     "./sdk/http": "./src/sdk/http.ts",
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",
     "./sdk/invoke": "./src/sdk/invoke.ts",

package/src/cms/resolve.ts

@@ -7,6 +7,7 @@ import {
 import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
 import { getMeter, MetricNames, withTracing } from "../middleware/observability";
 import { djb2Hex } from "../sdk/djb2";
+import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag, trafficToPct } from "../sdk/flags";
 import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
@@ -380,6 +381,15 @@ export interface MatcherContext {
   cookies?: Record<string, string>;
   headers?: Record<string, string>;
   request?: Request;
+  /**
+   * Sticky A/B flags recorded during resolution. The resolver appends a
+   * {@link StoredFlag} the first time it evaluates each sticky matcher (see
+   * `evaluateVariantRule`), reusing the decision for the rest of the request
+   * so every resolve pass picks the same variant. Read it after resolution to
+   * persist the `deco_flags` cookie and split the edge cache per cohort.
+   * Pass an array in to opt into recording; leave undefined to disable.
+   */
+  flags?: StoredFlag[];
   /**
    * Client-side (SPA) navigation via TanStack `<Link>`. Disables section
    * deferral: deferral is a streaming-SSR optimization, but a client nav
@@ -650,6 +660,85 @@ export function evaluateMatcher(
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// Sticky matchers (A/B)
+// ---------------------------------------------------------------------------
+
+/**
+ * Matcher types whose decision must stick per user instead of re-rolling every
+ * request. Mirrors the `sticky = "session"` export on the corresponding
+ * matchers in @decocms/apps (deco-start re-implements matchers inline, so it
+ * declares the set here rather than importing those exports).
+ */
+const STICKY_MATCHER_TYPES = new Set(["website/matchers/random.ts"]);
+
+interface StickyMeta {
+  /** Cohort identity — the named matcher block (e.g. "TestHero"). */
+  name: string;
+  /** Traffic share for the `true` branch. */
+  traffic: number;
+  /** `round(traffic * 100)` — the re-roll fingerprint. */
+  pct: number;
+}
+
+/**
+ * If `rule` points at a sticky matcher, return its cohort identity + traffic;
+ * otherwise `null` (evaluate normally). A rule is either a named matcher block
+ * (`{__resolveType: "TestHero"}`, dereferenced here to read its `traffic`) or
+ * an inline matcher; the block name is the stable cohort key when present.
+ */
+function stickyMatcherMeta(rule: Record<string, unknown> | undefined): StickyMeta | null {
+  const rt = rule?.__resolveType as string | undefined;
+  if (!rt) return null;
+
+  const blocks = loadBlocks();
+  const name = rt;
+  let resolved = rule as Record<string, unknown>;
+  if (blocks[rt]) {
+    resolved = blocks[rt] as Record<string, unknown>;
+  }
+
+  const type = resolved.__resolveType as string | undefined;
+  if (!type || !STICKY_MATCHER_TYPES.has(type)) return null;
+
+  const traffic = typeof resolved.traffic === "number" ? resolved.traffic : 0.5;
+  return { name, traffic, pct: trafficToPct(traffic) };
+}
+
+/**
+ * Evaluate a variant's rule, applying sticky persistence for A/B matchers.
+ *
+ * For a sticky matcher: reuse the decision already recorded this request; else
+ * honor the `deco_segment` cookie when its fingerprint still matches the current
+ * `traffic`; else roll fresh. Every decision is recorded on `ctx.flags` (when
+ * present) so the caller can persist the cookie and split the cache. Non-sticky
+ * rules fall through to the plain matcher.
+ */
+function evaluateVariantRule(
+  rule: Record<string, unknown> | undefined,
+  ctx: MatcherContext,
+): boolean {
+  const meta = stickyMatcherMeta(rule);
+  // Admin preview forces variants via x-deco-matchers-override; defer to
+  // evaluateMatcher so a forced decision wins. Sticky persistence is a
+  // production concern (previews aren't cached), so skipping it here is fine.
+  if (!meta || hasMatchersOverride(ctx)) return evaluateMatcher(rule, ctx);
+
+  // Reuse a decision already made this request so every resolve pass (page,
+  // shallow section-key, deferred) selects the same variant.
+  const already = ctx.flags?.find((f) => f.name === meta.name && f.pct === meta.pct);
+  if (already) return already.value;
+
+  const stored = parseSegmentCookie(ctx.cookies?.[SEGMENT_COOKIE]).find((f) => f.name === meta.name);
+  // pct === -1 marks a classic-deco segment without a fingerprint — honor it
+  // (stay sticky) instead of re-rolling. A stale fingerprint re-rolls.
+  const useStored = stored && (stored.pct === -1 || stored.pct === meta.pct);
+  const value = useStored ? stored.value : Math.random() < meta.traffic;
+
+  ctx.flags?.push({ name: meta.name, value, pct: meta.pct });
+  return value;
+}
+
 // ---------------------------------------------------------------------------
 // Select (partial field picking)
 // ---------------------------------------------------------------------------
@@ -742,7 +831,7 @@ async function internalResolve(value: unknown, rctx: ResolveContext): Promise<un
 
     for (const variant of variants) {
       const rule = variant.rule as Record<string, unknown> | undefined;
-      if (evaluateMatcher(rule, rctx.matcherCtx)) {
+      if (evaluateVariantRule(rule, rctx.matcherCtx)) {
         return internalResolve(variant.value, childCtx);
       }
     }
@@ -1047,7 +1136,7 @@ export async function resolvePageSeoBlock(
       let matched: unknown = null;
       for (const variant of variants) {
         const rule = variant.rule as Record<string, unknown> | undefined;
-        if (evaluateMatcher(rule, rctx.matcherCtx)) {
+        if (evaluateVariantRule(rule, rctx.matcherCtx)) {
           matched = variant.value;
           break;
         }
@@ -1228,7 +1317,7 @@ function resolveFinalSectionKey(section: unknown, matcherCtx?: MatcherContext):
       let matched: unknown = null;
       for (const variant of variants) {
         const rule = variant.rule as Record<string, unknown> | undefined;
-        if (evaluateMatcher(rule, matcherCtx ?? {})) {
+        if (evaluateVariantRule(rule, matcherCtx ?? {})) {
           matched = variant.value;
           break;
         }
@@ -1281,7 +1370,7 @@ function isCmsDeferralWrapped(section: unknown, matcherCtx?: MatcherContext): bo
       let matched: unknown = null;
       for (const variant of variants) {
         const rule = variant.rule as Record<string, unknown> | undefined;
-        if (evaluateMatcher(rule, matcherCtx ?? {})) {
+        if (evaluateVariantRule(rule, matcherCtx ?? {})) {
           matched = variant.value;
           break;
         }
@@ -1433,7 +1522,7 @@ function resolveSectionShallow(
       let matched: unknown = null;
       for (const variant of variants) {
         const rule = variant.rule as Record<string, unknown> | undefined;
-        if (evaluateMatcher(rule, matcherCtx ?? {})) {
+        if (evaluateVariantRule(rule, matcherCtx ?? {})) {
           matched = variant.value;
           break;
         }
@@ -1492,7 +1581,7 @@ export async function resolveSectionsList(
     const variants = obj.variants as Array<{ value: unknown; rule?: unknown }>;
     for (const variant of variants) {
       const rule = variant.rule as Record<string, unknown> | undefined;
-      if (evaluateMatcher(rule, rctx.matcherCtx)) {
+      if (evaluateVariantRule(rule, rctx.matcherCtx)) {
         return resolveSectionsList(variant.value, rctx, depth + 1);
       }
     }
@@ -1507,7 +1596,7 @@ export async function resolveSectionsList(
     if (!variants?.length) return [];
     for (const variant of variants) {
       const rule = variant.rule as Record<string, unknown> | undefined;
-      if (evaluateMatcher(rule, rctx.matcherCtx)) {
+      if (evaluateVariantRule(rule, rctx.matcherCtx)) {
         return resolveSectionsList(variant.value, rctx, depth + 1);
       }
     }
@@ -1634,10 +1723,14 @@ export async function resolveDecoPage(
     async () => {
       const result = await resolveDecoPageImpl(targetPath, matcherCtx);
       try {
+        // No path label: resolve duration is a per-service latency signal, and
+        // the request path is unbounded cardinality (one histogram series per
+        // URL — product pages, search, facets) that made this the single
+        // biggest series in ClickHouse. Per-route latency lives on the span
+        // below (raw deco.route), which is sampled — the right place for it.
         getMeter()?.histogramRecord?.(
           MetricNames.RESOLVE_DURATION,
-          performance.now() - startedAt,
-          { path: targetPath },
+          (performance.now() - startedAt) / 1000,
         );
       } catch {
         /* observability never fails the request */

package/src/cms/schema.ts

@@ -461,12 +461,7 @@ registerMatcherSchemas([
         matchers: {
           type: "array",
           title: "Matchers",
-          items: {
-            type: "object",
-            required: ["__resolveType"],
-            properties: { __resolveType: { type: "string" } },
-            additionalProperties: true,
-          },
+          items: { $ref: "#/root/matchers" },
         },
       },
     },
@@ -481,11 +476,8 @@ registerMatcherSchemas([
       type: "object",
       properties: {
         matcher: {
-          type: "object",
+          $ref: "#/root/matchers",
           title: "Matcher",
-          required: ["__resolveType"],
-          properties: { __resolveType: { type: "string" } },
-          additionalProperties: true,
         },
       },
     },

package/src/cms/sectionMixins.ts

@@ -16,7 +16,7 @@
  * });
  * ```
  */
-import { detectDevice } from "../sdk/useDevice";
+import { detectDevice } from "../sdk/detectDevice";
 import type { SectionLoaderFn } from "./sectionLoaders";
 
 /**

package/src/cms/stickyFlags.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./sectionLoaders", () => ({
+  isLayoutSection: () => false,
+  runSingleSectionLoader: vi.fn(async (section: any) => section),
+}));
+
+vi.mock("../sdk/normalizeUrls", () => ({
+  normalizeUrlsInObject: vi.fn(<T>(x: T) => x),
+}));
+
+// A page whose A/B "TestHero" matcher block resolves to a 50/50 random matcher.
+vi.mock("./loader", () => ({
+  findPageByPath: vi.fn(),
+  loadBlocks: vi.fn(() => ({
+    TestHero: { __resolveType: "website/matchers/random.ts", traffic: 0.5 },
+  })),
+}));
+
+vi.mock("./registry", () => ({
+  getSection: vi.fn(),
+}));
+
+import { DECO_MATCHERS_OVERRIDE_PARAM } from "../matchers/override";
+import { type StoredFlag, serializeSegmentCookie } from "../sdk/flags";
+import type { MatcherContext } from "./resolve";
+import { resolveValue } from "./resolve";
+
+const FLAG = {
+  __resolveType: "website/flags/multivariate.ts",
+  variants: [
+    { rule: { __resolveType: "TestHero" }, value: "VARIANT_1" },
+    { rule: { __resolveType: "website/matchers/always.ts" }, value: "VARIANT_2" },
+  ],
+};
+
+function ctx(decision?: { value: boolean; pct: number }): MatcherContext & { flags: StoredFlag[] } {
+  const cookie = decision
+    ? serializeSegmentCookie([{ name: "TestHero", value: decision.value, pct: decision.pct }])
+    : undefined;
+  return {
+    cookies: cookie ? { deco_segment: cookie } : {},
+    flags: [],
+  };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("sticky A/B multivariate resolution", () => {
+  it("honors a matching cookie without rolling (test cohort)", async () => {
+    const rand = vi.spyOn(Math, "random");
+    const c = ctx({ value: true, pct: 50 });
+
+    const result = await resolveValue(FLAG, undefined, c);
+
+    expect(result).toBe("VARIANT_1");
+    expect(rand).not.toHaveBeenCalled();
+    expect(c.flags).toEqual([{ name: "TestHero", value: true, pct: 50 }]);
+  });
+
+  it("honors a matching cookie without rolling (control cohort)", async () => {
+    const rand = vi.spyOn(Math, "random");
+    const c = ctx({ value: false, pct: 50 });
+
+    const result = await resolveValue(FLAG, undefined, c);
+
+    expect(result).toBe("VARIANT_2");
+    expect(rand).not.toHaveBeenCalled();
+    expect(c.flags).toEqual([{ name: "TestHero", value: false, pct: 50 }]);
+  });
+
+  it("rolls and records when there is no cookie", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.9); // >= 0.5 -> control
+    const c = ctx();
+
+    const result = await resolveValue(FLAG, undefined, c);
+
+    expect(result).toBe("VARIANT_2");
+    expect(c.flags).toEqual([{ name: "TestHero", value: false, pct: 50 }]);
+  });
+
+  it("re-rolls when the cookie's traffic fingerprint is stale", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.1); // < 0.5 -> test
+    // Cookie says the user was in control at 70% traffic; current traffic is 50%.
+    const c = ctx({ value: false, pct: 70 });
+
+    const result = await resolveValue(FLAG, undefined, c);
+
+    expect(result).toBe("VARIANT_1");
+    expect(c.flags).toEqual([{ name: "TestHero", value: true, pct: 50 }]);
+  });
+
+  it("does not record flags when recording is not opted into", async () => {
+    vi.spyOn(Math, "random").mockReturnValue(0.1);
+    // No `flags` array on the context -> nothing to record, but still resolves.
+    const result = await resolveValue(FLAG, undefined, { cookies: {} });
+    expect(result).toBe("VARIANT_1");
+  });
+
+  it("honors the admin matchers-override instead of the cookie/roll", async () => {
+    const rand = vi.spyOn(Math, "random");
+    // Admin forces TestHero=0 for preview, but the cookie says test cohort.
+    const c: MatcherContext & { flags: StoredFlag[] } = {
+      cookies: {
+        deco_segment: serializeSegmentCookie([{ name: "TestHero", value: true, pct: 50 }]),
+      },
+      headers: { [DECO_MATCHERS_OVERRIDE_PARAM]: "TestHero=0" },
+      flags: [],
+    };
+
+    const result = await resolveValue(FLAG, undefined, c);
+
+    expect(result).toBe("VARIANT_2"); // override wins over the cookie
+    expect(rand).not.toHaveBeenCalled();
+    expect(c.flags).toEqual([]); // previews don't persist a cohort
+  });
+});

package/src/hooks/Picture.tsx

@@ -1,5 +1,6 @@
 import {
 	type ComponentPropsWithoutRef,
+	type Context,
 	createContext,
 	forwardRef,
 	type ReactNode,
@@ -12,13 +13,27 @@ import { type FitOptions, getOptimizedMediaUrl, getSrcSet } from "./Image";
 // Preload context — flows from <Picture preload> to child <Source> elements
 // so each source can inject its own <link rel="preload"> with the correct
 // media query for responsive art direction.
+//
+// Created LAZILY (first render), not at module scope: this file has no
+// "use client" directive, so in a react-server graph (a Server Component
+// page, or ANY Next.js route handler — which ignores "use client"
+// entirely) the module evaluates against React's react-server build, where
+// `createContext` does not exist. A module-scope call crashes the whole
+// graph at import time ("createContext is not a function") even if
+// Picture/Source never render. Deferring to render time is safe: renders
+// only ever happen under a full React build (client or SSR), and both
+// components resolve the same memoized context object.
 // -------------------------------------------------------------------------
 
 interface PreloadContextValue {
 	preload: boolean;
 }
 
-const PreloadContext = createContext<PreloadContextValue>({ preload: false });
+let _preloadContext: Context<PreloadContextValue> | null = null;
+function getPreloadContext(): Context<PreloadContextValue> {
+	_preloadContext ??= createContext<PreloadContextValue>({ preload: false });
+	return _preloadContext;
+}
 
 // -------------------------------------------------------------------------
 // Source — composable <source> with automatic srcSet optimization and
@@ -41,7 +56,7 @@ export const Source = forwardRef<HTMLSourceElement, SourceProps>(function Source
 	{ src, width, height, fetchPriority, fit = "cover", ...rest },
 	ref,
 ) {
-	const { preload } = useContext(PreloadContext);
+	const { preload } = useContext(getPreloadContext());
 
 	const optimizedSrc = getOptimizedMediaUrl({
 		originalSrc: src,
@@ -93,6 +108,7 @@ export const Picture = forwardRef<HTMLPictureElement, PictureProps>(function Pic
 	ref,
 ) {
 	const value = useMemo(() => ({ preload }), [preload]);
+	const PreloadContext = getPreloadContext();
 
 	return (
 		<PreloadContext.Provider value={value}>

package/src/middleware/observability.test.ts

@@ -81,13 +81,13 @@ describe("recordRequestMetric — canonical labels (D-11)", () => {
     expect(counters).toHaveLength(0);
     expect(histograms).toHaveLength(1);
     expect(histograms[0]?.name).toBe(MetricNames.HTTP_SERVER_REQUEST_DURATION);
-    expect(histograms[0]?.value).toBe(42);
+    expect(histograms[0]?.value).toBe(0.042); // seconds (semconv)
     expect(histograms[0]?.labels).toMatchObject({
-      method: "GET",
+      "http.request.method": "GET",
       // Default normalization: dynamic segments collapsed.
-      route_pattern: "/products/:slug/p",
-      status: 200,
-      status_class: "2xx",
+      "http.route": "/products/:slug/p",
+      "http.response.status_code": 200,
+      "deco.http.status_class": "2xx",
     });
   });
 
@@ -99,7 +99,7 @@ describe("recordRequestMetric — canonical labels (D-11)", () => {
       route_pattern: "/_products/$slug/p",
     });
 
-    expect(histograms[0]?.labels?.route_pattern).toBe("/_products/$slug/p");
+    expect(histograms[0]?.labels?.["http.route"]).toBe("/_products/$slug/p");
   });
 
   it("tags 5xx requests with status_class=5xx for downstream error filtering", () => {
@@ -108,8 +108,8 @@ describe("recordRequestMetric — canonical labels (D-11)", () => {
 
     recordRequestMetric("POST", "/checkout", 503, 120);
 
-    expect(histograms[0]?.labels?.status_class).toBe("5xx");
-    expect(histograms[0]?.labels?.status).toBe(503);
+    expect(histograms[0]?.labels?.["deco.http.status_class"]).toBe("5xx");
+    expect(histograms[0]?.labels?.["http.response.status_code"]).toBe(503);
   });
 
   it("propagates optional labels (outcome, cache_decision, cache_layer, region, extra)", () => {
@@ -125,10 +125,10 @@ describe("recordRequestMetric — canonical labels (D-11)", () => {
     });
 
     expect(histograms[0]?.labels).toMatchObject({
-      outcome: "ok",
-      cache_decision: "STALE-HIT",
-      cache_layer: "edge",
-      region: "GRU",
+      "deco.http.outcome": "ok",
+      "deco.cache.decision": "STALE-HIT",
+      "deco.cache.layer": "edge",
+      "deco.http.region": "GRU",
       ab_variant: "B",
     });
   });
@@ -154,21 +154,22 @@ describe("recordCacheMetric — cache_layer label", () => {
     recordCacheMetric(true, "product", "HIT", "edge");
 
     expect(counters).toHaveLength(1);
-    expect(counters[0]?.name).toBe(MetricNames.CACHE_HIT);
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_REQUESTS);
     expect(counters[0]?.labels).toMatchObject({
-      profile: "product",
-      cache_decision: "HIT",
-      cache_layer: "edge",
+      "deco.cache.profile": "product",
+      "deco.cache.status": "HIT",
+      "deco.cache.layer": "edge",
     });
   });
 
-  it("emits cache_miss_total when hit=false", () => {
+  it("records status=MISS when hit=false", () => {
     const { adapter, counters } = captureMeter();
     configureMeter(adapter);
 
     recordCacheMetric(false, "search", "MISS", "edge");
 
-    expect(counters[0]?.name).toBe(MetricNames.CACHE_MISS);
+    expect(counters[0]?.name).toBe(MetricNames.CACHE_REQUESTS);
+    expect(counters[0]?.labels?.["deco.cache.status"]).toBe("MISS");
   });
 
   it("supports the legacy 3-arg signature for backward compat", () => {
@@ -177,7 +178,10 @@ describe("recordCacheMetric — cache_layer label", () => {
 
     recordCacheMetric(true, "static");
 
-    expect(counters[0]?.labels).toEqual({ profile: "static" });
+    expect(counters[0]?.labels).toEqual({
+      "deco.cache.status": "HIT",
+      "deco.cache.profile": "static",
+    });
   });
 
   it("distinguishes cachedLoader vs edge vs vtex-swr layers", () => {
@@ -187,8 +191,8 @@ describe("recordCacheMetric — cache_layer label", () => {
     recordCacheMetric(true, "loader-x", "HIT", "cachedLoader");
     recordCacheMetric(true, "vtex-product", "HIT", "vtex-swr");
 
-    expect(counters[0]?.labels?.cache_layer).toBe("cachedLoader");
-    expect(counters[1]?.labels?.cache_layer).toBe("vtex-swr");
+    expect(counters[0]?.labels?.["deco.cache.layer"]).toBe("cachedLoader");
+    expect(counters[1]?.labels?.["deco.cache.layer"]).toBe("vtex-swr");
   });
 });
 
@@ -209,7 +213,7 @@ describe("recordCommerceMetric (D-11)", () => {
 
     expect(histograms).toHaveLength(1);
     expect(histograms[0]?.name).toBe(MetricNames.HTTP_CLIENT_REQUEST_DURATION);
-    expect(histograms[0]?.value).toBe(123);
+    expect(histograms[0]?.value).toBe(0.123); // seconds (semconv)
     expect(histograms[0]?.labels).toMatchObject({
       provider: "vtex",
       operation: "intelligent-search.product_search",

package/src/middleware/observability.ts

@@ -34,6 +34,9 @@
 
 import * as asyncHooks from "node:async_hooks";
 import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_RESPONSE_STATUS_CODE,
+  ATTR_HTTP_ROUTE,
   METRIC_HTTP_CLIENT_REQUEST_DURATION,
   METRIC_HTTP_SERVER_REQUEST_DURATION,
 } from "@opentelemetry/semantic-conventions";
@@ -257,8 +260,10 @@ export const MetricNames = {
   HTTP_SERVER_REQUEST_DURATION: METRIC_HTTP_SERVER_REQUEST_DURATION,
   HTTP_CLIENT_REQUEST_DURATION: METRIC_HTTP_CLIENT_REQUEST_DURATION,
   // Deco extensions — no canonical OTel metric exists for these concepts.
-  CACHE_HIT: "deco.cache.hits",
-  CACHE_MISS: "deco.cache.misses",
+  // Single cache counter dimensioned by `deco.cache.status` — follows the OTel
+  // semconv pattern (cf. nfs.server.repcache.requests + .status). deco-cx/deco
+  // uses the same name so both frameworks aggregate together.
+  CACHE_REQUESTS: "deco.cache.requests",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
   LOADER_ERRORS: "deco.loader.errors",
@@ -266,11 +271,9 @@ export const MetricNames = {
 
 /**
  * Per-metric metadata emitted in the OTLP payload's `description` and
- * `unit` fields. The framework declares units honestly — durations are in
- * `ms` because that's what `recordRequestMetric`-style callers pass. If a
- * downstream consumer needs canonical OTel seconds for
- * `http.server.request.duration`, conversion happens in the collector or
- * the query layer, NOT in this framework.
+ * `unit` fields. Durations are normalized to **seconds at the source** (OTel
+ * semconv), matching the deco-cx/deco framework — NOT converted downstream in
+ * the collector. Callers still pass milliseconds; the record helpers divide.
  *
  * Keep keys aligned with `MetricNames` values so a missing entry is a
  * type error at compile time when a new metric ships without metadata.
@@ -278,27 +281,23 @@ export const MetricNames = {
 export const METRIC_METADATA: Record<string, { description: string; unit: string }> = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
     description: "Duration of HTTP server requests handled at the Worker entry point.",
-    unit: "ms",
+    unit: "s",
   },
   [MetricNames.HTTP_CLIENT_REQUEST_DURATION]: {
     description: "Duration of outbound HTTP client requests (commerce, generic fetch).",
-    unit: "ms",
+    unit: "s",
   },
-  [MetricNames.CACHE_HIT]: {
-    description: "Cache lookups resulting in HIT, STALE-HIT, or STALE-ERROR.",
-    unit: "{request}",
-  },
-  [MetricNames.CACHE_MISS]: {
-    description: "Cache lookups resulting in MISS or BYPASS.",
+  [MetricNames.CACHE_REQUESTS]: {
+    description: "Cache lookups, dimensioned by deco.cache.status (hit/stale/miss/bypass).",
     unit: "{request}",
   },
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",
-    unit: "ms",
+    unit: "s",
   },
   [MetricNames.LOADER_DURATION]: {
     description: "Per-loader execution duration, emitted by cachedLoader.",
-    unit: "ms",
+    unit: "s",
   },
   [MetricNames.LOADER_ERRORS]: {
     description: "Per-loader error count.",
@@ -321,10 +320,11 @@ export function statusClassFor(status: number): string {
 }
 
 /**
- * Optional dimensions stamped on `http_requests_total` /
- * `http_request_duration_ms` / `http_request_errors_total`. All fields
- * are optional — callers pass what they have, the framework fills in
- * the rest from defaults.
+ * Optional dimensions stamped on `http.server.request.duration` (semconv).
+ * Request count and error rate are derived from the histogram's `count` and
+ * a `http.response.status_code` filter — the old separate `_total` /
+ * `_errors_total` counters were removed. All fields are optional — callers
+ * pass what they have, the framework fills in the rest from defaults.
  *
  * Cardinality discipline: every field here is bounded. `route_pattern`
  * comes from the TanStack router (a closed set), `outcome` is the CF
@@ -403,16 +403,19 @@ export function recordRequestMetric(
   // Total combinations are bounded — safe for unbounded series on
   // ClickHouse but operators should still avoid grouping by `region`
   // unless explicitly needed.
+  // semconv attribute keys for the core HTTP dimensions; deco.* for the
+  // proprietary extras. Unified with deco-cx/deco so both frameworks land on
+  // the same series/labels in ClickHouse.
   const merged: Labels = {
-    method,
-    route_pattern: labels?.route_pattern ?? normalizePath(path),
-    status,
-    status_class: statusClassFor(status),
+    [ATTR_HTTP_REQUEST_METHOD]: method,
+    [ATTR_HTTP_ROUTE]: labels?.route_pattern ?? normalizePath(path),
+    [ATTR_HTTP_RESPONSE_STATUS_CODE]: status,
+    "deco.http.status_class": statusClassFor(status),
   };
-  if (labels?.outcome) merged.outcome = labels.outcome;
-  if (labels?.cache_decision) merged.cache_decision = labels.cache_decision;
-  if (labels?.cache_layer) merged.cache_layer = labels.cache_layer;
-  if (labels?.region) merged.region = labels.region;
+  if (labels?.outcome) merged["deco.http.outcome"] = labels.outcome;
+  if (labels?.cache_decision) merged["deco.cache.decision"] = labels.cache_decision;
+  if (labels?.cache_layer) merged["deco.cache.layer"] = labels.cache_layer;
+  if (labels?.region) merged["deco.http.region"] = labels.region;
   if (labels?.extra) {
     for (const [k, v] of Object.entries(labels.extra)) {
       // Defense-in-depth — refuse to stamp known per-request identifiers
@@ -430,7 +433,12 @@ export function recordRequestMetric(
   // filtering on `http.response.status_code`. Separate `_total` /
   // `_errors_total` counters were removed because they duplicate
   // histogram-derived signals and aren't part of the canonical spec.
-  m.histogramRecord?.(MetricNames.HTTP_SERVER_REQUEST_DURATION, durationMs, merged);
+  // Record in seconds (semconv) — caller passes ms.
+  m.histogramRecord?.(
+    MetricNames.HTTP_SERVER_REQUEST_DURATION,
+    durationMs / 1000,
+    merged,
+  );
 }
 
 /**
@@ -480,28 +488,30 @@ export function recordCacheMetric(
   // meter is a no-op (e.g. on tests, or in dev without DECO_METRICS).
   const active = getActiveSpan();
   if (active) {
-    if (decision) active.setAttribute?.("deco.cache.decision", decision);
+    if (decision) active.setAttribute?.("deco.cache.status", decision);
     if (profile) active.setAttribute?.("deco.cache.profile", profile);
     if (layer) active.setAttribute?.("deco.cache.layer", layer);
   }
 
   const m = getState().meter;
   if (!m) return;
-  // Label names mirror the dotted span attributes `deco.cache.decision`,
-  // `deco.cache.profile`, `deco.cache.layer` (see model/registry/deco.yaml +
-  // model/metrics.yaml). Prometheus convention requires snake_case without
-  // dots — so `cache_decision` / `cache_layer` (not `decision` / `layer`).
-  const labels: Labels = {};
-  if (profile) labels.profile = profile;
-  if (decision) labels.cache_decision = decision;
-  if (layer) labels.cache_layer = layer;
-  m.counterInc(hit ? MetricNames.CACHE_HIT : MetricNames.CACHE_MISS, 1, labels);
+  // Single counter dimensioned by deco.cache.status — unified with deco-cx/deco
+  // (follows the semconv nfs.server.repcache.requests + .status pattern). status
+  // is the decision when known (HIT/STALE-HIT/STALE-ERROR/MISS/BYPASS), else the
+  // hit boolean. Same key on span + metric.
+  const labels: Labels = {
+    "deco.cache.status": decision ?? (hit ? "HIT" : "MISS"),
+  };
+  if (profile) labels["deco.cache.profile"] = profile;
+  if (layer) labels["deco.cache.layer"] = layer;
+  m.counterInc(MetricNames.CACHE_REQUESTS, 1, labels);
 }
 
 /**
- * Labels for `commerce_request_duration_ms`. Owned by the framework so
- * apps-start (and any future provider package) can register operation
- * strings without owning the histogram declaration. Phase 2 (D-11).
+ * Labels for the outbound commerce sample recorded on
+ * `http.client.request.duration`. Owned by the framework so apps-start (and
+ * any future provider package) can register operation strings without owning
+ * the histogram declaration. Phase 2 (D-11).
  */
 export interface CommerceMetricLabels {
   /** `vtex`, `shopify`, `wake`, ... — small closed set. */
@@ -515,10 +525,10 @@ export interface CommerceMetricLabels {
 }
 
 /**
- * Record a commerce / outbound-fetch duration sample. No-op when no
- * meter is configured. The metric name is constant
- * (`commerce_request_duration_ms`) — providers vary by the `provider`
- * label, not by name, so dashboards aggregate cleanly across the fleet.
+ * Record a commerce / outbound-fetch duration sample. No-op when no meter is
+ * configured. Emitted on the canonical `http.client.request.duration` metric
+ * (semconv) — providers vary by the `provider`/`operation` labels, not by
+ * name, so dashboards aggregate cleanly across the fleet.
  */
 export function recordCommerceMetric(
   durationMs: number,
@@ -535,7 +545,12 @@ export function recordCommerceMetric(
   // Canonical OTel HTTP client metric — outbound commerce calls share the
   // same metric as any other outbound HTTP request; `peer.service` /
   // `commerce.operation` attributes disambiguate consumer queries.
-  m.histogramRecord?.(MetricNames.HTTP_CLIENT_REQUEST_DURATION, durationMs, merged);
+  // Record in seconds (semconv) — caller passes ms.
+  m.histogramRecord?.(
+    MetricNames.HTTP_CLIENT_REQUEST_DURATION,
+    durationMs / 1000,
+    merged,
+  );
 }
 
 /**
@@ -551,9 +566,10 @@ export function recordLoaderMetric(
 ) {
   const m = getState().meter;
   if (!m) return;
-  m.histogramRecord?.(MetricNames.LOADER_DURATION, durationMs, {
-    loader: name,
-    cache_status: cacheStatus,
+  // Record in seconds (semconv) — caller passes ms.
+  m.histogramRecord?.(MetricNames.LOADER_DURATION, durationMs / 1000, {
+    "deco.loader.name": name,
+    "deco.cache.result": cacheStatus,
   });
 }
 
@@ -564,10 +580,17 @@ export function recordLoaderMetric(
 export function recordLoaderError(name: string) {
   const m = getState().meter;
   if (!m) return;
-  m.counterInc(MetricNames.LOADER_ERRORS, 1, { loader: name });
+  m.counterInc(MetricNames.LOADER_ERRORS, 1, { "deco.loader.name": name });
 }
 
-function normalizePath(path: string): string {
+/**
+ * Collapse dynamic path segments (ids, product slugs) into placeholders so a
+ * path can be used as a bounded metric label. Exported so every metric that
+ * labels by route (`http.server.request.duration`, `deco.cms.resolve.duration`)
+ * shares the exact same normalization — a raw path is unbounded cardinality
+ * (one histogram series per URL) and must never reach a metric attribute.
+ */
+export function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
   return path
     .replace(/\/[0-9a-f]{8,}/gi, "/:id")

package/src/sdk/detectDevice.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure User-Agent device detection — no React, no RequestContext, no
+ * side effects. Import from HERE (not `./useDevice`) in any module that can
+ * end up in a Next.js App Router **route handler** graph.
+ *
+ * Why this file exists: `useDevice.ts` re-exports the `"use client"`
+ * context half (`./useDeviceContext`, which calls `createContext` at module
+ * scope) for backward compatibility. That re-export is harmless in Server
+ * Components — Next honors the `"use client"` boundary there — but route
+ * handlers (App Router route.ts files) have NO client graph: the directive
+ * is ignored, the module executes against Next's vendored **RSC** React
+ * (`vendored/rsc/react.js`), and that build has no `createContext`, so the
+ * whole route module crashes at evaluation time
+ * ("...createContext is not a function"). `@decocms/nextjs`'s admin route
+ * handlers reach device detection via `cms/sectionMixins.ts`
+ * (`detectDevice`) and `sdk/requestContext.ts` (`isMobileUA`) — both now
+ * import this leaf so their graphs never touch the client context file.
+ */
+
+export type Device = "mobile" | "tablet" | "desktop";
+
+// Android phones include "Mobile" in their UA; Android tablets do not.
+// Check TABLET_RE first so `android(?!.*mobile)` captures tablets before
+// the MOBILE_RE `android.*mobile` branch matches phones.
+export const MOBILE_RE = /mobile|android.*mobile|iphone|ipod|webos|blackberry|opera mini|iemobile/i;
+export const TABLET_RE = /ipad|tablet|kindle|silk|playbook|android(?!.*mobile)/i;
+
+/**
+ * Simple mobile-or-not check (mobile + tablet = true).
+ * Use this for cache key splitting or any context where you
+ * only need a mobile/desktop binary decision.
+ */
+export function isMobileUA(userAgent: string): boolean {
+  return MOBILE_RE.test(userAgent) || TABLET_RE.test(userAgent);
+}
+
+/**
+ * Detect device type from a User-Agent string.
+ * Pure function — no side effects, works anywhere.
+ */
+export function detectDevice(userAgent: string): Device {
+  if (TABLET_RE.test(userAgent)) return "tablet";
+  if (MOBILE_RE.test(userAgent)) return "mobile";
+  return "desktop";
+}

package/src/sdk/flags.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseSegmentCookie,
+  type StoredFlag,
+  segmentCacheToken,
+  serializeSegmentCookie,
+  trafficToPct,
+} from "./flags";
+
+describe("trafficToPct", () => {
+  it("maps a ratio to a 0-100 integer", () => {
+    expect(trafficToPct(0.5)).toBe(50);
+    expect(trafficToPct(0.234)).toBe(23);
+  });
+
+  it("clamps out-of-range and non-finite values", () => {
+    expect(trafficToPct(0)).toBe(0);
+    expect(trafficToPct(-1)).toBe(0);
+    expect(trafficToPct(1)).toBe(100);
+    expect(trafficToPct(2)).toBe(100);
+    expect(trafficToPct(NaN)).toBe(0);
+  });
+});
+
+describe("deco_segment round-trip", () => {
+  it("round-trips a single active flag", () => {
+    const flags: StoredFlag[] = [{ name: "TestHero", value: true, pct: 50 }];
+    expect(parseSegmentCookie(serializeSegmentCookie(flags))).toEqual(flags);
+  });
+
+  it("round-trips active + inactive flags (sorted by name)", () => {
+    const flags: StoredFlag[] = [
+      { name: "Zeta", value: false, pct: 20 },
+      { name: "Alpha", value: true, pct: 70 },
+    ];
+    expect(parseSegmentCookie(serializeSegmentCookie(flags))).toEqual([
+      { name: "Alpha", value: true, pct: 70 },
+      { name: "Zeta", value: false, pct: 20 },
+    ]);
+  });
+
+  it("produces the classic deco_segment shape that OneDollarStats reads", () => {
+    const raw = serializeSegmentCookie([
+      { name: "TestHero", value: true, pct: 50 },
+      { name: "Promo", value: false, pct: 30 },
+    ]);
+    // Mirrors @decocms/apps OneDollarStats readFlagsFromCookie decode.
+    const seg = JSON.parse(decodeURIComponent(atob(raw)));
+    expect(seg.active).toContain("TestHero");
+    expect(seg.inactiveDrawn).toContain("Promo");
+    expect(seg.pct).toEqual({ TestHero: 50, Promo: 30 });
+  });
+
+  it("is raw base64 (no percent-escapes) so atob() works directly", () => {
+    const raw = serializeSegmentCookie([{ name: "TestHero", value: true, pct: 50 }]);
+    expect(raw).not.toMatch(/%/);
+    expect(() => atob(raw)).not.toThrow();
+  });
+});
+
+describe("parseSegmentCookie robustness", () => {
+  it("returns [] for empty / nullish / malformed input", () => {
+    expect(parseSegmentCookie(undefined)).toEqual([]);
+    expect(parseSegmentCookie(null)).toEqual([]);
+    expect(parseSegmentCookie("")).toEqual([]);
+    expect(parseSegmentCookie("not-base64-!!!")).toEqual([]);
+  });
+
+  it("marks classic segments without a pct fingerprint as pct: -1", () => {
+    const raw = btoa(encodeURIComponent(JSON.stringify({ active: ["Legacy"], inactiveDrawn: [] })));
+    expect(parseSegmentCookie(raw)).toEqual([{ name: "Legacy", value: true, pct: -1 }]);
+  });
+});
+
+describe("segmentCacheToken", () => {
+  it("is empty for no flags so non-A/B pages share a cache entry", () => {
+    expect(segmentCacheToken([])).toBe("");
+  });
+
+  it("includes the pct fingerprint so a traffic change re-buckets", () => {
+    const at50 = segmentCacheToken([{ name: "TestHero", value: true, pct: 50 }]);
+    const at70 = segmentCacheToken([{ name: "TestHero", value: true, pct: 70 }]);
+    expect(at50).not.toBe(at70);
+  });
+
+  it("differs by decision so cohorts split", () => {
+    const on = segmentCacheToken([{ name: "TestHero", value: true, pct: 50 }]);
+    const off = segmentCacheToken([{ name: "TestHero", value: false, pct: 50 }]);
+    expect(on).not.toBe(off);
+  });
+});

package/src/sdk/flags.ts

@@ -0,0 +1,108 @@
+/**
+ * Sticky A/B flag persistence via the `deco_segment` cookie — shared by the
+ * resolver (SSR variant selection), the worker entry (cache-key cohort
+ * splitting), and consumed by analytics (@decocms/apps OneDollarStats reads
+ * the same cookie to enrich pageviews/events).
+ *
+ * ## Why
+ *
+ * `website/matchers/random.ts` is a stateless `Math.random() < traffic`, so a
+ * visitor's variant used to be re-rolled on every request AND frozen per
+ * edge-cache entry (the HTML is cached and the cache key never carried the
+ * variant). The variant a first visitor happened to roll then got served to
+ * everyone in that device/geo bucket, and analytics never saw the flag.
+ *
+ * ## Cookie format
+ *
+ * `deco_segment` is the classic deco segment cookie:
+ * `btoa(encodeURIComponent(JSON.stringify({ active, inactiveDrawn, pct })))`.
+ * - `active` — flag names the visitor was assigned to (`true` branch).
+ * - `inactiveDrawn` — flag names drawn but not matched (`false` branch).
+ * - `pct` — `{ name: round(traffic*100) }`, a deco-start extension (analytics
+ *   ignores unknown fields) used as the re-roll fingerprint: when the operator
+ *   changes `traffic` and redeploys, the fingerprint no longer matches and the
+ *   visitor is re-rolled once, then re-sticks — same self-healing scheme as
+ *   {@link ./abTesting.ts}.
+ *
+ * The cookie MUST be written un-encoded (raw base64) — OneDollarStats reads it
+ * with `atob()` directly. Base64's `+ / =` are all valid cookie-value octets
+ * (RFC 6265), so pass `encode: (v) => v` to the cookie setter.
+ */
+
+/** Cookie carrying the visitor's sticky flag decisions (classic deco segment). */
+export const SEGMENT_COOKIE = "deco_segment";
+
+/** A recorded flag decision: which named flag, the branch taken, and the
+ *  `traffic` fingerprint (0–100) it was decided under. */
+export interface StoredFlag {
+  /** Matcher block name, e.g. "TestHero". Stable identity for the cohort. */
+  name: string;
+  /** The branch the visitor was assigned to. */
+  value: boolean;
+  /** `round(traffic * 100)` at assignment time — the re-roll fingerprint. */
+  pct: number;
+}
+
+/** Wire shape of the `deco_segment` cookie payload. */
+interface DecoSegment {
+  active?: string[];
+  inactiveDrawn?: string[];
+  /** deco-start extension: per-flag traffic fingerprint. Ignored by analytics. */
+  pct?: Record<string, number>;
+}
+
+/** Convert a 0–1 traffic ratio to the 0–100 integer fingerprint. */
+export function trafficToPct(traffic: number): number {
+  if (!Number.isFinite(traffic) || traffic <= 0) return 0;
+  if (traffic >= 1) return 100;
+  return Math.round(traffic * 100);
+}
+
+/**
+ * Parse the `deco_segment` cookie value into decisions. The value is raw
+ * base64 (no URL-decoding needed). Foreign cookies without the `pct` extension
+ * parse with `pct: -1`, which the resolver treats as "always matches" so a
+ * classic-deco segment stays sticky instead of re-rolling. Malformed cookies
+ * yield `[]`.
+ */
+export function parseSegmentCookie(raw: string | undefined | null): StoredFlag[] {
+  if (!raw) return [];
+  try {
+    const seg = JSON.parse(decodeURIComponent(atob(raw))) as DecoSegment;
+    const pct = seg.pct ?? {};
+    const out: StoredFlag[] = [];
+    for (const name of seg.active ?? []) out.push({ name, value: true, pct: pct[name] ?? -1 });
+    for (const name of seg.inactiveDrawn ?? []) {
+      out.push({ name, value: false, pct: pct[name] ?? -1 });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** Serialize decisions into a raw-base64 `deco_segment` cookie value. */
+export function serializeSegmentCookie(flags: StoredFlag[]): string {
+  const active: string[] = [];
+  const inactiveDrawn: string[] = [];
+  const pct: Record<string, number> = {};
+  for (const f of [...flags].sort((a, b) => a.name.localeCompare(b.name))) {
+    (f.value ? active : inactiveDrawn).push(f.name);
+    pct[f.name] = f.pct;
+  }
+  const seg: DecoSegment = { active, inactiveDrawn, pct };
+  return btoa(encodeURIComponent(JSON.stringify(seg)));
+}
+
+/**
+ * Stable token for the cache key — includes the `pct` fingerprint so a
+ * `traffic` change lands cohorts in fresh buckets. Empty string when there are
+ * no flags, so non-A/B pages keep sharing one entry.
+ */
+export function segmentCacheToken(flags: StoredFlag[]): string {
+  if (!flags.length) return "";
+  return [...flags]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((f) => `${f.name}:${f.value ? "1" : "0"}:${f.pct}`)
+    .join(",");
+}

package/src/sdk/requestContext.ts

@@ -87,7 +87,7 @@ export interface RequestContextData {
 // Storage
 // -------------------------------------------------------------------------
 
-import { isMobileUA } from "./useDevice";
+import { isMobileUA } from "./detectDevice";
 
 const BOT_RE =
   /bot|crawl|spider|slurp|bingpreview|facebookexternalhit|linkedinbot|twitterbot|whatsapp|telegram|googlebot|yandex|baidu|duckduck/i;

package/src/sdk/useDevice.ts

@@ -21,52 +21,32 @@
  * ```
  */
 
+import { detectDevice } from "./detectDevice";
 import { RequestContext } from "./requestContext";
 
-export type Device = "mobile" | "tablet" | "desktop";
+// The pure UA-parsing half (`Device`, `MOBILE_RE`, `TABLET_RE`,
+// `isMobileUA`, `detectDevice`) lives in `./detectDevice` — a leaf with no
+// React and no RequestContext — and is re-exported below for backward
+// compatibility. Modules that can land in a Next.js route-handler graph
+// (`cms/sectionMixins.ts`, `sdk/requestContext.ts`) MUST import that leaf
+// directly, not this file: this file also re-exports the `"use client"`
+// context half, which crashes route handlers (see ./detectDevice's doc
+// comment for the vendored-RSC-React mechanics).
+export { type Device, detectDevice, isMobileUA, MOBILE_RE, TABLET_RE } from "./detectDevice";
 
 // `DeviceContext`, the `useDevice()` hook, and `DeviceProvider` live in
 // `./useDeviceContext` (a `"use client"` file) and are re-exported below for
 // full backward compatibility with this module's public API — see that
-// file's doc comment for why the split exists. Everything that stays in
-// *this* file is a plain, hook-free function, safe to import from
-// server-only code (e.g. `cms/sectionMixins.ts`'s `withDevice()`/
-// `withMobile()` loader mixins) without dragging a client-only hook/context
-// boundary into a Server Component's module graph.
+// file's doc comment for why the split exists.
 export { DeviceContext, useDevice, DeviceProvider } from "./useDeviceContext";
 
-// Android phones include "Mobile" in their UA; Android tablets do not.
-// Check TABLET_RE first so `android(?!.*mobile)` captures tablets before
-// the MOBILE_RE `android.*mobile` branch matches phones.
-export const MOBILE_RE = /mobile|android.*mobile|iphone|ipod|webos|blackberry|opera mini|iemobile/i;
-export const TABLET_RE = /ipad|tablet|kindle|silk|playbook|android(?!.*mobile)/i;
-
-/**
- * Simple mobile-or-not check (mobile + tablet = true).
- * Use this for cache key splitting or any context where you
- * only need a mobile/desktop binary decision.
- */
-export function isMobileUA(userAgent: string): boolean {
-  return MOBILE_RE.test(userAgent) || TABLET_RE.test(userAgent);
-}
-
-/**
- * Detect device type from a User-Agent string.
- * Pure function — no side effects, works anywhere.
- */
-export function detectDevice(userAgent: string): Device {
-  if (TABLET_RE.test(userAgent)) return "tablet";
-  if (MOBILE_RE.test(userAgent)) return "mobile";
-  return "desktop";
-}
-
 /**
  * Resolve the current device from the ambient runtime (RequestContext on the
  * server, `navigator.userAgent` on the client) — no React hooks involved.
  * Used both by the plain `check*()` helpers below and by `useDevice()`/
  * `DeviceProvider` in `./useDeviceContext`.
  */
-export function resolveDeviceFromRuntime(): Device {
+export function resolveDeviceFromRuntime(): ReturnType<typeof detectDevice> {
   // Server: use RequestContext UA header
   if (typeof document === "undefined") {
     const ctx = RequestContext.current;