@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/dev/cockpit/stepper.ts

@@ -0,0 +1,116 @@
+/**
+ * Progressive stepper + staged flow. Drives Run → Edit → What's next with
+ * progressive disclosure: only the current stage shows, completed stages
+ * collapse to a done-bar, and the flow AUTO-ADVANCES on monitor.ts's REAL loop
+ * signal (never a timer) — Step 1 completes when the local server is live,
+ * Step 2 when a real save→reload is observed since the edit step began.
+ * Consumes the shared tot:loop-state event from monitor.ts (one poll for the
+ * whole page). Imported from a processed `<script>` in cockpit.astro (ADR
+ * 0013), rendered only when isLocalDevLoop.
+ *
+ * Progress is persisted in sessionStorage. This is REQUIRED, not a nicety:
+ * saving a watched file triggers Vite's global full-reload, which reloads
+ * THIS /dev tab too — resetting in-memory state and re-baselining the very
+ * save that should advance Edit→Next. Persisting done-flags + current stage +
+ * the edit baseline (the lastSaveAt watermark captured when the edit step
+ * began, BEFORE the qualifying save) lets the flow survive that reload and
+ * credit the save.
+ */
+export function initStepper(): void {
+  const stepper: any = document.getElementById("stepper");
+  if (!stepper) return;
+  const stages: any = { run: document.getElementById("stage-run"), edit: document.getElementById("stage-edit"), next: document.getElementById("stage-next") };
+  const bars: any = { run: document.getElementById("bar-run"), edit: document.getElementById("bar-edit") };
+  const celRun = document.getElementById("cel-run");
+  const celEdit = document.getElementById("cel-edit");
+  const toNext: any = document.getElementById("toNext");
+  const detect = document.getElementById("detect");
+  const detectTxt = document.getElementById("detectTxt");
+  const detectEdit = document.getElementById("detect-edit");
+  const detectEditTxt = document.getElementById("detectEditTxt");
+  const barRunMeta = document.getElementById("bar-run-meta");
+  const barEditMeta = document.getElementById("bar-edit-meta");
+  const toast = document.getElementById("toast");
+  const toastMsg = document.getElementById("toastMsg");
+  let tT: ReturnType<typeof setTimeout>;
+  const reduce = window.matchMedia && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const SS = window.sessionStorage;
+  function load(k: string, d: any) { try { const v = SS.getItem(k); return v === null ? d : JSON.parse(v); } catch (e) { return d; } }
+  function put(k: string, v: any) { try { SS.setItem(k, JSON.stringify(v)); } catch (e) {} }
+
+  function ping(m: string, once?: string) {
+    if (once && load(once, false)) return;
+    if (once) put(once, true);
+    if (!toast || !toastMsg) return;
+    toastMsg.textContent = m; toast.classList.add("show");
+    clearTimeout(tT); tT = setTimeout(() => { toast.classList.remove("show"); }, 1900);
+  }
+
+  const state = {
+    unlocked: load("tot.unlocked", { run: true, edit: false, next: false }),
+    done: load("tot.done", { run: false, edit: false }),
+    current: load("tot.current", "run"),
+  };
+  let editBase = load("tot.editBase", null);
+  function persist() { put("tot.unlocked", state.unlocked); put("tot.done", state.done); put("tot.current", state.current); }
+
+  function render() {
+    Array.prototype.forEach.call(stepper.querySelectorAll(".snode"), (n: any) => {
+      const s = n.getAttribute("data-go");
+      n.setAttribute("data-st", state.current === s ? "active" : state.done[s] ? "done" : state.unlocked[s] ? "done" : "locked");
+    });
+    Object.keys(stages).forEach((s) => { if (stages[s]) stages[s].hidden = state.current !== s; });
+    if (bars.run) bars.run.hidden = !(state.done.run && state.current !== "run");
+    if (bars.edit) bars.edit.hidden = !(state.done.edit && state.current !== "edit");
+    // Contextual celebrate banners reflect achieved state (survive reloads).
+    if (celRun && state.done.run) celRun.hidden = false;
+    if (celEdit && state.done.edit) celEdit.hidden = false;
+    if (toNext) toNext.disabled = !state.unlocked.next;
+  }
+  function goTo(s: string) {
+    if (!state.unlocked[s]) return;
+    state.current = s; persist(); render();
+    window.scrollTo({ top: 0, behavior: reduce ? "auto" : "smooth" });
+  }
+
+  function onSignal(s: any) {
+    if (!s || s.offline) return;
+
+    // Step 1 — local server is live.
+    if (s.server && !state.done.run) {
+      state.done.run = true; state.unlocked.edit = true;
+      if (editBase === null) { editBase = s.lastSaveAt || 0; put("tot.editBase", editBase); }
+      persist();
+      if (barRunMeta && s.port) barRunMeta.textContent = "localhost:" + s.port + (s.tenant ? "/" + s.tenant + "/" : "/");
+      if (detect) detect.setAttribute("data-listening", "false");
+      if (detectTxt) detectTxt.textContent = "Your store is live on this machine.";
+      if (state.current === "run") { goTo("edit"); } else { render(); }
+      ping("Your store is live", "tot.pinged.run");
+    }
+
+    // Step 2 — a NEW save (since the edit step began) has been reflected by a reload.
+    if (state.done.run && !state.done.edit && editBase !== null) {
+      const newSave = (s.lastSaveAt || 0) > editBase;
+      const reflected = (s.lastSaveAt || 0) > 0 && (s.lastReloadAt || 0) >= (s.lastSaveAt || 0);
+      if (newSave && !reflected && detectEditTxt) {
+        detectEditTxt.textContent = "Change detected — reloading your store…";
+      }
+      if (newSave && reflected) {
+        state.done.edit = true; state.unlocked.next = true; persist();
+        if (barEditMeta && s.watchedFile) barEditMeta.textContent = s.watchedFile;
+        if (detectEdit) detectEdit.setAttribute("data-listening", "false");
+        if (detectEditTxt) detectEditTxt.textContent = "Saved — your store reloaded. That's the loop.";
+        if (state.current === "edit") { goTo("next"); } else { render(); }
+        ping("Saved — your page reloaded", "tot.pinged.edit");
+      }
+    }
+  }
+
+  render();
+  Array.prototype.forEach.call(document.querySelectorAll("[data-go]"), (el: any) => {
+    el.addEventListener("click", () => { goTo(el.getAttribute("data-go")); });
+  });
+  window.addEventListener("tot:loop-state", (e: any) => { onSignal(e.detail); });
+  if (window.__totLoop) onSignal(window.__totLoop);
+}

