@tokenoftrust/storefront-runner 2.0.41 → 2.0.43

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

@@ -0,0 +1,111 @@
+/**
+ * TENANT-WIDE DEBUG WINDOW — a merchant switches debug capture on from their admin console and it
+ * applies to EVERY session on that tenant until it expires.
+ *
+ * WHY THIS EXISTS ALONGSIDE THE PER-SESSION TOGGLE. The console toggle only helps someone who can
+ * already reproduce the problem in their own browser. The reports that are hardest to act on are the
+ * ones where they cannot: it happens to a colleague, on a phone, once a day, or only to whoever
+ * happens to hit it next. A window lets the merchant arm capture and then go and reproduce it
+ * however it actually occurs.
+ *
+ * IT EXPIRES, AND THAT IS THE DESIGN. Capture that can be left on forever eventually is, and then it
+ * is collecting on a tenant nobody is debugging — which is both a cost and a liability on a regulated
+ * storefront. An expiry means the safe state is reached by doing nothing, which is the only kind of
+ * safe state that survives people being busy. There is deliberately no "on indefinitely".
+ *
+ * Still gated by stage. A window has no effect on `live` — the resolver refuses there regardless of
+ * what any record says, so an armed window cannot follow a tenant onto their public site.
+ */
+
+/** A merchant-armed capture window. Absent/expired ⇒ tenant-wide capture is off. */
+export interface TenantDebugWindow {
+  /** When the window stops applying — ISO 8601, UTC. */
+  enabledUntil: string;
+  /** When it was armed, for the admin surface to show "turned on 2 hours ago". */
+  enabledAt: string;
+  /** Who armed it, for the audit trail. An opaque actor id, never a name or email. */
+  enabledBy?: string;
+}
+
+/** The default a merchant gets when they just click the toggle: long enough to reproduce something
+ * that happens a few times a day, short enough that forgetting is not a problem. */
+export const DEFAULT_DEBUG_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** The shortest window worth arming — below this the merchant cannot get to the other tab in time. */
+export const MIN_DEBUG_WINDOW_MS = 15 * 60 * 1000;
+
+/**
+ * The longest window anyone may arm. A ceiling rather than a preference: the whole value of an
+ * expiry is that it is not negotiable, and "just set it to a year" is how an expiry becomes
+ * decoration. A merchant who genuinely needs longer re-arms it, which is a deliberate act that
+ * leaves a fresh audit entry.
+ */
+export const MAX_DEBUG_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Clamp a requested duration into the permitted range. Invalid input falls back to the default
+ * rather than refusing — a bad number must not leave the merchant unable to turn capture on. */
+export function clampDebugWindowMs(requestedMs: unknown): number {
+  if (typeof requestedMs !== "number" || !Number.isFinite(requestedMs) || requestedMs <= 0) {
+    return DEFAULT_DEBUG_WINDOW_MS;
+  }
+  return Math.min(MAX_DEBUG_WINDOW_MS, Math.max(MIN_DEBUG_WINDOW_MS, Math.round(requestedMs)));
+}
+
+/**
+ * Arm a window. Duration is a parameter with a default, so the admin surface can offer choices
+ * (an hour, a day, a week) without any further change here.
+ */
+export function openDebugWindow(args: {
+  now?: Date;
+  durationMs?: number;
+  enabledBy?: string;
+}): TenantDebugWindow {
+  const now = args.now ?? new Date();
+  const durationMs = clampDebugWindowMs(args.durationMs);
+  const window: TenantDebugWindow = {
+    enabledAt: now.toISOString(),
+    enabledUntil: new Date(now.getTime() + durationMs).toISOString(),
+  };
+  if (args.enabledBy) window.enabledBy = args.enabledBy;
+  return window;
+}
+
+/**
+ * Is a window currently in force?
+ *
+ * Fails closed on anything it cannot read: absent, malformed, or an unparseable timestamp all mean
+ * off. A record we cannot interpret must never be treated as permission to capture.
+ */
+export function isDebugWindowActive(
+  window: TenantDebugWindow | null | undefined,
+  now: Date = new Date(),
+): boolean {
+  if (!window || typeof window.enabledUntil !== "string") return false;
+  const until = Date.parse(window.enabledUntil);
+  if (!Number.isFinite(until)) return false;
+  return until > now.getTime();
+}
+
+/** Milliseconds left on a window, or 0 when it is not active. For the admin surface's countdown. */
+export function debugWindowRemainingMs(
+  window: TenantDebugWindow | null | undefined,
+  now: Date = new Date(),
+): number {
+  if (!isDebugWindowActive(window, now)) return 0;
+  return Date.parse(window!.enabledUntil) - now.getTime();
+}
+
+/** A merchant-facing summary of the window's state — "Debug logging is on for another 3 hours". */
+export function describeDebugWindow(
+  window: TenantDebugWindow | null | undefined,
+  now: Date = new Date(),
+): string {
+  const remaining = debugWindowRemainingMs(window, now);
+  if (remaining <= 0) return "Debug logging is off for this store.";
+  const hours = Math.floor(remaining / (60 * 60 * 1000));
+  if (hours >= 1) {
+    return `Debug logging is on for this store for another ${hours} hour${hours === 1 ? "" : "s"}.`;
+  }
+  const minutes = Math.max(1, Math.round(remaining / (60 * 1000)));
+  return `Debug logging is on for this store for another ${minutes} minute${minutes === 1 ? "" : "s"}.`;
+}

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

