@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,99 @@
+/**
+ * Deterministic local placeholder art (brief: images note).
+ *
+ * Fixture image URLs are Shopify-CDN paths that 404 and we ship offline. Rather
+ * than a grey box, we synthesize a tasteful, aspect-correct SVG keyed by a
+ * stable seed (image id or product handle) so each product gets a consistent,
+ * on-brand gradient + monogram. The <Img> component swaps these out for real
+ * rehosted URLs when CatalogImage.rehosted === true.
+ *
+ * Palette is pulled from the theme's CSS vars at render time where possible, but
+ * the SVG is self-contained (inlines colors) so it works as a data URI / <img src>.
+ */
+
+// Quiet, on-brand duotone pairs (spruce/greige/amber family). Picked by seed.
+const PAIRS: Array<[string, string]> = [
+  ["#243B35", "#C9C2B2"], // spruce -> sand
+  ["#33514A", "#E3DCCB"], // pine -> paper
+  ["#1F3A34", "#B5612F"], // anchor -> amber
+  ["#3A4A45", "#D8D1C2"], // slate-sage -> light sand
+  ["#2C3E39", "#A88B5C"], // deep green -> ochre
+  ["#1C2624", "#7E8B86"], // ink -> stone
+];
+
+function hash(seed: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return Math.abs(h);
+}
+
+export interface PlaceholderOpts {
+  seed: string;
+  width: number;
+  height: number;
+  /** Short label drawn faintly (e.g. product initials). */
+  label?: string;
+}
+
+/** Returns a complete SVG string (aspect-correct, deterministic). */
+export function placeholderSvg({ seed, width, height, label }: PlaceholderOpts): string {
+  const h = hash(seed);
+  const pair = PAIRS[h % PAIRS.length] ?? PAIRS[0]!;
+  const [a, b] = pair;
+  const angle = (h % 6) * 30; // 0..150deg
+  const cx = 20 + (h % 60);
+  const cy = 20 + ((h >> 3) % 60);
+  const initials = (label ?? seed)
+    .split(/[\s-]+/)
+    .map((w) => w[0])
+    .filter(Boolean)
+    .slice(0, 2)
+    .join("")
+    .toUpperCase();
+
+  // Two soft radial blooms over a linear base — reads as considered, not noisy.
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-hidden="true">
+  <defs>
+    <linearGradient id="g" gradientTransform="rotate(${angle})">
+      <stop offset="0%" stop-color="${a}"/>
+      <stop offset="100%" stop-color="${b}"/>
+    </linearGradient>
+    <radialGradient id="r" cx="${cx}%" cy="${cy}%" r="70%">
+      <stop offset="0%" stop-color="${b}" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="${a}" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="100%" height="100%" fill="url(#g)"/>
+  <rect width="100%" height="100%" fill="url(#r)"/>
+  <text x="50%" y="50%" dy="0.35em" text-anchor="middle"
+        font-family="'Space Grotesk', system-ui, sans-serif"
+        font-size="${Math.round(Math.min(width, height) * 0.16)}"
+        font-weight="600" letter-spacing="0.04em"
+        fill="${b}" fill-opacity="0.22">${initials || "•"}</text>
+</svg>`;
+}
+
+/** Base64 data URI form (for <img src> and OG images). */
+export function placeholderDataUri(opts: PlaceholderOpts): string {
+  const svg = placeholderSvg(opts);
+  // btoa is available in Workers + browsers; encodeURIComponent path is the
+  // SSR-safe fallback that also handles non-latin labels.
+  const encoded = encodeURIComponent(svg)
+    .replace(/'/g, "%27")
+    .replace(/"/g, "%22");
+  return `data:image/svg+xml,${encoded}`;
+}
+
+/** True if a CatalogImage URL is usable vs a dead/synthetic fixture path. */
+export function isUsableImageUrl(url: string | undefined, rehosted?: boolean): boolean {
+  if (!url) return false;
+  if (rehosted) return true;
+  // The synthetic apparel fixtures use a fake shop id (…/s/files/1/0001/…) whose
+  // URLs 404 — draw placeholders for those. REAL store CDN URLs (e.g. a live POC
+  // migration) are usable as-is.
+  if (/\/s\/files\/1\/0001\//.test(url)) return false;
+  return /^https?:\/\//.test(url);
+}

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

@@ -0,0 +1,125 @@
+/**
+ * On-publish auto-refresh for the SHARED preview (reviewer/owner "it updates
+ * itself" experience). NOT the developer's local `tot dev` HMR loop — this is the
+ * shared `test`-env preview that others review.
+ *
+ * A tiny live-reload client is injected (by src/middleware) into `test`-env HTML
+ * pages ONLY — never `live`. It polls `GET /__preview/version?tenant=<id>` (the
+ * per-tenant edge cache-version integer, which bumps on every reconcile/publish;
+ * see lib/edgeCache.ts + api/preview/reconcile.ts) and reloads the page when the
+ * version changes. Poll-based v1; an SSE / Durable-Object PUSH is the later
+ * upgrade (TODO below) that removes the ~1s poll latency.
+ *
+ * CSP: the injected <script> carries the per-request nonce (same one the strict
+ * CSP header allows), so it is CSP-clean with no `unsafe-inline` and no inline
+ * event handlers.
+ */
+
+const DEFAULT_POLL_MS = 1000;
+
+/** Escape a value for safe embedding inside an inline <script> as JSON. */
+function jsonForScript(value: unknown): string {
+  // JSON.stringify covers quoting; escaping `<` defends against a `</script>`
+  // (or `<!--`) breakout even though tenant ids / base paths never contain it.
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+/**
+ * The live-reload client body (no <script> wrapper). Kept dependency-free and
+ * tiny so it is cheap to inline on every preview page.
+ */
+export function buildPreviewReloadScript(opts: {
+  tenantId: string;
+  basePath: string;
+  pollMs?: number;
+}): string {
+  const tenant = jsonForScript(opts.tenantId);
+  const base = jsonForScript(opts.basePath ?? "");
+  const pollMs = Math.max(250, Math.floor(opts.pollMs ?? DEFAULT_POLL_MS));
+  // The version endpoint is fetched UNDER basePath so the same tenant-routing the
+  // page used resolves it (path-routed previews carry a /<domain> prefix).
+  return `(() => {
+  const TENANT = ${tenant}, BASE = ${base}, POLL_MS = ${pollMs};
+  const url = BASE + "/__preview/version?tenant=" + encodeURIComponent(TENANT);
+  let known = null;
+  const tick = async () => {
+    try {
+      const res = await fetch(url, { headers: { accept: "application/json" }, cache: "no-store" });
+      if (res.ok) {
+        const v = (await res.json()).version;
+        if (known === null) { known = v; }
+        // TODO(theme-hot-swap): when the change is theme-only, swap the CSS custom
+        // properties in place (no reload). Needs the reconcile to report a
+        // theme-only delta; gated behind this same version signal until then.
+        else if (v !== known) { location.reload(); return; }
+      }
+    } catch (_e) { /* transient — keep polling */ }
+    setTimeout(tick, POLL_MS);
+  };
+  // TODO(push): replace this poll with an SSE / Durable-Object stream so the
+  // reload is instant instead of within POLL_MS of a publish.
+  setTimeout(tick, POLL_MS);
+})();`;
+}
+
+/** True when a response is HTML we can inject into. */
+export function isHtmlResponse(response: Response): boolean {
+  if (response.status !== 200) return false;
+  return (response.headers.get("content-type") ?? "").includes("text/html");
+}
+
+/**
+ * Inject the live-reload <script> into an HTML string, before </body> (or
+ * appended when there is no </body>). Pure + unit-testable.
+ */
+export function injectPreviewReloadHtml(
+  html: string,
+  opts: { tenantId: string; basePath: string; nonce: string; pollMs?: number },
+): string {
+  const script = `<script nonce="${opts.nonce}">${buildPreviewReloadScript(opts)}</script>`;
+  if (/<\/body>/i.test(html)) {
+    return html.replace(/<\/body>/i, `${script}</body>`);
+  }
+  return html + script;
+}
+
+/**
+ * Wrap a Response, returning a new one with the reload client injected. No-op
+ * (returns the original) for non-HTML responses. The caller must have already
+ * decided this is a `test`-env response — this helper does not check the env.
+ */
+export async function injectPreviewReload(
+  response: Response,
+  opts: { tenantId: string; basePath: string; nonce: string; pollMs?: number },
+): Promise<Response> {
+  if (!isHtmlResponse(response)) return response;
+  const html = await response.text();
+  const injected = injectPreviewReloadHtml(html, opts);
+  // Preserve status + headers; the body length changed but we don't set a manual
+  // Content-Length anywhere (Workers/Astro stream), so no header fix-up needed.
+  return new Response(injected, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+/**
+ * Env-gated entrypoint the middleware calls: inject the reload client ONLY for
+ * the SHARED preview (`test`) — NEVER `live`. Returns the response unchanged for
+ * `live` (or any non-HTML response). This is the single guardrail seam, so the
+ * "present in test, absent in live" contract is unit-testable here.
+ */
+export async function maybeInjectPreviewReload(
+  response: Response,
+  opts: {
+    env: "live" | "test";
+    tenantId: string;
+    basePath: string;
+    nonce: string;
+    pollMs?: number;
+  },
+): Promise<Response> {
+  if (opts.env !== "test") return response;
+  return injectPreviewReload(response, opts);
+}

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

@@ -0,0 +1,133 @@
+/**
+ * Raw marketing-HTML serving — the "vendor injects their own HTML" path.
+ *
+ * A marketing tenant can ship a self-contained document (`content/<tenant>/home.html`
+ * or `content/<tenant>/pages-html/<slug>.html`) that we serve VERBATIM, bypassing the
+ * block Layout. Two transforms are applied at serve time:
+ *   1. nonce-stamp the document's inline <style>/<script> so a strict CSP admits them;
+ *   2. under path-prefix tenant routing (locals.basePath set), prefix same-origin
+ *      root-absolute anchor hrefs with the base path so navigation stays in-tenant —
+ *      the raw doc bypasses the Layout's client base-path fixer, so we do it here.
+ *
+ * Single home for both routes (`index.astro`, `[...slug].astro`).
+ *
+ * SECURITY: this trusts the tenant's HTML (first-party marketing). The nonce
+ * injection is a deliberate string replace — robust for first-party documents, not a
+ * sanitizer. Untrusted vendor HTML must be sandboxed/sanitized instead.
+ */
+
+/**
+ * Marker a body-only page fragment's chrome wrapper uses to say "the page body
+ * goes here". A tenant's `content/<tenant>/chrome.html` is a full document with
+ * this comment where the fragment is spliced in. Kept as an HTML comment so the
+ * wrapper is still valid, previewable HTML on its own.
+ */
+export const CHROME_BODY_MARKER = "<!--PAGE_BODY-->";
+
+/**
+ * Marker in the chrome wrapper's <head> where a fragment's page-specific <head>
+ * (title / meta / canonical / OG / JSON-LD) is spliced in — so shared chrome does
+ * NOT flatten per-page SEO. A fragment may lead with a `<head>…</head>` block; its
+ * contents go here, the rest goes to CHROME_BODY_MARKER.
+ */
+export const CHROME_HEAD_MARKER = "<!--PAGE_HEAD-->";
+
+/**
+ * True when `html` is a complete document (has <html> or a doctype) rather than a
+ * body-only fragment. Full documents are served verbatim; fragments get wrapped
+ * in the tenant's shared chrome. This is what keeps the mechanism backward-
+ * compatible — every existing raw home/subpage is a full document.
+ */
+export function isFullDocument(html: string): boolean {
+  return /^\s*<!doctype/i.test(html) || /<html[\s>]/i.test(html);
+}
+
+/**
+ * Splice a body-only fragment into a tenant chrome wrapper at CHROME_BODY_MARKER.
+ * If the wrapper has no marker (misconfigured), the fragment is returned unwrapped
+ * so a page never disappears.
+ */
+export function wrapFragmentInChrome(fragment: string, chromeWrapper: string): string {
+  if (!chromeWrapper.includes(CHROME_BODY_MARKER)) return fragment;
+  // A fragment may lead with a <head>…</head> of page-specific SEO tags. Split it
+  // out so the shared wrapper keeps per-page title/meta/canonical/JSON-LD.
+  let head = "";
+  let body = fragment;
+  const m = fragment.match(/^\s*<head[^>]*>([\s\S]*?)<\/head>/i);
+  if (m) {
+    head = m[1] ?? "";
+    body = fragment.slice(m[0].length);
+  }
+  let out = chromeWrapper.replace(CHROME_BODY_MARKER, body);
+  if (out.includes(CHROME_HEAD_MARKER)) out = out.replace(CHROME_HEAD_MARKER, head);
+  return out;
+}
+
+/** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
+export function nonceInlineTags(html: string, nonce: string): string {
+  return html
+    .replaceAll("<style>", `<style nonce="${nonce}">`)
+    .replaceAll("<script", `<script nonce="${nonce}"`);
+}
+
+/**
+ * Prefix same-origin root-absolute hrefs (`href="/…"`) with the tenant base path,
+ * so `/pricing/` becomes `/<domain>/pricing/` under path-prefix routing. No-op when
+ * basePath is empty (host-routed prod). Skips protocol-relative `//…` and, crucially,
+ * `/tenants/…` — those are GLOBAL static assets (logo, favicon) served at root under
+ * both routing modes, so they must NOT get the tenant prefix. Asset `src="…"` isn't
+ * matched at all (href-only).
+ */
+export function prefixTenantLinks(html: string, basePath: string): string {
+  if (!basePath) return html;
+  return html.replace(/href="\/(?!\/|tenants\/)/g, `href="${basePath}/`);
+}
+
+/**
+ * Build the HTML Response for a raw marketing page (nonce + base-path).
+ *
+ * Shared-chrome mechanism: a page is served in one of two ways —
+ *   - FULL DOCUMENT (has <html>/doctype): served verbatim, as before.
+ *   - BODY FRAGMENT + a tenant `chromeWrapper`: the fragment is spliced into the
+ *     wrapper's CHROME_BODY_MARKER so chrome lives in ONE place, not copied into
+ *     every page. A fragment with no wrapper still serves (unwrapped) for safety.
+ * Either way, the FINAL document gets nonce-stamped and base-path-prefixed, so the
+ * chrome's own inline <style>/<script> and root-absolute nav links are handled too.
+ */
+export function rawHtmlResponse(
+  html: string,
+  opts: { nonce: string; basePath: string; chromeWrapper?: string | null },
+): Response {
+  let composed =
+    isFullDocument(html) || !opts.chromeWrapper
+      ? html
+      : wrapFragmentInChrome(html, opts.chromeWrapper);
+  // DEV ONLY: these pages are served verbatim, bypassing Astro's render pipeline,
+  // so the Vite HMR client is never injected — a save would reach the server (see
+  // the tenantHotReload plugin in astro.config.mjs) but the browser would have no
+  // listener to act on the full-reload. Inject the client so save→reload works.
+  // Stamped with the page nonce by nonceInlineTags below; tree-shaken from prod.
+  if (import.meta.env.DEV) {
+    const client = `<script type="module" src="/@vite/client"></script>`;
+    composed = composed.includes("</head>")
+      ? composed.replace("</head>", `${client}</head>`)
+      : `${client}${composed}`;
+    // Inline-AI edit loop's floating "✦ ask" affordance (WS5 G1) — same reason
+    // as the HMR client above, these pages bypass the Astro pipeline that
+    // inlineAiEditPlugin's transformIndexHtml hook (astro.config.mjs) covers
+    // for everything else, so it's injected here too. Unconditional in dev,
+    // matching the Vite client above: whether `tot dev` set an active tenant
+    // (TOT_DEV_TENANT) is a Node-process env var, invisible to this SSR code
+    // when it runs inside the Cloudflare/workerd dev runtime (see tot-dev.mjs's
+    // own note on this exact gap) — so the gate lives server-side instead, in
+    // inlineAiEditPlugin's Vite middleware, which DOES see the real env.
+    const widget = `<script type="module" src="/__tot/ai-widget-client.js"></script>`;
+    composed = composed.includes("</body>")
+      ? composed.replace("</body>", `${widget}</body>`)
+      : `${composed}${widget}`;
+  }
+  const doc = prefixTenantLinks(nonceInlineTags(composed, opts.nonce), opts.basePath);
+  return new Response(doc, {
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}

package/apps/storefront/src/lib/search/index.ts

@@ -0,0 +1,74 @@
+/**
+ * In-memory Fuse search index — the OFFLINE search floor.
+ *
+ * Used by FixtureToTClient.search (no D1 binding): typo-tolerant, relevance-ranked
+ * search over the bundled catalog snapshot, zero infra. When a D1 binding is wired
+ * (D1ToTClient), search instead goes through FTS5 — see lib/d1/catalog.ts and
+ * epics/edge-read-replica.md. This module is the portable floor an extracted
+ * merchant gets out of the box (docs/extraction-runbook.md).
+ */
+import Fuse, { type IFuseOptions } from "fuse.js";
+import type { CatalogProduct } from "@tot/public-runtime";
+
+export interface SearchHit {
+  product: CatalogProduct;
+  score: number;
+}
+
+export interface SearchIndex {
+  search(query: string, limit?: number): SearchHit[];
+}
+
+const FUSE_OPTIONS: IFuseOptions<CatalogProduct> = {
+  includeScore: true,
+  threshold: 0.38, // typo tolerance: lower = stricter
+  ignoreLocation: true,
+  minMatchCharLength: 2,
+  keys: [
+    { name: "title", weight: 0.5 },
+    { name: "vendor", weight: 0.15 },
+    { name: "product_type", weight: 0.15 },
+    { name: "tags", weight: 0.12 },
+    { name: "description_text", weight: 0.08 },
+  ],
+};
+
+export function buildSearchIndex(products: CatalogProduct[]): SearchIndex {
+  // Defensive: only ever index active products (the draft canary must never leak).
+  const active = products.filter((p) => p.status === "active");
+  const fuse = new Fuse(active, FUSE_OPTIONS);
+  return {
+    search(query: string, limit = 12): SearchHit[] {
+      const q = query.trim();
+      if (!q) return [];
+      return fuse.search(q, { limit }).map((r) => ({ product: r.item, score: r.score ?? 1 }));
+    },
+  };
+}
+
+/** Compact shape sent to the typeahead island (keeps client JSON tiny). */
+export interface TypeaheadDoc {
+  handle: string;
+  title: string;
+  vendor?: string;
+  type?: string;
+  price: number;
+  currency: string;
+  image?: string;
+  tags: string[];
+}
+
+export function toTypeaheadDoc(p: CatalogProduct): TypeaheadDoc {
+  const doc: TypeaheadDoc = {
+    handle: p.handle,
+    title: p.title,
+    price: p.price_range.min,
+    currency: p.price_range.currency,
+    tags: p.tags,
+  };
+  if (p.vendor) doc.vendor = p.vendor;
+  if (p.product_type) doc.type = p.product_type;
+  const img = p.images[0];
+  if (img?.url) doc.image = img.url;
+  return doc;
+}

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

@@ -0,0 +1,129 @@
+/**
+ * SectionSource — the single, typed contract every merchandising section binds
+ * to. A section component (ProductCarousel, ProductGrid, …) never talks to the
+ * catalog directly; it declares WHAT set of products it wants as a SectionSource
+ * and calls resolveSectionSource() to get them. This keeps the components
+ * tenant-agnostic and data-source-agnostic: swap the ToTClient backend (D1 vs
+ * fixture) and every section keeps working.
+ *
+ * Fidelity to a merchant's storefront comes from theme tokens + variant props +
+ * the source they point a section at — NEVER from forking a component per
+ * merchant. That's what keeps a tenant single-tenant-extractable.
+ */
+import type { CatalogProduct } from "@tot/public-runtime";
+import type { ToTClient } from "@/lib/tot/ToTClient";
+import { isOnSale } from "@/lib/tot/query";
+
+/**
+ * Where a merchandising section gets its products. Exactly one shape per source.
+ * `handle` placeholders are product/collection handles (unique per tenant).
+ */
+export type SectionSource =
+  | { collection: string } // products in a collection (by handle)
+  | { tag: string } // products carrying a tag
+  | { featured: true } // the curated/featured set (getFeatured)
+  | { newest: true } // newest-first
+  | { bestSelling: true } // bestseller-tagged
+  | { onSale: true } // anything with a live compare-at markdown
+  | { handles: string[] } // an explicit, ordered handle list
+  | { related: string } // products related to a base product (by handle)
+  | { recentlyViewed: true }; // client-personalized — resolves empty server-side
+
+export const DEFAULT_SECTION_LIMIT = 12;
+
+/** Bestseller signal is tag-based in Phase 1 (no order history at the edge). */
+const BESTSELLER_TAGS = new Set(["bestseller", "best-seller", "best-sellers"]);
+
+const isActive = (p: CatalogProduct) => p.status === "active";
+
+/**
+ * Resolve a SectionSource to a concrete, active product list via the tenant's
+ * ToTClient. Always returns at most `limit` ACTIVE products (drafts/archived are
+ * excluded from every public surface — see ToTClient docs). Backend-agnostic:
+ * tag/onSale/bestSelling filter over the client's list methods rather than
+ * assuming a SQL facet, so the fixture and D1 backends behave identically.
+ */
+export async function resolveSectionSource(
+  source: SectionSource,
+  tot: ToTClient,
+  limit: number = DEFAULT_SECTION_LIMIT,
+): Promise<CatalogProduct[]> {
+  if ("collection" in source) {
+    const { products } = await tot.listProducts({
+      collection: source.collection,
+      pageSize: limit,
+    });
+    return products.slice(0, limit);
+  }
+
+  if ("featured" in source) {
+    return (await tot.getFeatured(limit)).slice(0, limit);
+  }
+
+  if ("newest" in source) {
+    const { products } = await tot.listProducts({ sort: "newest", pageSize: limit });
+    return products.slice(0, limit);
+  }
+
+  if ("handles" in source) {
+    const found = await Promise.all(
+      source.handles.map((h) => tot.getProductByHandle(h)),
+    );
+    return found
+      .filter((p): p is CatalogProduct => !!p && isActive(p))
+      .slice(0, limit);
+  }
+
+  if ("tag" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all.filter((p) => p.tags.includes(source.tag)).slice(0, limit);
+  }
+
+  if ("onSale" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all.filter(isOnSale).slice(0, limit);
+  }
+
+  if ("bestSelling" in source) {
+    const all = await tot.getAllActiveProducts();
+    return all
+      .filter((p) => p.tags.some((t) => BESTSELLER_TAGS.has(t)))
+      .slice(0, limit);
+  }
+
+  if ("related" in source) {
+    const base = await tot.getProductByHandle(source.related);
+    if (!base) return [];
+    const baseCollections = new Set(base.collections);
+    const baseTags = new Set(base.tags);
+    const all = await tot.getAllActiveProducts();
+    const scored = all
+      .filter((p) => p.handle !== base.handle)
+      .map((p) => {
+        const shared =
+          p.collections.filter((c) => baseCollections.has(c)).length +
+          p.tags.filter((t) => baseTags.has(t)).length;
+        return { p, shared };
+      })
+      .filter((s) => s.shared > 0)
+      .sort((a, b) => b.shared - a.shared);
+    return scored.slice(0, limit).map((s) => s.p);
+  }
+
+  // recentlyViewed: server has no per-visitor history; the client island
+  // (RecentlyViewed.tsx) hydrates this. Resolve empty so the section can decide
+  // to hide or defer to its island.
+  return [];
+}
+
+/**
+ * Ready-made sources for the common merchandising rows. A preset carousel is
+ * just `<ProductCarousel source={SECTION_PRESETS.bestSellers} />` — there are no
+ * separate BestSellers/NewArrivals/OnSale components to maintain.
+ */
+export const SECTION_PRESETS = {
+  featured: { featured: true } as SectionSource,
+  bestSellers: { bestSelling: true } as SectionSource,
+  newArrivals: { newest: true } as SectionSource,
+  onSale: { onSale: true } as SectionSource,
+} as const;

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

@@ -0,0 +1,31 @@
+/**
+ * Baseline security response headers (Epic Phase-2 S1).
+ *
+ * Applied to every storefront response in middleware and baked into cached pages.
+ * The Content-Security-Policy itself (default-src/frame-ancestors/base-uri/…) is
+ * built separately in @tot/private-controlplane `csp.ts`; these are the complementary
+ * transport / sniffing / referrer / feature-permission headers that the appraisal
+ * flagged as missing.
+ */
+export const SECURITY_HEADERS: Readonly<Record<string, string>> = {
+  // 2-year HSTS with preload — production is HTTPS-only behind Cloudflare;
+  // browsers ignore this header on plain http (localhost dev), so it's safe to
+  // always set.
+  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
+  "X-Content-Type-Options": "nosniff",
+  // Legacy backstop; modern browsers honour the CSP `frame-ancestors 'self'`.
+  "X-Frame-Options": "SAMEORIGIN",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  // Lock powerful features off for the browse storefront. Verification and
+  // checkout (Powered by FoxyCart) run in their own surfaces that grant only
+  // what they need via per-frame Permissions-Policy.
+  "Permissions-Policy":
+    "camera=(), microphone=(), geolocation=(), browsing-topics=(), interest-cohort=()",
+};
+
+/** Set the baseline headers on a response, without clobbering anything already set. */
+export function applySecurityHeaders(headers: Headers): void {
+  for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+    if (!headers.has(key)) headers.set(key, value);
+  }
+}