package/apps/storefront/src/lib/dev/cockpit/themeToggle.ts

@@ -0,0 +1,23 @@
+/**
+ * Theme toggle: flip data-theme on <html>, seeded from the OS preference on
+ * first click, and PERSISTED to localStorage so a reload stays on the manual
+ * choice (the is:inline head seed script reads this same key before first
+ * paint — that one stays is:inline because it must run synchronously before
+ * CSS paints, the one legitimate is:inline case per ADR 0013). Clearing
+ * storage falls back to prefers-color-scheme again, same as a first-ever
+ * visit. Imported from a processed `<script>` in cockpit.astro.
+ */
+export function initThemeToggle(): void {
+  const root = document.documentElement;
+  const btn = document.getElementById("themeBtn");
+  if (!btn) return;
+  const KEY = "tot.theme";
+  function store(v: string) { try { localStorage.setItem(KEY, v); } catch (e) {} }
+  btn.addEventListener("click", () => {
+    const cur = root.getAttribute("data-theme");
+    const next = cur === "dark" ? "light" : cur === "light" ? "dark"
+      : (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "dark");
+    root.setAttribute("data-theme", next);
+    store(next);
+  });
+}

package/apps/storefront/src/lib/dev/cockpitStore.ts

@@ -3,20 +3,12 @@
  * cockpit page, its /api/dev/* routes, and the CLI sign-in-code mint all share, so
  * they never disagree about the developer's store.
  *
- * REGRESSION FIXED (8500 <tenant>/cockpit): the page and the mint used to derive
- * the store purely from the session's FIRST membership
- * (`session.tenants?.[0]?.resource ?? session.resource`), ignoring the store the
- * request URL actually named. An invite to `/<tenantB>/cockpit` therefore rendered —
- * and minted a `tot login --code … && tot start` for — whatever store happened to be
- * listed first in the session, "losing track of the store" for any developer who
- * belongs to more than one.
- *
  * Rule: the URL wins WHEN THE VIEWER CAN ACCESS IT. The middleware has already
  * resolved the request's host/path to `locals.tenant` (the trusted, authenticated
  * store seam — never client body input), so when that is a SPECIFIC store (not the
  * public marketing home) and the signed-in developer holds a membership for it (or a
  * live staff admission), that store is authoritative. Otherwise we fall back to the
- * session's own first store (the generic-host `/cockpit` case, unchanged), and for an
+ * session's own first store (the generic-host `/cockpit` case), and for an
  * anonymous viewer to the path store's branding, else the caller-supplied `?tenant=`.
  *
  * Access is gated with the SAME primitive (`viewerCanAccess`) the vendor dashboard

package/apps/storefront/src/lib/dev/devDraft.ts

@@ -1,6 +1,6 @@
 /**
  * Per-developer DRAFT overlay for the /dev live preview — the signed token + KV key
- * contract behind decision `draft-overlay-same-origin` (workstream 8500-dev-live-preview).
+ * contract for the same-origin draft overlay.
  *
  * WHAT A DRAFT IS: when the /dev page's onscreen AI loop edits the developer's site
  * (`/api/content-edit/ai-edit`), the edited artifacts land in TENANT_CACHE KV under

package/apps/storefront/src/lib/dev/previewStatus.ts

@@ -1,41 +1,29 @@
 /**
  * Read whether a tenant appDomain's store is SET UP — its forge repo is provisioned —
  * from the credential-free MCP preview-status seam (tot-mcp
- * GET /internal/preview-status; legacy alias /internal/dev-access/preview-status). The
+ * GET /internal/preview-status; alias /internal/dev-access/preview-status). The
  * seam answers `{ tenant, app, repo, provisioned, previewReleased }`.
  *
- * This is the cockpit's own small reader — self-contained, mirroring `cliSignInCode.ts`
- * (same MCP-origin + service-secret seam) rather than importing another cluster's copy,
- * so the two stay decoupled (the same reason `cliSignInCode` duplicates its transport).
- * It gates the CLI sign-in-code mint + the /cockpit setup fastpath so a developer whose
+ * This is the cockpit's own small reader over the same MCP-origin + service-secret seam
+ * `cliSignInCode.ts` uses. It gates the CLI sign-in-code mint + the /cockpit setup
+ * fastpath so a developer whose
  * store isn't provisioned yet gets an honest "not set up" state instead of a
  * `tot login --code … && tot start` command that would die at checkout on
- * "Repo <owner>-main is not provisioned" (James's 2026-07-19 first-run failure).
+ * "Repo <owner>-main is not provisioned".
  *
  *   - MCP host  ← the ORIGIN of MCP_APP_BINDING_URL (one source, so this read hits the
  *                 SAME MCP tier the sign-in-code mint does).
  *   - auth      ← header x-mcp-service-secret: MCP_SERVICE_SHARED_SECRET.
  *
  * Fail-closed but non-blocking by design: an UNCONFIGURED seam (no URL/secret) →
- * { configured:false } so callers keep today's behavior (no regression); any non-2xx /
+ * { configured:false } so callers keep the default behavior; any non-2xx /
  * transport / parse fault → { configured:true, ok:false } so a caller can distinguish
  * "definitely not provisioned" (ok + provisioned:false) from "couldn't tell". Never throws.
  */
 import { readEnv } from "@/lib/env";
