@tokenoftrust/storefront-runner 2.0.40 → 2.0.42

package/apps/storefront/src/lib/content/trustStrip.ts

@@ -12,17 +12,43 @@
  *
  * Node-free + presentation-free; the .astro widget renders the sanitized items.
  */
-import { isFabricatedTrustProof } from "@tot/public-runtime";
+import {
+  isFabricatedTrustProof,
+  isSafeRehostedAssetPath,
+  isSafeRehostedAssetPathForTenant,
+} from "@tot/public-runtime";
 
 export type TrustStripItem =
   /** A plain proof claim, e.g. "Ships from USA", "Lab-tested". */
-  | { kind: "claim"; label: string }
+  | { kind: "claim"; label: string; icon?: string; iconAlt?: string }
   /**
    * A REAL aggregate rating. Surfaced only when `average` (1–5) and `count`
    * are real positive finite numbers — a half-populated aggregate is dropped.
    */
   | { kind: "rating"; average: number; count: number; label?: string };
 
+/** Stable, declarative mobile ordering; unknown/duplicate labels are harmless. */
+export function orderTrustStripForMobile(
+  items: ReadonlyArray<TrustStripItem>,
+  preferredLabels?: ReadonlyArray<string>,
+): TrustStripItem[] {
+  if (!preferredLabels?.length) return [...items];
+  const rank = new Map<string, number>();
+  for (const label of preferredLabels) {
+    const normalized = label.trim();
+    if (normalized && !rank.has(normalized)) rank.set(normalized, rank.size);
+  }
+  return items
+    .map((item, index) => ({ item, index, rank: rank.get(item.label?.trim() ?? "") }))
+    .sort((a, b) => {
+      if (a.rank === undefined && b.rank === undefined) return a.index - b.index;
+      if (a.rank === undefined) return 1;
+      if (b.rank === undefined) return -1;
+      return a.rank - b.rank;
+    })
+    .map(({ item }) => item);
+}
+
 /** True when a rating token is backed by real, positive, finite numbers. */
 export function isRealRating(
   item: Extract<TrustStripItem, { kind: "rating" }>,
@@ -46,13 +72,22 @@ export function isRealRating(
  */
 export function sanitizeTrustStrip(
   items: ReadonlyArray<TrustStripItem>,
+  tenantId?: string,
 ): TrustStripItem[] {
   const out: TrustStripItem[] = [];
   for (const item of items) {
     if (item.kind === "claim") {
       const label = item.label.trim();
       if (label.length > 0 && !isFabricatedTrustProof(label)) {
-        out.push({ kind: "claim", label });
+        out.push({
+          kind: "claim",
+          label,
+          ...((tenantId
+            ? isSafeRehostedAssetPathForTenant(item.icon, tenantId)
+            : isSafeRehostedAssetPath(item.icon))
+            ? { icon: item.icon, iconAlt: item.iconAlt?.trim() || "" }
+            : {}),
+        });
       }
     } else if (item.kind === "rating") {
       if (isRealRating(item)) out.push(item);

package/apps/storefront/src/lib/cspStaticHashes.ts

@@ -2,7 +2,8 @@
  * CSP hashes for the **static** inline `<script>`/`<style>` that Astro emits in
  * the production build — the `client:load|idle|only` hydration directive
  * loaders, the `<astro-island>` definition, the `astro-island{display:contents}`
- * style, and bundled Layout scripts. These are identical across tenants and
+ * style, bundled Layout scripts, and reviewed static runtime documents such as
+ * the GA4 sandbox. These are identical across tenants and
  * requests (no dynamic data), so hashes (not nonces) are the correct, strict
  * tool for them.
  *
@@ -17,6 +18,8 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c='",
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
+  "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
+  "'sha256-yxhGRh5KeGL1P3NgVN7YoKE4N5zBl1XGEycWPbX0TWo='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

package/apps/storefront/src/lib/diag/capture.ts

@@ -0,0 +1,161 @@
+/**
+ * What debug mode is ALLOWED to capture (ADR 0034).
+ *
+ * THE DIRECTION IS THE DECISION. This is an allowlist, not a denylist. A denylist captures every new
+ * field until someone remembers to exclude it, which makes the leak the default and guarantees that
+ * the one field nobody thought about is the one that ships. Here a new field is invisible until
+ * somebody deliberately adds it, and the cost — some bugs still need us — is accepted.
+ *
+ * The permitted set is derived from what the flows actually emit, not invented:
+ *   - operation stages are a CLOSED set (`operation-contract.ts`), so they cannot carry tenant data;
+ *   - problem codes are a CLOSED enum;
+ *   - routes are captured as PATTERNS from a fixed list, never as URLs — a raw URL carries path
+ *     params and query strings, which on a regulated storefront is exactly where the data is;
+ *   - timings and viewport are numbers.
+ *
+ * Everything else is dropped: raw URLs, query strings and fragments, form values, request/response
+ * bodies, error MESSAGE text (the name only), cookies, storage contents, headers, DOM content, and
+ * the full user-agent.
+ */
+/**
+ * Stages the client may report.
+ *
+ * Declared here rather than imported from the operation contract, for two reasons that point the
+ * same way. The architectural one: `lib/diag` is renderer core and `lib/change` is the control-plane
+ * moat, and the renderer must stay carve-able into a source-available distributable
+ * (`renderer-no-controlplane`). The behavioural one: this is an ALLOWLIST, so a stage added to the
+ * contract must be considered before it becomes capturable — inheriting it automatically is exactly
+ * the drift this file exists to prevent.
+ */
+export const CAPTURABLE_STAGES: readonly string[] = Object.freeze([
+  "queued",
+  "preparing",
+  "publishing",
+  "verifying",
+  "live",
+]);
+
+/** Routes the client may report timing/status for. Fixed list: an unlisted route is DROPPED, not
+ * recorded as "other" — a route we did not anticipate is one we have not reasoned about. */
+export const CAPTURABLE_ROUTES: readonly string[] = Object.freeze([
+  "/api/changes",
+  "/api/changes/ship",
+  "/api/changes/accept",
+  "/api/changes/accept-issue",
+  "/api/changes/reconcile-delivery",
+  "/api/publish/stage-bundle",
+  "/api/preview/build",
+]);
+
+/** Problem codes the client may report. Closed enum from the operation contract. */
+export const CAPTURABLE_PROBLEM_CODES: readonly string[] = Object.freeze([
+  "needs-confirmation",
+  "entitlement-required",
+  "bundle-unavailable",
+  "not-ready",
+  "delivery-undeliverable",
+  "checks-blocked",
+]);
+
+/** A captured event, after the allowlist has had its say. Every variant is closed-vocabulary. */
+export type CaptureEvent =
+  | { kind: "stage"; operation: string; stage: string; at: string }
+  | { kind: "request"; route: string; status: number; durationMs: number; at: string }
+  | { kind: "problem"; code: string; at: string }
+  | { kind: "navigation"; route: string; ttfbMs: number; loadMs: number; at: string }
+  | { kind: "error"; name: string; at: string }
+  | { kind: "viewport"; width: number; height: number; online: boolean; at: string };
+
+/**
+ * Reduce a URL to an allowlisted route PATTERN, or null.
+ *
+ * Only the pathname is ever consulted — `search` and `hash` are discarded before matching rather
+ * than after, so a query string cannot reach the comparison, let alone the output. A path that is
+ * not on the list returns null and the caller drops the event entirely.
+ */
+export function captureRoute(rawUrl: string | null | undefined): string | null {
+  if (!rawUrl) return null;
+  let pathname: string;
+  try {
+    // A base is supplied so relative URLs parse; its origin is never read.
+    pathname = new URL(rawUrl, "https://example.invalid").pathname;
+  } catch {
+    return null;
+  }
+  const normalised = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  return CAPTURABLE_ROUTES.includes(normalised) ? normalised : null;
+}
+
+/** A finite, non-negative number rounded to a whole millisecond, or null. Guards against `Infinity`
+ * and `NaN` reaching the ingest as a "timing". */
+function millis(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
+  return Math.round(value);
+}
+
+/** A plausible HTTP status, or null. */
+function httpStatus(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 100 || value > 599) return null;
+  return value;
+}
+
+/**
+ * Build a `request` event, or null when anything about it is not capturable.
+ *
+ * Returning null rather than a partially-populated event is the fail-closed half: a half-recorded
+ * request is worse than none, because it looks like evidence.
+ */
+export function captureRequest(input: {
+  url: string | null | undefined;
+  status: unknown;
+  durationMs: unknown;
+  at: string;
+}): CaptureEvent | null {
+  const route = captureRoute(input.url);
+  const status = httpStatus(input.status);
+  const durationMs = millis(input.durationMs);
+  if (!route || status === null || durationMs === null) return null;
+  return { kind: "request", route, status, durationMs, at: input.at };
+}
+
+/** Build a `navigation` event, or null. Same fail-closed rule, same route allowlist. */
+export function captureNavigation(input: {
+  url: string | null | undefined;
+  ttfbMs: unknown;
+  loadMs: unknown;
+  at: string;
+}): CaptureEvent | null {
+  const route = captureRoute(input.url);
+  const ttfbMs = millis(input.ttfbMs);
+  const loadMs = millis(input.loadMs);
+  if (!route || ttfbMs === null || loadMs === null) return null;
+  return { kind: "navigation", route, ttfbMs, loadMs, at: input.at };
+}
+
+/** Build a `stage` event, or null when the stage is not one this allowlist admits. */
+export function captureStage(operation: unknown, stage: unknown, at: string): CaptureEvent | null {
+  if (typeof operation !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(operation)) return null;
+  if (typeof stage !== "string" || !CAPTURABLE_STAGES.includes(stage)) return null;
+  return { kind: "stage", operation, stage, at };
+}
+
+/** Build a `problem` event from a closed-enum code, or null when the code is not one of ours. */
+export function captureProblem(code: unknown, at: string): CaptureEvent | null {
+  if (typeof code !== "string" || !CAPTURABLE_PROBLEM_CODES.includes(code)) return null;
+  return { kind: "problem", code, at };
+}
+
+/**
+ * Build an `error` event carrying the error's NAME only.
+ *
+ * `message` is deliberately never captured. An exception message is free text assembled at the
+ * throw site, and on a storefront it routinely interpolates a URL, an id, or a value — the exact
+ * content this allowlist exists to keep out. The name is a type, and a type is a fact about our
+ * code rather than about the tenant's data.
+ */
+export function captureError(error: unknown, at: string): CaptureEvent | null {
+  const name =
+    error instanceof Error ? error.name : typeof error === "object" && error && "name" in error ? String((error as { name: unknown }).name) : null;
+  if (!name || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name)) return null;
+  return { kind: "error", name, at };
+}

package/apps/storefront/src/lib/diag/consoleLine.ts

@@ -0,0 +1,76 @@
+/**
+ * The one console line a tenant can screenshot.
+ *
+ * A merchant who hits a problem does one of two things: reads the dialog, or opens devtools. Today
+ * those two surfaces share nothing — the dialog has a support reference, the console has whatever
+ * the error happened to throw, and neither can be joined to the other or to our logs. So a console
+ * screenshot, which is what people actually send, has been the least useful artifact in a report.
+ *
+ * This emits the SAME reference the dialog shows, plus the session id and the path that resolves
+ * them. Holding the line is then equivalent to holding the dialog, and either one is enough.
+ *
+ * ONE LINE, NEVER A DUMP. It is pasted into chat and photographed off a screen, so it has to survive
+ * both. It also must never carry anything sensitive: a console line goes wherever a screenshot goes,
+ * including into a support thread with people who should not see tenant data. Everything here is an
+ * identifier we minted — no URLs, no message bodies, no tenant content.
+ */
+import { diagnosticPathFor } from "./reference";
+
+/** What the line describes. `summary` is merchant-facing text we already show, never raw error text. */
+export interface DiagnosticConsoleLine {
+  /** The quotable reference for this problem. */
+  reference: string;
+  /** A short merchant-safe description — reuse what the dialog says, never an exception message. */
+  summary: string;
+  /** The browser session this happened in, when one could be established. */
+  sessionId?: string | null;
+  /**
+   * Advertise `tot.debug()` — pass true when capture is AVAILABLE here and currently OFF.
+   *
+   * This is the discovery mechanism for the console toggle, and the timing is the whole point: the
+   * merchant is looking at a failure with devtools already open, which is the one moment they will
+   * read a hint about how to record one. Suppressed when capture is already on (nothing to offer)
+   * and on live (where the answer is no).
+   */
+  offerDebug?: boolean;
+}
+
+/**
+ * Format the line. Pure, so its exact shape is testable and cannot drift from what support is told
+ * to look for.
+ *
+ * The `[tot]` prefix is deliberate: it is what someone greps a noisy console for, and what lets a
+ * reader tell OUR line from a tenant's own logging in a screenshot full of both.
+ */
+export function formatDiagnosticConsoleLine(input: DiagnosticConsoleLine): string {
+  const parts = [
+    `[tot] ${input.reference}`,
+    input.summary,
+    input.sessionId ? `session ${input.sessionId}` : null,
+    `diagnostics: ${diagnosticPathFor(input.reference)}`,
+    // Last, so it never pushes the reference — the thing they must copy — off the readable part of
+    // a narrow console or a screenshot.
+    input.offerDebug ? "run tot.debug() to record more detail" : null,
+  ].filter((p): p is string => Boolean(p));
+  return parts.join(" · ");
+}
+
+/**
+ * Emit the line, once, for a problem.
+ *
+ * `console.warn` rather than `.error`: this is a pointer to diagnostics, not an exception. Sites
+ * that fail their own builds on console errors should not start failing because we explained
+ * ourselves, and a merchant scanning a red console should see THEIR problem first.
+ *
+ * Never throws — a console that refuses to print must not take the page down with it.
+ */
+export function emitDiagnosticConsoleLine(
+  input: DiagnosticConsoleLine,
+  sink: Pick<Console, "warn"> = console,
+): void {
+  try {
+    sink.warn(formatDiagnosticConsoleLine(input));
+  } catch {
+    // A sandboxed or replaced console. Losing the line is acceptable; losing the page is not.
+  }
+}

package/apps/storefront/src/lib/diag/debugConsole.ts

@@ -0,0 +1,118 @@
+/**
+ * `tot.debug()` — the console entry point a merchant can actually type.
+ *
+ * WHY A CONSOLE FUNCTION AT ALL. The admin toggle arms capture for everyone, which is the right tool
+ * when the problem happens to someone else. But a developer who is already looking at the broken
+ * page, with devtools open, should not have to go to another surface, find a setting, and come back
+ * — by which point they have navigated away from the state they were trying to capture. Typing one
+ * word is the shortest path from "this is broken right now" to "I am recording it".
+ *
+ * IT ANSWERS, IT DOES NOT JUST ACT. Every call prints what happened and what is true now. A silent
+ * toggle in a console is indistinguishable from a typo, and the only thing worse than capture being
+ * off is believing it is on.
+ *
+ * DISCOVERABILITY IS THE HARD PART, and it is not solved here: a function nobody knows about is not
+ * an entry point. The `[tot]` problem line advertises it (see `consoleLine.ts`), which is the moment
+ * it is relevant — the merchant is already looking at a failure and already has the console open.
+ */
+import type { IntegrationEnvironment } from "@tot/public-runtime";
+import {
+  isDebugAvailable,
+  setDebugEnabled,
+  resolveDebugMode,
+  readSessionPreference,
+  debugUnavailableReason,
+} from "./debugMode";
+import type { SessionStore } from "./session";
+import { describeDebugWindow, type TenantDebugWindow } from "./debugWindow";
+
+/** The surface `window.tot` exposes. Kept to one verb — this is a debugging aid, not an API. */
+export interface TotConsoleApi {
+  /** Turn capture on (default), off, or report the current state with no argument. */
+  debug(on?: boolean): string;
+}
+
+export interface DebugConsoleContext {
+  environment: IntegrationEnvironment | null | undefined;
+  store?: SessionStore | null;
+  /** The tenant-wide window, when the page was rendered with one. */
+  tenantWindow?: TenantDebugWindow | null;
+  now?: () => Date;
+}
+
+/**
+ * Build the console API. Pure — returns an object rather than touching `window`, so its wording is
+ * testable and so nothing is attached to the global scope as a side effect of an import.
+ */
+export function createTotConsoleApi(ctx: DebugConsoleContext): TotConsoleApi {
+  const now = () => ctx.now?.() ?? new Date();
+
+  const state = (): string => {
+    const resolution = resolveDebugMode({
+      environment: ctx.environment,
+      sessionPreference: readSessionPreference(ctx.store),
+      tenantWindow: ctx.tenantWindow ?? null,
+      now: now(),
+    });
+    if (!resolution.enabled) {
+      // Say WHY it is off, not just that it is. "Off" with no reason is what sends someone to
+      // support to ask whether the feature is broken.
+      if (resolution.source === "stage-ineligible") return `Debug logging is off. ${debugUnavailableReason(ctx.environment)}`;
+      return "Debug logging is off. Run tot.debug() to turn it on for this browser tab.";
+    }
+    const via =
+      resolution.source === "tenant-window"
+        ? describeDebugWindow(ctx.tenantWindow, now())
+        : "Debug logging is on for this browser tab.";
+    return `${via} Run tot.debug(false) to turn it off here.`;
+  };
+
+  return {
+    debug(on?: boolean): string {
+      // No argument = "tell me", not "toggle me". A bare `tot.debug()` typed by someone who is
+      // unsure of the current state must never flip it to the opposite of what they wanted.
+      if (on === undefined) {
+        const resolution = resolveDebugMode({
+          environment: ctx.environment,
+          sessionPreference: readSessionPreference(ctx.store),
+          tenantWindow: ctx.tenantWindow ?? null,
+          now: now(),
+        });
+        // ...except when it is off and CAN be on, where the obvious intent of typing it is to start.
+        if (!resolution.enabled && isDebugAvailable(ctx.environment)) return this.debug(true);
+        return state();
+      }
+
+      const outcome = setDebugEnabled(on, { environment: ctx.environment, store: ctx.store });
+      if (!outcome.changed) {
+        if (outcome.reason === "stage-ineligible") {
+          return `Not turned on. ${debugUnavailableReason(ctx.environment)}`;
+        }
+        return "Not changed — this browser is blocking site data, so the setting cannot be remembered. Debug logging needs session storage.";
+      }
+      return state();
+    },
+  };
+}
+
+/**
+ * Attach the API to a global. Never throws and never overwrites an existing `tot` object's other
+ * keys — a tenant may well have their own `window.tot`, and clobbering it would be a bug we
+ * introduced into their site while trying to diagnose one.
+ */
+export function installTotConsoleApi(
+  ctx: DebugConsoleContext,
+  globalObject: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
+): void {
+  try {
+    const api = createTotConsoleApi(ctx);
+    const existing = globalObject.tot;
+    if (existing && typeof existing === "object") {
+      (existing as Record<string, unknown>).debug = api.debug.bind(api);
+      return;
+    }
+    globalObject.tot = api;
+  } catch {
+    // A frozen or exotic global. Losing the shortcut is acceptable; breaking the page is not.
+  }
+}

package/apps/storefront/src/lib/diag/debugMode.ts

@@ -0,0 +1,163 @@
+/**
+ * DEBUG MODE — a tenant developer can turn on richer client-side capture while reproducing a
+ * problem, and turn it off again. Off by default, and impossible to turn on where it does not belong.
+ *
+ * NEVER ON A LIVE PUBLIC SITE, and the gate is structural rather than advisory (ADR 0034):
+ *
+ *   - the public path is CDN → content-addressed storage with at most ONE submillisecond edge
+ *     function (ADR 0013). A debug beacon in that path is origin compute on a ranked,
+ *     revenue-bearing surface, which is a direct commercial cost on every cache miss;
+ *   - increased client-side logging is precisely where PII leaks, and this is a REGULATED
+ *     storefront;
+ *   - the people who need it are previewing, which is where the failures happen anyway.
+ *
+ * So `live` is refused at BOTH the read and the write: a stored `on` flag carried into a live
+ * document — by a shared sessionStorage, a copied profile, or a stage that changed under it — still
+ * reads as off. Enabling is the request; eligibility is the answer, and eligibility is re-decided
+ * every time rather than trusted from what was stored.
+ */
+import type { IntegrationEnvironment } from "@tot/public-runtime";
+import type { SessionStore } from "./session";
+import { isDebugWindowActive, type TenantDebugWindow } from "./debugWindow";
+
+/** Where the toggle is remembered. Session-scoped, like the session id: debug is for one sitting. */
+export const DEBUG_STORAGE_KEY = "tot.diag.debug";
+
+/**
+ * Stages where debug capture may run. Written as the ALLOWED set, not as `!== "live"`: a fifth stage
+ * added later must be considered deliberately rather than inheriting permission from a negation.
+ */
+export const DEBUG_ELIGIBLE_STAGES: readonly IntegrationEnvironment[] = Object.freeze([
+  "local",
+  "candidate",
+  "staged",
+]);
+
+/** May debug mode run at all here? The stage decides; the stored flag never overrides this. */
+export function isDebugAvailable(environment: IntegrationEnvironment | null | undefined): boolean {
+  return !!environment && DEBUG_ELIGIBLE_STAGES.includes(environment);
+}
+
+/**
+ * This browser session's explicit choice, or null when the developer has not expressed one.
+ *
+ * The three states are load-bearing. "Not set" and "explicitly off" look identical while capture is
+ * off anyway, but they differ the moment the merchant arms a tenant-wide window: an untouched
+ * session joins it, and a session someone deliberately switched off stays off. Collapsing them would
+ * silently re-enable capture in a tab where a person had just turned it off.
+ */
+export function readSessionPreference(store?: SessionStore | null): SessionDebugPreference {
+  if (!store) return null;
+  try {
+    const raw = store.getItem(DEBUG_STORAGE_KEY);
+    return raw === "on" || raw === "off" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A session's explicit choice: on, off, or never asked. */
+export type SessionDebugPreference = "on" | "off" | null;
+
+/** Why capture is on or off, so a surface can explain itself rather than just showing a state. */
+export type DebugModeSource = "stage-ineligible" | "session" | "tenant-window" | "default-off";
+
+export interface DebugModeResolution {
+  enabled: boolean;
+  source: DebugModeSource;
+}
+
+/**
+ * Resolve whether capture is on, from the three things that can say so.
+ *
+ * PRECEDENCE, and why:
+ *
+ *   1. STAGE first, and it can only ever say no. `live` refuses regardless of what any session or
+ *      any armed window claims (ADR 0034). A tenant-wide window is stored per tenant, not per stage,
+ *      so this is the check that stops an armed window following a merchant onto their public site.
+ *   2. The SESSION's explicit choice next, either way. Someone who turned it on in their own tab
+ *      gets it without waiting for an admin, and someone who turned it OFF while a tenant window is
+ *      running stays off — otherwise the only way to quieten your own console would be to disarm
+ *      capture for every colleague mid-investigation.
+ *   3. The tenant WINDOW, for every session that has not expressed a preference. This is the whole
+ *      point of the window: it reaches the sessions nobody has touched, including the colleague who
+ *      can actually reproduce the bug.
+ *   4. Off.
+ */
+export function resolveDebugMode(args: {
+  environment: IntegrationEnvironment | null | undefined;
+  sessionPreference?: SessionDebugPreference;
+  tenantWindow?: TenantDebugWindow | null;
+  now?: Date;
+}): DebugModeResolution {
+  if (!isDebugAvailable(args.environment)) return { enabled: false, source: "stage-ineligible" };
+  const preference = args.sessionPreference ?? null;
+  if (preference === "on") return { enabled: true, source: "session" };
+  if (preference === "off") return { enabled: false, source: "session" };
+  if (isDebugWindowActive(args.tenantWindow, args.now ?? new Date())) {
+    return { enabled: true, source: "tenant-window" };
+  }
+  return { enabled: false, source: "default-off" };
+}
+
+/**
+ * Is capture ON right now?
+ *
+ * Fails closed on every uncertainty: no stage, an ineligible stage, no store, a store that throws,
+ * or anything in storage other than our exact markers.
+ */
+export function isDebugEnabled(args: {
+  environment: IntegrationEnvironment | null | undefined;
+  store?: SessionStore | null;
+  tenantWindow?: TenantDebugWindow | null;
+  now?: Date;
+}): boolean {
+  return resolveDebugMode({
+    environment: args.environment,
+    sessionPreference: readSessionPreference(args.store),
+    tenantWindow: args.tenantWindow ?? null,
+    ...(args.now ? { now: args.now } : {}),
+  }).enabled;
+}
+
+/** What a toggle attempt did — returned so the UI can explain a refusal instead of silently no-oping. */
+export type DebugToggleOutcome =
+  | { changed: true; enabled: boolean }
+  | { changed: false; reason: "stage-ineligible"; environment: string | null }
+  | { changed: false; reason: "no-store" };
+
+/**
+ * Turn capture on or off.
+ *
+ * Turning it ON at an ineligible stage is REFUSED and says so — it is never silently ignored, and
+ * never silently honoured. A developer who asked for debug on a live site deserves to be told the
+ * stage is why, rather than left wondering why no events appear.
+ *
+ * Turning it OFF is always allowed, at any stage: switching something off must never be gated by the
+ * same condition that makes it dangerous to have on.
+ */
+export function setDebugEnabled(
+  enabled: boolean,
+  args: { environment: IntegrationEnvironment | null | undefined; store?: SessionStore | null },
+): DebugToggleOutcome {
+  const store = args.store;
+  if (!store) return { changed: false, reason: "no-store" };
+  if (enabled && !isDebugAvailable(args.environment)) {
+    return { changed: false, reason: "stage-ineligible", environment: args.environment ?? null };
+  }
+  try {
+    store.setItem(DEBUG_STORAGE_KEY, enabled ? "on" : "off");
+    return { changed: true, enabled };
+  } catch {
+    // Private mode or blocked site data. The toggle did not take; say so rather than report success.
+    return { changed: false, reason: "no-store" };
+  }
+}
+
+/** The merchant-facing sentence for why debug is unavailable here, or null when it is available. */
+export function debugUnavailableReason(
+  environment: IntegrationEnvironment | null | undefined,
+): string | null {
+  if (isDebugAvailable(environment)) return null;
+  return "Debug logging is available on preview, not on your live site. Turn it on there, reproduce the problem, then quote the reference.";
+}