@@ -0,0 +1,148 @@
+/**
+ * The DIAGNOSTIC REFERENCE — one short, self-describing handle a tenant can quote when something
+ * goes wrong, and the key every diagnostic surface correlates on.
+ *
+ * WHY A NEW ID WHEN WE ALREADY MINT SEVERAL. We do not lack correlation ids — `dispatchId`,
+ * `operationId`, `runUrl` and the activity rows all exist and all work. What none of them is, is
+ * QUOTABLE. The publish dialog's support reference today is the raw dispatch id
+ * (`dsp:rcpt:tenant.com:preview:run-<uuid>:5:<uuid>`): correct, unambiguous, and unusable by a human
+ * who has to read it off a screen, type it into a message, or say it on a call. So a tenant hitting
+ * a problem either pastes something they cannot check, or — as actually happened — opens an agent
+ * session to file a report on their behalf.
+ *
+ * This is a KEY, NOT A CONTAINER. It carries no diagnostic data of its own and replaces none of the
+ * ids above; it resolves TO them. Nothing moves, and the existing per-surface redaction rules keep
+ * deciding who may see what.
+ *
+ * FORMAT: `TOT-<stage><YYMMDD>-<token>` — e.g. `TOT-P260923-K7M4QX`.
+ *
+ *   stage   `P` preview / `L` live. Which substrate this happened on, before opening anything —
+ *           the first question asked of every report, answered by the reference itself.
+ *   YYMMDD  the UTC day. Makes retention self-evident: a reference older than the window cannot
+ *           resolve, and reads as old rather than as broken.
+ *   token   6 chars of Crockford base32, an alphabet that omits I, L, O and U by construction. The
+ *           first three cannot be misread as 1/1/0 on a screen or over a call, and the absence of U
+ *           is what keeps a random token from spelling something unfortunate in front of a merchant.
+ *
+ * Case-insensitive on the way in, canonical upper on the way out, because it WILL be retyped.
+ */
+
+/** Stages a reference can be minted for, and the letter each contributes. */
+export type DiagnosticStage = "preview" | "live";
+
+const STAGE_LETTER: Readonly<Record<DiagnosticStage, string>> = Object.freeze({
+  preview: "P",
+  live: "L",
+});
+
+const LETTER_STAGE: Readonly<Record<string, DiagnosticStage>> = Object.freeze({
+  P: "preview",
+  L: "live",
+});
+
+/**
+ * Crockford base32 — 32 symbols that already omit I, L, O and U, which is exactly why it is the
+ * right alphabet here rather than something to be filtered after the fact. 6 chars gives 32^6 ≈
+ * 1.07 billion, ample for a handle scoped to one stage and one day.
+ */
+const TOKEN_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** How many token characters a reference carries. */
+const TOKEN_LENGTH = 6;
+
+/** The canonical shape, anchored — used to validate anything arriving from a URL or a paste. */
+const REFERENCE_RE = new RegExp(`^TOT-([PL])(\\d{6})-([${TOKEN_ALPHABET}]{${TOKEN_LENGTH}})$`);
+
+/** The parts a reference encodes, recovered from the string itself. */
+export interface ParsedDiagnosticReference {
+  /** Which substrate the problem occurred on. */
+  stage: DiagnosticStage;
+  /** The UTC day, as `YYMMDD` — exactly the characters in the reference, not a re-derivation. */
+  day: string;
+  /** The random token, canonical upper-case. */
+  token: string;
+  /** The whole reference, canonicalised. */
+  reference: string;
+}
+
+/** `YYMMDD` in UTC. Deliberately UTC: a reference must mean the same day to a reporter and to us. */
+function utcDay(now: Date): string {
+  const yy = String(now.getUTCFullYear() % 100).padStart(2, "0");
+  const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(now.getUTCDate()).padStart(2, "0");
+  return `${yy}${mm}${dd}`;
+}
+
+/**
+ * Mint a reference for a problem that just occurred.
+ *
+ * `randomBytes` is injected so this stays pure and testable; real callers omit it and get
+ * `crypto.getRandomValues`, which exists on Workers and in the browser.
+ */
+export function mintDiagnosticReference(args: {
+  stage: DiagnosticStage;
+  /** When it happened. Injected so a test is not at the mercy of the clock. */
+  now?: Date;
+  /** Fill a byte array with randomness. Injected for tests; defaults to WebCrypto. */
+  randomBytes?: (n: number) => Uint8Array;
+}): string {
+  const now = args.now ?? new Date();
+  return `TOT-${STAGE_LETTER[args.stage]}${utcDay(now)}-${mintToken(TOKEN_LENGTH, args.randomBytes)}`;
+}
+
+/**
+ * `length` characters of the reading-safe alphabet. Exported so every human-quotable id in the
+ * diagnostics surface — the reference, the session id — draws from ONE alphabet. A second id that
+ * quietly used a different one would reintroduce exactly the characters this alphabet exists to
+ * keep out, on the id nobody thought to check.
+ */
+export function mintToken(length: number, randomBytes?: (n: number) => Uint8Array): string {
+  const fill = randomBytes ?? ((n: number) => crypto.getRandomValues(new Uint8Array(n)));
+  // 256 is a whole multiple of 32, so a plain modulo is already uniform here and `limit` is 256 —
+  // nothing is ever discarded. It is written as rejection sampling anyway so that changing the
+  // alphabet to a non-power-of-two length stays correct instead of silently skewing the token.
+  const limit = Math.floor(256 / TOKEN_ALPHABET.length) * TOKEN_ALPHABET.length;
+  let token = "";
+  while (token.length < length) {
+    for (const byte of fill(length * 2)) {
+      if (token.length >= length) break;
+      if (byte >= limit) continue;
+      token += TOKEN_ALPHABET[byte % TOKEN_ALPHABET.length];
+    }
+  }
+  return token;
+}
+
+/**
+ * Parse a reference a human supplied — from a URL, a pasted message, a screenshot they retyped.
+ * Tolerant of case and surrounding whitespace, strict about everything else: an id that is not
+ * exactly this shape is not one of ours, and saying so beats a lookup that mysteriously finds
+ * nothing.
+ *
+ * Returns null rather than throwing — every caller here is handling someone's typo, not an
+ * exceptional condition.
+ */
+export function parseDiagnosticReference(raw: string | null | undefined): ParsedDiagnosticReference | null {
+  if (!raw) return null;
+  const canonical = raw.trim().toUpperCase();
+  const m = REFERENCE_RE.exec(canonical);
+  if (!m) return null;
+  const [, letter, day, token] = m;
+  const stage = LETTER_STAGE[letter!];
+  if (!stage) return null;
+  return { stage, day: day!, token: token!, reference: canonical };
+}
+
+/** Is this a well-formed reference? Sugar over {@link parseDiagnosticReference} for guard clauses. */
+export function isDiagnosticReference(raw: string | null | undefined): boolean {
+  return parseDiagnosticReference(raw) !== null;
+}
+
+/**
+ * The path a reference resolves at. Kept here, beside the format, because the WHOLE POINT of the
+ * reference is that holding it is enough to reach the diagnostics — so the code and the door it
+ * opens must never drift apart in two files.
+ */
+export function diagnosticPathFor(reference: string): string {
+  return `/diag/${reference.trim().toUpperCase()}`;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Where a diagnostic reference resolves TO.
+ *
+ * The reference is a key (see `reference.ts`); this is the record it opens. Without it `/diag/<ref>`
+ * has nothing to show and the code is just a nicer-looking dispatch id — so this is the module that
+ * makes the whole contract true rather than merely well-formed.
+ *
+ * WHAT IT HOLDS, AND WHAT IT DELIBERATELY DOES NOT. Only the correlation ids we minted plus the
+ * merchant-facing text the surface was already showing. No request bodies, no error messages, no
+ * tenant content. A record is read by whoever holds the code, and the code travels in screenshots
+ * and support threads — so its contents must be safe wherever the code itself is safe.
+ *
+ * TTL, NOT FOREVER. A reference encodes its own date, so an expired one reads as old rather than as
+ * broken. Thirty days is long enough that a merchant who reports something a fortnight later still
+ * gets an answer, and short enough that this never becomes an archive of everything that ever went
+ * wrong on every tenant.
+ */
+import type { DiagnosticStage } from "./reference";
+
+/** How long a record outlives the problem it describes. */
+export const DIAGNOSTIC_RECORD_TTL_SECONDS = 30 * 24 * 60 * 60;
+
+/** What `/diag/<ref>` shows, and what a report quotes. */
+export interface DiagnosticRecord {
+  reference: string;
+  /** Which substrate — matches the letter in the reference itself. */
+  stage: DiagnosticStage;
+  /** The tenant this happened on. */
+  tenant: string;
+  /** Merchant-facing summary: the text the surface already displayed, never an exception message. */
+  summary: string;
+  /** ISO timestamp. */
+  at: string;
+  /** The operation's problem code, when it had one. */
+  code?: string | null;
+  /** Our own correlation ids, for tracing through build and delivery logs. */
+  dispatchId?: string | null;
+  receiptId?: string | null;
+  pinnedSha?: string | null;
+  /** The CI run URL. Subject to the same non-owner redaction as everywhere else. */
+  runUrl?: string | null;
+}
+
+/** The minimal KV surface this needs, so tests need no Workers runtime. */
+export interface DiagnosticKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+}
+
+/** Namespaced so a reference can never collide with tenant content or another subsystem's keys. */
+export function diagnosticRecordKey(reference: string): string {
+  return `diag:ref:${reference.trim().toUpperCase()}`;
+}
+
+/**
+ * Persist a record. NEVER THROWS.
+ *
+ * A diagnostic record is a secondary artifact of a failure that has already happened. If writing it
+ * fails, the merchant must still get their error, their retry and their reference — losing the
+ * ability to explain a problem must never also lose the problem's own handling. Returns whether it
+ * landed so a caller can say "reference unavailable" rather than print a code that resolves to
+ * nothing.
+ */
+export async function putDiagnosticRecord(
+  kv: DiagnosticKv | null | undefined,
+  record: DiagnosticRecord,
+  ttlSeconds: number = DIAGNOSTIC_RECORD_TTL_SECONDS,
+): Promise<boolean> {
+  if (!kv) return false;
+  try {
+    await kv.put(diagnosticRecordKey(record.reference), JSON.stringify(record), {
+      expirationTtl: ttlSeconds,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a record back, or null.
+ *
+ * Null covers every failure mode on purpose — absent, expired, unreadable KV, malformed JSON, or a
+ * record whose shape we no longer recognise. `/diag` shows one honest "we can't find that
+ * reference" for all of them, because to the person holding the code they are the same situation.
+ */
+export async function getDiagnosticRecord(
+  kv: DiagnosticKv | null | undefined,
+  reference: string,
+): Promise<DiagnosticRecord | null> {
+  if (!kv) return null;
+  try {
+    const raw = await kv.get(diagnosticRecordKey(reference));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as unknown;
+    return isDiagnosticRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Structural check on a record read back from storage. Anything we cannot vouch for is not shown. */
+function isDiagnosticRecord(value: unknown): value is DiagnosticRecord {
+  if (!value || typeof value !== "object") return false;
+  const r = value as Record<string, unknown>;
+  return (
+    typeof r.reference === "string" &&
+    (r.stage === "preview" || r.stage === "live") &&
+    typeof r.tenant === "string" &&
+    typeof r.summary === "string" &&
+    typeof r.at === "string"
+  );
+}

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

@@ -0,0 +1,109 @@
+/**
+ * "REPORT THIS" — turn a problem the merchant is already looking at into a filed report, with the
+ * diagnostic reference already in it.
+ *
+ * THE LOOP THIS CLOSES. Filing friction has required an MCP tool call, which means a signed-in agent
+ * session. A tenant developer hitting a publish failure therefore had two options: describe it in
+ * prose to a human, or open an agent session so something else could file on their behalf. Both
+ * happened this week. Neither is a reporting path — they are workarounds for the absence of one.
+ *
+ * WHAT THIS MODULE IS. The pure payload builder: problem + reference in, a `feedback_submit`-shaped
+ * report out. It performs no I/O, so the rule about what a report may contain is testable on its own
+ * and does not depend on whichever surface ends up posting it.
+ *
+ * PII IS THE WHOLE RISK HERE. `feedback_submit` clusters reports by title and description and may
+ * show them to OTHER builders — so those fields carry only our own identifiers and closed-vocabulary
+ * text. Nothing typed by a person and nothing read from the page goes in them. The tool has a
+ * dedicated `sensitive` field that is private to ToT admins and never matched; a merchant's own note
+ * goes THERE, not into the description, because the merchant cannot be expected to know which field
+ * is which.
+ */
+import { diagnosticPathFor } from "./reference";
+
+/** The `feedback_submit` fields this builder populates. Deliberately a subset — anything not listed
+ * is not ours to guess at from a UI click. */
+export interface DiagnosticReport {
+  type: "bug";
+  category: "platform-bug";
+  severity: "critical" | "high" | "medium" | "low";
+  title: string;
+  description: string;
+  project: string;
+  scope: "project";
+  /** Free text the merchant typed, kept out of the clustered fields. Omitted when they typed none. */
+  sensitive?: string;
+  /** Stable class for triage, when the problem carried a code. */
+  errorClass?: string;
+}
+
+/** What the surface knows when the merchant clicks Report. */
+export interface DiagnosticReportInput {
+  /** The quotable reference for this problem. */
+  reference: string;
+  /** The tenant this happened on. */
+  tenant: string;
+  /** Merchant-facing summary already on screen — our text, not an exception message. */
+  summary: string;
+  /** The operation's problem code, when it had one. Closed enum; used for triage clustering. */
+  code?: string | null;
+  /** The browser session, when one was established. */
+  sessionId?: string | null;
+  /** Whether debug capture was on, so triage knows whether a trail exists before going to look. */
+  debugCaptureOn?: boolean;
+  /** Anything the merchant typed. Goes to `sensitive`, never to the clustered fields. */
+  note?: string | null;
+}
+
+/** Severity by problem code. A publish that cannot proceed is blocking; everything else defaults to
+ * high rather than critical, because a human triages these and over-claiming is its own noise. */
+function severityFor(code: string | null | undefined): DiagnosticReport["severity"] {
+  switch (code) {
+    case "delivery-undeliverable":
+    case "bundle-unavailable":
+      return "critical";
+    case "checks-blocked":
+    case "needs-confirmation":
+    case "not-ready":
+      return "medium";
+    default:
+      return "high";
+  }
+}
+
+/**
+ * Build the report.
+ *
+ * The title leads with the reference so the queue is searchable by the thing the merchant is
+ * holding — someone who quotes only the code in a thread can be matched to their own report without
+ * a lookup.
+ */
+export function buildDiagnosticReport(input: DiagnosticReportInput): DiagnosticReport {
+  const lines = [
+    `Reported from the storefront UI by a tenant, using the in-product report action.`,
+    ``,
+    `Reference: ${input.reference}`,
+    `Diagnostics: ${diagnosticPathFor(input.reference)}`,
+    `Tenant: ${input.tenant}`,
+    `What the merchant was shown: ${input.summary}`,
+    input.code ? `Problem code: ${input.code}` : null,
+    input.sessionId ? `Session: ${input.sessionId}` : null,
+    // Say plainly whether a trail exists. Triage otherwise opens the reference, finds nothing, and
+    // cannot tell "no events" from "capture was off" — which is the ambiguity that wastes the hour.
+    `Debug capture: ${input.debugCaptureOn ? "on — a session trail is attached to the reference" : "off — no client trail was recorded"}`,
+  ].filter((l): l is string => l !== null);
+
+  const report: DiagnosticReport = {
+    type: "bug",
+    category: "platform-bug",
+    severity: severityFor(input.code),
+    title: `${input.reference}: ${input.summary}`.slice(0, 200),
+    description: lines.join("\n").slice(0, 4000),
+    project: "storefront",
+    scope: "project",
+  };
+  if (input.code) report.errorClass = input.code;
+  // The merchant's own words are the one field that can contain anything at all.
+  const note = input.note?.trim();
+  if (note) report.sensitive = note.slice(0, 4000);
+  return report;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * The DIAGNOSTIC SESSION ID — a correlation handle for everything one browser session did, so a
+ * report can be read as a sequence rather than as a single failing call.
+ *
+ * WHY, GIVEN WE ALREADY MINT A REFERENCE PER PROBLEM. A reference answers "what broke". Most reports
+ * also contain some version of "it did something odd just before", and that half has never been
+ * answerable: each failure is its own island, with nothing tying it to the navigation, the retry, or
+ * the earlier error that actually explains it. The session id is what lets the trail be assembled.
+ *
+ * `TOTS-<8>`, from the SAME reading-safe alphabet as the reference, because it appears in the same
+ * console line and gets retyped the same way.
+ *
+ * DELIBERATELY PER-SESSION, NOT PER-USER. It is a correlation handle with a natural lifetime, not an
+ * identifier of a person: it lives in `sessionStorage`, so it dies with the tab and never follows
+ * anyone between visits. On a regulated storefront that distinction is the difference between a
+ * diagnostic aid and a tracking identifier, and `sessionStorage` is what enforces it rather than a
+ * promise that we will not join it to anything.
+ */
+import { mintToken } from "./reference";
+
+/** The key the session id is cached under. Namespaced so it cannot collide with tenant content. */
+export const SESSION_STORAGE_KEY = "tot.diag.session";
+
+/** How many token characters a session id carries — longer than a reference's, and never retyped
+ * from a screenshot as often, but still readable aloud. */
+const SESSION_TOKEN_LENGTH = 8;
+
+/** The canonical session-id shape. */
+const SESSION_RE = /^TOTS-[0-9A-HJKMNP-TV-Z]{8}$/;
+
+/**
+ * The minimal storage surface this needs. Typed structurally rather than as `Storage` so a test can
+ * pass a plain object, and so a caller can hand over any equivalent store without a cast.
+ */
+export interface SessionStore {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/** Is this a well-formed session id? */
+export function isSessionId(raw: string | null | undefined): boolean {
+  return typeof raw === "string" && SESSION_RE.test(raw.trim().toUpperCase());
+}
+
+/** Mint a fresh session id. */
+export function mintSessionId(randomBytes?: (n: number) => Uint8Array): string {
+  return `TOTS-${mintToken(SESSION_TOKEN_LENGTH, randomBytes)}`;
+}
+
+/**
+ * The session id for this browser session, creating one on first use.
+ *
+ * NEVER THROWS, and that is the point rather than politeness: `sessionStorage` throws outright in a
+ * Safari private window and wherever site data is blocked, and this is DIAGNOSTIC code. Code that
+ * exists to explain failures must not become one — a storefront that will not render because its
+ * diagnostics could not find a place to keep an id is a worse bug than any it would have reported.
+ * When storage is unavailable the id is still minted and returned; it just does not survive the
+ * navigation, which degrades the trail rather than the page.
+ */
+export function readOrCreateSessionId(args?: {
+  store?: SessionStore | null;
+  randomBytes?: (n: number) => Uint8Array;
+}): string {
+  const store = args?.store !== undefined ? args.store : safeSessionStore();
+  if (store) {
+    try {
+      const existing = store.getItem(SESSION_STORAGE_KEY);
+      if (isSessionId(existing)) return existing!.trim().toUpperCase();
+    } catch {
+      // Readable-in-principle, unreadable-in-fact. Fall through and mint.
+    }
+  }
+  const minted = mintSessionId(args?.randomBytes);
+  if (store) {
+    try {
+      store.setItem(SESSION_STORAGE_KEY, minted);
+    } catch {
+      // Storage refused the write (private mode, quota, blocked site data). The id is still good
+      // for this page; it simply will not be the same one after a navigation.
+    }
+  }
+  return minted;
+}
+
+/** `sessionStorage` when it exists AND is usable, else null. Merely existing is not enough — the
+ * accessor itself throws in some configurations. */
+function safeSessionStore(): SessionStore | null {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,5 @@
+import type { FeaturedProductsBlock } from "@/lib/storyblok/content-model";
+
+export function featuredProductsPresentationView(presentation: FeaturedProductsBlock["presentation"]) {
+  return presentation === "carousel" ? "carousel" : "grid";
+}

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

@@ -0,0 +1,41 @@
+import type { HeroBlock } from "@/lib/storyblok/content-model";
+import { withBase } from "@/lib/basePath";
+
+export function heroAutoplayAllowed(input: {
+  enabled: boolean;
+  reducedMotion: boolean;
+  paused: boolean;
+  pageVisible: boolean;
+  slideCount: number;
+}) {
+  return input.enabled && !input.reducedMotion && !input.paused && input.pageVisible && input.slideCount > 1;
+}
+
+export function nextHeroSlideIndex(current: number, slideCount: number) {
+  if (slideCount < 1) return -1;
+  return current < 0 ? 0 : (current + 1) % slideCount;
+}
+
+export function heroSlideshowView(block: HeroBlock, instanceKey: string, basePath: string) {
+  const slides = block.slides ?? [];
+  return {
+    id: `hero-slides-${instanceKey}`,
+    autoplay: slides.length > 1,
+    intervalMs: 6_000,
+    slides: slides.map((slide, index) => ({
+      ...slide,
+      href: slide.ctaHref ? withBase(basePath, slide.ctaHref) : undefined,
+      checked: index === 0,
+      loading: index === 0 ? ("eager" as const) : ("lazy" as const),
+      fetchpriority: index === 0 ? ("high" as const) : ("auto" as const),
+      decoding: index === 0 ? ("sync" as const) : ("async" as const),
+      width: 1920,
+      height: 650,
+      radioId: `hero-slides-${instanceKey}-${index}`,
+      radioLabel: `Show slide ${index + 1}: ${slide.headline ?? slide.imageAlt}`,
+      groupRole: "group" as const,
+      groupLabel: `${index + 1} of ${slides.length}`,
+      focusTarget: "slide" as const,
+    })),
+  };
+}