+import { FetchHttpTransport, type HttpGetTransport } from "@/lib/http/fetchTransport";
 
-export interface HttpGetTransport {
-  get(
-    url: string,
-    headers: Record<string, string>,
-  ): Promise<{ status: number; json(): Promise<unknown> }>;
-}
-
-export class FetchGetTransport implements HttpGetTransport {
-  async get(url: string, headers: Record<string, string>) {
-    const res = await fetch(url, { method: "GET", headers });
-    return { status: res.status, json: () => res.json() };
-  }
-}
+export type { HttpGetTransport };
 
 export interface TenantPreviewStatus {
   /** False when the seam isn't wired on this deploy (no URL/secret) — gate inactive. */
@@ -68,7 +56,7 @@ export async function readTenantPreviewStatus(
     return { configured: false, ok: false, reason: "bad-mcp-url" };
   }
 
-  const transport = deps.transport ?? new FetchGetTransport();
+  const transport = deps.transport ?? new FetchHttpTransport();
   const full = `${endpoint}?tenant=${encodeURIComponent(tenant.toLowerCase())}`;
   let res: { status: number; json(): Promise<unknown> };
   try {

package/apps/storefront/src/lib/dev/rendezvousBroker.ts

@@ -21,20 +21,14 @@
  */
 import { readEnv } from "@/lib/env";
 import { mintMcpClientAssertion, McpClientAssertionError } from "@/lib/auth/mcpClientAssertion";
+import { FetchHttpTransport, type HttpTransport } from "@/lib/http/fetchTransport";
+
+export type { HttpTransport };
 
 const JWT_BEARER_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
 /** The path whose audience the MCP binds EVERY rendezvous assertion to. */
 const RENDEZVOUS_AUDIENCE_PATH = "/oauth/device/rendezvous";
 
-/** Injectable transport so the broker calls unit-test with no network. */
-export interface HttpTransport {
-  post(
-    url: string,
-    headers: Record<string, string>,
-    body: unknown,
-  ): Promise<{ status: number; json(): Promise<unknown> }>;
-}
-
 // Bound every rendezvous call to the MCP. The MCP runs on AppRunner (scale-to-zero),
 // so the FIRST call after idle hits a cold instance that can take many seconds to
 // answer. Without a bound the storefront Worker's subrequest hangs and the browser's
@@ -44,20 +38,6 @@ export interface HttpTransport {
 // 502 ("having a moment — try again"); the retry lands on a now-warm MCP and succeeds.
 const RENDEZVOUS_FETCH_TIMEOUT_MS = 12_000;
 
-export class FetchHttpTransport implements HttpTransport {
-  async post(url: string, headers: Record<string, string>, body: unknown) {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json", ...headers },
-      body: JSON.stringify(body),
-      // A timeout/abort rejects the fetch → callRendezvous's catch → a 502 the cockpit
-      // renders as a retryable error, instead of a hung request the browser gives up on.
-      signal: AbortSignal.timeout(RENDEZVOUS_FETCH_TIMEOUT_MS),
-    });
-    return { status: res.status, json: () => res.json() };
-  }
-}
-
 export interface RendezvousDeps {
   transport?: HttpTransport;
   /** Override the assertion minter in tests (defaults to the real private-key signer). */
@@ -97,7 +77,12 @@ async function callRendezvous(
 ): Promise<{ status: number; body: Record<string, unknown> }> {
   const mint = deps.mintAssertion ?? ((aud: string) => mintMcpClientAssertion(aud));
   const clientAssertion = await mint(target.audience);
-  const transport = deps.transport ?? new FetchHttpTransport();
+  const transport =
+    deps.transport ??
+    new FetchHttpTransport({
+      defaultHeaders: { "Content-Type": "application/json" },
+      timeoutMs: RENDEZVOUS_FETCH_TIMEOUT_MS,
+    });
   const res = await transport.post(
     `${target.origin}${path}`,
     {},

package/apps/storefront/src/lib/dev/runtimeStore.ts

@@ -1,6 +1,6 @@
 /**
  * Per-DEVELOPER "local dev runtime" latest-state — the LIVE half of the
- * local→hosted activity bridge (G1). Where activityStore.ts holds a ring buffer
+ * local→hosted activity bridge. Where activityStore.ts holds a ring buffer
  * of file-SAVE events, this holds the most recent heartbeat a developer's LOCAL
  * `tot dev`/`tot start` sent (see the CLI's dev-heartbeat.mjs). The hosted cockpit
  * reads it to show a LIVE, clickable local-dev link + the running CLI version.

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

@@ -15,10 +15,11 @@
  * response with Set-Cookie, and anything non-200/non-HTML. In `astro dev` there
  * is no `caches` global, so every helper is a clean no-op.
  *
- * Note on the CSP nonce: a stored page carries the nonce it was rendered with, in
- * both its inline tags and its CSP header, and is served to many users. That is
- * safe — the nonce is not a secret; it only has to match within one identical,
- * non-personalized document, which it does.
+ * Note on the CSP nonce (ADR 0018): a stored page is NONCE-FREE — its inline tags
+ * and CSP header carry the nonce placeholder, not a live nonce. A fresh per-response
+ * nonce is stamped in at serve time (stampResponseNonce), on both the cold render and
+ * the warm cache hit, so no cached artifact ever holds a reusable nonce and every
+ * response gets its own matching nonce/CSP pair.
  */
 
 /** Synthetic internal origin for cache keys — never hits the network. */
@@ -62,8 +63,36 @@ export function pageCacheKey(
   pathname: string,
   search: string,
   version: number,
+  planRevision?: string,
 ): Request {
-  return new Request(`${CACHE_ORIGIN}/${tenantId}/v${version}${pathname}${search}`);
+  // A stored page carries the CSP header it was rendered with, INCLUDING any
+  // version-scoped integration origins. Folding the resolved `planRevision` into
+  // the key makes a warm entry plan-scoped: a rollback/uninstall resolves a new
+  // revision, so the old entry is unreachable (a clean miss that re-renders
+  // without the removed origins) instead of surviving to TTL. Absent (no
+  // integration plane resolved) the key is byte-identical to the non-integration
+  // form, so a plain tenant pays nothing and its cache is never busted.
+  const planSegment = planRevision ? `/pr:${planRevision}` : "";
+  return new Request(
+    `${CACHE_ORIGIN}/${tenantId}/v${version}${planSegment}${pathname}${search}`,
+  );
+}
+
+/**
+ * Cache key for a digest-addressed static-bundle response (ADR 0012).
+ * Keyed by `treeDigest` instead of the integer `cachever` `pageCacheKey` uses —
+ * a pointer flip to a NEW digest is a different key, so it is a clean cache
+ * miss (never a stale serve of the old digest); an unchanged digest keeps
+ * serving its warm entry across requests. Shares `getCachedPage`/
+ * `putCachedPage` with the page cache (both just take a Request key + Cache).
+ */
+export function staticBundleCacheKey(
+  tenantId: string,
+  digest: string,
+  pathname: string,
+  search: string,
+): Request {
+  return new Request(`${CACHE_ORIGIN}/${tenantId}/digest-${digest}${pathname}${search}`);
 }
 
 /** Current cache version for a tenant (defaults to 1). KV read is edge-cached. */

package/apps/storefront/src/lib/email/candidateConflictEmail.ts

@@ -0,0 +1,80 @@
+/**
+ * The storefront's OWN branded "your open change now conflicts" email. When the shared
+ * preview base advances (another change was accepted/integrated), every OTHER open
+ * candidate is auto-rebased onto the new base; a clean rebuild is silent, but a genuine
+ * same-line overlap can't be auto-combined and needs the author's call. This is the push
+ * notification for that case — the author is pinged the MOMENT their change actually
+ * conflicts with someone else's merge, not at their own accept attempt.
+ *
+ * Rendered here (our brand), transmitted by tot20 (see lib/messaging/messagesClient.ts).
+ * Email HTML rules: inline styles only, table-free simple layout, a visible fallback URL
+ * under the button.
+ */
+
+/** Minimal HTML escape for untrusted interpolation (file paths, store name). */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export interface CandidateConflictEmailInput {
+  /** Display name of the store/experience. Default "Regulated Storefront". */
+  storeName?: string;
+  /** The author's open change PR number, when known. */
+  prNumber?: number | null;
+  /** Repo-relative paths that changed on both sides and need the author's pick. */
+  unresolved: string[];
+  /** Absolute deep-link to the resolve UI (admin#publish), or null when no origin is known. */
+  resolveUrl?: string | null;
+}
+
+const FILE_LIMIT = 12;
+
+export function renderCandidateConflictEmail(input: CandidateConflictEmailInput): {
+  subject: string;
+  html: string;
+} {
+  const store = input.storeName?.trim() || "Regulated Storefront";
+  const label = input.prNumber != null ? `PR #${input.prNumber}` : "your change";
+  const subject = `Action needed: ${label} now conflicts with ${store}`;
+  const url = input.resolveUrl || null;
+
+  const files = input.unresolved.slice(0, FILE_LIMIT);
+  const overflow = input.unresolved.length - files.length;
+  const fileList = files.length
+    ? `<ul style="margin:8px 0 0;padding-left:20px;color:#33415b;font-size:14px;">${files
+        .map((f) => `<li style="margin:2px 0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">${esc(f)}</li>`)
+        .join("")}${overflow > 0 ? `<li style="margin:2px 0;color:#8593a8;">…and ${overflow} more file(s)</li>` : ""}</ul>`
+    : "";
+
+  const cta = url
+    ? `<div style="margin:28px 0;">
+        <a href="${esc(url)}" style="display:inline-block;background:#0b7a6d;color:#ffffff;text-decoration:none;font-weight:600;font-size:16px;padding:14px 28px;border-radius:999px;">Resolve it now</a>
+      </div>
+      <p style="margin:0 0 4px;font-size:13px;color:#55637a;">Or paste this link into your browser:</p>
+      <p style="margin:0 0 24px;font-size:13px;word-break:break-all;"><a href="${esc(url)}" style="color:#0b7a6d;">${esc(url)}</a></p>`
+    : "";
+
+  const html = `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /></head>
+  <body style="margin:0;padding:0;background:#f7f9fc;">
+    <div style="max-width:520px;margin:0 auto;padding:32px 20px;font:16px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#33415b;">
+      <div style="font:600 12px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.12em;text-transform:uppercase;color:#0b7a6d;margin:0 0 24px;">
+        Token of Trust&#169; &middot; ${esc(store)}
+      </div>
+      <h1 style="font-size:22px;line-height:1.3;letter-spacing:-.02em;margin:0 0 12px;color:#0a2540;">${esc(label)} needs your input</h1>
+      <p style="margin:0 0 8px;color:#33415b;">The store moved on — another change was just accepted into <strong>${esc(store)}</strong>, and we tried to rebuild ${esc(label)} on top of it automatically. Most of it merged cleanly, but these files were edited on both sides and need you to pick which version wins:</p>
+      ${fileList}
+      ${cta}
+      <p style="margin:16px 0 0;font-size:14px;color:#33415b;">You can also resolve it from the command line — <code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">tot preview --strategy=ours</code> keeps your version, <code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace;">tot preview --strategy=theirs</code> takes the store's.</p>
+      <p style="margin:24px 0 0;font-size:12px;color:#8593a8;border-top:1px solid #e3e8ef;padding-top:16px;">Your change is safe and still open — it just stays not-mergeable until you resolve these files. Nothing was overwritten.</p>
+    </div>
+  </body>
+</html>`;
+
+  return { subject, html };
+}

package/apps/storefront/src/lib/http/fetchTransport.ts

@@ -0,0 +1,63 @@
+/**
+ * The one shared `fetch`-backed HTTP transport seam used by the storefront's
+ * server-to-server clients. A transport is injectable so those clients unit-test
+ * with no network; this is the production implementation they default to.
+ *
+ * Both `post` and `get` return the minimal `{ status, json }` shape the callers
+ * read — never the raw `Response` — so a test stub and the real transport are
+ * interchangeable. `defaultHeaders` are merged under each call's own headers
+ * (per-call wins); `timeoutMs`, when set, aborts each request via
+ * `AbortSignal.timeout` so a hung subrequest becomes a fast, retryable failure.
+ */
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+
+export interface HttpGetTransport {
+  get(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+}
+
+export interface FetchHttpTransportOptions {
+  /** Merged UNDER each call's headers (a per-call header of the same name wins). */
+  defaultHeaders?: Record<string, string>;
+  /** When set, every request aborts after this many ms via `AbortSignal.timeout`. */
+  timeoutMs?: number;
+}
+
+export class FetchHttpTransport implements HttpTransport, HttpGetTransport {
+  private readonly defaultHeaders: Record<string, string>;
+  private readonly timeoutMs?: number;
+
+  constructor(options: FetchHttpTransportOptions = {}) {
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.timeoutMs = options.timeoutMs;
+  }
+
+  private signal(): AbortSignal | undefined {
+    return this.timeoutMs != null ? AbortSignal.timeout(this.timeoutMs) : undefined;
+  }
+
+  async post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike> {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { ...this.defaultHeaders, ...headers },
+      body: JSON.stringify(body),
+      signal: this.signal(),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+
+  async get(url: string, headers: Record<string, string>): Promise<HttpResponseLike> {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { ...this.defaultHeaders, ...headers },
+      signal: this.signal(),
+    });
+    return { status: res.status, json: () => res.json() };
+  }
+}

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

@@ -0,0 +1,25 @@
+// Human-readable, in-language display names for the reader language switcher,
+// keyed by BCP-47 primary subtag. Unmapped codes fall back to the uppercased code.
+const LANGUAGE_LABELS: Record<string, string> = {
+  en: "English",
+  es: "Español",
+  fr: "Français",
+  de: "Deutsch",
+  it: "Italiano",
+  pt: "Português",
+  nl: "Nederlands",
+  sv: "Svenska",
+  pl: "Polski",
+  ru: "Русский",
+  ja: "日本語",
+  ko: "한국어",
+  zh: "中文",
+  ar: "العربية",
+  hi: "हिन्दी",
+  tr: "Türkçe",
+};
+
+export function languageLabel(code: string): string {
+  const primary = code.toLowerCase().split(/[-_]/)[0] ?? code;
+  return LANGUAGE_LABELS[primary] ?? code.toUpperCase();
+}